Mattermost

本指南将向您介绍如何在 SmartLink 和 Mattermost 之间配置单点登录（SSO）。Mattermost 在专业版和企业版中均支持 SAML2 和 OpenID Connect。

先决条件

• Mattermost 版本 5.0+（SAML2）或 5.35+（OpenID Connect）
• Mattermost 专业版或企业版
• 对 Mattermost 的系统管理员访问权限
• 在 SmartLink 中配置的应用程序

使用 OpenID Connect 进行配置（推荐）

在 SmartLink 中进行配置

1. 创建应用程序

1. 以管理员身份登录 SmartLink
2. 转到 应用程序 → 添加
3. 创建一个新应用程序：
   • 名称：Mattermost
   • URL：https://mattermost.example.com
   • 描述：团队消息平台
   • 图标：选择 Mattermost 图标

2. 配置 OpenID Connect

1. 在 身份验证 选项卡中
2. 选择 OpenID Connect
3. 记下以下信息：
   • 客户端 ID：mattermost-xxxxxx
   • 客户端密钥：secret-xxxxxx
   • 发行者 URL：https://votre-smartlink.link.vaultys.org
   • 应用程序 ID：[appid]（在 SmartLink 中的应用程序的唯一标识）

3. 授权重定向 URL

添加到 允许的重定向 URL 中：

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

4. 所需范围

• openid
• profile
• email
• groups（可选，用于团队同步）

在 Mattermost 中进行配置

1. 通过系统控制台

1. 以系统管理员身份登录
2. 转到 系统控制台 → 身份验证 → OpenID Connect
3. 启用 启用 OpenID Connect 身份验证

2. 配置参数

配置以下字段：

• 选择 OpenID Connect 服务提供商：Custom
• 按钮名称：SmartLink SSO
• 按钮颜色：#0066CC
• 发现端点：https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
• 客户端 ID：mattermost-xxxxxx
• 客户端密钥：secret-xxxxxx

3. 高级配置（可选）

如果自动发现无法正常工作，请手动配置：

• 授权端点：https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
• 令牌端点：https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/token
• 用户 API 端点：https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo

4. 属性映射

• ID 属性：sub
• 用户名属性：email
• 电子邮件属性：email
• 名字属性：given_name
• 姓氏属性：family_name
• 昵称属性：nickname
• 职位属性：title
• 语言属性：locale
• 图片属性：picture

通过 config.json 进行配置

用文件配置：

{
  "GitLabSettings": {
    "Enable": true,
    "Secret": "",
    "Id": "",
    "Scope": "",
    "AuthEndpoint": "",
    "TokenEndpoint": "",
    "UserApiEndpoint": "",
    "DiscoveryEndpoint": "https://votre-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://votre-smartlink.link.vaultys.org/api/oidc/[appid]/authorize",
    "TokenEndpoint": "https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/token",
    "UserApiEndpoint": "https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo",
    "DiscoveryEndpoint": "https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration",
    "ButtonText": "SmartLink SSO",
    "ButtonColor": "#0066CC"
  }
}

使用 SAML2 进行配置

在 SmartLink 中进行配置

1. 配置 SAML2

1. 在 Mattermost 应用程序中
2. 选项卡 身份验证 → SAML2
3. 配置：
   • 实体 ID：https://mattermost.example.com
   • ACS URL：https://mattermost.example.com/login/sso/saml
   • NameID 格式：emailAddress 或 persistent

2. 下载元数据

• IdP 元数据：https://votre-smartlink.link.vaultys.org/api/saml2/[appid]/metadata
• SSO URL：https://votre-smartlink.link.vaultys.org/api/saml2/[appid]/sso
• SLO URL：https://votre-smartlink.link.vaultys.org/api/saml2/[appid]/slo
• X.509 证书：从 SmartLink 下载

在 Mattermost 中进行配置

1. 通过系统控制台

1. 系统控制台 → 身份验证 → SAML 2.0
2. 启用 使用 SAML 2.0 登录

2. 配置 SAML 参数

• 身份提供商元数据 URL：https://votre-smartlink.link.vaultys.org/api/saml2/[appid]/metadata

或手动配置：

• SAML SSO URL：https://votre-smartlink.link.vaultys.org/api/saml2/[appid]/sso
• 身份提供商发行者 URL：https://votre-smartlink.link.vaultys.org
• 身份提供商公共证书：粘贴 X.509 证书

3. 配置服务提供商

• 服务提供商标识符：https://mattermost.example.com
• 验证签名：true
• 启用加密：false

4. SAML 属性映射

• 电子邮件属性：email
• 用户名属性：username
• ID 属性：uid
• 名字属性：firstName
• 姓氏属性：lastName
• 昵称属性：nickname
• 职位属性：title
• 语言属性：preferredLanguage
• 登录按钮文本：使用 SmartLink 登录

团队和频道同步

配置 SCIM 组

自动同步团队：

1. 系统控制台 → 团队
2. 启用 启用 AD/LDAP 组同步
3. 配置组映射：

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

自动团队映射

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

自动创建频道

基于组自动创建频道的脚本：

#!/bin/bash
# 为每个组创建频道

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

# 创建团队
mmctl team create --name development --display-name "Development"
mmctl team create --name marketing --display-name "Marketing"

# 创建频道
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 配置

使用 OpenID Connect 的 Docker Compose

version: '3.8'

services:
  mattermost:
    image: mattermost/mattermost-enterprise-edition:latest
    container_name: mattermost
    restart: unless-stopped
    environment:
      # 数据库
      - 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://votre-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
      - MM_OPENIDSETTINGS_BUTTONTEXT=SmartLink SSO
      - MM_OPENIDSETTINGS_BUTTONCOLOR=#0066CC
      
      # 站点 URL
      - MM_SERVICESETTINGS_SITEURL=https://mattermost.example.com
      
      # 文件存储
      - 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:

权限管理

系统角色

角色映射配置：

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

自定义权限模式

{
  "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"
      ]
    }
  }
}

配置测试

1. 连接测试

# 通过 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. 使用 mmctl 进行测试

# 安装 mmctl
brew install mmctl  # macOS
# 或
wget https://releases.mattermost.com/mmctl/v7.8.0/linux_amd64.tar

# 登录
mmctl auth login https://mattermost.example.com

# 验证
mmctl user list
mmctl team list
mmctl channel list development

3. Webhook 测试

# 创建传入 Webhook
WEBHOOK_URL=$(mmctl webhook create-incoming \
  --team development \
  --channel general \
  --display-name "SmartLink Integration")

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

故障排除

错误 "Invalid login credentials"

解决方案：

1. 检查 Mattermost 日志：

   docker logs mattermost 2>&1 | grep -i auth
2. 测试 OpenID 发现：

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

错误 "SAML login was unsuccessful"

解决方案：

1. 检查 X.509 证书
2. 使用 saml-tracer（浏览器扩展）进行测试
3. 检查日志：

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

团队未同步

解决方案：

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

错误 "User is not authorized"

解决方案：

1. 确保用户在 SmartLink 中分配了应用程序
2. 检查 Mattermost 中的权限：

   mmctl user search user@example.com
   mmctl permissions show-role system_user

安全性

推荐配置

{
  "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
  }
}

审计和合规性

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

高级集成

机器人和应用程序

# Mattermost 的 Python 机器人
from mattermostdriver import Driver

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

driver.login()

# 发送消息
driver.posts.create_post({
    'channel_id': 'channel-id',
    'message': 'Bonjour depuis SmartLink SSO!'
})

与 GitLab 集成

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

资源

• Mattermost SSO 文档
• Mattermost OpenID Connect
• Mattermost API
• mmctl CLI