# Amazon Cognito
<a name="identity-idp-cognito"></a>

Amazon Cognito 可以設定為用於存取 AgentCore Gateway 和執行期的身分提供者，或用於傳出資源存取的 AgentCore Identity 憑證提供者。這可讓您的代理程式使用 Cognito 做為身分提供者和授權伺服器來驗證和授權代理程式使用者，或您的代理程式取得憑證以存取 Cognito 授權的資源。

## 傳入
<a name="identity-idp-cognito-inbound"></a>

若要新增 Cognito 做為存取 AgentCore Gateway 和 Runtime 的身分提供者和授權伺服器，您必須：
+ 從 IDP 目錄設定探索 URL。這有助於 AgentCore Identity 取得與您的 OAuth 授權伺服器和權杖驗證金鑰相關的中繼資料。
+ 輸入字符的有效 `clientId`或 `aud`宣告。這有助於驗證來自您 IDP 的字符，並允許存取包含預期宣告的字符。

使用下列程序建立 Cognito 使用者集區，做為使用 AgentCore 執行期進行使用者身分驗證的傳入身分提供者。下列步驟會建立 Cognito 使用者集區、使用者集區用戶端、新增使用者，並為使用者產生承載字符。根據預設，字符有效期為 60 分鐘。

 **建立 Cognito 使用者集區做為執行期身分驗證的傳入身分提供者** 

1. 建立名為 `setup_cognito.sh` 且具有下列內容的檔案：
**注意**  
下列指令碼僅做為範例。您應該視需要為您的應用程式自訂使用者集區設定和使用者登入資料。請勿直接在生產環境中使用此指令碼。

   ```
   #!/bin/bash
   
   # Create User Pool and capture Pool ID directly
   export POOL_ID=$(aws cognito-idp create-user-pool \
     --pool-name "MyUserPool" \
     --policies '{"PasswordPolicy":{"MinimumLength":8}}' \
     --region us-east-1 | jq -r '.UserPool.Id')
   
   # Create App Client and capture Client ID directly
   export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
     --user-pool-id $POOL_ID \
     --client-name "MyClient" \
     --no-generate-secret \
     --explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
     --region us-east-1 | jq -r '.UserPoolClient.ClientId')
   
   # Create User
   aws cognito-idp admin-create-user \
     --user-pool-id $POOL_ID \
     --username "testuser" \
     --temporary-password "${temp-password}" \
     --region us-east-1 \
     --message-action SUPPRESS > /dev/null
   
   # Set Permanent Password
   aws cognito-idp admin-set-user-password \
     --user-pool-id $POOL_ID \
     --username "testuser" \
     --password "${permanent-user-password}" \
     --region us-east-1 \
     --permanent > /dev/null
   
   # Authenticate User and capture Access Token
   export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
     --client-id "$CLIENT_ID" \
     --auth-flow USER_PASSWORD_AUTH \
     --auth-parameters USERNAME='testuser',PASSWORD='${permanent-user-password}' \
     --region us-east-1 | jq -r '.AuthenticationResult.AccessToken')
   
   # Output the required values
   echo "Pool id: $POOL_ID"
   echo "Discovery URL: https://cognito-idp.us-east-1.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
   echo "Client ID: $CLIENT_ID"
   echo "Bearer Token: $BEARER_TOKEN"
   ```

1. 執行指令碼以建立 Cognito 資源：

   ```
   source setup_cognito.sh
   ```

1. 記錄輸出值，看起來類似於：

   ```
   Pool id: us-east-1_poolid
   Discovery URL: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_userpoolid/.well-known/openid-configuration
   Client ID: clientid
   Bearer Token: bearertoken
   ```

   在接下來的步驟中，您將需要這些值。

使用下列程序建立 Cognito 使用者集區，做為使用 AgentCore Gateway machine-to-machine身分驗證的傳入身分提供者。下列步驟將建立使用者集區、資源伺服器、用戶端登入資料和探索 URL 組態。此設定會啟用閘道存取的 M2M 身分驗證流程。

 **建立 Cognito 使用者集區做為閘道身分驗證的傳入身分提供者** 

1. 建立使用者集區：

   ```
   aws cognito-idp create-user-pool \
     --region us-west-2 \
     --pool-name "gateway-user-pool"
   ```

1. 從回應記錄使用者集區 ID，或使用下列方式擷取：

   ```
   aws cognito-idp list-user-pools \
     --region us-west-2 \
     --max-results 60
   ```

1. 為使用者集區建立資源伺服器：

   ```
   aws cognito-idp create-resource-server \
     --region us-west-2 \
     --user-pool-id <UserPoolId> \
     --identifier "gateway-resource-server" \
     --name "GatewayResourceServer" \
     --scopes '[{"ScopeName":"read","ScopeDescription":"Read access"}, {"ScopeName":"write","ScopeDescription":"Write access"}]'
   ```

1. 為使用者集區建立用戶端：

   ```
   aws cognito-idp create-user-pool-client \
     --region us-west-2 \
     --user-pool-id <UserPoolId> \
     --client-name "gateway-client" \
     --generate-secret \
     --allowed-o-auth-flows client_credentials \
     --allowed-o-auth-scopes "gateway-resource-server/read" "gateway-resource-server/write" \
     --allowed-o-auth-flows-user-pool-client \
     --supported-identity-providers "COGNITO"
   ```

   從回應記錄用戶端 ID 和用戶端秘密。您需要這些值才能在 AgentCore Identity 中設定 Cognito 供應商。

1. 如有需要，請為您的使用者集區建立網域：

   ```
   aws cognito-idp create-user-pool-domain \
     --domain <UserPoolIdWithoutUnderscore> \
     --user-pool-id <UserPoolId> \
     --region us-west-2
   ```
**注意**  
建立網域`UserPoolId`時，從 移除任何底線。例如，如果您的使用者集區 ID 是「us-west-2\_gmSGKKGr9」，請使用「us-west-2gmSGKKGr9」做為網域。

1. 建構 Cognito 使用者集區的探索 URL：

   ```
   https://cognito-idp.us-west-2.amazonaws.com/<UserPoolId>/.well-known/openid-configuration
   ```

1. 使用下列值設定閘道傳入身分驗證：

   1.  **探索 URL** ：在上一個步驟中建構的 URL

   1.  **允許用戶端** ：建立使用者集區用戶端時取得的用戶端 ID

## 傳出
<a name="identity-idp-cognito-outbound"></a>

**注意**  
AgentCore Identity 會為您建立的每個登入資料提供者發出唯一的 OAuth2 回呼 URL。唯一的回呼 URL 可啟用工作階段繫結，透過確保授權回應只能針對啟動它的特定憑證提供者進行兌換，以保護 OAuth2 授權碼交換免受跨供應商重播和 CSRF 型攻擊。由於每個提供者的 URL 都是唯一的，因此在呼叫 **之前**，您都不會知道它`CreateOauth2CredentialProvider`。首先建立您的 Cognito 使用者集區應用程式用戶端，然後在 AgentCore Identity 發出後返回 Amazon Cognito 主控台來註冊回呼 URL。

 **步驟 1：建立 Cognito 使用者集區應用程式用戶端** 

使用下列程序為傳出 OAuth2 聯合設定 Cognito 使用者集區應用程式用戶端。在 AgentCore Identity 發出唯一的回呼 URL 之後，您將在步驟 3 中註冊重新導向 URI。

 **設定 Cognito 使用者集區應用程式用戶端** 

1. 在 Amazon Cognito 主控台中，開啟或建立您要用作傳出資源提供者的使用者集區。

1. 設定使用者集區網域，讓託管 UI 可以發出授權碼。

1. 為使用者集區建立應用程式用戶端、產生用戶端秘密，並啟用**授權碼授予** OAuth2 流程。

1. 選取應用程式所需的 OAuth2 範圍。

1. 現在將**允許回呼 URLs** 欄位保留空白 — 您將在步驟 3 中新增唯一的回呼 URL。

1. 記錄**用戶端 ID** 和**用戶端秘密**。您需要這些值才能在 AgentCore Identity 中設定 Cognito 供應商。

1. 請注意使用者集區的網域字首和使用者集區 ID。您將使用這些項目來建構步驟 2 中的授權、字符和發行者端點。

如需詳細資訊，請參閱《Amazon Cognito 開發人員指南》中的[設定應用程式用戶端](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-app-idp-settings.html)。

 **步驟 2：建立 AgentCore Identity 登入資料提供者** 

若要將 Cognito 使用者集區設定為傳出資源提供者，請使用下列組態：

```
{
  "name": "Cognito",
  "credentialProviderVendor": "CognitoOauth2",
  "oauth2ProviderConfigInput" : {
    "includedOauth2ProviderConfig": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "authorizationEndpoint": "https://{your-cognito-domain}.auth.us-east-1.amazoncognito.com/oauth2/authorize",
      "tokenEndpoint": "https://{your-cognito-domain}.auth.us-east-1.amazoncognito.com/oauth2/token",
      "issuer": "https://cognito-idp.us-east-1.amazonaws.com/{your-user-pool-id}"
    }
  }
}
```

[CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html) 回應包含 `callbackUrl` 欄位。此 URL 對此登入資料提供者是唯一的，如下所示：`https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`。儲存此值以供下一個步驟使用。

 **步驟 3：向 Cognito 註冊唯一的回呼 URL** 

返回 Amazon Cognito 主控台，並將唯一的回呼 URL 新增至應用程式用戶端允許的回呼。

1. 在 Amazon Cognito 主控台中，開啟您在步驟 1 中建立的使用者集區應用程式用戶端。

1. 在應用程式用戶端的託管 UI 組態中，將 傳回`callbackUrl`的值新增至`CreateOauth2CredentialProvider`**允許的回呼 URLs**。

1. 儲存您的變更。