OIDC 管理

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

对于最短的初始集成，请使用 Form 选项卡。当必须显式选择返回的 username Claim、必须重新映射 Claims、必须查询 UserInfo，或者需要 OIDC groups 和额外字段时，请使用 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 Provider 管理员提供一个代表性账号的 ID token 或 UserInfo Claim 名称。Claim 名称区分大小写。ACP Connector 创建会验证 discovery 和客户端可达性，但不能证明真实用户的 token 一定包含所需的 Claims。

Claim 或设置	何时需要	ACP 用途
`sub`	始终需要	OIDC 协议使用的稳定上游 subject。它必须是字符串。
`name`	未配置 `userNameKey`	ACP username 的默认来源。
由 `userNameKey` 选择的 Claim	默认 `name` Claim 缺失或不合适时	ACP username 的来源。已验证的回退为 `preferred_username`。
`email` 或由 `claimMapping.email` 选择的 Claim	请求了 `email` scope 时	ACP 用户身份。它必须是字符串，并且不应与现有 ACP 用户冲突。
`email_verified`	请求了 `email` scope 时	当前登录流程要求的布尔验证标志。
由 `claimMapping.groups` 选择的 Claim	启用了 OIDC group 处理时	用于创建和关联 ACP groups 的字符串或数组 group 名称。
由 `claimMapping.phone` 和 `claimMapping.mail` 选择的 Claims	已配置这些可选的 profile 字段时	复制到 ACP 用户 mobile 和 mail 字段的字符串值。
`claimExtra` 中列出的 Claim	额外值必须存储到 ACP 中时	当其配置类型匹配时，复制到 `spec.extra`。本指南记录的是已验证的 `string` 类型。

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

上游 OIDC 证书验证限制

在此 ACP 版本中，Connector 验证和 OIDC 登录运行时都使用 insecureSkipVerify: true。因此，ACP 不会验证上游 OIDC 服务器证书。HTTPS 仍会加密连接，但成功创建 Connector 并不代表证书链已受信任。

如果客户的安全策略要求验证上游服务器证书，则此版本不满足该要求。请在 rollout 之前解决产品版本或安全策略要求。

使用 Form 添加 OIDC

进入 Users > IDP。
点击 Add OIDC。
填写 Basic Info：Name、Display Name 和可选的 Description。
填写 Server Setting：Server Provider URL、Client ID 和 Client Key。
对于此集成流程，Logout URL 保持为空。
点击 Add。

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

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

控制台字段参考

ACP 控制台字段	YAML 字段	产品行为
Name	`id` 和 `metadata.name`	两个字段使用相同的、与 DNS 兼容的值。
Display Name	`name`	显示在 ACP IDP 选择器中的名称。
Description	`metadata.annotations["cpaas.io/description"]`	可选的、面向 operator 的描述。
Server Provider URL	`spec.config.issuer`	用于 OIDC discovery 的 Issuer 根地址。
Client ID	`spec.config.clientID`	在上游注册的客户端标识符。
Client Key	`spec.config.clientSecret`	初始创建输入；ACP 会将其存储到受管 Secret 中。
Logout URL	`logoutUrl`	保持为空。已验证的运行时不会将其用作登出后的重定向。

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

验证集成

启动一个不带 ACP 登录状态的独立浏览器会话。
打开 ACP 并选择已配置的 OIDC Display Name。
在上游 Identity Provider 完成身份验证。
确认浏览器返回 ACP，而不是 HTTP 500 错误。
在 Users 中找到生成的用户，并验证其 IDP source、email、username 和 active state。
如果由于上游响应不包含默认 name Claim 导致 username 为空，请使用下面的 YAML 示例重新创建或更新 Connector，并再次登录。
使用 Manage User Roles 分配一个最小 role。
再次登录，并确认已分配的 ACP permission 可用。

Email 身份冲突

在此版本中，通过另一个映射相同 email 的 OIDC Connector 登录时，会更新现有 ACP 用户，并将其重新关联到较新的 Connector。它不会创建第二个用户，也不会拒绝该冲突。请使用专用的、不会冲突的账号进行验收测试，并在 rollout 前检查现有 ACP 用户。

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。如果提供方不暴露 UserInfo endpoint，或者所有必需的 Claims 都已经在 ID token 中，请将 getUserInfo: false。如果不需要 group 处理，请移除 insecureEnableGroups、allowedGroups 和 claimMapping.groups。

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

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

完整 OIDC 字段参考

顶层和 metadata 字段：

字段	需要性	产品行为
`apiVersion`	是	使用 `dex.coreos.com/v1`。
`kind`	是	使用 `Connector`。
`id`	是	Connector 标识。保持其与 `metadata.name` 相同。
`name`	是	显示在 ACP 登录选择器中的显示名称。
`type`	是	使用 `oidc`。
`metadata.name`	是	Kubernetes 资源名称和 ACP Connector 查询键。
`metadata.namespace`	是	使用 `cpaas-system`。
`metadata.annotations["cpaas.io/description"]`	否	ACP 显示的描述。
`metadata.annotations["cpaas.io/idp.validation"]`	仅限临时排障	字符串值 `"false"` 会在此次创建或变更 spec 的更新中跳过上游连通性验证；格式验证仍会执行。不要将其设置为 `"true"`。
`metadata.labels["cpaas.io/idp.version"]`	推荐	使用 `v2`；当前 ACP 在创建时也会添加该 label。

连接和登录字段：

字段	需要性	产品行为
`issuer`	是	用于获取 `/.well-known/openid-configuration` 的 Issuer 根地址。
`clientID`	是	在上游注册的客户端标识符。
`clientSecret`	初始创建	ACP YAML 页面接受的明文输入。ACP 会移除它并将其存储到受管 Secret 中。
`clientSecretRef`	存储输出	ACP 写入的受管 Secret 引用。不要将其与 `clientSecret` 一起提交，也不要手动编辑它。
`redirectURI`	是	上游注册的精确 ACP 回调：`https://<ACP_ADDRESS>/dex/callback`。
`scopes`	否	额外的 scopes，例如 `profile` 和 `email`。ACP 会自动添加 `openid`。
`getUserInfo`	否	当为 `true` 时，请求 UserInfo endpoint，并在映射前合并返回的 Claims。请确认提供方支持此 endpoint。
`userNameKey`	否	作为 ACP username 的 Claim，而不是默认的 `name`；已验证的回退为 `preferred_username`。

Claim 和 group 字段：

字段	需要性	产品行为
`overrideClaimMapping`	强制使用自定义映射时	当标准 Claim 也存在，但 ACP 必须使用下面选定的 Claim 时，设置为 `true`。
`claimMapping.preferred_username`	否	用作 preferred username 的 Claim。
`claimMapping.email`	重新映射 email 时	用作 ACP primary identity 的 Claim。请在 rollout 前检查冲突。
`claimMapping.groups`	启用 group 处理时	包含字符串或数组 group 名称的 Claim。该嵌套字段是运行时的 group 映射。
`claimMapping.phone`	否	复制到 ACP 用户 mobile 字段的字符串 Claim。
`claimMapping.mail`	否	复制到 ACP 用户 mail 字段的字符串 Claim。
`claimExtra[].field`	否	复制到 ACP 用户 `spec.extra` map 的 Claim。
`claimExtra[].type`	与 `claimExtra[].field` 一起使用	在本指南验证的工作流中使用 `string`。当 Claim 缺失或具有其他类型时删除该项。
`insecureEnableGroups`	需要 group 处理时	设置为 `true` 以读取已映射的 group Claim，并在登录期间创建或关联 ACP groups。
`allowedGroups`	否	当非空时，只有至少一个已映射 group 匹配时才允许登录。ACP 仅保留匹配的允许 group。

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

临时验证绕过

仅当 Connector 必须在上游服务暂时不可达时进行阶段性部署，才使用 cpaas.io/idp.validation: "false"。ACP 仍会检查配置结构，但会跳过 discovery 和上游连通性检查。因此，即使浏览器登录无法工作，Connector 仍可能存在。

admission webhook 会从已存储的 Connector 中移除此注解，并将跳过标记复制到受管凭证 Secret。后续不带该注解、且会变更 spec 的 Connector 更新将执行正常的 Connector 验证。要为将来的 Client Key 变更恢复验证，请通过 Connector 在不带该注解的情况下更新凭证；不要直接编辑受管 Secret。不要使用 cpaas.io/idp.validation: "true"；正常验证时请省略该注解。

在 rollout 前，请完成一次正常验证的创建或真实的修正更新，然后执行一次真实的浏览器登录并检查生成的 ACP 用户。仅 metadata 更新并不能证明正常验证已运行。

ACP 受管且无效的字段

已存储的 YAML 可能包含控制器添加的默认值，例如 issuerAlias: ""、顶层 groupsKey: groups 和 insecureSkipVerify: true。

使用 claimMapping.groups 配置 group 映射。当前运行时不会将控制器添加的顶层 groupsKey 用作 group Claim 选择器。
不要将 insecureSkipVerify: false 作为证书信任控制。正如 开始前准备 中所述，已验证的运行时不会验证上游证书。
除非某个产品特定的集成操作步骤明确要求，否则请不要在已验证的工作流中使用 issuerAlias。

登录、更新和删除行为

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

请使用 ACP 控制台操作或 ACP 产品 API 进行删除。直接使用 kubectl 删除底层 Connector 自定义资源会绕过 ACP 的用户失效和清理行为。

登出行为

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

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

按阶段排查

症状	已证明的阶段	下一步检查
ACP 在创建期间拒绝 Connector。	discovery 或集群侧可达性未完成。	确认 Server Provider URL 是 Issuer 根地址，从与 ACP 等效的网络路径获取其 discovery document，并重试创建。
Connector 创建成功，但回调返回 HTTP 500，并显示 `unauthorized_client` 或 `Invalid client secret`。	discovery 和上游授权页已正常工作；token endpoint 上的客户端认证失败。	修正 Client Key，然后在新的浏览器会话中重新执行完整登录。仅创建并不能验证该值。
登录成功，但 ACP username 为空。	ACP 已接受上游身份并创建了用户。	确认存在 `preferred_username`，通过 YAML 设置 `userNameKey: preferred_username`，然后再次登录。
登录失败，并提示缺少 email 或 `email_verified`。	授权和 token exchange 已完成，但所需 Claims 缺失或类型错误。	检查 ID token 和 UserInfo 响应，修正 `scopes` 或 `claimMapping.email`，然后重新登录。
登录失败，并提示 `user not a member of allowed groups`。	已读取已映射的 group Claim，但没有任何值匹配 `allowedGroups`。	确认 group 值的大小写完全一致，然后修正上游成员关系、`claimMapping.groups` 或 `allowedGroups`。
登录成功，但未关联任何 ACP groups。	认证和用户映射已完成，但没有得到可用的 group 结果。	确认 `insecureEnableGroups: true`，检查已映射 group Claim 的类型和值，并验证 `claimMapping.groups`。
已配置的额外 Claim 未出现在 ACP 用户中。	登录已完成，但 Claim 缺失或与配置的类型不匹配。	检查合并后的 ID token 和 UserInfo Claims；对于本指南，仅在字符串 Claim 上使用 `type: string`。
测试登录后，现有用户的 IDP source 或映射发生变化。	回调映射到了一个已被 ACP 用户使用的 email。	停止 rollout，选择一个不会冲突的测试账号，并在重试前检查现有 ACP 用户。
ACP 登出后返回 IDP 选择器，但再次选择 OIDC 时无需额外提示即可登录。	ACP 会话已结束，而上游会话仍然有效。	将 ACP 登出和上游登出视为独立的验收检查；不要依赖未验证的 Logout URL 字段。
通过 `kubectl` 删除 Connector 自定义资源后，用户仍然保持 active。	绕过了 ACP 产品删除工作流。	如有需要先恢复测试 Connector，然后使用 ACP 控制台操作删除它，并选择所需的清理选项。

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

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

#OIDC 管理

#目录

#开始前准备

#确认返回的 Claims

#使用 Form 添加 OIDC

#控制台字段参考

#验证集成

#通过 YAML 添加 OIDC

#完整 OIDC 字段参考

#登录、更新和删除行为

#登出行为

#按阶段排查