Skip to main content
Mattermost provides comprehensive user management capabilities including user creation, role-based access control, team/channel permissions, and multiple authentication methods.

​
User Creation

​
Creating Users via CLI

1

Create a User

Use mmctl to create users:
# Create a regular user
mmctl user create --email [email protected] \
  --username john.doe \
  --password SecurePass123! \
  --firstname John \
  --lastname Doe

# Create a system admin
mmctl user create --email [email protected] \
  --username admin \
  --password AdminPass123! \
  --system-admin
2

Verify User Creation

Confirm the user was created:
mmctl user search john.doe
3

Add to Team

Add the user to a team:
mmctl team users add myteam john.doe

​
Bulk User Import

Import multiple users from a JSON file: 
[
  {
    "type": "user",
    "user": {
      "username": "john.doe",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "password": "SecurePass123!",
      "position": "Developer",
      "roles": "system_user",
      "teams": [
        {
          "name": "engineering",
          "roles": "team_user"
        }
      ]
    }
  }
]

# Import users
mmctl import upload users.json

​
Roles and Permissions

Mattermost uses a role-based permission system with hierarchical scopes.

​
System-Level Roles

Role ID: system_admin

Full administrative access:
- Manage all users, teams, and channels
- Access System Console
- Modify system configuration
- View all content
- Manage integrations and plugins

​
Team-Level Roles

# Team Admin
- Manage team settings
- Add/remove team members
- Manage team channels
- Set team roles

# Team User
- Create public/private channels
- Join public channels
- Invite users to team
- Post in channels they're members of

# Team Guest
- Limited to assigned channels
- Cannot invite users
- Cannot create channels

​
Channel-Level Roles

# Channel Admin
- Manage channel settings
- Add/remove members
- Delete channel
- Archive channel

# Channel User
- Post messages
- Upload files
- React to messages
- Create threads

# Channel Guest
- Read and post messages
- Limited to this channel only

​
Managing User Roles

​
Promote to System Admin

# Grant system admin role
mmctl user role assign john.doe system_admin

# Verify role assignment
mmctl user get john.doe --json | jq '.roles'

​
Team Role Management

# Make user a team admin
mmctl team users add myteam john.doe --role team_admin

# Demote from team admin
mmctl team users add myteam john.doe --role team_user

​
Channel Role Management

# Add as channel admin
mmctl channel users add myteam:engineering john.doe --role channel_admin

# List channel members
mmctl channel users list myteam:engineering

​
Authentication Methods

Mattermost supports multiple authentication providers.

​
Email/Password Authentication

Default authentication method: 
{
  "EmailSettings": {
    "EnableSignUpWithEmail": true,
    "EnableSignInWithEmail": true,
    "EnableSignInWithUsername": true,
    "RequireEmailVerification": true
  },
  "PasswordSettings": {
    "MinimumLength": 10,
    "Lowercase": true,
    "Number": true,
    "Uppercase": true,
    "Symbol": true
  },
  "ServiceSettings": {
    "MaximumLoginAttempts": 10
  }
}
Password Security:
  • Minimum length: 5-72 characters
  • Default recommended: 10+ characters
  • Failed login attempts tracked per user
  • Account locked after max attempts (default: 10)

​
LDAP Authentication

Integrate with Active Directory or OpenLDAP: 
{
  "LdapSettings": {
    "Enable": true,
    "EnableSync": true,
    "LdapServer": "ldap.example.com",
    "LdapPort": 389,
    "ConnectionSecurity": "STARTTLS",
    "BaseDN": "ou=Users,dc=example,dc=com",
    "BindUsername": "cn=admin,dc=example,dc=com",
    "BindPassword": "password",
    "UserFilter": "(objectClass=user)",
    "EmailAttribute": "mail",
    "UsernameAttribute": "sAMAccountName",
    "IdAttribute": "objectGUID",
    "FirstNameAttribute": "givenName",
    "LastNameAttribute": "sn",
    "LoginFieldName": "AD/LDAP Username",
    "MaximumLoginAttempts": 10,
    "SyncIntervalMinutes": 60
  }
}
Test LDAP Connection:
1

Configure LDAP

Set LDAP settings in config.json or System Console
2

Test Connection

mmctl ldap test
3

Sync Users

# Manual sync
mmctl ldap sync

# Schedule automatic sync (configured in LdapSettings.SyncIntervalMinutes)
4

Verify Users

mmctl user search "@ldap.example.com"

​
SAML 2.0 Authentication

Enterprise feature for SSO integration: 
{
  "SamlSettings": {
    "Enable": true,
    "EnableSyncWithLdap": false,
    "Verify": true,
    "Encrypt": true,
    "SignRequest": false,
    "IdpUrl": "https://idp.example.com/saml/sso",
    "IdpDescriptorUrl": "https://idp.example.com/saml/metadata",
    "IdpMetadataUrl": "https://idp.example.com/saml/metadata.xml",
    "ServiceProviderIdentifier": "https://mattermost.example.com",
    "AssertionConsumerServiceURL": "https://mattermost.example.com/login/sso/saml",
    "SignatureAlgorithm": "RSAwithSHA256",
    "CanonicalAlgorithm": "Canonical1.0",
    "IdAttribute": "id",
    "EmailAttribute": "email",
    "UsernameAttribute": "username",
    "FirstNameAttribute": "firstName",
    "LastNameAttribute": "lastName"
  }
}
Certificate Management: 
# Upload SAML certificates
mmctl saml certificate upload-idp --cert /path/to/idp.crt
mmctl saml certificate upload-public --cert /path/to/public.crt
mmctl saml certificate upload-private --cert /path/to/private.key

# Check certificate status
mmctl saml certificate status

​
OAuth 2.0 (GitLab, Google, Office365)

{
  "GitLabSettings": {
    "Enable": true,
    "Id": "your-gitlab-app-id",
    "Secret": "your-gitlab-app-secret",
    "UserApiEndpoint": "https://gitlab.example.com/api/v4/user",
    "AuthEndpoint": "https://gitlab.example.com/oauth/authorize",
    "TokenEndpoint": "https://gitlab.example.com/oauth/token"
  }
}

​
Multi-Factor Authentication (MFA)

Add an extra layer of security: 
{
  "ServiceSettings": {
    "EnableMultifactorAuthentication": true,
    "EnforceMultifactorAuthentication": false
  }
}
Enable MFA for a User: 
# User must enable via Account Settings > Security > Multi-factor Authentication
# Or admin can enforce:
mmctl config set ServiceSettings.EnforceMultifactorAuthentication true

​
User Lifecycle Management

​
Deactivate Users

# Deactivate a user
mmctl user deactivate john.doe

# Deactivate multiple users
mmctl user deactivate john.doe jane.smith bob.wilson

# Verify deactivation
mmctl user get john.doe --json | jq '.delete_at'

​
Reactivate Users

# Reactivate a deactivated user
mmctl user activate john.doe

​
Delete Users

User deletion is permanent and removes all user data including:
  • Posts and messages
  • File uploads
  • Direct message history
  • Profile information
# Permanently delete user (requires confirmation)
mmctl user delete john.doe --confirm

​
Password Management

# Reset user password
mmctl user reset-password john.doe --password NewSecurePass123!

# Force password change on next login
mmctl user update-password john.doe --password TempPass123! --must-change

​
Guest Accounts

Guest accounts provide restricted access: 
# Demote user to guest
mmctl user demote john.doe

# Promote guest to user
mmctl user promote john.guest

# Create new guest
mmctl user create --email [email protected] \
  --username guest.user \
  --password GuestPass123! \
  --guest
Guest Restrictions:
  • Cannot create teams
  • Cannot discover public channels
  • Limited to explicitly added channels
  • Cannot invite other users
  • Cannot access System Console

​
User Access Tokens

Create tokens for API access: 
# Enable user access tokens
mmctl config set ServiceSettings.EnableUserAccessTokens true

# Create token for user
mmctl token generate john.doe "API Integration Token"

# List user tokens
mmctl token list john.doe

# Revoke token
mmctl token revoke token_id_here

​
Session Management

​
View Active Sessions

# List user sessions
mmctl user sessions john.doe

# Revoke all sessions for user
mmctl user revoke-sessions john.doe

​
Session Configuration

{
  "ServiceSettings": {
    "SessionLengthWebInHours": 720,
    "SessionLengthMobileInHours": 720,
    "SessionLengthSSOInHours": 720,
    "SessionCacheInMinutes": 10,
    "SessionIdleTimeoutInMinutes": 43200,
    "ExtendSessionLengthWithActivity": true,
    "TerminateSessionsOnPasswordChange": true
  }
}

​
Troubleshooting

​
User Cannot Login

1

Check Account Status

mmctl user get john.doe --json | jq '{username, delete_at, auth_service, failed_attempts}'
2

Reset Failed Attempts

# Reactivate if deactivated
mmctl user activate john.doe

# Reset password if needed
mmctl user reset-password john.doe --password NewPass123!
3

Check Authentication Method

Verify the user is using correct auth method (email, LDAP, SAML, OAuth)

​
LDAP Sync Issues

# Check LDAP connectivity
mmctl ldap test

# Force manual sync
mmctl ldap sync

# Check sync job status
mmctl ldap job list

​
Permission Denied

# Check user roles
mmctl user get john.doe --json | jq '.roles'

# Verify team membership
mmctl team users list myteam | grep john.doe

# Check channel membership
mmctl channel users list myteam:engineering | grep john.doe

Build docs developers (and LLMs) love

Get started for freeTalk to us