单点登录配置

单点登录（SSO）允许用户在企业身份提供方（IdP）完成认证后返回 CAN，无需再次输入 CAN 账号和密码。CAN 使用 ssoCode 识别一套 SSO 配置，并根据该配置完成回调参数读取、令牌或票据校验、用户信息获取及登录会话创建。

适用范围：本文说明部署级 SSO 配置。它不同于 管理设置 → 系统集成 → 免登设置：免登使用 URL 白名单和加密凭证；SSO 使用企业身份提供方的认证回调。两者可同时存在，互不替代。

配置前准备

请由 CAN 实施人员、运维人员和企业身份管理员共同完成以下准备：

在身份提供方创建应用，获取授权地址、客户端凭证、令牌地址、用户信息地址或 CAS 服务地址等所需信息。
约定 CAN 用户账号与身份提供方的唯一标识映射。CAN 登录最终需要得到 account；若允许自动创建用户，还可提供 nickName、email、phone 等字段。
规划唯一、稳定的 ssoCode，例如 company_sso。回调地址、登录入口配置和 CAN 的 SSO 配置必须使用同一个值。
准备测试账号、测试租户和可回退的账号密码登录方式。首次上线不要直接把 SSO 设为唯一入口。

权限说明：当前前端登录认证页面会展示已启用的 SSO 登录项，但不提供 SSO 协议配置的新增或编辑界面。实施人员需要通过部署配置与数据库配置完成变更，并按企业变更流程留存审批、配置备份和回滚方案。

配置表与职责

一套可用的 SSO 至少需要两类配置；前者负责“如何认证”，后者负责“是否在登录页展示”。

配置表	关键字段	职责
`am_auth2_sso_login_config`	`name`、`sso_code`、`config`	保存每套 SSO 协议配置。`sso_code` 是唯一标识；`config` 保存协议、令牌和用户信息接口等 JSON 内容。
`am_login_authentication_config`	`name`、`code`、`type`、`config`、`status`	保存登录页认证方式。SSO 行的 `type` 为 `AUTH2_SSO_LOGIN`，`status` 设为 `OPEN` 后才会在登录页展示；默认方式的版本限制见下文。

两张表中的字段不要混用：am_login_authentication_config.code 是认证方式记录自身的唯一标识；其 config 数组中每一项的 code 才应填写对应的 sso_code。登录入口的 ssoUrl 也必须指向同一个 sso_code 的回调地址。

配置模型与登录链路

每套 SSO 配置包含显示名称、唯一的 ssoCode 和协议配置。CAN 从 am_auth2_sso_login_config 中按 ssoCode 查询协议配置；登录页通过 am_login_authentication_config 决定是否展示该 SSO 入口及其 displayName、ssoUrl。

典型登录链路如下：

用户在 CAN 登录页选择已启用的 SSO 登录方式；浏览器跳转到该方式配置的 ssoUrl。
用户在身份提供方完成认证；身份提供方回调 CAN。
回调地址应包含 ssoCode，标准示例为：

https://can.example.com/user/ssoLogin?ssoCode=company_sso

对于 OAuth 2.0、OIDC 和 CAS，身份提供方还会附加授权码或 ticket。CAN 使用配置中的 codeKey 读取该参数

CAN 按协议换取或校验令牌，获取用户信息，并以 account 查找已有 CAN 用户。
找到用户后，CAN 建立登录会话并跳转回原访问页面；未找到用户时，只有 registerUser 开启才会尝试自动创建用户。

回调地址与登录入口

回调地址

在身份提供方应用中登记 CAN 回调地址。地址必须与实际部署域名、路径、ssoCode 完全一致：

https://<CAN 域名>/user/ssoLogin?ssoCode=<ssoCode>

若身份提供方要求预先登记精确地址，不要遗漏 ssoCode。身份提供方回调时也应保留其返回的授权码、ticket 和 state 参数；不要用自定义跳转页面丢弃这些查询参数。

当部署启用回调 IP 校验时，CAN 会在跳转至身份提供方时附加 state，并在回调时校验来源 IP。此场景下，身份提供方必须原样回传 state；若企业网关、代理或身份提供方改变了用户出口 IP，应先在测试环境验证，避免合法登录被拦截。

登录入口与默认跳转

在 am_login_authentication_config 中新增或维护 SSO 登录认证项时，使用 type = AUTH2_SSO_LOGIN，status = OPEN，并在 config 中配置一个或多个入口。配置项的字段如下：

字段	用途
`code`	与 SSO 配置表的 `sso_code` 对应，用于关联登录项和回调。
`displayName`	登录页显示的名称，例如“使用企业统一身份登录”。
`ssoUrl`	用户单击登录项后跳转的身份提供方授权地址。
`status`	位于登录认证表记录中，控制该认证方式是否启用。

以下是登录认证表 config 字段的示例。redirect_uri 的值应进行 URL 编码，示例中的域名、客户端标识和 ssoCode 均须替换为实际值。

[
  {
    "code": "company_sso",
    "displayName": "企业统一身份登录",
    "ssoUrl": "https://idp.example.com/oauth2/authorize?client_id=<客户端标识>&response_type=code&redirect_uri=https%3A%2F%2Fcan.example.com%2Fuser%2FssoLogin%3FssoCode%3Dcompany_sso"
  }
]

标准 OAuth 2.0 配置示例

以下示例适用于 AUTH2 授权码流程，可作为 am_auth2_sso_login_config.config 的起点。示例中的地址、客户端凭证、字段路径和成功码均为占位值，必须按身份提供方的接口文档替换。

{
  "protocol": "AUTH2",
  "codeKey": "code",
  "registerUser": true,
  "token": {
    "requestConfig": {
      "url": "https://idp.example.com/oauth/token",
      "method": "POST",
      "header": {
        "Content-Type": "application/x-www-form-urlencoded"
      },
      "params": {
        "grant_type": "authorization_code",
        "client_id": "<客户端标识>",
        "client_secret": "<客户端密钥>"
      }
    },
    "ssoResultConfig": {
      "codePath": "code",
      "codeSuccessValue": "200",
      "valueMapping": {
        "access_token": "data.access_token",
        "refresh_token": "data.refresh_token",
        "expires_in": "data.expires_in"
      }
    }
  },
  "userInfo": {
    "requestConfig": {
      "url": "https://idp.example.com/api/userinfo",
      "method": "GET",
      "header": {
        "Authorization": "Bearer %s"
      },
      "headerMapping": {
        "Authorization": "access_token"
      },
      "params": {},
      "paramsMapping": {
        "token": "access_token"
      }
    },
    "ssoResultConfig": {
      "codePath": "code",
      "codeSuccessValue": "200",
      "valueMapping": {
        "account": "data.userName",
        "nickName": "data.nickName",
        "email": "data.email",
        "phone": "data.phone"
      }
    }
  }
}

CAN 会在 token 请求中自动补充由 codeKey 指定的授权码参数；用户信息请求则会根据 paramsMapping 和 headerMapping 把获取到的 access token 写入参数或请求头。header 在当前代码中是键值对象，不能按旧示例写成数组。

注意：将 codePath 留空可跳过成功码校验；只有在身份提供方不返回统一状态字段且已完成联调时才建议这样做。生产客户端密钥必须通过受控配置管理，不要将真实值提交到数据库脚本、Git 仓库、截图或工单正文。

默认登录方式与强制跳转

“默认登录方式”和“未登录时强制跳转到 SSO”是两项不同的配置：

默认登录方式：管理员可在 管理设置 → 用户角色 → 登录认证 的“默认登录方式”中选择已启用的认证项。该设置决定登录页初始显示的认证方式，建议先在测试环境验证后再调整。
强制跳转 SSO：在 Nacos 或等效的部署配置中设置唯一的默认 SSO：

sso.login.config.code: company_sso

该值必须与 am_auth2_sso_login_config.sso_code 一致，并且对应 SSO 配置必须设置 redirectUri。CAN 检测到未登录访问时，会读取此配置并跳转到该 SSO 的 redirectUri。

多 SSO 注意：多个 SSO 配置可以同时出现在登录页，但强制跳转只能指定一个 sso.login.config.code。不要为多套配置同时设置默认跳转意图，否则会造成入口竞争或重定向循环。

通用配置字段

SSO 协议配置以 JSON 形式保存于 am_auth2_sso_login_config.config。以下为各协议共用或常用的字段；并非每个协议都需要全部字段。

字段	说明
`protocol`	协议类型，使用大写枚举值，例如 `AUTH2`、`OIDC`、`CAS`。
`ssoCode`	配置表中的唯一标识 `sso_code`（不是 JSON 必填字段）；应与回调 URL、登录认证项 `config[].code` 一致。
`name`	配置名称，用于实施和运维识别。
`codeKey`	身份提供方回调中授权码或 ticket 的参数名，例如 `code` 或 `ticket`。
`tokenKey`	WPS 等由请求 Cookie 或 Header 传递令牌的协议所使用的令牌名称。
`redirectUri`	未登录访问需要直接跳转 SSO 时使用的身份提供方授权地址；与登录页入口的 `ssoUrl` 分别配置。
`retryUrl`	回调未携带授权码时可跳转的重试地址；仅在确有兼容需求时配置。
`stateKey`	身份提供方使用非标准状态参数名时的兼容字段；通常使用默认 `state`。
`logoutUrl`	CAN 退出后需要跳转的企业统一退出地址。
`registerUser`	是否允许首次 SSO 登录时自动创建 CAN 用户。
`registerTenantId`	自动创建用户后加入的租户 ID；未配置时不会自动加入指定租户。

token、userInfo（以及部分协议的 refreshToken、logoutRequest）使用同一类 HTTP 配置，主要包括：

配置项	说明
`requestConfig.url` / `method`	令牌、用户信息或退出回调的请求地址及 HTTP 方法。
`header` / `params`	固定请求头与固定参数。客户端密钥、refresh token 等敏感值应使用受控密钥管理，不要写入帮助文档、截图或前端代码。
`headerMapping` / `paramsMapping`	将上一步取得的动态值映射到请求头或参数，例如把 access token 写入 `Authorization`。
`ssoResultConfig.codePath` / `codeSuccessValue`	响应成功标识的解析位置和值。
`ssoResultConfig.valueMapping`	将身份提供方响应字段映射为 CAN 所需字段；用户信息映射必须能得到 `account`。

建议先在非生产环境使用脱敏参数完成一次令牌请求和用户信息请求的联调，再写入正式配置。不要把生产客户端密钥、refresh token 或 Cookie 值提交到 Git 仓库。

用户匹配与自动创建

CAN 先使用返回用户信息中的 account 查询用户。为避免错误授权，身份提供方应返回稳定且唯一的企业账号，不建议使用可变的显示名称或邮箱别名作为唯一账号。

若启用 registerUser：

返回信息至少应包含 account；nickName、email、phone 可用于补充用户资料。
配置 registerTenantId 时，CAN 会把新用户加入该租户，并赋予基础使用者角色。
未配置 registerTenantId 时，新用户不会自动加入指定租户；请在上线前明确用户开通和权限授予流程。

若不启用自动创建，身份提供方账号必须预先在 CAN 中存在，并具备目标租户的访问权限。

验证与上线检查

按以下顺序验证：

在身份提供方检查回调地址白名单、客户端凭证、授权范围和测试账号。
在 CAN 配置中核对 ssoCode、协议、codeKey、授权地址和用户字段映射。
从 CAN 登录页单击 SSO 入口，完成身份提供方登录，并确认能够返回原访问页面。
验证已存在用户、首次用户（分别覆盖允许和禁止自动创建两种策略）以及不同租户用户。
验证取消授权、授权码过期、退出登录和账号密码回退路径。
将客户端密钥、令牌和完整回调参数从浏览器记录、网关日志、截图和工单正文中排除或脱敏。

常见问题

提示找不到 SSO 配置

错误 AM_06_0024 表示 CAN 未按 ssoCode 找到有效配置。检查回调 URL 中的 ssoCode 是否与配置记录完全一致，并确认配置已写入当前环境实际连接的数据库且未被逻辑删除。

回调后缺少授权码或 ticket

核对身份提供方返回的参数名与 codeKey 是否一致；OAuth/OIDC 通常为 code，CAS 通常为 ticket。如配置了 retryUrl，还应确认该地址会重新发起授权，而不是形成重定向循环。

已完成认证但 CAN 无法登录

先检查 token 和 userInfo 请求是否成功，再检查 valueMapping 是否能解析出 account。若用户不存在，确认是否开启 registerUser；若已存在但不能访问目标内容，还需检查其租户归属与角色权限。

退出 CAN 后没有退出企业认证中心

配置 logoutUrl 可让 CAN 退出后跳转到统一退出地址；部分 OAuth 2.0 场景还需要配置 logoutRequest 调用身份提供方的注销接口。请按身份提供方的登出规范联调，并避免把登出地址配置为普通登录入口。

设为默认登录后无法进入系统

先停用默认 SSO 跳转或清除 redirectUri，使用保留的账号密码运维账号恢复访问。生产环境启用默认跳转前，应至少完成正常登录、身份提供方不可用、回调参数缺失和退出登录四类回归测试。