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

在创建网关之前，必须设置入站授权。入站授权对尝试通过您的 AgentCore 网关访问目标的用户进行验证。 AgentCore 支持以下类型的入站授权：
+  **JSON 网络令牌 (JWT)** — 一种用于授权的安全而紧凑的令牌。创建 JWT 后，您可以在创建网关时将其指定为授权配置。您可以在提供商[设置和配置](identity-idps.md)中使用任何身份提供商创建 JWT。
+  **IAM 身份** — 通过尝试访问网关的 AWS IAM 身份的证书进行授权。
+  **卸载的授权类型**-网关不自行做出授权决定，而是将授权转移到其他组件，例如下游目标、连接到网关的策略引擎或拦截器 Lambda 函数。此类别包括 “**仅限身份验证**” 和 “**不授权**”。有关详细信息和指导，请参阅[已卸载的入站授权](#gateway-inbound-auth-offloaded)。

**注意**  
如果您使用 AWS 管理控制台或 AgentCore CLI 创建网关，则可以在创建网关期间使用 Amazon Cognito 创建默认的入站授权配置。如果您计划使用默认的授权配置，则可以跳过此先决条件。

如果您不打算使用 Amazon Cognito 使用默认授权配置，请选择与您计划使用的授权类型相对应的主题，以了解如何进行设置：

**Topics**
+ [IAM-based 入站授权](#gateway-inbound-auth-iam)
+ [基于 JSON 网络令牌 (JWT) 的入站授权](#gateway-inbound-auth-jwt)
+ [已卸载的入站授权](#gateway-inbound-auth-offloaded)

## IAM-based 入站授权
<a name="gateway-inbound-auth-iam"></a>

IAM-based 入站授权允许您使用网关调用方的 IAM 凭证进行授权。如果您想创建一个 IAM 身份，通过该身份可以对调用您的网关的用户进行身份验证，则可以使用此选项。

 **设置 IAM-based 入站授权** 

1. 为您的网关调用者创建或使用现有 IAM 身份。

1. 创建包含以下权限的基于身份的 IAM 策略：
   +  `bedrock-agentcore:InvokeGateway`— 创建网关后，应修改此策略，使该`Resource`字段的范围限定为作为安全最佳实践而创建的网关。

1. 将策略附加到网关呼叫者身份。

 **示例策略** 

以下示例显示了您可以附加到身份的策略，以允许其调用 ID 为的网关 `my-gateway-12345` 

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowGatewayInvocation",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeGateway"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-12345"
      ]
    }
  ]
}
```

 **资源** 
+ 有关 AWS 身份和访问管理的更多信息，请参阅 [Amazon Bedrock AgentCore 的身份和访问管理](security-iam.md)。
+ 有关您可以在 IAM 策略中指定的 Amazon Bedrock AgentCore 操作、资源和条件键的更多信息，请参阅 A [mazon Bedro AgentCore ck 的操作、资源和条件键](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockagentcore.html)。

## 基于 JSON 网络令牌 (JWT) 的入站授权
<a name="gateway-inbound-auth-jwt"></a>

JSON 网络令牌 (JWT) 是一种用于授权的安全而紧凑的令牌。您可以使用支持的身份提供商创建 JWT。创建 JWT 后，您可以检索它，并在创建网关时将其指定为授权配置。

**重要**  
使用基于 JWT 令牌的入站授权将导致对 JWT 令牌的某些声明进行登录。 CloudTrail该条目包括所提供的 Web 身份令牌[的主](http://openid.net/specs/openid-connect-core-1_0.html#Claims)题。我们建议您避免在此字段中使用任何个人身份信息 (PII)。例如，您可以改用 GUID 或成对标识符，如 [OIDC 规范中所建议](http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes)的那样。

您可以使用 AgentCore CLI 来设置默认 JWT，也可以使用支持的身份提供商手动创建一个。要了解有关设置 JWT 的不同方法的更多信息，请从以下主题中进行选择：

**Topics**
+ [设置默认 JWT](#gateway-inbound-auth-jwt-default)
+ [手动设置 JWT](#gateway-inbound-auth-jwt-manual)
+ [身份验证挑战中的范围广告](#gateway-inbound-auth-jwt-scope-advertisement)
+ [使用私有 (VPC-hosted) 身份提供商](#gateway-inbound-auth-jwt-private-idp)

### 设置默认 JWT
<a name="gateway-inbound-auth-jwt-default"></a>

通过 AgentCore CLI，您可以使用 Amazon Cognito 轻松创建默认授权配置，然后可以在创建网关时使用该配置。运行时`agentcore create`，CLI 会提示您配置入站授权，并且可以自动为您设置 Amazon Cognito 用户池。

```
agentcore create
```

命令完成后， AgentCore CLI 将提供身份验证和授权信息：
+ 创建网关时，您将使用授权方配置。
+ 要在调用网关时进行入站授权，您需要使用客户端 ID、客户端密钥和令牌端点获取访问令牌。有关如何获取访问令牌的更多信息，请参阅 Amazon Cognito 开发者指南中的[使用 AgentCore 网关](gateway-using.md)或[令牌发行者终端节点](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html)中的**示例**。

### 手动设置 JWT
<a name="gateway-inbound-auth-jwt-manual"></a>

Amazon Bedrock AgentCore 支持来自所有身份提供商的 JWT。您可以在[提供商设置和配置](identity-idps.md)中查看一些示例。

在创建 JWT 的过程中，请注意以下值，如果这些值适用于您的用例，则您将在创建网关[CustomJWTAuthorizerConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CustomJWTAuthorizerConfiguration.html)时填写这些值：
+  **发现 URL** — 可以从中检索登录凭据和令牌端点的 URL。
+  **客户端 ID** — 请求令牌的客户端应用程序的公共标识符，并根据`client_id`声明进行验证。
+  **客户端密**钥-用于验证客户端应用程序检索令牌的访问权限的私钥。
+  **允许的受众** — 通过`aud`声明验证代币的预期接收者或消费者的标识符。
+  **允许的范围**-定义应用程序访问用户账户的限制的范围。有关更多信息，请参阅 [OAuth 作用域。](https://oauth.net/2/scope/)
+  **其他必需的索赔值**-根据您使用的授权方，您可能需要指定所需的自定义索赔字段和规则，以匹配索赔字段的值以进行身份验证。

您需要使用这些值来执行以下操作：
+ 通过在[授权者配置](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_AuthorizerConfiguration.html)中指定值来创建网关。
+ 获取用于调用网关的授权凭证。要了解如何获取您的证书，请查看您的身份提供商的文档。例如，如果您使用了 Amazon Cognito，请参阅亚马逊 Cognito 开发[者指南中的令牌发行者终端节点](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html)。

### 身份验证挑战中的范围广告
<a name="gateway-inbound-auth-jwt-scope-advertisement"></a>

当客户端向没有有效访问令牌的 JWT-authorized 网关发送请求时，网关会返回错误响应，其中包含通告所需的 OAuth 范围的`WWW-Authenticate`标头。这遵循 [RFC 6750 Bearer代币挑战赛](https://datatracker.ietf.org/doc/html/rfc6750#section-3)格式，使 MCP-compliant 客户能够自动发现代币获取所需的范围。

网关会根据错误返回以下响应：
+  **401 未授权**-请求没有令牌或令牌无效。标`WWW-Authenticate`题包括`resource_metadata`和`scope`参数。
+  **403 禁止** — 令牌有效，但不包含所需的范围。标`WWW-Authenticate`题包括`error="insufficient_scope"``scope`、和`resource_metadata`参数。

该`scope`值包含网关中配置为**允许范围的以空格分隔的范围**。[CustomJWTAuthorizerConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CustomJWTAuthorizerConfiguration.html)该`resource_metadata`值指向网关的 [OAuth 受保护的资源元数据](https://datatracker.ietf.org/doc/html/rfc9728)文档`/.well-known/oauth-protected-resource`，客户端可以获取该文档以发现授权服务器和支持的范围。

### 使用私有 (VPC-hosted) 身份提供商
<a name="gateway-inbound-auth-jwt-private-idp"></a>

AgentCore Gateway 支持通过托管在您的 VPC 内的身份提供商进行 JWT-based 入站授权。您可以在`privateEndpoint`上配置，使其`customJWTAuthorizer` AgentCore 能够访问您的私有 OIDC 发现、令牌和 JWKS 端点，而无需将其暴露在公共互联网上。

您的 IAM 委托人必须拥有的`iam:CreateServiceLinkedRole`权限`identity-network.bedrock-agentcore.amazonaws.com`，这样 Ident AgentCore ity 才能代表您创建`AWSServiceRoleForBedrockAgentCoreIdentity`服务相关角色（如果该角色尚不存在）。

`privateEndpoint`适用于中的域`discoveryUrl`。如果您的身份提供商为其他终端节点使用不同的域（例如，令牌或 JWKS 终端节点解析为与发现 URL 不同的域），请使用`privateEndpointOverrides`为每个其他域指定单独的私有终端节点配置。

以下示例使用托管莱迪思创建带有私有身份提供商的网关：

```
{
  "name": "my-private-idp-gateway",
  "protocolType": "MCP",
  "roleArn": "arn:aws:iam::123456789012:role/my-gateway-role",
  "authorizerType": "CUSTOM_JWT",
  "authorizerConfiguration": {
    "customJWTAuthorizer": {
      "allowedAudience": [
        "my-audience"
      ],
      "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration",
      "privateEndpoint": {
        "managedVpcResource": {
          "vpcIdentifier": "vpc-0abc123def456",
          "subnetIds": ["subnet-0abc123", "subnet-0def456"],
          "endpointIpAddressType": "IPV4",
          "securityGroupIds": ["sg-0abc123def"]
        }
      }
    }
  }
}
```

如果您的令牌或 JWKS 端点使用的域与发现 URL 不同，请为每个额外的域添加一个`privateEndpointOverrides`条目。目前，`privateEndpointOverrides`仅支持自我管理的莱迪思资源：

```
{
  ...
  "authorizerConfiguration": {
    "customJWTAuthorizer": {
      "allowedAudience": ["my-audience"],
      "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration",
      "privateEndpoint": {
        "selfManagedLatticeResource": {
          "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-abc123"
        }
      },
      "privateEndpointOverrides": [
        {
          "domain": "my-token-server.internal.example.com",
          "privateEndpoint": {
            "selfManagedLatticeResource": {
              "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-def456"
            }
          }
        }
      ]
    }
  }
}
```

有关莱迪思自我管理、跨账户设置和高级配置，请参阅[使用 VPC Lattice 连接您的 VPC 中的私](vpc-egress-private-endpoints.md)有资源。有关涵盖入站和出站私有 IdP 场景的全面指南，请参阅 Conn [ect to 私有身份提供商](identity-private-idp.md)。

## 已卸载的入站授权
<a name="gateway-inbound-auth-offloaded"></a>

使用卸载的入站授权，网关不会自行做出任何授权决定。相反，它将授权转移到另一个组件：
+ 下游目标服务，它对它收到的请求进行授权。
+ 连接到网关的策略引擎，用于评估访问策略。
+ 拦截器 Lambda 函数，可在请求到达目标之前运行您的自定义身份验证或授权逻辑。

AgentCore 提供两种卸载类型：
+  **仅限身份验证** (`AUTHENTICATE_ONLY`)-网关验证呼叫者的 SigV4 签名以对呼叫者进行身份验证，但不做出任何授权决定。请求必须经过签名，但任何经过身份验证的呼叫者都会被转发到目标。
+  **无授权** (`NONE`)-网关不执行入站身份验证或授权。请求可以未经身份验证，任何呼叫者都会被转发到目标。

无论哪种类型，您都可以决定实际在何处强制执行授权：
+  **策略引擎**-将策略引擎附加到网关以集中评估访问策略。这是生产网关的推荐模式，经常与 OAuth 一起使用。
+  **拦截器 Lambda** 函数 — 在请求到达目标之前运行您自己的身份验证或授权逻辑。当内置的入站授权选项不符合您的要求时，建议将其用于生产网关。
+  **下游目标**-让目标对其收到的请求强制授权。这对于实验和渐进式入门非常有用，例如，在**不更改运行时的身份验证和授权的情况下将网关放在现有运行时的前**面，这样你就可以在运行时继续强制执行其已经信任的身份验证的同时，逐步采用网关功能。

**重要**  
如果您通过选择`AUTHENTICATE_ONLY`或来卸载入站授权`NONE`，则 AgentCore Gateway 不会自行强制执行授权。在这种情况下，您必须将授权卸载到单独的组件（策略引擎、拦截器 Lambda 函数或下游目标），否则任何调用者都可以到达您的目标。

### Authenticate-only 授权
<a name="gateway-inbound-auth-authenticate-only"></a>

使用仅限身份验证的授权 (`AUTHENTICATE_ONLY`)，网关会验证呼叫者的签名版本 4 (Sigv4) 签名以确认其身份，但不会自行做出任何授权决定。任何经过身份验证的 IAM 委托人无论其权限如何，都可以调用网关，并且请求会被转发到目标。授权委托给下游目标服务或连接到网关的策略引擎。

**重要**  
使用`AUTHENTICATE_ONLY`，网关不强制执行任何授权策略。任何有效的 SigV4-signed 请求都将转发给目标。确保您的下游目标实现自己的授权逻辑，或者将策略引擎附加到网关以控制访问权限。如果没有目标或网关策略级别的适当授权，任何经过身份验证的呼叫者都可以访问您的后端服务。

### 没有授权
<a name="gateway-inbound-auth-none"></a>

您可以使用创建配置为无需授权的网关`authorizerType=NONE`。网关不会对传入的网关请求执行任何授权，并且该请求可以未经身份验证。

**重要**  
除非您已经实施了下面列出的所有安全最佳实践，否则请勿对生产工作负载使用无授权网关。如果您需要自定义身份验证逻辑，可以考虑使用[拦截器 Lambda](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-interceptors.html) 函数在请求到达目标之前处理身份验证。

 **安全最佳实践** 

1. 使用`bedrock-agentcore:GatewayAuthorizerType`条件密钥在组织内有选择地 allow/deny 访问以创建网关 `authorizerType=NONE` 

1. 为了方便测试，请勿使用无授权网关。它们应用于您打算公开但已实施自己的自定义限制规则和检查以确保您的公共网关可以处理未经身份验证的用户的网关

1. 请勿对可能使用敏感信息做出响应的目标使用无授权网关。尽管目标使用自己的授权配置进行配置，但最好在网关上再添加一个安全层。

### 在不更改其身份验证的情况下加载现有运行时
<a name="gateway-inbound-auth-offloaded-onboarding"></a>

当您将卸载的入站类型与匹配的出站授权类型配对，从而将呼叫者的身份转发到运行时，网关的登录就像在现有客户端上设置终端节点覆盖一样简单，无需更改身份验证：
+  **IAM 运行时** — 将`AUTHENTICATE_ONLY`入站授权与**呼叫者 IAM 证书** (`CALLER_IAM_CREDENTIALS`) 出站授权相结合。网关对 Sigv4 调用者进行身份验证，然后使用相同的调用者身份向运行时签署请求，因此运行时的现有 IAM 授权继续适用，保持不变。有关更多信息，请参阅[呼叫者 IAM 证书](gateway-building-adding-targets-authorization.md#gateway-building-adding-targets-authorization-caller-iam)。
+  **OAuth 运行时** — 将**无授权入站授权**与**令牌直通** () `JWT_PASSTHROUGH` 出站授权相结合。网关无需修改即可将入站 JWT 转发到运行时，因此运行时会像今天一样验证令牌。（Token passhrough 会转发不记名令牌，因此它需要 JWT-bearing 入站类型 — JWT 入站授权或。`NONE` 它不适用于不记名令牌 `AUTHENTICATE_ONLY` SigV4-based ，也没有不记名令牌。） 有关更多信息，请参阅[令牌直通](gateway-building-adding-targets-authorization.md#gateway-building-adding-targets-authorization-jwt-passthrough)。
**注意**  
Token passhrough (`JWT_PASSTHROUGH`) **不是**推荐的生产方法。当您不变地转发入站令牌时，网关和下游目标都接受相同的令牌，因此应严格限定其范围——例如，应将每个令牌的受众 (`aud`) 限制在目标资源范围内。推荐的模式是代替 [(OBO) 代币交换，即网关将调用者的令牌交换为目标的新的、受众范围内的](on-behalf-of-token-exchange.md)代币，而不是重播调用者的代币。使用令牌直通可以轻松进行实验、测试和入门，并迁移到 OBO 来处理长期的生产工作负载。

**警告**  
本节中的身份转发配置仅依赖下游运行时来授权请求；网关不添加自己的授权。它们旨在进行测试、实验和低中断入门。对于生产网关，请在网关强制授权 — 配置 JWT 或 IAM 入站授权、附加策略引擎或使用拦截器 Lambda 函数。为确保在您采用网关后呼叫者无法绕过网关，请参阅[强制流量通过网关](gateway-target-http-runtime.md#gateway-target-http-runtime-source-validation)。