本地部署的单点登录

本页面面向本地部署 MonoChat 的运维人员，介绍如何让员工通过 OpenID Connect（OIDC）使用公司的身份提供商（IdP）登录，例如 Microsoft Entra ID、Okta、Keycloak、AD FS 或 Google Workspace。

单点登录在服务器设置中为整个安装配置，而不是按组织配置。一个 MonoChat 账户可以属于多个组织，用户在选择组织之前登录。登录获得的是账户，而不是访问权限：只有在组织邀请并分配角色之后，用户才能看到该组织。

用户在登录页点击 SSO 按钮后，MonoChat 会在弹出窗口中打开您的 IdP 登录页。用户在那里登录后，IdP 会带着一次性代码将浏览器送回 MonoChat。MonoChat 服务器用该代码换取 ID 令牌，并在让用户登录之前对其进行校验：

每次登录时，都会从 IdP 的发现文档 <issuer>/.well-known/openid-configuration 读取其端点和签名密钥。
登录使用带 PKCE（S256）、state 和 nonce 的授权码流程。一个登录请求在 10 分钟内有效，且只能使用一次。
ID 令牌必须由 IdP 的某个密钥签名，并包含您的 issuer（iss）、您的客户端 ID（aud）、请求的 nonce，以及尚未过期的过期时间（exp）。
ID 令牌必须包含用户的电子邮件地址（email）。如果 IdP 表示该地址未经验证（email_verified: false），登录会被拒绝。

1. 在身份提供商中注册 MonoChat

在您的 IdP 中为 MonoChat 创建一个应用（客户端），使用以下值：

IdP 中的设置	值
应用类型	带客户端密钥的 Web 应用（机密客户端）
登录重定向 URI	`https://<your MonoChat domain>/api/oauth/oidc/redirect`
授权类型	授权码（Authorization code）
范围（Scopes）	`openid email profile`
令牌端点的客户端认证	通过 HTTP Basic 认证发送的客户端密钥（`client_secret_basic`）

确保 ID 令牌包含 email 声明。记下客户端 ID、客户端密钥和 issuer。issuer 是 IdP 发现文档中的 issuer 值。常见形式：

身份提供商	Issuer
Microsoft Entra ID	`https://login.microsoftonline.com/<tenant id>/v2.0`
Okta	`https://<your Okta domain>/oauth2/default`，或 `https://<your Okta domain>`
Keycloak	`https://<your Keycloak host>/realms/<realm>`
AD FS（2016 或更高版本）	`https://<your AD FS host>/adfs`
Google Workspace	`https://accounts.google.com`

在浏览器中打开 <issuer>/.well-known/openid-configuration，原样复制其中的 issuer 值，如果末尾有 / 也一并复制。两者不一致时，MonoChat 不会让任何人登录。

2. 添加设置

将 oidc 配置块添加到服务器设置中，然后重启 MonoChat。公开配置块放在 public.oauth 下，机密配置块放在 oauth 下：

{
  "oauth": {
    "oidc": {
      "clientSecret": "<client secret>",
      "autoCreateAccounts": true,
      "allowedEmailDomains": ["company.com"]
    }
  },
  "public": {
    "oauth": {
      "oidc": {
        "issuer": "https://login.microsoftonline.com/<tenant id>/v2.0",
        "clientId": "<client id>",
        "redirectPath": "/api/oauth/oidc/redirect",
        "scope": "openid email profile",
        "buttonLabel": "Sign in with Company SSO"
      }
    }
  }
}

设置	作用
`public.oauth.oidc.issuer`	第 1 步中的 issuer
`public.oauth.oidc.clientId`	第 1 步中的客户端 ID
`public.oauth.oidc.redirectPath`	第 1 步中重定向 URI 的路径
`public.oauth.oidc.scope`	MonoChat 请求的范围
`public.oauth.oidc.buttonLabel`	登录按钮的文字。留空时以用户的语言显示“使用 SSO 登录”
`oauth.oidc.clientSecret`	客户端密钥。仅保存在服务器上
`oauth.oidc.autoCreateAccounts`	设为 `true` 时，即使注册仅限邀请（`public.disableSignup`），也会在用户首次 SSO 登录时创建 MonoChat 账户
`oauth.oidc.allowedEmailDomains`	只有电子邮件地址属于这些域的用户才能通过 SSO 登录。省略则允许所有域

之后，登录页上就会出现 SSO 按钮。

新用户。 设置 autoCreateAccounts: true 后，用户首次 SSO 登录会创建其账户。未设置时，只有在 public.disableSignup 关闭或用户通过邀请登录时才会创建账户。
已有相同电子邮件地址账户的用户。 设置 oauth.autoMerge: true 后，首次 SSO 登录会将 SSO 关联到现有账户，但仅限 ID 令牌表明该地址已验证（email_verified: true）的情况。不满足该条件或未设置 autoMerge 时，MonoChat 会要求用户先用密码登录一次，并在那时将 SSO 关联到账户。接受组织的邀请也会完成关联。Microsoft Entra ID 和 AD FS 不发送 email_verified，因此使用它们时，请在所有人都关联 SSO 之前继续允许密码登录，或重新邀请这些用户。
允许的域。 设置 allowedEmailDomains 后，其他域的地址会被拒绝。对于 Google Workspace（issuer https://accounts.google.com），由于个人 Google 账户可以使用任何域的地址，MonoChat 检查的是 hd 声明（账户所属的 Workspace 域），而不是电子邮件地址。

将 public.auth.methods 设为 ["oidc"]。登录页随后只显示 SSO 按钮，服务器会拒绝密码登录和社交账户登录。
root super 用户（在根组织中拥有 root super 角色的用户）仍可在 /auth/signin?fallback=1 使用密码登录，因此即使 IdP 宕机，安装也不会被锁死。
如需阻止新的 SSO 账户创建自己的组织，请将 public.disableTenantCreation 设为 true。之后只有在某个组织中拥有相应角色的人才能在其下创建组织。

网络

确保登录的用户能够访问 /api/oauth/oidc/authorize 和您的 redirectPath。两者都会在用户的浏览器中打开。
MonoChat 服务器必须能通过 HTTPS 访问 IdP 的发现文档、令牌端点和密钥集（jwks_uri）。

限制

MonoChat 移动应用尚不支持 SSO。如果将 SSO 设为唯一的登录方式，客服人员将无法登录移动应用。
退出 MonoChat 不会让用户退出 IdP，而退出 IdP 目前也不会让用户退出 MonoChat。

检查配置

打开登录页并点击 SSO 按钮。在 IdP 中登录后，弹出窗口会关闭，您即已登录 MonoChat。
用一个还没有 MonoChat 账户的用户登录，确认账户已创建（如果未开启 autoCreateAccounts，则确认被拒绝）。
如果设置了 allowedEmailDomains，请用其他域的用户尝试，确认登录被拒绝。
如果设置了 public.auth.methods，请确认密码登录被拒绝，并且 root super 用户仍可在 /auth/signin?fallback=1 登录。

登录的工作方式​

1. 在身份提供商中注册 MonoChat​

2. 添加设置​

谁可以登录​

将 SSO 设为唯一的登录方式​

网络​

限制​

检查配置​

登录的工作方式

1. 在身份提供商中注册 MonoChat

2. 添加设置

谁可以登录

将 SSO 设为唯一的登录方式

网络

限制

检查配置