Problem
A System Administrator may become locked out of the Mattermost system in the following scenarios:
- During SAML configuration process when authentication method changes
- When email sign-in is disabled before switching to a new sign-in method
- After misconfiguring authentication settings
When this occurs, the administrator cannot access the System Console to fix the configuration or manage the system.
Solution
Use mmctl in local mode to either promote an existing user account or create a new account and promote it to System Admin. Local mode bypasses authentication requirements by connecting directly to the Mattermost server using the configuration file.
Option 1: Promote an Existing User Account
If you have an existing user account that you can access, you can promote it to System Admin.
Bare Metal / Tarball Installation
1. SSH into your Mattermost server.
2. Navigate to the Mattermost installation directory:
cd /opt/mattermost
3. Promote the user to System Admin:
sudo -u mattermost bin/mmctl --local roles system_admin username
Replace username with the username of the account you want to promote.
Docker Installation
Promote the user to System Admin directly using docker exec:
docker exec mattermost-container-name mmctl --local roles system_admin username
Replace mattermost-container-name with your actual container name and username with the username to promote.
Kubernetes Installation
1. Get the Mattermost pod name:
kubectl get pods -n mattermost
2. Execute the command in the pod:
kubectl exec -it mattermost-pod-name -n mattermost -- mmctl --local roles system_admin username
Replace mattermost-pod-name with your actual pod name and username with the username to promote.
Option 2: Create a New User Account with System Admin Role
If you don't have access to any existing accounts, you can create a new user account with System Admin privileges in a single command.
Bare Metal / Tarball Installation
1. SSH into your Mattermost server.
2. Navigate to the Mattermost installation directory:
cd /opt/mattermost
3. Create a new user account with System Admin role:
sudo -u mattermost bin/mmctl --local user create --email admin@example.com --username newadmin --password Password123! --system-admin
Docker Installation
Create a new user account with System Admin role:
docker exec mattermost-container-name mmctl --local user create --email admin@example.com --username newadmin --password Password123! --system-admin
Kubernetes Installation
1. Get the Mattermost pod name:
kubectl get pods -n mattermost
2. Create a new user account with System Admin role:
kubectl exec -it mattermost-pod-name -n mattermost -- mmctl --local user create --email admin@example.com --username newadmin --password Password123! --system-admin
Verify the Role Assignment
After promoting the user, verify the role assignment was successful:
Bare Metal / Tarball:
sudo -u mattermost bin/mmctl --local user get username
Docker:
docker exec mattermost-container-name mmctl --local user get username
Kubernetes:
kubectl exec -it mattermost-pod-name -n mattermost -- mmctl --local user get username
The output should show that the user has the system_admin role assigned.
Additional Resources
For more information, see:
Comments
Article is closed for comments.