本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定外部身分提供者 (IdP) 身分驗證
<a name="aws-devops-agent-security-setting-up-external-identity-provider-idp-authentication"></a>

外部身分提供者 (IdP) 身分驗證可讓您的組織使用現有的 OIDC 相容身分提供者，例如 Okta 或 Microsoft Entra ID，來管理使用者對 AWS DevOps Agent Space Web 應用程式的存取。使用者直接透過 IdP 使用其公司登入資料登入，而不需要 AWS IAM Identity Center。

## 先決條件
<a name="prerequisites"></a>

在設定外部 IdP 身分驗證之前，請確定您已：
+ OIDC 相容身分提供者 (Okta 或 Microsoft Entra ID)
+ 身分提供者的管理員存取權
+ 存取 AWS DevOps Agent 主控台的管理員許可
+ 已設定或準備建立的客服人員空間

## 運作方式
<a name="how-it-works"></a>

當您設定外部 IdP 身分驗證時：
+ 使用者導覽至 Agent Space Web 應用程式 URL
+ 它們會重新導向至您的身分提供者的登入頁面
+ 使用其公司登入資料進行驗證後，它們會重新導向回 Web 應用程式
+ Web 應用程式會交換身分驗證字符，以取得範圍為客服人員空間的短期 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 網域** — 這是您的發行者 URL （例如 `https://dev-12345678.okta.com`)。

**注意**  
** 在**登入**索引標籤上，確認**發行者**設定為 ** Okta URL **（非動態）。這可確保穩定的發行者 URL。

**注意**  
** 請勿將**群組**宣告新增至授權伺服器的宣告索引標籤中的 ID 字符。 AWS DevOps 代理程式不會使用來自 IdP 的群組成員資格。

#### 選項 B：Microsoft Entra ID
<a name="option-b-microsoft-entra-id"></a>

1. 在 Azure 入口網站中，導覽至 **Microsoft Entra ID** > **應用程式註冊** > **新註冊**

1. 設定描述性名稱 （例如 `AWS DevOps Agent`)

1. 在**支援的 帳戶類型**下，選取適合您組織的選項 （通常**僅適用於此組織目錄中的帳戶**)

1. 現在將**重新導向 URI** 保留空白。選擇**註冊**

1. 在應用程式**概觀**頁面上，記下下列值：
   + **應用程式 （用戶端） ID** — 在設定客服人員空間時用作用戶端 ID
   + **目錄 （租戶） ID** — 用來建構發行者 URL

1. 導覽至**憑證和秘密** > **新用戶端秘密**
   + 設定描述和過期期間
   + 選擇**新增**並立即複製秘密**值** — 不會再次顯示

1. Entra ID 的發行者 URL 遵循此格式。`{tenant-id}` 將 取代為步驟 5 中的目錄 （租戶） ID：
   + `https://login.microsoftonline.com/{tenant-id}/v2.0`

**注意**  
** 請勿在權杖組態 中啟用****群組選用宣告****。 AWS DevOps 代理程式不會使用來自 IdP 的群組成員資格。

### 步驟 2：使用 IdP 身分驗證啟用 Operator App
<a name="step-2-enable-the-operator-app-with-idp-authentication"></a>

1. 在 AWS DevOps 代理程式主控台中，選取您的代理程式空間

1. 前往**存取**索引標籤

1. 在**使用者存取**下，選擇**外部身分提供者**

1. 在組態表單中，設定下列項目：
   + **身分提供者** — 選取您的身分提供者 (Okta 或 Microsoft Entra ID)
   + **發行者 URL** — 來自您的身分提供者的 OIDC 發行者 URL
   + **用戶端 ID** — 您建立之 OIDC 應用程式的用戶端 ID
   + **用戶端秘密** — 來自 OIDC 應用程式的用戶端秘密

1. 在**身分提供者應用程式角色名稱**下，選擇三個選項之一：
   + **自動建立新的 DevOps Agent 角色** （建議） — 建立具有適當許可的新服務角色
   + **指派現有角色** — 使用您已建立的現有 IAM 角色
   + **使用政策範本建立新的 DevOps 代理程式角色** — 使用提供的詳細資訊在 IAM 主控台中建立您自己的角色

1. 檢閱表單底部顯示的**回呼 URL** 警告提醒。複製此 URL — 您需要將其新增至身分提供者允許的重新導向 URIs使用者才能登入。

1. 選擇**連線**

選擇**連線**後，主控台會顯示**外部身分提供者組態**，其中包含下列詳細資訊：
+ **提供者** — 您選取的身分提供者
+ **發行者 URL** — 設定的 OIDC 發行者 URL
+ **用戶端 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** 以從 Okta 儀表板啟用 IdP 起始的登入：
   + `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 Web 應用程式
+ 工作階段自動重新整理 — 如需詳細資訊，請參閱[工作階段管理](#session-management) 

## 工作階段管理
<a name="session-management"></a>

Agent Space Web 應用程式的外部 IdP 工作階段具有下列特性：
+ **工作階段持續時間** — 瀏覽器工作階段最多持續 8 小時。這無法設定 in 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 金鑰進行加密。它永遠不會在 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 失敗** — 驗證發行者 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，驗證`requestedAccessTokenVersion`未在`null`應用程式**資訊清單中**設定為 。對於 Okta，驗證**發行者 URL** 是否正確。
+ **按一下登出 (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。 ****