#OIDC 管理

ACP 可以将用户重定向到符合标准的 OIDC Identity Provider，并在成功登录后创建或更新其平台身份。

使用 Form 选项卡可以实现最快的初始集成。当前端返回的 username Claim 必须显式选择、Claim 必须重映射、必须查询 UserInfo，或者需要 OIDC groups 和额外字段时，请使用 YAML 选项卡。请参见 通过 YAML 添加 OIDC。

#开始之前

请准备以下值：

• Issuer URL，在 ACP 中标记为 Server Provider URL。
• Client ID。
• Client Secret，在 ACP 中标记为 Client Key。
• 一个具有代表性的测试账号，其 email 地址尚未被 ACP 本地用户或其他 IDP 使用。
• 一个为该测试账号返回的稳定 username Claim。已验证的 YAML 回退使用 preferred_username。

向上游 Identity Provider 注册以下精确回调：

https://<ACP_ADDRESS>/dex/callback

ACP 会根据平台地址派生回调地址。表单中不包含 Redirect URI 字段。

Server Provider URL 必须是 Issuer 根地址，而不是 authorization endpoint、token endpoint 或登录页。其 discovery document 通常位于以下路径：

<ISSUER_URL>/.well-known/openid-configuration

你可以从一个具有与 ACP 相当可达性的诊断主机检查 discovery：

curl -fsS 'https://idp.example.com/.well-known/openid-configuration'

对于使用私有 CA 的上游服务，请使用该 CA 独立验证证书链：

curl -fsS --cacert /path/to/oidc-ca.pem \
  'https://idp.example.com/.well-known/openid-configuration'

此外部查询只是初步证据。ACP Connector 创建才是集群侧的 discovery 和可达性检查。

#确认返回的 Claims

请要求上游 Identity 管理员提供某个具有代表性的账号的 ID token 或 UserInfo Claim 名称。Claim 名称区分大小写。ACP Connector 创建会验证 discovery 和客户端可达性，但不能证明真实用户的 token 包含所需的 Claims。

在正式发布前完成一次真实的浏览器登录，并检查生成的 ACP 用户。该登录是验证 Claim 可用性、映射、冲突行为以及 group 限制的权威检查。

#使用表单添加 OIDC

1. 转到 Users > IDP。
2. 单击 Add OIDC。
3. 填写 Basic Info：Name、Display Name 和可选的 Description。
4. 填写 Server Setting：Server Provider URL、Client ID 和 Client Key。
5. 对于此集成流程，将 Logout URL 留空。
6. 单击 Add。

在创建过程中，ACP 会从 Issuer URL 读取 OIDC discovery。无效或不可达的 Issuer 会在此阶段被拒绝。当前的创建检查不能证明 Client Key 正确，或上游 TLS 证书受信任：即使 key 不正确，Connector 也可能被创建，随后在浏览器回调期间失败；而未受信任的自签名证书也可能被接受。因此，认证仍需要一次真实登录，证书合规性必须按上文所述单独评估。

创建完成后，ACP 会将提交的 Client Key 迁移到受管 Secret。存储的 Connector 引用该 Secret，而不是在其配置中保留 clientSecret。

#控制台字段参考

表单不暴露 redirectURI、scopes、UserInfo、Claim mappings、group 处理或额外 Claims。请仅在确认上游响应后，通过 YAML 配置这些字段。

#验证集成

1. 启动一个独立的浏览器会话，确保没有 ACP 登录状态。
2. 打开 ACP，并选择已配置的 OIDC Display Name。
3. 在上游 Identity Provider 完成认证。
4. 确认浏览器返回到 ACP，而不是 HTTP 500 错误。
5. 在 Users 中找到生成的用户，并验证其 IDP source、email、username 和 active 状态。
6. 如果由于上游响应不包含默认 name Claim 而导致 username 为空，请使用下方 YAML 示例重新创建或更新 Connector，然后再次登录。
7. 使用 管理用户角色 分配一个最小角色。
8. 再次登录，并确认已分配的 ACP permission 可用。

Connector 创建、上游认证、ACP 用户创建和 ACP 授权是相互独立的检查点。请分别验证每个检查点。

#通过 YAML 添加 OIDC

当上游响应需要显式选择 Claim 或进行高级映射时，请使用 Users > IDP > Add OIDC > YAML。下面的完整示例假定上游响应包含 sub、preferred_username、email、email_verified、groups 和 phone_number，并且测试用户属于 acp-users。请移除真实上游响应不满足的可选映射和 group 限制。

apiVersion: dex.coreos.com/v1
kind: Connector
id: corporate-oidc
name: Corporate OIDC
type: oidc
metadata:
  name: corporate-oidc
  namespace: cpaas-system
  annotations:
    cpaas.io/description: Corporate OIDC
    # cpaas.io/idp.validation: "false"
  labels:
    cpaas.io/idp.version: v2
spec:
  config:
    issuer: https://idp.example.com
    clientID: <CLIENT_ID>
    clientSecret: <CLIENT_SECRET>
    redirectURI: https://acp.example.com/dex/callback
    scopes:
      - profile
      - email
    getUserInfo: true
    userNameKey: preferred_username
    overrideClaimMapping: true
    claimMapping:
      preferred_username: preferred_username
      email: email
      groups: groups
      phone: phone_number
      mail: email
    claimExtra:
      - field: preferred_username
        type: string
    insecureEnableGroups: true
    allowedGroups:
      - acp-users

提交之前，请替换 Issuer、凭证、ACP 地址、Claim 名称和允许的 group。如果 provider 不提供 UserInfo endpoint，或者所有必需的 Claims 都已经在 ID token 中，则将 getUserInfo: false。如果不需要 group 处理，请移除 insecureEnableGroups、allowedGroups 和 claimMapping.groups。

不要在 scopes 中添加 openid；Connector 会自动将其加入 authorization request。如果上游 provider 要求使用特定于 provider 的 scope 来获取 group Claims，请仅在 discovery 和 provider 配置中确认后再添加该 scope。

请通过 ACP 控制台的 YAML 选项卡提交此初始配置。ACP 会将 clientSecret 迁移到受管 Secret，并且存储的 Connector 会改为包含 clientSecretRef。不要使用带内联 clientSecret 的 kubectl apply：Kubernetes 的 last-applied annotation 可能会在 Connector metadata 中保留所提交的 secret。

#OIDC 字段完整参考

顶层和 metadata 字段：

连接和登录字段：

Claim 和 group 字段：

如果 email 出现在 scopes 中，则所选 email Claim 必须是字符串，并且合并后的响应中 email_verified 必须是 Boolean。任一值缺失都会导致登录失败。

#登录、更新和删除行为

• OIDC 用户会在浏览器成功登录后被创建或更新。OIDC 不提供类似 LDAP 的手动或计划性用户同步。
• 更新 username 映射后，请启动新的浏览器会话并重新登录，以验证更新后的用户。
• 通过 ACP 删除 Connector 而不进行清理时，会保留源用户并将其标记为无效。
• 选择 Clean up IDP users and User Groups 会删除生成的源用户以及该 Connector 的受管 Secret。

请使用 ACP 控制台操作或 ACP 产品 API 执行删除。直接使用 kubectl 删除底层 Connector custom resource 会绕过 ACP 的用户失效和清理行为。

#退出登录行为

在此版本中，ACP logout 会结束 ACP 会话，并将浏览器返回到 ACP IDP 选择器。再次选择同一个 OIDC 条目时，可能会复用仍处于活动状态的上游会话，并在无需再次输入凭证的情况下完成登录。因此，ACP logout 不能证明上游会话已结束。

此流程不会将配置的 Logout URL 用作浏览器重定向。请将该字段留空，并在客户安全要求需要时单独验证上游会话终止。

#按阶段排查问题

如需查看回调和用户映射证据，请检查当前 ACP 登录组件日志：

kubectl -n cpaas-system logs deployment/apollo --since=10m