View a markdown version of this page

设置外部身份提供商 (IdP) 身份验证 - AWS DevOps 代理人
先决条件工作原理配置外部 IdP 身份验证管理用户和群组访问权限更新 IdP 配置用户如何访问 Agent Space Web 应用程序会话管理安全注意事项断开外部 IdP 的连接问题排查

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

设置外部身份提供商 (IdP) 身份验证

外部身份提供商 (IdP) 身份验证允许您的组织使用现有的 OIDC-compatible 身份提供商（例如 Okta 或 Microsoft Entra ID）来管理用户对 AWS DevOps Agent Space Web 应用程序的访问权限。用户直接通过您的 IdP 使用其公司证书登录，无需 AWS IAM 身份中心。

先决条件

在设置外部 IdP 身份验证之前，请确保您有：

  • OIDC-compatible 身份提供商（Okta 或微软 Entra ID）

  • 管理员访问您的身份提供商

  • 访问 AWS DevOps 代理控制台的管理员权限

  • 代理空间已配置或准备创建

工作原理

配置外部 IdP 身份验证时：

  • 用户导航到 Agent Space Web 应用程序 URL

  • 它们被重定向到您的身份提供商的登录页面

  • 使用公司凭据进行身份验证后，他们将被重定向回 Web 应用程序

  • Web 应用程序将身份验证令牌交换为限于 Agent Space 的短期 AWS 凭证

会话有效期最长为 8 小时。使用 OIDC 刷新令牌自动刷新凭据，无需用户重新进行身份验证。

配置外部 IdP 身份验证

第 1 步：在您的身份提供商中注册应用程序

选择您的身份提供商并按照相应的设置说明进行操作。

选项 A：Okta

  1. 在 Okta 管理控制台中，导航到 “应用程序” > “应用程序”，然后选择 “创建应用程序集成”

  2. 选择 OIDC-OpenID Connect 作为登录方法，选择 Web 应用程序作为应用程序类型。选择下一步。

  3. 为应用程序设置描述性名称（例如，AWS DevOps Agent）

  4. 在 “拨款类型” 下，确保选中以下内容：

    • 授权码（默认）

    • 刷新令牌 -这是会话刷新所必需的。如果未启用，用户将无法维护会话。

注意

默认情况下，Okta 不启用刷新令牌授权类型。你必须明确启用它。

  1. 暂时将Sign-in 重定向 URI 保留为默认值——您将在配置代理空间后对其进行更新

  2. 在 “任务” 下，分配应具有访问权限的用户或群组。应用程序分配控制谁可以登录。有关更多信息，请参阅管理用户和群组访问权限。

  3. 选择保存

  4. 在应用程序的 “常规” 选项卡上，记下以下值：

    • 客户端 ID

    • 客户机密钥 — 选择 “复制” 以安全地保存此值

  5. 注意您的 Okta 域名 — 这是您的发行商 URL（例如，https://dev-12345678.okta.com）。

注意

在 “登录” 选项卡上，验证颁发者是否设置为 Okta URL（非动态）。这样可以确保发行人网址稳定。

注意

请勿将群组声明添加到授权服务器的 Claims 选项卡中的 ID 令牌中。 AWS DevOps 代理不使用您的 IdP 中的群组成员资格。

选项 B：微软 Entra ID

  1. 在 Azure 门户中，导航到 Microsoft Entra ID > 应用程序注册 > 新注册

  2. 设置描述性名称（例如，AWS DevOps Agent）

  3. 在 “支持的帐户类型” 下，选择适合您的组织的选项（通常仅限此组织目录中的帐户）

  4. 暂时将重定向 URI 留空。选择注册

  5. 在应用程序概述页面上，记下以下值：

    • 应用程序（客户端）ID — 配置代理空间时用作客户端 ID

    • 目录（租户）ID — 用于构造发行者 URL

  6. 导航到 “证书和密钥” > “新建客户端密钥”

    • 设置描述和到期时间

    • 选择 “添加” 并立即复制密钥值——它不会再次显示

  7. Entra ID 的发行者 URL 遵循此格式。{tenant-id}使用步骤 5 中的目录（租户）ID 替换：

    • https://login.microsoftonline.com/{tenant-id}/v2.0

注意

请勿在令牌配置中启用群组的可选声明。 AWS DevOps 代理不使用您的 IdP 中的群组成员资格。

第 2 步：启用带有 IdP 身份验证的操作员应用程序

  1. 在 AWS DevOps 代理控制台中，选择您的代理空间

  2. 转到 “访问” 选项卡

  3. 在 “用户访问权限” 下，选择外部身份提供商

  4. 在配置表单中，配置以下内容：

    • 身份提供商 — 选择您的身份提供商（Okta 或 Microsoft Entra ID）

    • 颁发者 URL — 来自您的身份提供商的 OIDC 颁发者 URL

    • 客户端 ID — 您创建的 OIDC 应用程序中的客户端 ID

    • 客户端密钥 — 来自您的 OIDC 应用程序的客户端密钥

  5. 在 “身份提供者应用程序角色名称” 下，选择三个选项之一：

    • Auto-create 新的 DevOps 代理角色（推荐）-创建具有适当权限的新服务角色

    • 分配现有角色 — 使用您已经创建的现有 IAM 角色

    • 使用策略模板创建新的 DevOps 代理角色 -使用提供的详细信息在 IAM 控制台中创建自己的角色

  6. 查看表单中显示的回调 URL 警告提醒。复制此 URL — 您需要将其添加到身份提供商允许的重定向 URI 中，然后用户才能登录。

  7. 选择 Connect (连接)。

选择 “连接” 后，控制台将显示外部身份提供商配置以及以下详细信息：

  • 提供商 -您选择的身份提供商

  • 发行者 URL — 配置的 OIDC 发行商 URL

  • 客户端 ID — 配置的客户端 ID

  • IAM 角色 ARN — 用于用户访问的 IAM 角色

  • 回调 URL — 在身份提供商中将此 URL 配置为允许的重定向 URI

  • 登录 URL — 使用此 URL 通过您的身份提供商访问 Web 应用程序

第 3 步：将回调 URL 添加到您的身份提供商

Okta

  1. 在 Okta 管理控制台中，导航到应用程序的 “常规” 选项卡

  2. 在 “登录” 下，选择 “编辑”

  3. 将回调 URL 添加为Sign-in 重定向 URI：

    • https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/callback

  4. （可选）设置启动登录 URI 以启用从 Okta 仪表板 IdP-initiated 登录：

    • https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/login

  5. （推荐）添加Sign-out 重定向 URI，在注销后将用户重定向回 Web 应用程序。否则，用户在注销时可能会看到错误页面：

    • https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome

  6. 选择保存

Microsoft Entra ID

  1. 在 Azure 门户中，导航到应用程序的身份验证页面

  2. 在 “平台配置” 下，选择添加平台 > Web

  3. 输入回调 URL 作为重定向 URI：

    • https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/callback

  4. （可选）添加注销重定向 URI 以在注销后将用户重定向回 Web 应用程序：

    • https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome

  5. 选择 “配置”

步骤 4：验证配置

  1. 导航到控制台中显示的登录 URL：

    • https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/login

  2. 您应该被重定向到身份提供商的登录页面

  3. 使用您的公司凭证登录

  4. 成功进行身份验证后，您将被重定向回 Agent Space Web 应用程序

管理用户和群组访问权限

通过外部 IdP 身份验证，您的身份提供商是您授予和撤消对 Agent Space Web 应用程序访问权限的地方。

在 Okta 中管理访问权限

对您在步骤 1 中创建的 OIDC 应用程序的分配将控制访问权限。

在 Okta 中授予访问权限

  1. 在 Okta 管理控制台中，导航到应用程序和资源 > 应用程序，然后选择您的应用程序

  2. 选择 “任务” 选项卡

  3. 选择 “分配”，然后选择 “分配给人员” 或 “分配给群组”

  4. 选择每个人或群组旁边的 “分配”，然后选择 “完成”

尽可能分配群组，而不是个人。然后在 “目录” > “群组” 中进行持续维护。将某人添加到群组可授予访问权限；移除他们会撤消该权限，无需编辑应用程序。

移除 Okta 中的访问权限

  1. 在 “任务” 选项卡上，找到人员或群组

  2. 选择 X（取消分配）图标并确认

移除群组会撤消其唯一任务来自该群组的所有人的访问权限。如果一个人也被直接分配，也要删除直接分配。

要通过一次操作撤消某人对所有应用程序的访问权限，请在目录 > 用户中停用或暂停这些应用程序。

管理微软 Entra ID 中的访问权限

Entra ID 将您的应用程序表示为两个对象，第二个对象管理用户和群组分配：

  • 应用程序注册（在 “应用程序注册” 下）存储客户端 ID、客户端密钥和重定向 URI。您在步骤 1 和步骤 3 中对其进行了配置。

  • 企业应用程序（在 “企业应用程序” 下），也称为服务主体，用于管理用户和群组分配以及登录属性。

需要作业

默认情况下，租户中成功进行身份验证的每位用户都可以使用在租户中注册的应用程序。在你开启之前，Entra ID 不会强制分配。

  1. 在 Azure 门户或 Microsoft Entra 管理中心中，导航到企业应用程序并选择你的应用程序

  2. 选择 “属性”

  3. 设置为必填任务？改为 “是”

  4. 选择保存

在 Entra ID 中授予访问权限

  1. 导航到企业应用程序并选择您的应用程序

  2. 选择用户和群组

  3. 选择添加 user/group

  4. 选择用户或群组，然后选择分配

移除 Entra ID 中的访问权限

  1. 在 “用户和群组” 页面上，选择任务

  2. 选择 “移除” 并确认

要移除用户对所有应用程序的访问权限，请禁用该帐户。导航到 “用户”，选择用户，然后将 “启用帐户” 设置为 “否” 。

更新 IdP 配置

你可以在不断开连接的情况下轮换客户端密钥：

  1. 在 AWS DevOps 代理控制台中，选择您的代理空间

  2. 转到 “访问” 选项卡

  3. 在 “外部身份提供者配置” 下，选择 “轮换客户端密钥”

  4. 输入新的客户密钥

  5. 选择保存

要更改任何其他 IdP 配置字段（例如发行人 URL、客户端 ID 或身份提供商），必须断开现有 IdP 的连接并配置一个新字段。

用户如何访问 Agent Space Web 应用程序

配置外部 IdP 身份验证后：

  • 确认用户已在身份提供商中分配给 OIDC 应用程序。有关更多信息，请参阅管理用户和群组访问权限。

  • 与授权用户共享 Agent Space Web 应用程序 URL

  • 当用户导航到 URL 时，他们会被重定向到您的身份提供商的登录页面

  • 输入他们的证书（如果由您的 IdP 配置，则完成 MFA）后，他们将被重定向回 Agent Space Web 应用程序

  • 会话自动刷新 — 有关详细信息，请参阅会话管理

会话管理

Agent Space Web 应用程序的外部 IdP 会话具有以下特征：

  • 会话持续时间 — 浏览器会话最长持续 8 小时。这在 AWS DevOps 代理中不可配置。如果您的 IdP 会话生命周期超过 8 小时，则用户可以在下次访问时自动重新进行身份验证，而无需输入凭据。根据组织的安全要求配置 IdP 的会话和令牌生命周期。

  • 凭据刷新 — 使用 OIDC 刷新令牌自动刷新会话，无需用户重新进行身份验证

  • Multi-factor 身份验证 -在身份提供商中配置时支持。IdP 在登录期间处理 MFA — 无需在代理中进行其他配置 AWS DevOps

注销行为

当用户在 Web 应用程序中单击 “注销” 时：

  1. 所有会话 cookie 都会立即清除

  2. 用户被重定向到身份提供商的 OIDC 注销端点以终止 SSO 会话

  3. 如果配置了注销重定向 URI，则用户将被重定向回 Web 应用程序欢迎页面

撤消用户访问权限

要立即撤消用户的访问权限，您可以直接在身份提供商的管理门户中撤消他们的会话：

  • Okta — 在 Okta 管理控制台中，导航到 “目录” > “用户”，选择用户，选择 “更多操作” > “清除用户会话”

  • Microsoft Entra ID — 在 Azure 门户中，导航到 “用户”，选择用户，然后选择 “撤消会话”

安全注意事项

客户端密钥存储 — 如果您在创建代理空间时提供了客户管理的 KMS 密钥，则使用客户管理的 KMS 密钥对您在安装期间提供的客户端密钥进行加密，否则使用服务自有密钥进行加密。初始配置后，它永远不会在 API 响应中返回或显示在控制台中。

客户端密钥轮换 — Entra 客户端密钥的到期时间可配置。使用 AWS DevOps 代理控制台中的 “轮换客户端密钥” 选项设置提醒，在密钥到期之前轮换密钥。如果密钥过期，用户在轮换之前将无法登录。

令牌生命周期管理 -您的身份提供商颁发的令牌（访问令牌、刷新令牌）的生命周期由您的 IdP 的配置控制。我们建议在 IdP 中配置适当的令牌生命周期：

  • Okta — 在 “安全” > “API” > “授权服务器” > “访问策略” 下配置令牌生命周期

  • Microsoft Entra ID — 使用令牌生命周期策略配置令牌生命周期

群组声明 -请勿在身份提供商的令牌配置中启用群组声明。 AWS DevOps 代理目前不使用您的 IdP 的群组成员资格。

用户标识符 — AWS DevOps 代理使用提供商特定的声明来唯一标识用户：

  • Okta — 使用 ID 令牌中的sub声明

  • Microsoft Entra ID — 使用 ID 令牌中的oid（对象标识符）声明

这些标识符是不可变的，出现在 CloudTrail 日志中以供审计。

断开外部 IdP 的连接

  1. 在 AWS DevOps 代理控制台中，选择您的代理空间

  2. 转到 “访问” 选项卡

  3. 在 “用户访问权限” 下，选择断开连接

  4. 查看确认对话框中列出的影响并确认

断开连接将：

  • 从代理空间中删除 IdP 配置

  • 防止用户通过外部身份提供商登录

  • 移除与 IdP 用户帐户关联的个人聊天记录和构件历史记录

活跃的用户会话将持续到期或下次凭据刷新失败为止。

问题排查

  • 重定向到 IdP 失败 — 验证颁发者 URL 是否与您的 IdP 的 OIDC 发现端点相匹配。对于 Okta，请确保在 “登录” 选项卡上将发行人设置为 Okta URL（非动态）。对于 Entra，请使用格式https://login.microsoftonline.com/{tenant-id}/v2.0。

  • 访问被拒绝或策略错误 (Okta) -验证用户或其组是否已在 “分配” 下分配给应用程序。选中 “登录” > “登录政策” 规则。

  • 登录后出现 IdP 配置错误 -您的身份提供商未返回刷新令牌。确保启用offline_access范围和刷新令牌授予类型：

    • Okta — 转到应用程序的 “常规” 选项卡，启用 “授予类型” 下的 “刷新令牌” 复选框

    • Entra — 转到 API 权限，确保offline_access在 “委托权限” 下方列出

  • 身份验证成功但是 Web 应用程序显示错误 — 验证您的 IdP 中的重定向 URI 是否与 AWS DevOps 代理控制台中显示的回调 URL 完全匹配。

  • 身份验证失败 -如果您的 IdP 中启用了群组的可选声明，请将其禁用。 AWS DevOps 代理不使用团体索赔。

  • IdP 身份验证后登录失败 — 对于 Entra，应用程序清单null中未将验证requestedAccessTokenVersion设置为。对于 Okta，请验证发行者 URL 是否正确。

  • 选择注销 (Okta) 后出现错误页面 — 如果您在注销后看到post_logout_redirect_uri错误，请在 Okta 应用程序的 “常规” 选项卡中添加https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome为Sign-out 重定向 URI。

  • 用户在注销后留在身份提供商页面 (Entra) — 要在注销后将用户重定向回网络应用程序，请在您的 Entra 应用程序的身份验证页面中添加https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome为重定向 URI。