How to Manually Change a User's Authentication Method via Database

Applies to: Mattermost Server (All versions)

Symptoms: Need to change a user's authentication method when standard UI and System Console methods are unavailable

🛑 Problem

In rare circumstances, administrators may need to manually modify the PostgreSQL database to change a user's authentication method. This involves updating the authservice and authdata columns in the users table when standard administrative methods are insufficient or unavailable.

Symptoms

Users or administrators experiencing this issue will see:

• A need to migrate users between authentication providers (e.g., LDAP to SAML)
• Authentication configuration issues that cannot be resolved through System Console Authentication
• Recovery from an authentication system failure that has left users unable to log in
• Other rare edge cases as directed by Mattermost support staff

✅ Solution

To change a user's authentication method, update two columns in the users table: authservice and authdata. Both must be set consistently for the target authentication method.

⚠️ Important: Perform this procedure only when explicitly instructed by Mattermost support staff. Incorrect database modifications can cause authentication failures, data corruption, or system instability. Always create a complete database backup before making any manual changes.

Update the authservice Column

The authservice column defines the authentication provider. Set it to one of the following values:

Update the authdata Column

The authdata column stores the user's identifier from the external authentication provider. This column has a unique key constraint and must be handled carefully:

• For SAML, LDAP, or GitLab: Set the value to the user's IdAttribute from the authentication provider. Ensure the value is unique across all users in the database.
• For email/password: Set the value to NULL (not an empty string).

Example SQL to switch a user to LDAP authentication:

UPDATE users
SET authservice = 'ldap',
    authdata = '<ldap-id-attribute-value>'
WHERE username = '<target-username>';

Example SQL to switch a user back to email/password authentication:

UPDATE users
SET authservice = '',
    authdata = NULL
WHERE username = '<target-username>';

Additional Resources

For more information, see:

Mattermost Authentication Configuration Documentation