Sanitized mirror from private repository - 2026-04-18 11:19:59 UTC

docs/services/individual/mattermost-oauth.md

@@ -0,0 +1,122 @@
+# 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