#OIDC 管理

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

初始集成若要尽可能简短，请使用 Form 选项卡。 当返回的用户名 Claim 必须显式选择、Claim 必须重映射、必须查询 UserInfo，或者需要 OIDC 组和额外字段时，请使用 YAML 选项卡。参见 使用 YAML 添加 OIDC。

#开始之前

准备以下值：

• Issuer URL，在 ACP 中标记为 Server Provider URL。
• Client ID。
• Client Secret，在 ACP 中标记为 Client Key。
• 一个具有电子邮件地址的代表性测试账户，该地址尚未被 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 可用性、映射、冲突行为和组限制的权威检查。

#使用 Form 添加 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、组处理或额外 Claims。只有在确认上游响应后，才通过 YAML 配置这些字段。

#验证集成

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

Connector 创建、上游身份验证、ACP 用户创建以及 ACP 授权是彼此独立的检查点。请分别验证每个检查点。

#使用 YAML 添加 OIDC

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

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 名称以及允许的组。如果提供方未暴露 UserInfo endpoint，或者所有必需的 Claims 都已包含在 ID token 中，请将 getUserInfo 设为 false。如果不需要组处理，请移除 insecureEnableGroups、allowedGroups 和 claimMapping.groups。

不要在 scopes 中添加 openid；Connector 会自动将其添加到 authorization request 中。如果上游提供方需要一个特定于该提供方的 scope 来获取组 Claims，请仅在 discovery 和提供方配置确认后再添加该 scope。

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

#OIDC 字段完整参考

顶层和 metadata 字段：

连接和登录字段：

Claim 和组字段：

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

#登录、更新和删除行为

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

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

#注销行为

在已验证的当前流程中，ACP 注销会结束 ACP 会话，并将浏览器返回到 ACP IDP 选择器。再次选择同一个 OIDC 条目会复用仍然有效的上游会话，并在不再次提示凭证的情况下完成登录。因此，ACP 注销并不能证明上游会话已经结束。

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

#按阶段排查

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

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