IdP / SSO 错误码（105*）

段位：105001 - 105015 + 105024 - 105029；共 21 个；全部 V1 暴露

其中 105024 - 105029 为上游凭证换取 User Token（POST /v1/auth/ssoExchange，OAuth2 上游）链路的错误码；端到端流程见上游身份接入与 User Token 桥接。

通用约定（HTTP status / code=1 兜底 / 响应结构）见 README

105001 IDP_NOT_FOUND

• HTTP status：200
• 含义：IdP 不存在
• 典型触发条件：请求指定的 IdP（identity provider）providerId 在本租户内未配置
• 处理建议：核对 providerId；IdP 需先在 Console「身份提供商」面板配置
• 示例响应：

{ "code": 105001, "msg": "IdP 不存在", "data": null }

105002 IDP_DISABLED

• HTTP status：200
• 含义：IdP 已禁用
• 典型触发条件：目标 IdP 在 Console 已被管理员禁用
• 处理建议：联系管理员启用，或切换到其它已启用的 IdP
• 示例响应：

{ "code": 105002, "msg": "IdP 已禁用", "data": null }

105003 SSO_TOKEN_INVALID

• HTTP status：200
• 含义：SSO Token 无效（签名失败 / 过期）
• 典型触发条件：SSO 回调或 token 验证时，token 签名验证失败或已过期
• 处理建议：让用户重新走 SSO 登录流程获取新 token；若反复失败，核对 IdP 时钟同步与签名密钥配置
• 示例响应：

{ "code": 105003, "msg": "SSO Token 无效", "data": null }

105004 SSO_TOKEN_ISSUER_MISMATCH

• HTTP status：200
• 含义：SSO Token Issuer 不匹配
• 典型触发条件：SSO token 的 iss claim 与 IdP 配置中的 issuerUrl 不一致
• 处理建议：核对 IdP 配置的 issuerUrl；若 IdP 侧 issuer 变更（如域名迁移），同步更新 atkonbase 内的 IdP 配置
• 示例响应：

{ "code": 105004, "msg": "SSO Token Issuer 不匹配", "data": null }

105005 SSO_TOKEN_TYPE_UNSUPPORTED

• HTTP status：200
• 含义：SSO Token 类型不支持
• 典型触发条件：传入的 token 不是 atkonbase 支持的 SSO token 类型（如非 OIDC id_token、非 CAS service ticket）
• 处理建议：核对 IdP 协议；同一 IdP 不可混用不同协议的 token
• 示例响应：

{ "code": 105005, "msg": "SSO Token 类型不支持", "data": null }

105006 USER_NOT_SYNCED

• HTTP status：200
• 含义：用户未同步（SSO 验证通过但找不到对应业务用户）
• 典型触发条件：SSO token 验证通过，但 token 中的用户标识在 atkonbase 内无对应业务用户记录（首次登录前未完成建档，或同步链路异常）
• 处理建议：若 IdP 启用了首次登录自动建档，应能自动建立映射；否则需要管理员主动同步用户；常见根因是 IdP claim 字段映射配置错误
• 示例响应：

{ "code": 105006, "msg": "用户未同步", "data": null }

105007 IDP_ALREADY_EXISTS

• HTTP status：200
• 含义：IdP providerId 已存在
• 典型触发条件：创建 IdP 时使用了已被占用的 providerId
• 处理建议：换用唯一的 providerId；providerId 在租户内唯一
• 示例响应：

{ "code": 105007, "msg": "IdP providerId 已存在", "data": null }

105008 IDP_OIDC_ISSUER_REQUIRED

• HTTP status：200
• 含义：OIDC 协议下 issuerUrl 必填
• 典型触发条件：创建 / 更新 OIDC 类型的 IdP 但未提供 issuerUrl
• 处理建议：补齐 issuerUrl；OIDC 端点发现依赖 issuerUrl
• 示例响应：

{ "code": 105008, "msg": "OIDC 协议下 issuerUrl 必填", "data": null }

105009 IDP_INVALID_PRINCIPAL_SOURCE_TYPE

• HTTP status：200
• 含义：无效的 principalSourceType
• 典型触发条件：IdP 配置的 principalSourceType 不在允许枚举内（principalSourceType 决定通过该 IdP 进来的用户归到哪个 source 域）
• 处理建议：核对取值；同一 IdP 的 principalSourceType 应与租户内其它 IdP 协调，避免来源冲突
• 示例响应：

{ "code": 105009, "msg": "无效的 principalSourceType", "data": null }

105010 IDP_CONNECTIVITY_FAILED

• HTTP status：200
• 含义：IdP 连通性测试失败
• 典型触发条件：调用 IdP 连通性测试端点，但 atkonbase 无法连接到 IdP（DNS / 防火墙 / 证书 / IdP 自身故障）
• 处理建议：检查网络可达性、TLS 证书有效性、IdP 端点 URL 拼写
• 示例响应：

{ "code": 105010, "msg": "IdP 连通性测试失败", "data": null }

105011 IDP_JWKS_URL_NOT_CONFIGURED

• HTTP status：200
• 含义：JWKS URL 未配置
• 典型触发条件：OIDC IdP 需要 JWKS（JSON Web Key Set）端点用于签名验证，但当前 IdP 配置未指定
• 处理建议：在 IdP 配置中补齐 JWKS URL；多数 OIDC IdP 通过 .well-known/openid-configuration 暴露
• 示例响应：

{ "code": 105011, "msg": "JWKS URL 未配置", "data": null }

105012 IDP_JWKS_RESPONSE_INVALID

• HTTP status：200
• 含义：JWKS 端点响应格式异常
• 典型触发条件：JWKS URL 可达，但返回内容不符合 JWKS 规范
• 处理建议：直接访问 JWKS URL 检查返回结构；常见根因是 IdP 配置错把别的 JSON 接口路径填到 JWKS URL 字段
• 示例响应：

{ "code": 105012, "msg": "JWKS 端点响应格式异常", "data": null }

105013 IDP_CAS_URL_NOT_CONFIGURED

• HTTP status：200
• 含义：CAS Server URL 未配置
• 典型触发条件：CAS 类型 IdP 缺少 CAS Server URL 配置
• 处理建议：在 IdP 配置中补齐 CAS Server URL
• 示例响应：

{ "code": 105013, "msg": "CAS Server URL 未配置", "data": null }

105014 SSO_ONBOARD_FAILED

• HTTP status：200
• 含义：SSO 回调首次登录建档写入失败
• 典型触发条件：SSO 验证通过但写入新用户记录到 atkonbase 时失败（写入异常 / 数据冲突）
• 处理建议：检查响应 msg 字段获取具体原因；常见是用户名冲突或 IdP 返回的必填字段缺失
• 示例响应：

{ "code": 105014, "msg": "SSO 回调建档写入失败", "data": null }

105015 SSO_STATE_INVALID

• HTTP status：200
• 含义：SSO 回调 state / service 参数非法或已过期（CSRF 校验失败）
• 典型触发条件：SSO 回调中携带的 state 参数无法验证——通常是 CSRF 攻击防御机制触发，或用户在登录页停留过久导致 state 过期
• 处理建议：让用户重新发起 SSO 登录流程（重新获取 state）；不要尝试绕过本校验
• 示例响应：

{ "code": 105015, "msg": "SSO 回调 state 非法或已过期", "data": null }

105024 IDP_OAUTH2_TOKEN_ENDPOINT_NOT_CONFIGURED

• HTTP status：200
• 含义：OAuth2 上游 tokenEndpoint 未配置
• 典型触发条件：调 /v1/auth/ssoExchange 以 source=oauth2 换取 User Token 时，目标租户的 OAuth2 IdP 缺少 token 端点配置
• 处理建议：联系管理员在 Console 为该租户的 OAuth2 IdP 补齐 tokenEndpoint（授权码换 access_token 的端点）
• 示例响应：

{ "code": 105024, "msg": "OAuth2 tokenEndpoint 未配置", "data": null }

105025 SSO_OAUTH2_TOKEN_EXCHANGE_FAILED

• HTTP status：200
• 含义：OAuth2 Token 交换失败（token 端点调用异常 / 网络错误）
• 典型触发条件：atkonbase 以授权码调上游 token 端点换 access_token 时，端点不可达 / 超时 / 返回非预期内容
• 处理建议：核对 IdP token 端点的网络可达性与 URL 配置；偶发网络抖动可重试；持续失败时核对上游 IdP 运行状态
• 示例响应：

{ "code": 105025, "msg": "OAuth2 Token 交换失败", "data": null }

105026 SSO_OAUTH2_ACCESS_TOKEN_MISSING

• HTTP status：200
• 含义：OAuth2 Token 端点未返回 access_token
• 典型触发条件：上游 token 端点正常响应但响应体里没有 access_token——多因授权码已过期 / 被复用，或 clientId / clientSecret / redirectUri 与上游应用配置不一致导致上游返回 error
• 处理建议：核对授权码是否一次性且未过期、clientId / clientSecret / redirectUri 与上游应用登记一致；让终端用户重新发起上游登录取新授权码
• 示例响应：

{ "code": 105026, "msg": "OAuth2 Token 端点未返回 access_token", "data": null }

105027 IDP_OAUTH2_USERINFO_ENDPOINT_NOT_CONFIGURED

• HTTP status：200
• 含义：OAuth2 上游 userinfoEndpoint 未配置
• 典型触发条件：换取 User Token 时，目标租户的 OAuth2 IdP 缺少 userinfo 端点配置（纯 OAuth2 须调 userinfo 取身份）
• 处理建议：联系管理员在 Console 为该租户的 OAuth2 IdP 补齐 userinfoEndpoint
• 示例响应：

{ "code": 105027, "msg": "OAuth2 userinfoEndpoint 未配置", "data": null }

105028 SSO_OAUTH2_USERINFO_FAILED

• HTTP status：200
• 含义：OAuth2 userinfo 端点调用失败（响应异常 / 网络错误 / 非 JSON）
• 典型触发条件：atkonbase 持 access_token 调上游 userinfo 端点取用户资料时失败——端点不可达 / 超时 / 返回非 JSON
• 处理建议：核对 userinfo 端点的网络可达性与 URL 配置；偶发网络抖动可重试
• 示例响应：

{ "code": 105028, "msg": "OAuth2 userinfo 端点调用失败", "data": null }

105029 SSO_OAUTH2_SUBJECT_MISSING

• HTTP status：200
• 含义：OAuth2 userinfo 响应未返回可用主体标识（subjectField 映射为空）
• 典型触发条件：userinfo 响应正常，但按 IdP 配置的 subjectField 字段映射取不到稳定主体标识（字段名配错，或上游该字段为空）
• 处理建议：核对 IdP 的 subjectField 字段映射配置与 userinfo 实际返回字段一致；subjectField 应指向上游侧稳定不变的主体键
• 示例响应：

{ "code": 105029, "msg": "OAuth2 userinfo 未返回可用主体标识", "data": null }