homelab-optimized/docs/services/individual/mattermost-oauth.md

Mattermost OAuth2 with Authentik

Host: Matrix Ubuntu VM (192.168.0.154)
Domain: mm.crista.love
Port: 8065
Compose File: /opt/mattermost/docker-compose.yml
Status: 🔧 Requires Authentik Property Mappings (see below)

Important: Mattermost Team Edition Limitation

⚠️ Mattermost Team Edition (free) does NOT support generic OpenID Connect!

OpenID Connect is Enterprise-only. For Team Edition, we use the GitLab OAuth workaround where Authentik emulates GitLab's OAuth endpoints.

Authentication Methods

1. Local Login - Email/password on the login page ✅ Always works
2. GitLab OAuth (via Authentik) - "Log in with authentik" button

Authentik Configuration

Step 1: Create Custom Scope Mappings

In Authentik Admin → Customization → Property Mappings → Create → Scope Mapping:

Mapping 1: mattermost-username

• Name: mattermost-username
• Scope Name: username
• Description: Maps the user's authentik username to the username field for Mattermost authentication.
• Expression:

  return {
      "username": request.user.username,
  }
  

Mapping 2: mattermost-id (optional but recommended)

• Name: mattermost-id
• Scope Name: id
• Description: Maps the user's Mattermost ID or primary key to the id field for Mattermost authentication.
• Expression:

  return {
      "id": request.user.attributes.get("mattermostId", request.user.pk),
  }
  

Step 2: Provider Configuration

• Name: Mattermost OAuth2
• Type: OAuth2/OpenID Provider
• Client ID: OGxIdZLKqYKgf9Sf9zAFAyhKzBdDvonL7HHSBu1w
• Redirect URI: strict: https://mm.crista.love/signup/gitlab/complete
• Scopes: Add the custom mattermost-username and mattermost-id scopes, plus openid, email, profile

Application Created

• Name: Mattermost
• Slug: mattermost
• Launch URL: https://mm.crista.love

Mattermost Configuration

Update /opt/mattermost/config/config.json with GitLabSettings (NOT OpenIDSettings!):

"GitLabSettings": {
    "Enable": true,
    "Secret": "<client_secret_from_authentik>",
    "Id": "OGxIdZLKqYKgf9Sf9zAFAyhKzBdDvonL7HHSBu1w",
    "Scope": "",
    "AuthEndpoint": "https://sso.vish.gg/application/o/authorize/",
    "TokenEndpoint": "https://sso.vish.gg/application/o/token/",
    "UserAPIEndpoint": "https://sso.vish.gg/application/o/userinfo/",
    "DiscoveryEndpoint": "https://sso.vish.gg/application/o/mattermost/.well-known/openid-configuration",
    "ButtonText": "Log in with authentik",
    "ButtonColor": "#fd4b2d"
}

Activation Steps

1. Create Authentik Property Mappings (see Step 1 above)
2. Update Provider Scopes - Add the new mappings to the Mattermost OAuth2 provider
3. SSH to Matrix Ubuntu VM:

   ssh test@matrix-ubuntu-ip  # or via Cloudflare tunnel
   

4. Edit config.json:

   sudo nano /opt/mattermost/config/config.json
   

5. Restart Mattermost:

   cd /opt/mattermost && docker compose restart
   

6. Test by visiting https://mm.crista.love - you should see "Log in with authentik" button

Troubleshooting

GitLab button not appearing

• Verify GitLabSettings.Enable is true in config.json
• Restart Mattermost after changes
• Check for JSON syntax errors: cat config.json | jq .

Login fails after redirect

• Verify redirect URI matches exactly: https://mm.crista.love/signup/gitlab/complete
• Ensure the custom scope mappings are created AND assigned to the provider
• Check Mattermost logs: docker logs mattermost

User created with wrong username format

• If you see usernames like person-example.com, you need the mattermost-id scope mapping
• The id field prevents Mattermost from generating IDs from email addresses

Related Documentation

• Authentik Mattermost Team Edition Integration
• Mattermost GitLab Authentication

Change Log

• 2026-01-31: Updated to use GitLab OAuth approach for Team Edition compatibility
• 2026-01-31: Created OAuth2 provider and application in Authentik