# 为您的网关设置出站授权
<a name="gateway-outbound-auth"></a>

出站授权允许 Amazon Bedrock AgentCore 网关代表在入站授权期间经过身份验证和授权的用户安全地访问网关目标。

AgentCore 网关支持以下类型的出站授权：
+  **无授权（不推荐）**-某些目标类型允许您选择绕过出站授权。不建议使用这种不太安全的选项。
+  **IAM-based 出站授权**-使用[网关服务角色](gateway-prerequisites-permissions.md#gateway-service-role-permissions)通过[AWS 签名版本 4（Sig V4）](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)对网关目标的访问进行身份验证。
+  **调用方 IAM 证书** — 网关使用呼叫者的 IAM 证书签署对目标的请求。网关使用联合访问服务 (FAS) 代表呼叫者扮演角色，并使用呼叫者的身份对出站请求进行签名。当目标服务需要根据原始调用者的身份而不是网关服务角色进行授权时，这很有用。
+  **OAuth** — 一种开放式授权框架，允许客户端应用程序访问资源。您可以将 OAuth 与[内置身份提供商或自定义身份提供商](identity-idps.md)一起使用。有关更多信息，请参阅 [OAuth 2.0。](https://oauth.net/2/)您可以使用以下类型的 OAuth 授权授权：
  +  **客户端凭证授予** — Machine-to-machine 身份验证（也称为双向 OAuth）。客户端应用程序代表应用程序访问资源，而不是代表用户访问资源。
  +  **授权码授权** — User-delegated 访问权限（也称为三足型 OAuth）。用户同意客户端应用程序代表用户访问资源。
  +  **Token exchange grant (On-behalf-of)** — 网关将入站用户的访问令牌交换为针对下游资源的新的、限定范围的访问令牌。交换的令牌同时携带用户的身份和代理的身份，使下游服务能够在每次跳跃时强制执行细粒度的授权，而无需触发额外的同意流。有关更多信息，请参阅[On-behalf-of 代币交换](on-behalf-of-token-exchange.md)。
+  **令牌直通**-网关无需修改即可将入站授权令牌直接传递到目标。目标服务负责验证令牌。这要求网关使用`AUTHENTICATE_ONLY`入站授权，以便令牌经过验证但保留用于转发。
+  **API 密钥**-使用该 AgentCore 服务生成 API 密钥以验证对网关目标的访问权限。

您可以设置的出站授权类型取决于您授权访问的网关目标类型：


| Target type | 没有授权 | 网关服务角色 | 来电者 IAM 证书 | OAuth（客户端凭证） | OAuth（授权码） | OAuth（代币交换） | 代币直通 | API 密钥 | 
| --- | --- | --- | --- | --- | --- | --- | --- | --- | 
| API Gateway 阶段 | 支持 | 是 | 否 | 否 | 否 | 否 | 否 | 是 | 
| Lambda 函数 | 否 | 是 | 否 | 否 | 否 | 否 | 否 | 否 | 
| MCP 服务器 | 支持 | 是 | 否 | 是 | 是 | 是 | 否 | 是 | 
| OpenAPI 架构 | 支持 | 是 | 否 | 是 | 是 | 是 | 否 | 是 | 
| Smithy 架构 | 否 | 是 | 否 | 是 | 否 | 否 | 否 | 否 | 
| AgentCore 运行时间 (HTTP) | 否 | 是 | 是 | 是 | 否 | 否 | 是 | 否 | 

**注意**  
如果您使用集成提供商模板作为目标，请在以[集成提供商为目标的模板中查看不同Built-in 模板](gateway-target-integrations.md)支持的授权类型。

在向网关添加目标之前，必须通过其中一种支持的方法为其设置授权。

**注意**  
如果您计划使用 AWS 管理控制台或 AgentCore CLI 创建网关，则可以跳过此先决条件。如果您使用其中任何一种工具，则可以允许 AgentCore 自动为您创建一个具有访问目标所需权限的服务角色。每次添加目标时，必需的权限都将自动附加到您的服务角色。

选择一个主题以了解如何设置该类型的授权：

**Topics**
+ [使用网关服务角色设置 IAM-based 出站授权](#gateway-outbound-auth-iam)
+ [使用 OAuth 客户端设置出站授权](#gateway-outbound-auth-oauth)
+ [使用 API 密钥设置出站授权](#gateway-outbound-auth-api-key)

## 使用网关服务角色设置 IAM-based 出站授权
<a name="gateway-outbound-auth-iam"></a>

IAM-based 出站授权允许您使用网关服务角色的 IAM 凭证通过[AWS 签名版本 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) 进行授权。此选项允许 Amazon Bedrock AgentCore 服务代表您的网关呼叫者向网关目标进行身份验证。

如果使用此选项，请验证网关服务角色是否具有`bedrock-agentcore:InvokeGateway`权限。网关在调用期间使用服务角色凭据进行身份验证。

 **MCP 服务器和 OpenAPI 目标的其他配置** 

当您对 MCP 服务器或 OpenAPI 目标使用 IAM-based 出站授权时，必须为 Sigv4 签名提供其他配置。在中`credentialProviderConfigurations`，包括`iamCredentialProvider`带有以下字段的：
+  **服务**（必填）-用于 Sigv4 签名的 AWS 服务名称。例如，`bedrock-agentcore`对于托管在 Amazon Bedro AgentCore ck 上的 MCP 服务器。
+  **区域**（可选）— Sigv4 签名的 AWS 区域。如果您未指定区域，则网关将使用自己的区域。

对于 Lambda、API Gateway 和 Smithy 目标，请不要包含该字段。`iamCredentialProvider`这些目标类型仅支持基本`GATEWAY_IAM_ROLE`配置。`credentialProviderType`有关指定凭证提供商配置的更多信息，请参阅[AgentCore 网关服务角色 (IAM) 授权](gateway-building-adding-targets-authorization.md#gateway-building-adding-targets-authorization-service-role)。

### IAM-based 出站授权的安全最佳实践
<a name="_security_best_practices_for_iam_based_outbound_authorization"></a>

网关执行角色在配置为的所有目标之间共享`GATEWAY_IAM_ROLE`。它的权限是任何授权呼叫者可以通过网关行使权限的上限。请遵循以下最佳做法来限制暴露：
+  **将执行角色限定为最低权限**-仅授予所有已配置目标所需的权限。避免使用宽泛`Resource`符`Action`或通配符。
+  **为不同的信任边界使用不同的网关** — 如果目标具有不同的敏感度级别或服务于不同的工作负载，请将其部署在具有不同执行角色的单独网关后面。
+  **使用策略引擎限制来电者访问权限** — 在共享网关上，使用[策略引擎](policy-getting-started.md)控制哪些呼叫者可以调用哪些目标，从而限制任何单个呼叫者权限的爆炸半径。

## 使用 OAuth 客户端设置出站授权
<a name="gateway-outbound-auth-oauth"></a>

要使用 OAuth 客户端设置出站授权，您可以使用 AgentCore 身份服务并指定在内置身份提供商（请参阅提供商[设置和配置](identity-idps.md)）或自定义身份提供商中创建客户端时收到的客户端凭据。

 **使用 OAuth 客户端设置出站授权** 

1. 向支持的第三方提供商注册您的客户端应用程序。

1. 您将收到客户端 ID、客户端密钥，可能还有其他值，您将在设置出站授权时引用这些值。

1. 根据您的要求，请按照以下步骤之一进行操作：
   + 要使用内置身份提供商在控制台中配置出站授权，请按照[使用包含的提供商添加 OAuth 客户端](identity-add-oauth-client-included.md)中的步骤进行操作。
   + 要使用自定义身份提供商在控制台中配置出站授权，请按照使用自定义身份提供商[添加 OAuth 客户端中的步骤进行](identity-add-oauth-client-custom.md)操作。
   + 要使用 API 配置出站授权，请[CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)使用[AgentCore 控制平面端点](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp)之一发送。有关示例，请参阅[设置 OAuth 客户端授权的示](#gateway-outbound-auth-oauth-examples)例。
**注意**  
`oauth2ProviderConfigInput`字段映射到的 JSON 对象的形状取决于您使用的提供程序，并且必须与您指定的`credentialProviderVendor`值一致。要查看不同凭证提供商的不同配置示例，请参阅提供商[设置和](identity-idps.md)配置中您选择的凭证提供商中的出站授权示例。

1. 记下生成的凭证 ARN`credentialProviderArn`（在 API 中）和 Secrets AWS Manager 的密钥 ARN`secretArn`（在 API 中）。创建网关目标时，您将使用这些值。

1. （如果您使用的是自定义网关服务角色）将以下基于身份的策略附加到您的网关服务角色：

   ```
   {
   "Version": "2012-10-17",		 	 	 
       "Statement": [
         {
           "Sid": "GetWorkloadAccessToken",
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetWorkloadAccessToken",
           ],
           "Resource": [
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
           ]
         },
         {
           "Sid": "GetResourceOauth2Token",
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetResourceOauth2Token",
           ],
           "Resource": [
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/oauth2credentialprovider/CredentialName"
           ]
         },
         {
           "Sid": "GetSecretValue",
           "Effect": "Allow",
           "Action": [
               "secretsmanager:GetSecretValue",
           ],
           "Resource": [
               "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
           ]
         }
       ]
   }
   ```

   替换以下字段的值：
   + 在`GetWorkloadAccessToken`语句中，将`Resource`列表{{GatewayName}}中的替换为您的网关名称。
   + 在`GetResourceOauth2Token`语句中，将`Resource`列表中的值替换为您刚生成的凭证的 ARN。
   + 在`GetSecretValue`语句中，将`Resource`列表中的值替换为生成凭证时响应中返回的 AWS 密钥的 ARN。

### 设置 OAuth 客户端授权的示例
<a name="gateway-outbound-auth-oauth-examples"></a>

以下示例说明如何通过 OAuth 客户端为网关目标设置授权：

**Example**  

1.  AgentCore CLI 凭证命令必须在现有 agentcore 项目中运行。如果您还没有，请先使用创建一个项目`agentcore create`。

   ```
   agentcore add credential \
     --name oauth-credential-provider \
     --type oauth \
     --discovery-url <DiscoveryUrl> \
     --client-id <ClientId> \
     --client-secret <ClientSecret>
   agentcore deploy
   ```

1. 

   ```
   aws bedrock-agentcore-control create-oauth2-credential-provider \
     --name oauth-credential-provider \
     --credential-provider-vendor CustomOAuth2 \
     --oauth2-provider-config-input '{
       "customOAuth2ProviderConfig": {
         "oauthDiscovery": {
           "discoveryUrl": "<DiscoveryUrl>"
         },
         "clientId": "<ClientId>",
         "clientSecret": "<ClientSecret>"
       }
     }'
   ```

1. 

   ```
   import boto3
   
   client = boto3.client("bedrock-agentcore-control")
   
   client.create_oauth2_credential_provider(
     name="oauth-credential-provider",
     credentialProviderVendor="CustomOAuth2",
     oauth2ProviderConfigInput={
       "oauthDiscovery": {
         "discoveryUrl": "<DiscoveryUrl>"
       },
       "clientId": "<ClientId>",
       "clientSecret": "<ClientSecret>"
     }
   )
   ```

## 使用 API 密钥设置出站授权
<a name="gateway-outbound-auth-api-key"></a>

要使用 API 密钥设置出站授权，您可以使用 AgentCore 身份服务并指定从支持的身份提供商处收到的 API 密钥。

 **使用 OAuth 客户端设置出站授权** 

1. 向支持的第三方提供商注册您的客户端应用程序。

1. 为提供商的服务设置 API 密钥。请记下以下值，这些值将在添加网关目标时指定：
   +  **凭据位置**-API 密钥是应放在标题中还是作为查询参数。
   +  **凭证前缀** — 凭证的前缀（例如 Bearer）。

1. 根据您的要求，请按照以下步骤之一进行操作：
   + 要在 AgentCore 控制台中创建 API 密钥，请按照[添加 API 密钥](identity-add-api-key.md)中的步骤操作并指定 API 密钥的值。
   + 要使用 API 创建 AgentCore API 密钥，请使用[AgentCore 控制平面端点](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp)之一发送[CreateApiKeyCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateApiKeyCredentialProvider.html)请求，并在`apiKey`字段中指定 API 密钥的值。有关示例，[请参阅设置 API 密钥的示](#gateway-outbound-auth-api-key-examples)例。

1. 请记下以下值，这些值将在添加网关目标时指定：
   +  **凭证提供者 ARN** — 为凭证提供者生成的亚马逊资源名称 (ARN)。
   +  **名称**-您为 API 密钥指定的名称。
   +  S@@ **ecret ARN — 为** API AWS 密钥生成的 Secrets Manager 秘密 ARN。

1. （如果您使用的是自定义网关服务角色）将以下基于身份的策略附加到您的网关服务角色：

   ```
   {
   "Version": "2012-10-17",		 	 	 
       "Statement": [
         {
           "Sid": "GetWorkloadAccessToken",
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetWorkloadAccessToken",
           ],
           "Resource": [
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
           ]
         },
         {
           "Sid": "GetResourceApiKey",
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetResourceApiKey",
           ],
           "Resource": [
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/apikeycredentialprovider/Name"
           ]
         },
         {
           "Sid": "GetSecretValue",
           "Effect": "Allow",
           "Action": [
               "secretsmanager:GetSecretValue",
           ],
           "Resource": [
               "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
           ]
         }
       ]
   }
   ```

   替换以下字段的值：
   + 在`GetWorkloadAccessToken`语句中，将`Resource`列表{{GatewayName}}中的替换为您的网关名称。
   + 在`GetResourceApiKey`语句中，将`Resource`列表中的值替换为您刚生成的凭证的 ARN。
   + 在`GetSecretValue`语句中，将`Resource`列表中的值替换为生成凭证时响应中返回的 AWS 密钥的 ARN。

### 设置 API 密钥的示例
<a name="gateway-outbound-auth-api-key-examples"></a>

以下示例向您展示了如何为网关目标设置 API 密钥：

**Example**  

1.  AgentCore CLI 凭证命令必须在现有 agentcore 项目中运行。如果您还没有，请先使用创建一个项目`agentcore create`。

   ```
   agentcore add credential \
     --name api-key-credential-provider \
     --type api-key \
     --api-key <API_KEY_VALUE>
   agentcore deploy
   ```

1. 

   ```
   aws bedrock-agentcore-control create-api-key-credential-provider \
     --name api-key-credential-provider \
     --api-key <API_KEY_VALUE>
   ```

1. 

   ```
   import boto3
   
   client = boto3.client("bedrock-agentcore-control")
   
   client.create_api_key_credential_provider(
     name="api-key-credential-provider",
     apiKey="<API_KEY_VALUE>"
   )
   ```