123 lines
4.2 KiB
Markdown
123 lines
4.2 KiB
Markdown
# 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
|