Mattermost

This guide explains how to set up single sign-on (SSO) between VaultysHub and Mattermost. Mattermost supports both SAML2 and OpenID Connect in the Professional and Enterprise editions.

Prerequisites

Mattermost version 5.0+ (SAML2) or 5.35+ (OpenID Connect)
Mattermost Professional or Enterprise Edition
System administrator access to Mattermost
Application configured in VaultysHub

Configuration with OpenID Connect (Recommended)

Configuration in VaultysHub

1. Create the application

Log in to VaultysHub as an administrator
Go to Applications → Add
Create a new application:
- Name: Mattermost
- URL: https://mattermost.example.com
- Description: Team messaging platform
- Icon: Choose the Mattermost icon

2. Configure OpenID Connect

In the Authentication tab
Select OpenID Connect
Note the information:
- Client ID: mattermost-xxxxxx
- Client Secret: secret-xxxxxx
- Issuer URL: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]
- App ID: [appid] (unique identifier of the application in VaultysHub)

3. Redirect URLs

Add to Authorized Redirect URLs:

https://mattermost.example.com/signup/openid/complete
https://mattermost.example.com/login/openid/complete

4. Required Scopes

openid
profile
email

Configuration in Mattermost

1. Via the System Console

Log in as a system administrator
Go to System Console → Authentication → OpenID Connect
Enable Enable OpenID Connect Authentication

2. Configure the settings

Configure the following fields:

Select OpenID Connect Service Provider: Custom
Button Name: VaultysHub SSO
Button Color: #0066CC
Discovery Endpoint: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
Client ID: mattermost-xxxxxx
Client Secret: secret-xxxxxx

3. Advanced configuration (optional)

If automatic discovery does not work, configure manually:

Authorization Endpoint: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/auth
Token Endpoint: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/token
User API Endpoint: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/userinfo

4. Attribute mapping

ID Attribute: sub
Username Attribute: email
Email Attribute: email
First Name Attribute: given_name
Last Name Attribute: family_name

Configuration via config.json

For file-based configuration:

{
  "GitLabSettings": {
    "Enable": true,
    "Secret": "",
    "Id": "",
    "Scope": "",
    "AuthEndpoint": "",
    "TokenEndpoint": "",
    "UserApiEndpoint": "",
    "DiscoveryEndpoint": "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration",
    "ButtonText": "VaultysHub SSO",
    "ButtonColor": "#0066CC"
  },
  "OpenIdSettings": {
    "Enable": true,
    "Secret": "secret-xxxxxx",
    "Id": "mattermost-xxxxxx",
    "Scope": "openid profile email",
    "AuthEndpoint": "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/auth",
    "TokenEndpoint": "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/token",
    "UserApiEndpoint": "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/userinfo",
    "DiscoveryEndpoint": "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration",
    "ButtonText": "VaultysHub SSO",
    "ButtonColor": "#0066CC"
  }
}

Configuration with SAML2

Configuration in VaultysHub

1. Configure SAML2

In the Mattermost application
Tab Authentication → SAML2
Configure:
- Entity ID: https://mattermost.example.com
- ACS URL: https://mattermost.example.com/login/sso/saml
- Format NameID: emailAddress

2. Download the metadata

IdP Metadata: https://your-vaultyshub.link.vaultys.org/api/saml2/metadata/[appid]
SSO URL: https://your-vaultyshub.link.vaultys.org/api/saml2/sso/[appid]
X.509 Certificate: Download from VaultysHub

Single Logout from VaultysHub is not supported.

Configuration in Mattermost

1. Via System Console

System Console → Authentication → SAML 2.0
Enable Enable Login With SAML 2.0

2. Configure SAML settings

Identity Provider Metadata URL: https://your-vaultyshub.link.vaultys.org/api/saml2/metadata/[appid]

Or manual configuration:

SAML SSO URL: https://your-vaultyshub.link.vaultys.org/api/saml2/sso/[appid]
Identity Provider Issuer URL: https://your-vaultyshub.link.vaultys.org/[appid]
Identity Provider Public Certificate: Paste the X.509 certificate

3. Service Provider configuration

Service Provider Identifier: https://mattermost.example.com
Verify Signature: true
Enable Encryption: false

4. SAML attribute mapping

Email Attribute: email
Username Attribute: email
Id Attribute: userId
First Name Attribute: firstName
Last Name Attribute: lastName
Login Button Text: Log in with VaultysHub

Team and channel synchronization

VaultysHub does not transmit user groups: team and channel membership is managed directly in Mattermost.

Automatic channel creation

Script to automatically create teams and channels:

#!/bin/bash
# Create teams and channels

mmctl auth login https://mattermost.example.com \
  --name production \
  --username admin \
  --password-file password.txt

# Create teams
mmctl team create --name development --display-name "Development"
mmctl team create --name marketing --display-name "Marketing"

# Create channels
mmctl channel create --team development --name backend --display-name "Backend"
mmctl channel create --team development --name frontend --display-name "Frontend"
mmctl channel create --team marketing --name campaigns --display-name "Campaigns"

Docker Configuration

Docker Compose with OpenID Connect

version: '3.8'

services:
  mattermost:
    image: mattermost/mattermost-enterprise-edition:latest
    container_name: mattermost
    restart: unless-stopped
    environment:
      # Database
      - MM_SQLSETTINGS_DRIVERNAME=postgres
      - MM_SQLSETTINGS_DATASOURCE=postgres://mattermost:mattermost@db:5432/mattermost?sslmode=disable
      
      # OpenID Connect
      - MM_OPENIDSETTINGS_ENABLE=true
      - MM_OPENIDSETTINGS_ID=mattermost-xxxxxx
      - MM_OPENIDSETTINGS_SECRET=secret-xxxxxx
      - MM_OPENIDSETTINGS_DISCOVERYENDPOINT=https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
      - MM_OPENIDSETTINGS_BUTTONTEXT=VaultysHub SSO
      - MM_OPENIDSETTINGS_BUTTONCOLOR=#0066CC
      
      # Site URL
      - MM_SERVICESETTINGS_SITEURL=https://mattermost.example.com
      
      # File storage
      - MM_FILESETTINGS_DIRECTORY=/mattermost/data/
      
    volumes:
      - ./data:/mattermost/data
      - ./config:/mattermost/config
      - ./logs:/mattermost/logs
      - ./plugins:/mattermost/plugins
    ports:
      - "8065:8065"
    depends_on:
      - db

  db:
    image: postgres:13-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=mattermost
      - POSTGRES_PASSWORD=mattermost
      - POSTGRES_DB=mattermost
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Permission management

System roles

VaultysHub does not transmit user groups or roles: system administrator and team roles are assigned directly in Mattermost.

Custom permission schemas

{
  "Roles": {
    "channel_user": {
      "permissions": [
        "create_post",
        "add_reaction",
        "remove_reaction",
        "upload_file"
      ]
    },
    "team_admin": {
      "permissions": [
        "manage_team",
        "add_user_to_team",
        "remove_user_from_team",
        "manage_channel_roles"
      ]
    }
  }
}

Configuration testing

# Test via API
curl -X POST https://mattermost.example.com/api/v4/users/login \
  -H "Content-Type: application/json" \
  -d '{"login_id":"[email protected]","password":"password"}'

2. Test with mmctl

# Install mmctl
brew install mmctl  # macOS
# or
wget https://releases.mattermost.com/mmctl/v7.8.0/linux_amd64.tar

# Login
mmctl auth login https://mattermost.example.com

# Verification
mmctl user list
mmctl team list
mmctl channel list development

3. Test webhooks

# Create an incoming webhook
WEBHOOK_URL=$(mmctl webhook create-incoming \
  --team development \
  --channel general \
  --display-name "VaultysHub Integration")

# Test sending
curl -X POST $WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"text": "Test SSO integration"}'

Troubleshooting

Solution:

Check the Mattermost logs:

docker logs mattermost 2>&1 | grep -i auth

Test OpenID discovery:

curl https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration

Solution:

Check the X.509 certificate
Test with saml-tracer (browser extension)

Check the logs:

tail -f /opt/mattermost/logs/mattermost.log | grep SAML

Teams are not synchronized

Solution: this is the expected behavior. VaultysHub does not transmit groups: add users to teams directly in Mattermost.

Error "User is not authorized"

Solution:

Check that the user is assigned to the application in VaultysHub

Check permissions in Mattermost:

mmctl user search [email protected]
mmctl permissions show-role system_user

Security

Recommended configuration

{
  "ServiceSettings": {
    "EnableInsecureOutgoingConnections": false,
    "EnableLocalMode": false,
    "SessionLengthWebInDays": 7,
    "SessionLengthMobileInDays": 30,
    "SessionCacheInMinutes": 10,
    "WebsocketSecurePort": 443,
    "TLSMinVer": "1.2"
  },
  "PasswordSettings": {
    "MinimumLength": 10,
    "Lowercase": true,
    "Number": true,
    "Uppercase": true,
    "Symbol": true
  }
}

Audit and compliance

{
  "ComplianceSettings": {
    "Enable": true,
    "Directory": "/mattermost/compliance/",
    "EnableDaily": true
  },
  "LogSettings": {
    "EnableConsole": true,
    "ConsoleLevel": "INFO",
    "EnableFile": true,
    "FileLevel": "INFO",
    "FileLocation": "/mattermost/logs/"
  }
}

Advanced integrations

Bots and applications

# Python bot for Mattermost
from mattermostdriver import Driver

driver = Driver({
    'url': 'https://mattermost.example.com',
    'token': 'bot-token-xxxxxx',
    'scheme': 'https',
    'port': 443
})

driver.login()

# Post a message
driver.posts.create_post({
    'channel_id': 'channel-id',
    'message': 'Hello from VaultysHub SSO!'
})

Integration with GitLab

{
  "PluginSettings": {
    "Plugins": {
      "com.github.manland.mattermost-plugin-gitlab": {
        "gitlaburl": "https://gitlab.example.com",
        "gitlaboauthclientid": "gitlab-oauth-id",
        "gitlaboauthclientsecret": "gitlab-oauth-secret"
      }
    }
  }
}

Prerequisites​

Configuration with OpenID Connect (Recommended)​

Configuration in VaultysHub​

1. Create the application​

2. Configure OpenID Connect​

3. Redirect URLs​

4. Required Scopes​

Configuration in Mattermost​

1. Via the System Console​

2. Configure the settings​

3. Advanced configuration (optional)​

4. Attribute mapping​

Configuration via config.json​

Configuration with SAML2​

Configuration in VaultysHub​

1. Configure SAML2​

2. Download the metadata​

Configuration in Mattermost​

1. Via System Console​

2. Configure SAML settings​

3. Service Provider configuration​

4. SAML attribute mapping​

Team and channel synchronization​

Automatic channel creation​

Docker Configuration​

Docker Compose with OpenID Connect​

Permission management​

System roles​

Custom permission schemas​

Configuration testing​

1. Login test​

2. Test with mmctl​

3. Test webhooks​

Troubleshooting​

Error "Invalid login credentials"​

Error "SAML login was unsuccessful"​

Teams are not synchronized​

Error "User is not authorized"​

Security​

Recommended configuration​

Audit and compliance​

Advanced integrations​

Bots and applications​

Integration with GitLab​

Resources​

Prerequisites

Configuration with OpenID Connect (Recommended)

Configuration in VaultysHub

1. Create the application

2. Configure OpenID Connect

3. Redirect URLs

4. Required Scopes

Configuration in Mattermost

1. Via the System Console

2. Configure the settings

3. Advanced configuration (optional)

4. Attribute mapping

Configuration via config.json

Configuration with SAML2

Configuration in VaultysHub

1. Configure SAML2

2. Download the metadata

Configuration in Mattermost

1. Via System Console

2. Configure SAML settings

3. Service Provider configuration

4. SAML attribute mapping

Team and channel synchronization

Automatic channel creation

Docker Configuration

Docker Compose with OpenID Connect

Permission management

System roles

Custom permission schemas

Configuration testing

1. Login test

2. Test with mmctl

3. Test webhooks

Troubleshooting

Error "Invalid login credentials"

Error "SAML login was unsuccessful"

Teams are not synchronized

Error "User is not authorized"

Security

Recommended configuration

Audit and compliance

Advanced integrations

Bots and applications

Integration with GitLab

Resources