📚 课程目录第4章联合身份与SSO集成

4. 联合身份与SSO集成

OCI 的联合身份（Federation）解决的是一个非常具体的问题：让企业已有的身份源成为 OCI 的登录入口，而不是在 OCI 里再维护一套用户名和密码。用户在企业 IdP（Microsoft Entra ID、Okta、Oracle Identity Cloud Service 等）完成认证后，通过 SAML 2.0 断言或 OIDC 令牌被 OCI 信任，从而以联合用户身份进入控制台或调用 API。理解这一机制的关键，是把“认证”和“授权”分开看：认证由 IdP 负责，OCI 只负责根据断言中的身份信息映射到本地用户，再按 IAM 策略授权。

一、联合身份的整体链路

无论对接哪家 IdP，OCI 侧的联合配置都围绕三个对象展开：Identity Provider（身份提供者）、IdP Group 映射和联合用户。IdP 负责签发断言，OCI 的 Identity Provider 对象负责验证签名并提取属性，Group 映射把 IdP 中的组名对应到 OCI 中的组，联合用户则在首次登录时按需自动创建。下图展示了从用户发起登录到获得 OCI 会话的完整信号链，以及 SCIM 预配这条并行的用户生命周期通道。

二、SAML 2.0 与 OIDC 的选择与配置要点

SAML 2.0 和 OIDC 在 OCI 联合身份中都能用，但适用场景不同。SAML 2.0 基于 XML 断言和签名证书，成熟稳定，适合以浏览器控制台访问为主、IdP 侧已有 SAML 应用模板的企业；OIDC 基于 JSON 令牌和 OAuth 2.0，更适合需要与 API、CLI、自动化工具链配合的场景，令牌体积小、解析方便。选择时优先看 IdP 侧的支持程度和现有集成资产，而不是单纯比较协议新旧。

以 Microsoft Entra ID 对接 SAML 为例，OCI 侧需要提供两个关键地址给 IdP：Assertion Consumer Service (ACS) URL 和 Entity ID / Audience。在 OCI 控制台创建 SAML Identity Provider 后，系统会给出形如下面的地址：

ACS URL:
https://cloud.oracle.com/fed/assert?tenant=ocid1.tenancy.oc1..aaaa...&idp=ocid1.saml2idp.oc1..bbbb...

Entity ID (Audience):
https://cloud.oracle.com/fed/assert?tenant=ocid1.tenancy.oc1..aaaa...&idp=ocid1.saml2idp.oc1..bbbb...

在 Entra ID 的企业应用中选择“SAML 单一登录”，把上述 ACS URL 填入“回复 URL（断言使用者服务 URL）”，把 Entity ID 填入“标识符（实体 ID）”。随后下载 Entra ID 的联合元数据 XML或 Base64 证书，回填到 OCI Identity Provider 的元数据/证书字段。关键属性映射必须包含：NameID 使用 user.userprincipalname 或 user.mail，组声明使用 user.groups 并选择“以组 ID 形式发出”或“以组名称形式发出”。OCI 侧再配置 IdP Group 映射，把 IdP 组名对应到 OCI 组。

OIDC 的配置路径类似，但交换的是客户端凭据和令牌端点。在 OCI 创建 OIDC Identity Provider 时，需要填写 IdP 的 Issuer URL、Client ID、Client Secret，并把 OCI 提供的 Redirect URL 注册到 IdP 应用。OIDC 断言中的 sub、email、groups 声明分别用于用户标识和组映射。相比 SAML，OIDC 的组声明通常需要 IdP 侧额外配置“组声明”或“应用角色”，否则默认令牌里可能不含组信息。

三、用户预配：SCIM 与即时预配（JIT）

用户预配解决的是“OCI 里怎么有这些用户和组”的问题，有两条路径：SCIM 主动预配和JIT 即时预配。SCIM（System for Cross-domain Identity Management）是 IdP 向 OCI 推送用户和组的标准协议，OCI 暴露 /admin/v1/Users 和 /admin/v1/Groups 端点，IdP 侧配置 SCIM 连接器后，用户的创建、更新、禁用会自动同步。JIT 则是在用户首次通过 SAML/OIDC 登录时，OCI 根据断言自动创建联合用户，无需提前推送。

两者不是互斥关系，实践中常见组合是：SCIM 负责用户和组的生命周期，JIT 作为兜底。例如新员工入职时 SCIM 已把用户和组同步到 OCI，登录时直接匹配；如果 SCIM 同步延迟或失败，JIT 仍能保证首次登录可用。但要注意，JIT 创建的用户默认没有组归属，必须依赖组映射或后续 SCIM 同步补上，否则会出现“能登录但无权限”的情况。

SCIM 配置的关键参数包括：Base URL（OCI 的 SCIM 端点）、Bearer Token（OCI 生成的 SCIM 凭据）、同步范围（哪些用户和组参与同步）。在 Entra ID 中，SCIM 配置位于企业应用的“预配”页，需要把 OCI 的 SCIM 端点和令牌填入，并设置映射：userPrincipalName → userName、displayName → displayName、mail → emails[type eq "work"].value。组映射则把 Entra ID 的组 displayName 对应到 OCI 组名。配置完成后先做一次“按需预配”测试单个用户，确认 OCI 侧出现对应用户和组，再开启全量同步。

建议在正式启用联合身份前，先用一个测试用户完成端到端验证：IdP 登录 → 断言到达 OCI → 联合用户创建 → 组映射生效 → 策略授权可访问目标资源。验证通过后再批量放开，避免影响全员登录。

四、常见问题与排查方向

联合身份集成中最常见的故障有三类。第一类是断言验证失败，表现为登录后跳回 IdP 或提示签名无效，通常原因是 OCI 侧证书与 IdP 当前签名证书不一致，或 ACS URL 配置错误。排查时先核对 IdP 元数据中的证书指纹与 OCI Identity Provider 中导入的证书是否一致，再检查 ACS URL 是否包含正确的 tenant 和 idp OCID。第二类是登录成功但无权限，原因是组映射缺失或组名不匹配。此时应检查断言中实际发出的组声明值，与 OCI IdP Group 映射中配置的 IdP 组名逐字比对，注意大小写和空格。第三类是 SCIM 同步失败，表现为 OCI 中用户缺失或离职用户未禁用。排查时查看 IdP 预配日志中的 HTTP 状态码，401 通常是 Bearer Token 失效，409 通常是用户已存在但属性冲突，需要根据日志定位具体对象。

此外，联合用户与本地用户的一个关键差异是：联合用户的密码由 IdP 管理，OCI 侧不能重置。如果 IdP 账号被禁用，联合用户即使存在于 OCI 也无法登录。因此离职流程必须同时覆盖 IdP 禁用和 SCIM 同步，不能只依赖 OCI 侧删除用户。对于需要 API 访问的联合用户，还要额外配置 API Key 或使用 OCI CLI 的联合登录方式，因为 API 调用不经过浏览器 SSO 流程。

联合身份配置完成后，务必保留至少一个本地应急管理员账号（本地用户 + 强密码 + MFA），并确认其属于 Administrators 组。一旦 IdP 故障或联合配置被误改，本地账号是恢复访问的唯一通道。

把以上内容串起来看，OCI 联合身份集成的核心就是三件事：选对协议并正确交换元数据、把 IdP 组准确映射到 OCI 组、用 SCIM 和 JIT 配合管理用户生命周期。三者都到位，用户才能既登录得进来，又拿到该有的权限；任何一环缺失，都会表现为“登录异常”或“权限异常”，排查时按认证链路和预配链路分别定位即可。