Troubleshooting: Migrating a User from GitLab OAuth to SAML in Mattermost

Applies To: Mattermost Self-Hosted (Enterprise Edition)
Use Case: Switching user authentication from GitLab OAuth to SAML SSO

 Problem

You need to migrate an existing user in Mattermost from GitLab authentication to SAML Single Sign-On, without losing account history or access.

Requirements

• SAML is configured and enabled in Mattermost.

• The user’s email and username match in GitLab, Mattermost, and your SAML IdP.

• You have access to the mmctl CLI with --local support.

• If using Docker, you have the container ID (not just the service name).

Solution

1. Create a JSON file:

{
  "user@example.com": "username"
}

Save it as single-user.json.

2. Run the command:

Docker:

docker exec -it <container_id> mmctl user migrate-auth gitlab saml single-user.json --local

Non-Docker:

mmctl user migrate-auth gitlab saml single-user.json --local

✅ Replace <container_id> with the actual container ID.

Common Issues

Related Articles

• mmctl CLI Tool

• SAML Setup Guide

• Switching Authentication Methods