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

# 设置外部身份提供商 (IdP) 身份验证
<a name="aws-devops-agent-security-setting-up-external-identity-provider-idp-authentication"></a>

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

## 先决条件
<a name="prerequisites"></a>

在设置外部 IdP 身份验证之前，请确保：
+ 兼容 OIDC 的身份提供商（Okta 或 Microsoft Entra ID）
+ 管理员对您的身份提供商的访问权限
+ 访问 AWS DevOps 代理控制台的管理员权限
+ 已配置或准备创建的代理空间

## 工作原理
<a name="how-it-works"></a>

配置外部 IdP 身份验证时：
+ 用户导航到 Agent Space Web 应用程序 URL
+ 它们会被重定向到您的身份提供商的登录页面
+ 使用公司凭证进行身份验证后，他们会被重定向回 Web 应用程序
+ Web 应用程序将身份验证令牌交换为限于 Agent Space 的短期 AWS 凭证

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

## 配置外部 IdP 身份验证
<a name="configuring-external-idp-authentication"></a>

### 步骤 1：在您的身份提供商中注册应用程序
<a name="step-1-register-an-application-in-your-identity-provider"></a>

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

#### 选项 A：Okta
<a name="option-a-okta"></a>

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

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

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

1. 在 “**拨款类型**” 下，确保选中以下各项：
   + **授权码**（默认）
   + **刷新令牌**-这是会话刷新所必需的。如果未启用，用户将无法维护会话。

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

1. 暂时**将登录重定向 URIs**保留为默认值 — 您将在配置代理空间后对其进行更新

1. 在 “**分配**” 下，分配应具有访问权限的用户或群组

1. 选择**保存**

1. 在应用程序的 “**常规**” 选项卡上，记下以下值：
   + **客户端 ID**
   + **客户机密钥**-选择 “**复制**” 以安全地保存此值

1. 记下你的 **Okta 域名** ——这是你的发行商网址（例如`https://dev-12345678.okta.com`）。

**注意**  
**在** “登录**” 选项卡上，确认颁发者已****设置为** Okta URL**（不是动态）。这样可以确保发行者 URL 稳定。

**注意**  
**请勿在授权服务器的 “**声明” 选项卡中的 ID 令牌中添加**群组声明。 AWS DevOps 代理不使用您的 IdP 的群组成员资格。

#### 选项 B：微软 Entra ID
<a name="option-b-microsoft-entra-id"></a>

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

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

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

1. 暂时将**重定向 URI** 留空。选择 “**注册**”

1. 在应用程序**概述**页面上，记下以下值：
   + **应用程序（客户端）ID** — 在配置代理空间时用作客户端 ID
   + **目录（租户）ID** — 用于构造发行者 URL

1. 导航到 “**证书和密钥**” > “**新建客户机密**”
   + 设置描述和到期时间
   + 选择 “**添加**” 并立即复制密钥**值** — 它不会再次显示

1. Entra ID 的发行者网址遵循此格式。`{tenant-id}`替换为步骤 5 中的目录（租户）ID：
   + `https://login.microsoftonline.com/{tenant-id}/v2.0`

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

### 步骤 2：启用带有 IdP 身份验证的操作员应用程序
<a name="step-2-enable-the-operator-app-with-idp-authentication"></a>

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

1. 前往 “**访问权限**” 选项卡

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

1. 在配置表单中，配置以下内容：
   + **身份提供商**-选择您的身份提供商（Okta 或 Microsoft Entra ID）
   + **颁发者网址**-您的身份提供商提供的 OIDC 颁发者网址
   + **客户端 ID** — 来自您创建的 OIDC 应用程序的客户端 ID
   + **客户端密钥** — 来自 OIDC 应用程序的客户端密钥

1. 在 “**身份提供商应用程序角色名称**” 下，选择以下三个选项之一：
   + **自动创建新的 DevOps 代理角色**（推荐）-创建具有适当权限的新服务角色
   + **分配现有角色**-使用您已经创建的现有 IAM 角色
   + **使用策略模板创建新的 DevOps 代理角色** — 使用提供的详细信息在 IAM 控制台中创建自己的角色

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

1. 选择 **Connect (连接)**。

选择 **Connect** 后，控制台将显示包含以下详细信息的**外部身份提供者配置**：
+ **提供商**-您选择的身份提供商
+ **颁发者网址**-已配置的 OIDC 颁发者网址
+ **客户端 ID**-配置的客户端 ID
+ **IAM 角色 ARN** — 用于用户访问的 IAM 角色
+ **回调 URL** — 在您的身份提供商中将此 URL 配置为允许的重定向 URI
+ **登录 URL** — 使用此 URL 通过您的身份提供商访问 Web 应用程序

### 第 3 步：将回传 URL 添加到您的身份提供商
<a name="step-3-add-the-callback-url-to-your-identity-provider"></a>

#### Okta
<a name="okta"></a>

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

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

1. 将回调 URL 添加为**登录重定向 URI**：
   + `https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/callback`

1. （可选）设置**启动登录 URI** 以启用 IdP 从 Okta 控制面板启动的登录：
   + `https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/login`

1. （推荐）添加注**销重定向 URI**，以便在注销后将用户重定向回 Web 应用程序。否则，用户在注销时可能会看到错误页面：
   + `https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome`

1. 选择**保存**

#### Microsoft Entra ID
<a name="microsoft-entra-id"></a>

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

1. 在**平台配置**下，选择**添加平台** > **Web**

1. 输入回传 URL 作为**重定向 URI**：
   + `https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/callback`

1. （可选）添加注销重定向 URI，以便在注销后将用户重定向回 Web 应用程序：
   + `https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome`

1. 选择 “**配置”**

### 步骤 4：验证配置
<a name="step-4-verify-the-configuration"></a>

1. 导航到控制台中显示的**登录 URL**：
   + `https://{agentSpaceId}.aidevops.global.app.aws/authorizer/idp/login`

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

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

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

## 更新 IdP 配置
<a name="updating-idp-configuration"></a>

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

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

1. 前往 “**访问权限**” 选项卡

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

1. 输入新的**客户密钥**

1. 选择**保存**

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

## 用户如何访问 Agent Space Web 应用程序
<a name="how-users-access-the-agent-space-web-app"></a>

配置外部 IdP 身份验证后：
+ 与授权用户共享 Agent Space Web 应用程序 URL
+ 当用户导航到该 URL 时，他们会被重定向到您的身份提供商的登录页面
+ 输入他们的凭证（如果由你的 IdP 配置，则完成 MFA）后，他们将被重定向回 Agent Space 网络应用程序
+ 会话会自动刷新 — 有关详细信息，请参阅[会话管理](#session-management)

## 会话管理
<a name="session-management"></a>

Agent Space Web 应用程序的外部 IdP 会话具有以下特征：
+ **会话时长**-浏览器会话持续长达 8 小时。这在 AWS DevOps 代理中不可配置。如果您的 IdP 会话生命周期超过 8 小时，则可以在用户下次访问时自动重新进行身份验证，而无需输入凭据。根据组织的安全要求配置 IdP 的会话和令牌生命周期。
+ **凭据刷新** — 使用 OIDC 刷新令牌自动刷新会话，无需用户重新进行身份验证
+ **多重身份验证**-在您的身份提供商中配置时支持。IdP 在登录期间处理 MFA — 无需在代理中进行其他配置 AWS DevOps 

### 注销行为
<a name="logout-behavior"></a>

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

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

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

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

### 撤消用户访问权限
<a name="revoking-user-access"></a>

要立即撤消用户的访问权限，您可以直接在身份提供商的管理门户中撤消他们的会话：
+ **Okta** — 在 Okta 管理员控制台中，导航到 “**目录**” > “**人员**”，选择用户，选择 “**更多操作**” > “**清除**用户会话”
+ **Microsoft Entra ID** — 在 Azure 门户中，导航到 “**用户**”，选择用户，然后选择 “**撤消**会话”

## 安全注意事项
<a name="security-considerations"></a>

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

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

**令牌生命周期管理** — 身份提供商颁发的令牌（访问令牌、刷新令牌）的生命周期由您的 IdP 的配置控制。我们建议在您的 IdP 中配置适当的令牌生命周期：
+ **Okta** **— 在 “**安全**” > “**API**” > “**授权服务器**” > “访问策略” 下配置令牌生命周期**
+ **Microsoft Entra ID** — 使用令牌生命周期策略配置[令牌](https://learn.microsoft.com/en-us/entra/identity-platform/configurable-token-lifetimes)生命周期

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

**用户标识符**- AWS DevOps 代理使用特定于提供商的声明来唯一识别用户：
+ **Okta** — 使用 ID 令牌中的`sub`声明
+ **Microsoft Entra ID** — 使用 ID 令牌中的`oid`（对象标识符）声明

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

## 断开外部 IdP 的连接
<a name="disconnecting-external-idp"></a>

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

1. 前往 “**访问权限**” 选项卡

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

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

断开连接将：
+ 从代理空间中删除 IdP 配置
+ 阻止用户通过外部身份提供商登录
+ 移除与 IdP 用户帐户关联的个人聊天和构件历史记录

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

## 问题排查
<a name="troubleshooting"></a>
+ **重定向到 IdP 失败 — 验证颁发者**网址是否与您的 IdP 的 OIDC 发现端点相匹配。对于 Okta，请确保在 “**登录**” 选项卡上将**发行**者设置为 **Okta URL**（不是**动态**）。对于 Entra，请使用格式`https://login.microsoftonline.com/{tenant-id}/v2.0`。
+ **访问被拒绝或策略错误 (Okta)**-在 “**分**配” 下验证用户或其组已分配给应用程序。选中 **“登录”** > **“登录政策**” 规则。
+ **登录后出现 IdP 配置错误**-您的身份提供商未返回刷新令牌。确保已启用`offline_access`范围和刷新令牌授予类型：
  + **Okta** — 前往应用程序的 “**常规**” 选项卡并启用 “**授权**类型” 下的 “**刷新令牌**” 复选框
  + **Entra** — 前往 **API 权限**并确保列`offline_access`在委托权限下
+ **身份验证成功但网络应用显示错误** — 验证您的 IdP 中的重定向 URI 与代理控制台中 AWS DevOps 显示**的回调** URL 完全匹配。
+ **身份验证失败**-如果您的 IdP 中启用了**群组**可选声明，请将其禁用。 AWS DevOps 代理不使用团体索赔。
+ **IdP 身份验证后登录失败** **— 对于 Entra，应用程序清单`null`中未将 ver `requestedAccessTokenVersion` ify 设置为。**对于 Okta，请验证**发行者网址**是否正确。
+ **单击 “注销” 后出现错误页面 (Okta)** **— 如果您在注销后看到`post_logout_redirect_uri`错误，请在 Okta 应用程序的 “常规” 选项卡中添加`https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome`为注销**重定向 URI**。**
+ **用户在注销后会留在身份提供者页面上 (Entra) — 要在注****销后将用户重定向回 Web 应用程序，请在您的 Entra 应用程序的身份验证页面中添加`https://{agentSpaceId}.aidevops.global.app.aws/authorizer/welcome`为**重定向 URI**。**