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。本文档验证过的回退值使用 preferred_username。

在上游 Identity Provider 中注册以下精确的 callback：

https://<ACP_ADDRESS>/dex/callback

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

Server Provider URL 必须是 Issuer 根地址，而不是 authorization endpoint、token endpoint 或登录页面。其 discovery 文档通常可通过以下路径访问：

<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。

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 的字符串或字符串数组。
由 `claimMapping.phone` 和 `claimMapping.mail` 选定的 Claim	已配置这些可选的 profile 字段	复制到 ACP 用户 mobile 和 mail 字段的字符串值。
`claimExtra` 中列出的 Claim	额外值必须存储到 ACP	当其配置的类型匹配时，值会被复制到 `spec.extra`。本文档验证的是 `string` 类型。

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

上游 OIDC 证书验证限制

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

如果客户的安全策略要求验证上游 server 证书，则此版本不满足该要求。在正式上线前，请先解决产品版本或安全策略要求。

使用 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 证书受信任：使用错误密钥的 Connector 仍然可以创建成功，但会在浏览器 callback 时失败，而不受信任的自签名证书也可能被接受。因此，身份验证仍需要一次真实登录；证书合规性必须按照上文单独评估。

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

控制台字段参考

ACP console field	YAML field	产品行为
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`	留空。已验证的运行时未将其用作 logout 后重定向地址。

表单不提供 redirectURI、scopes、UserInfo、Claim mappings、group 处理或额外 Claims 的配置。只有在确认上游响应后，才通过 YAML 配置这些字段。

验证集成

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

Email 身份冲突

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

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

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

完整 OIDC 字段参考

顶层和 metadata 字段：

Field	Required	产品行为
`apiVersion`	Yes	使用 `dex.coreos.com/v1`。
`kind`	Yes	使用 `Connector`。
`id`	Yes	Connector 标识。保持其与 `metadata.name` 相同。
`name`	Yes	显示在 ACP 登录选择器中的名称。
`type`	Yes	使用 `oidc`。
`metadata.name`	Yes	Kubernetes 资源名称和 ACP Connector 查找键。
`metadata.namespace`	Yes	使用 `cpaas-system`。
`metadata.annotations["cpaas.io/description"]`	No	ACP 显示的描述。
`metadata.labels["cpaas.io/idp.version"]`	Recommended	使用 `v2`；当前 ACP 在创建时也会添加此标签。

连接和登录字段：

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

Claim 和 group 字段：

Field	Required	产品行为
`overrideClaimMapping`	强制使用自定义映射时	当标准 Claim 也存在，但 ACP 必须使用下方选定的 Claim 时，设为 `true`。
`claimMapping.preferred_username`	No	作为首选 username 的 Claim。
`claimMapping.email`	重新映射 email 时	用作 ACP 主身份的 Claim。上线前请检查冲突。
`claimMapping.groups`	已启用 group 处理时	包含 group 名称字符串或数组的 Claim。该嵌套字段是运行时 group 映射。
`claimMapping.phone`	No	复制到 ACP 用户 mobile 字段的字符串 Claim。
`claimMapping.mail`	No	复制到 ACP 用户 mail 字段的字符串 Claim。
`claimExtra[].field`	No	复制到 ACP 用户 `spec.extra` map 的 Claim。
`claimExtra[].type`	与 `claimExtra[].field` 一起使用	对于本指南中已验证的流程，请使用 `string`。如果 Claim 不存在或类型不同，请移除该条目。
`insecureEnableGroups`	需要 group 处理时	设为 `true` 以读取映射后的 group Claim，并在登录期间创建或关联 ACP groups。
`allowedGroups`	No	当其非空时，只有至少一个映射后的 group 匹配时才允许登录。ACP 只保留匹配的允许 group。

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

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 custom resource，会绕过 ACP 的用户失效和清理行为。

Logout 行为

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

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

按阶段排查

症状	已验证阶段	下一步检查
ACP 在创建期间拒绝 Connector。	discovery 或集群侧可达性未完成。	确认 Server Provider URL 是 Issuer 根地址，从与 ACP 等效的网络路径获取其 discovery 文档，然后重试创建。
Connector 创建成功，但 callback 返回 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 交换已完成，但所需的 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 来源或映射发生变化。	callback 映射到了一个已被 ACP 用户使用的 email。	停止上线，选择一个不会冲突的测试账号，并在重试前检查现有 ACP 用户。
ACP logout 返回到 IDP 选择器，但再次选择 OIDC 后无需再次提示即可登录。	ACP 会话已结束，而上游会话仍然有效。	将 ACP 和上游 logout 视为独立的验收检查；不要依赖未验证的 Logout URL 字段。
使用 `kubectl` 删除 Connector custom resource 后，用户仍保持 active。	绕过了 ACP 产品删除流程。	如有需要先恢复测试 Connector，然后使用 ACP 控制台操作删除它，并选择所需的清理选项。

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

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

#OIDC 管理

#目录

#开始之前

#确认返回的 Claims

#使用 Form 添加 OIDC

#控制台字段参考

#验证集成

#使用 YAML 添加 OIDC

#完整 OIDC 字段参考

#登录、更新和删除行为

#Logout 行为

#按阶段排查