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

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

Amazon Cognito 可以配置为用于访问 AgentCore 网关和运行时的身份提供商，或配置为用于出站资源访问的 AgentCore 身份凭证提供商。这允许您的代理使用 Cognito 作为身份提供商和授权服务器对代理用户进行身份验证和授权，或者您的代理获得访问由 Cognito 授权的资源的证书。

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

要将 Cognito 添加为用于访问 AgentCore Gateway 和 Runtime 的身份提供商和授权服务器，您必须：
+ 从 IDP 目录配置发现 URL。这有助于 AgentCore Identity 获取与您的 OAuth 授权服务器和令牌验证密钥相关的元数据。
+ 输入令牌的有效`clientId`或`aud`索赔。这有助于验证来自您的 IDP 的令牌，并允许访问包含预期声明的令牌。

使用以下步骤创建 Cognito 用户池作为入站身份提供商，用于通过 AgentCore Runtime 进行用户身份验证。以下步骤将创建 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 用户池作为入站身份提供商，用于通过 Gateway 进行机器对机器身份验证。 AgentCore 以下步骤将创建用户池、资源服务器、客户机凭证和发现 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 和客户端密钥。你需要这些值来在 I AgentCore dentity 中配置 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-style 攻击。由于每个提供商的网址都是唯一的，所以你要等到打电话**之后才**会知道`CreateOauth2CredentialProvider`。首先创建您的 Cognito 用户池应用程序客户端，然后在 I AgentCore dentity 发布回调网址后返回亚马逊 Cognito 控制台注册回调网址。

 **第 1 步：创建 Cognito 用户池应用程序客户端 ** 

使用以下步骤为出站 OAuth2 联合身份验证设置 Cognito 用户池应用程序客户端。在 I AgentCore dentity 发布唯一回调 URL 后，您将在步骤 3 中注册重定向 URI。

 **配置 Cognito 用户池应用程序客户端 ** 

1. 在 Amazon Cognito 控制台中，打开或创建您要用作出站资源提供商的用户池。

1. 配置用户池域，以便托管用户界面可以颁发授权码。

1. 为用户池创建应用程序客户端，生成客户端密钥，并启用**授权码授予 ** OAuth2 流程。

1. 选择您的应用程序所需的 OAuth2 范围。

1. 暂时将 “**允许的回传 URL” ** 字段留空——您将在步骤 3 中添加唯一的回传 URL。

1. 记录**客户端 ID ** 和**客户端密钥**。你需要这些值来在 I AgentCore dentity 中配置 Cognito 提供商。

1. 记下您的用户池的域前缀和用户池 ID。在步骤 2 中，您将使用它们来构造授权、令牌和颁发者端点。

有关更多详细信息，请参阅 Amazon Cognito 开发人员指南[中的](https://docs.amazonaws.cn/cognito/latest/developerguide/cognito-user-pools-app-idp-settings.html)配置应用程序客户端。

 **第 2 步：创建 AgentCore 身份凭证提供商 ** 

要将 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.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)响应包含一个`callbackUrl`字段。此网址是该凭证提供商所独有的，看起来像:`https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`. 保存此值以供下一步使用。

 **第 3 步：使用 Cognito 注册唯一的回传 URL ** 

返回亚马逊 Cognito 控制台，将唯一的回传 URL 添加到应用程序客户端允许的回传中。

1. 在 Amazon Cognito 控制台中，打开您在步骤 1 中创建的用户池应用程序客户端。

1. 在应用程序客户端的托管界面配置中，将返回的`callbackUrl`值`CreateOauth2CredentialProvider`添加到**允许的回调 URL 中**。

1. 保存更改。