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 根路径，而不是授权端点、令牌端点或登录页。其 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 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 的字符串或组名数组。
由 `claimMapping.phone` 和 `claimMapping.mail` 选择的 Claims	配置了这些可选 profile 字段	复制到 ACP 用户的 mobile 和 mail 字段的字符串值。
`claimExtra` 中列出的 Claim	该额外值必须存储在 ACP 中	当其配置的类型匹配时，值会复制到 `spec.extra`。本指南记录的已验证类型为 `string`。

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

上游 OIDC 证书验证限制

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

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

使用 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 来源、email、username 和 active 状态。
如果由于上游响应不包含默认 name Claim 导致 username 为空，请使用下面的 YAML 示例重新创建或更新 Connector，然后再次登录。
使用 Manage User Roles 分配一个最小 role。
再次登录并确认已分配的 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 会自动将其添加到授权请求中。如果上游提供方要求某个 provider-specific 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 字段：

字段	是否必需	产品行为
`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.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 主身份的 Claim。发布前请检查是否冲突。
`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。任一值缺失都会导致登录失败。

ACP 管理且无效的字段

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

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

登录、更新和删除行为

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

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

注销行为

在此版本中，ACP logout 会结束 ACP session，并将浏览器返回到 ACP IDP 选择器。再次选择同一个 OIDC 条目时，可能会复用仍然有效的上游 session，并且无需再次提示凭证即可让用户登录。因此，ACP logout 不能证明上游 session 已结束。

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

按阶段排查

症状	已证明的阶段	下一步检查
ACP 在创建期间拒绝 Connector。	discovery 或集群侧可达性未完成。	确认 Server Provider URL 是 Issuer 根路径，从 ACP 等效网络路径获取其 discovery 文档，然后重试创建。
Connector 创建成功，但回调返回带有 `unauthorized_client` 或 `Invalid client secret` 的 HTTP 500。	discovery 和上游授权页面工作正常；在 token endpoint 处的客户端身份验证失败。	更正 Client Key，然后在新的浏览器会话中重复完整登录。仅创建本身不会验证该值。
登录成功，但 ACP username 为空。	ACP 接受了上游身份并创建了用户。	确认存在 `preferred_username`，通过 YAML 将 `userNameKey` 设置为 `preferred_username`，然后再次登录。
登录失败并提示缺少 email 或 `email_verified`。	授权和令牌交换已完成，但所需 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 来源或映射发生变化。	回调映射到了已被 ACP 用户使用的 email。	停止发布，选择一个不会冲突的测试账号，并在重试前检查现有 ACP 用户。
ACP logout 返回到 IDP 选择器，但选择 OIDC 后无需再次提示即可登录。	ACP session 已结束，而上游 session 仍然有效。	将 ACP 和上游 logout 视为独立的验收检查；不要依赖未验证的 Logout URL 字段。
使用 `kubectl` 删除 Connector custom resource 后，用户仍然处于 active 状态。	绕过了 ACP product 删除流程。	如有需要先恢复测试 Connector，然后使用 ACP 控制台操作删除它，并选择所需的清理选项。

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

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

#OIDC 管理

#目录

#开始之前

#确认返回的 Claims

#使用 Form 添加 OIDC

#控制台字段参考

#验证集成

#通过 YAML 添加 OIDC

#完整 OIDC 字段参考

#登录、更新和删除行为

#注销行为

#按阶段排查