本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 为您的网关设置入站授权 在创建网关之前，必须设置入站授权。入站授权会验证尝试通过您的 AgentCore 网关访问目标的用户。 AgentCore 支持以下类型的入站授权： + **JSON 网络令牌 (JWT) ** — 一种用于授权的安全而紧凑的令牌。创建 JWT 后，您可以在创建网关时将其指定为授权配置。您可以在提供商设置和配置[中使用任何身份提供商创建 JWT。](identity-idps.md) + **IAM 身份 ** — 通过 Amazon IAM 身份的证书授权尝试访问网关。 + **卸载的授权类型 ** — 网关不自行做出授权决定，而是将授权卸载到另一个组件，例如下游目标、连接到网关的策略引擎或拦截器 Lambda 函数。此类别包括 “仅限**身份验证” ** 和 “**无授权**”。有关详细信息和指南，请参阅[卸载入站授权](#gateway-inbound-auth-offloaded)。 **注意** 如果您使用 Amazon 管理控制台或 AgentCore CLI 创建网关，则可以在网关创建期间使用 Amazon Cognito 创建默认的入站授权配置。如果您计划使用默认授权配置，则可以跳过此先决条件。 如果您不打算使用 Amazon Cognito 使用默认授权配置，请选择与您计划使用的授权类型相对应的主题来学习如何进行设置： **Topics** + [IAM-based 入站授权](#gateway-inbound-auth-iam) + [基于 JSON Web 令牌 (JWT) 的入站授权](#gateway-inbound-auth-jwt) + [已卸载的入站授权](#gateway-inbound-auth-offloaded) ## IAM-based 入站授权 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" ] } ] } ``` **资源** + 有关 Amazon 身份和访问管理的更多信息，请参阅 Amazon Bedrock AgentCore [ 的](security-iam.md)身份和访问管理。 + 有关您可以在 IAM 政策中指定的 Amazon Bedrock AgentCore 操作、资源和条件密钥的更多信息，请参阅 Amazon Bedro AgentCore [ ck 的](https://docs.amazonaws.cn/service-authorization/latest/reference/list_amazonbedrockagentcore.html)操作、资源和条件密钥。 ## 基于 JSON Web 令牌 (JWT) 的入站授权 JSON 网络令牌 (JWT) 是一种安全且紧凑的令牌，用于授权。您可以使用支持的身份提供商创建 JWT。创建 JWT 后，您可以检索它并在创建网关时将其指定为授权配置。 **重要** 使用基于 JWT 令牌的入站授权将导致将 JWT 令牌的某些声明记录在案。 CloudTrail该条目包括[所提供的网络身份令牌](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 授权器 使用支持的身份提供商创建应用程序和客户端。有关亚马逊 Cognito 的示例，请参阅亚马逊 Cogn [ ito ](identity-getting-started-cognito.md) 入门。记下 OIDC 发现 URL 和客户端 ID。 在 AgentCore 项目目录中运行以下命令： ``` agentcore add gateway \ --name MyGateway \ --protocol-type MCP \ --authorizer-type CUSTOM_JWT \ --discovery-url \ --allowed-clients ``` AgentCore CLI 使用现有的 OIDC 配置；它不创建身份提供者资源。要调用网关，请从您的提供商处获取访问令牌。对于亚马逊 Cognito，请参阅[亚马逊 Cognito 开发者](https://docs.amazonaws.cn/cognito/latest/developerguide/token-endpoint.html)指南中的代币发行者终端节点。 ### 手动设置 JWT 亚马逊 Bedrock AgentCore 支持来自所有身份提供商的 JWT。您可以在[提供商设置和配置中查看一些示例](identity-idps.md)。 在创建 JWT 的过程中，请注意以下值，如果这些值适用于您的用例，您将在创建网关[CustomJWTAuthorizerConfiguration](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CustomJWTAuthorizerConfiguration.html)时填写这些值： + **发现 URL ** — 可以从中检索登录凭据和令牌端点的 URL。 + **客户端 ID ** — 请求令牌的客户端应用程序的公共标识符，根据`client_id`索赔进行验证。 + **客户端密钥 **-用于验证客户端应用程序检索令牌的访问权限的私钥。 + **允许的受众 **-通过`aud`声明验证代币的预期接收者或消费者的标识符。 + **允许的范围 **-定义应用程序访问用户帐户的限制的范围。有关更多信息，请参阅 [ OAuth 范围。](https://oauth.net/2/scope/) + **其他必需的声明值 **-根据您使用的授权方，您可能需要指定所需的自定义声明字段和规则，以使声明字段值与身份验证相匹配。 你需要这些值来执行以下操作： + 通过在[授权者配置](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_AuthorizerConfiguration.html)中指定值来创建网关。 + 获取授权凭证以调用网关。要了解如何获取您的证书，请查看身份提供商的文档。例如，如果您使用亚马逊 Cognito，请参阅[亚马逊 Cognito 开发人员指南](https://docs.amazonaws.cn/cognito/latest/developerguide/token-endpoint.html)中的代币发行者终端节点。 ### 身份验证质询中的范围广告 当客户端向没有有效访问令牌的 JWT-authorized 网关发送请求时，网关会返回带有标头的错误响应，`WWW-Authenticate`标头会通告所需的 OAuth 范围。这遵循 [ 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.amazonaws.cn/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) 身份提供商 AgentCore 网关支持向您的 VPC 内托管的身份提供商进行 JWT-based 入站授权。您可以在`privateEndpoint`上进行配置，使其`customJWTAuthorizer` AgentCore 能够访问您的私有 OIDC 发现、令牌和 JWKS 终端节点，而无需将其暴露给公共互联网。 您的 IAM 委托人必须具有`iam:CreateServiceLinkedRole`权限`identity-network.bedrock-agentcore.amazonaws.com`，这样，如果`AWSServiceRoleForBedrockAgentCoreIdentity`服务相关角色尚不存在，Id AgentCore entity 可以代表您创建该角色。 `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 场景的综合指南，请参阅[连接私有身份提供商](identity-private-idp.md)。 ## 已卸载的入站授权 在卸载入站授权后，网关不会自行做出任何授权决定。相反，它将授权转移到另一个组件： + 下游目标服务，它对接收到的请求进行授权。 + 连接到网关的策略引擎，用于评估访问策略。 + 拦截器 Lambda 函数，在请求到达目标之前运行您的自定义身份验证或授权逻辑。 AgentCore 提供两种卸载类型： + **仅限身份验证 ** (`AUTHENTICATE_ONLY`) — 网关验证调用者的 SigV4 签名以对呼叫者进行身份验证，但不做出授权决定。请求必须经过签名，但任何经过身份验证的呼叫者都将转发到目标。 + **无授权 ** (`NONE`) — 网关不执行入站身份验证或授权。请求可以未经身份验证，任何呼叫者都会被转发到目标。 无论使用哪种类型，您都可以决定授权的实际执行地点： + **策略引擎 **-将策略引擎连接到网关，以集中评估访问策略。这是生产网关的推荐模式，经常与 OAuth 一起使用。 + **拦截器 Lambda 函数 ** — 在请求到达目标之前，运行您自己的身份验证或授权逻辑。当内置的入站授权选项不符合您的要求时，建议生产网关使用此方法。 + **下游目标 **-让目标对其收到的请求强制授权。这对于实验和渐进式入门非常有用，例如，在**不更改运行时的身份验证和授权**的情况下将网关置于现有运行时的前面，因此您可以逐步采用网关功能，同时运行时继续执行其已经信任的身份验证。 **重要** 如果您通过选择`AUTHENTICATE_ONLY`或来卸载入站授权`NONE`，则 AgentCore Gateway 不会自行强制授权。在这种情况下，您必须将授权转移到单独的组件（策略引擎、拦截器 Lambda 函数或下游目标），否则任何调用者都可以到达您的目标。 ### Authenticate-only 授权 使用仅限身份验证的授权 (`AUTHENTICATE_ONLY`)，网关会验证呼叫者的签名版本 4 (SigV4) 签名以确认其身份，但不会自行做出任何授权决定。任何经过身份验证的 IAM 委托人无论权限如何都可以调用网关，并且请求会转发到目标。授权委托给下游目标服务或连接到网关的策略引擎。 **重要** 使用`AUTHENTICATE_ONLY`，网关不强制执行任何授权策略。任何有效的 SigV4-signed 请求都将转发给目标。确保您的下游目标实现自己的授权逻辑，或将策略引擎附加到网关以控制访问权限。如果没有目标或网关策略级别的适当授权，任何经过身份验证的调用者都可以访问您的后端服务。 ### 没有授权 您可以使用创建未经授权配置的网关`authorizerType=NONE`。网关不会对传入的网关请求执行任何授权，并且该请求可以未经身份验证。 **重要** 除非您已经实施了下面列出的所有安全最佳实践，否则不要对生产工作负载使用无授权网关。如果您需要自定义身份验证逻辑，可以考虑使用[拦截器 Lambda 函数](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/gateway-interceptors.html)在请求到达目标之前处理身份验证。 **安全最佳实践 ** 1. 使用`bedrock-agentcore:GatewayAuthorizerType`条件密钥在组织内有选择地 allow/deny 访问以创建网关 `authorizerType=NONE` 1. 为了方便测试，请勿使用无授权网关。它们应用于您打算公开但已实施自定义限制规则和检查的网关，以确保您的公共网关可以处理未经身份验证的用户 1. 不要对可能使用敏感信息响应的目标使用无授权网关。尽管目标是使用自己的授权配置配置配置的，但最好在网关上添加另一个安全层。 ### 在不更改其身份验证的情况下启动现有运行时 当您将卸载的入站类型与匹配的出站授权类型配对（将呼叫者的身份转发到运行时）时，网关的入门可以像在现有客户端上设置终端节点覆盖一样简单，无需更改身份验证： + **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 转发到运行时，因此运行时会像今天一样验证令牌。（令牌直通会转发持有者令牌，因此它需要 JWT-bearing 入站类型——JWT 入站授权或。`NONE`它不适用于持有者代币 `AUTHENTICATE_ONLY` SigV4-based ，也没有持有者代币。） 有关更多信息，请参阅[令牌直通](gateway-building-adding-targets-authorization.md#gateway-building-adding-targets-authorization-jwt-passthrough)。 **注意** Token passthrough (`JWT_PASSTHROUGH`) ** 不是**推荐的生产方法。当您不变地转发入站令牌时，网关和下游目标都接受相同的令牌，因此应严格限制其范围——例如，每个代币的 audience (`aud`) 应仅限于预期资源。推荐的模式是代表（O [ BO）代币交换](on-behalf-of-token-exchange.md)，即网关将呼叫者的代币交换为目标的新的、受众范围的代币，而不是重播呼叫者的代币。使用代币直通可以轻松进行实验、测试和入门，并迁移到 OBO 来处理长期生产工作负载。 **警告** 本节中的身份转发配置仅依赖下游运行时来授权请求；网关没有添加自己的授权。它们旨在用于测试、实验和低干扰的入职培训。对于生产网关，在网关上强制授权 — 配置 JWT 或 IAM 入站授权、连接策略引擎或使用拦截器 Lambda 函数。为确保呼叫者在采用网关后无法绕过网关，请参阅[强制通过网关](gateway-target-http-runtime.md#gateway-target-http-runtime-source-validation)进行流量。