Mattermost

This guide explains how to set up Single Sign-On (SSO) between SmartLink 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 SmartLink

Configuration with OpenID Connect (Recommended)

Configuration in SmartLink

1. Create the application

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

2. Configure OpenID Connect

1. In the Authentication tab
2. Select OpenID Connect
3. Note the information:
   • Client ID: mattermost-xxxxxx
   • Client Secret: secret-xxxxxx
   • Issuer URL: https://your-smartlink.link.vaultys.org
   • App ID: [appid] (unique application identifier in SmartLink)

3. Allowed Redirect URLs

Add to Allowed Redirect URLs:

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

4. Required Scopes

• openid
• profile
• email
• groups (optional, for team synchronization)

Configuration in Mattermost

1. Via System Console

1. Log in as a system administrator
2. Go to System Console → Authentication → OpenID Connect
3. Enable Enable OpenID Connect Authentication

2. Configure the settings

Configure the following fields:

• Select OpenID Connect Service Provider: Custom
• Button Name: SmartLink SSO
• Button Color: #0066CC
• Discovery Endpoint: https://your-smartlink.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-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
• Token Endpoint: https://your-smartlink.link.vaultys.org/api/oidc/[appid]/token
• User API Endpoint: https://your-smartlink.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
• Nickname Attribute: nickname
• Position Attribute: title
• Language Attribute: locale
• Picture Attribute: picture

Configuration via config.json

For file-based configuration:

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

Configuration with SAML2

Configuration in SmartLink

1. Configure SAML2

1. In the Mattermost application
2. Authentication tab → SAML2
3. Configure:
   • Entity ID: https://mattermost.example.com
   • ACS URL: https://mattermost.example.com/login/sso/saml
   • NameID Format: emailAddress or persistent

2. Download the metadata

• IdP Metadata: https://your-smartlink.link.vaultys.org/api/saml2/[appid]/metadata
• SSO URL: https://your-smartlink.link.vaultys.org/api/saml2/[appid]/sso
• SLO URL: https://your-smartlink.link.vaultys.org/api/saml2/[appid]/slo
• X.509 Certificate: Download from SmartLink

Configuration in Mattermost

1. Via System Console

1. System Console → Authentication → SAML 2.0
2. Enable Enable Login With SAML 2.0

2. Configure SAML settings

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

Or manual configuration:

• SAML SSO URL: https://your-smartlink.link.vaultys.org/api/saml2/[appid]/sso
• Identity Provider Issuer URL: https://your-smartlink.link.vaultys.org
• 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: username
• Id Attribute: uid
• First Name Attribute: firstName
• Last Name Attribute: lastName
• Nickname Attribute: nickname
• Position Attribute: title
• Language Attribute: preferredLanguage
• Login Button Text: Log in with SmartLink

Team and Channel Synchronization

SCIM Group Configuration

To automatically synchronize teams:

1. System Console → Groups
2. Enable Enable AD/LDAP Group Sync
3. Configure group mapping:

{
  "GroupSettings": {
    "EnableCustomUserGroups": true,
    "EnableSyncWithLdap": true,
    "EnableSyncWithSaml": true
  }
}

Automatic Team Mapping

{
  "TeamSettings": {
    "EnableOpenIDConnectGroupSync": true,
    "GroupsField": "groups",
    "TeamMapping": {
      "smartlink-dev": "development-team",
      "smartlink-marketing": "marketing-team",
      "smartlink-support": "support-team"
    }
  }
}

Automatic Channel Creation

Script to automatically create channels based on groups:

#!/bin/bash
# Create channels for each group

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-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
      - MM_OPENIDSETTINGS_BUTTONTEXT=SmartLink 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

Role mapping configuration:

{
  "OpenIdSettings": {
    "AdminAttribute": "is_admin",
    "AdminAttributeValue": "true",
    "SystemAdminRoles": ["smartlink-admins"],
    "TeamAdminRoles": ["smartlink-team-leads"]
  }
}

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

1. Connection Test

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

2. Testing 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. Webhooks Testing

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

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

Troubleshooting

Error "Invalid login credentials"

Solution:

1. Check Mattermost logs:

   docker logs mattermost 2>&1 | grep -i auth
2. Test OpenID discovery:

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

Error "SAML login was unsuccessful"

Solution:

1. Verify the X.509 certificate
2. Test with saml-tracer (browser extension)
3. Check logs:

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

Teams are not synchronized

Solution:

{
  "OpenIdSettings": {
    "GroupsClaim": "groups",
    "EnableGroupSync": true,
    "GroupsField": "groups"
  }
}

Error "User is not authorized"

Solution:

1. Ensure the user is assigned to the application in SmartLink
2. Check permissions in Mattermost:

   mmctl user search user@example.com
   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 SmartLink 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"
      }
    }
  }
}

Resources

• Mattermost SSO Documentation
• Mattermost OpenID Connect
• Mattermost API
• mmctl CLI