# 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**:
  ```python
  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**:
  ```python
  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!):

```json
"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**:
   ```bash
   ssh test@matrix-ubuntu-ip  # or via Cloudflare tunnel
   ```
4. **Edit config.json**:
   ```bash
   sudo nano /opt/mattermost/config/config.json
   ```
5. **Restart Mattermost**:
   ```bash
   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](https://integrations.goauthentik.io/chat-communication-collaboration/mattermost-team-edition/)
- [Mattermost GitLab Authentication](https://docs.mattermost.com/integrations-guide/gitlab.html)

## 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