# 為您的閘道設定傳入授權 建立閘道之前，您必須設定傳入授權。傳入授權會驗證嘗試透過 AgentCore 閘道存取目標的使用者。AgentCore 支援以下類型的傳入授權： + **JSON Web 權杖 (JWT)** – 用於授權的安全精簡權杖。建立 JWT 之後，您可以在建立閘道時將其指定為授權組態。您可以在[提供者設定和組態](identity-idps.md)中，使用任何身分提供者建立 JWT。 + **IAM 身分** – 透過嘗試存取閘道的 IAM AWS 身分憑證進行授權。 + **卸載授權類型** – 閘道不會自行做出授權決策，而是將授權卸載至另一個元件，例如下游目標、連接至閘道的政策引擎，或攔截器 Lambda 函數。此類別包含**僅驗證**和**無授權**。如需詳細資訊和指引，請參閱[卸載傳入授權](#gateway-inbound-auth-offloaded)。 **注意** 如果您使用 AWS 管理主控台或 AgentCore CLI 建立閘道，您可以在閘道建立期間使用 Amazon Cognito 建立預設傳入授權組態。如果您計劃使用預設授權組態，您可以略過此先決條件。 如果您不打算使用 Amazon Cognito 使用預設授權組態，請選取與您計劃使用的授權類型對應的主題，以了解如何設定它： **Topics** + [IAM 型傳入授權](#gateway-inbound-auth-iam) + [JSON Web Token (JWT) 型傳入授權](#gateway-inbound-auth-jwt) + [卸載傳入授權](#gateway-inbound-auth-offloaded) ## IAM 型傳入授權 IAM 型傳入授權可讓您使用閘道發起人的 IAM 憑證進行授權。如果您想要建立 IAM 身分，呼叫閘道的使用者可以透過該身分進行身分驗證，您可以使用此選項。 **設定以 IAM 為基礎的傳入授權** 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 Identity and Access Management 的詳細資訊，請參閱 [Amazon Bedrock AgentCore 的 Identity and Access Management](security-iam.md)。 + 如需您可以在 IAM 政策中指定的 Amazon Bedrock AgentCore 動作、資源和條件金鑰的詳細資訊，請參閱 [Amazon Bedrock AgentCore 的動作、資源和條件金鑰](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockagentcore.html)。 ## JSON Web Token (JWT) 型傳入授權 JSON Web 權杖 (JWT) 是用於授權的安全精簡權杖。您可以使用支援的身分提供者建立 JWT。建立 JWT 之後，您可以在建立閘道時擷取它，並將其指定為授權組態。 **重要** 根據 JWT 權杖使用傳入授權會導致在 CloudTrail 中記錄 JWT 權杖的一些宣告。項目包含所提供 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。若要進一步了解設定 JWT 的不同方法，請從下列主題中選取 ： **Topics** + [設定預設 JWT](#gateway-inbound-auth-jwt-default) + [手動設定 JWT](#gateway-inbound-auth-jwt-manual) + [身分驗證挑戰中的範圍公告](#gateway-inbound-auth-jwt-scope-advertisement) + [使用私有 (VPC 託管） 身分提供者](#gateway-inbound-auth-jwt-private-idp) ### 設定預設 JWT 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 Amazon Bedrock AgentCore 支援來自所有身分提供者JWTs。您可以在[提供者設定和組態](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，請參閱[《Amazon Cognito 開發人員指南》中的字符發行者端點](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html)。 Amazon Cognito ### 身分驗證挑戰中的範圍公告 當用戶端將請求傳送至沒有有效存取權杖的 JWT 授權閘道時，閘道會傳回錯誤回應，其中包含公告所需 OAuth 範圍的`WWW-Authenticate`標頭。這遵循 [RFC 6750 承載權杖挑戰](https://datatracker.ietf.org/doc/html/rfc6750#section-3)格式，並讓 MCP 相容用戶端自動探索權杖擷取所需的範圍。 閘道會根據錯誤傳回下列回應： + **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 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) 文件`/.well-known/oauth-protected-resource`，用戶端可以擷取這些文件來探索授權伺服器和支援的範圍。 ### 使用私有 (VPC 託管） 身分提供者 AgentCore Gateway 支援使用 VPC 內託管的身分提供者進行 JWT 型傳入授權。您可以在 `privateEndpoint`上設定 `customJWTAuthorizer`，讓 AgentCore 能夠到達您的私有 OIDC 探索、字符和 JWKS 端點，而不會將其公開至公有網際網路。 您的 IAM 主體必須擁有 的 `iam:CreateServiceLinkedRole` 許可`identity-network.bedrock-agentcore.amazonaws.com`，以便 AgentCore Identity 可以在服務`AWSServiceRoleForBedrockAgentCoreIdentity`連結角色不存在時代表您建立該角色。 `privateEndpoint` 適用於 中的網域`discoveryUrl`。如果您的身分提供者對其他端點使用不同的網域 （例如，字符或 JWKS 端點解析為與探索 URL 不同的網域），請使用 `privateEndpointOverrides`為每個額外的網域指定單獨的私有端點組態。 下列範例使用 受管 Lattice 建立具有私有身分提供者的閘道： ``` { "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`僅支援自我管理的 Lattice 資源： ``` { ... "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" } } } ] } } } ``` 如需自我管理的 Lattice、跨帳戶設定和進階組態，請參閱[使用 VPC Lattice 連線至 VPC 中的私有資源](vpc-egress-private-endpoints.md)。如需涵蓋傳入和傳出私有 IdP 案例的完整指南，請參閱[連線至私有身分提供者](identity-private-idp.md)。 ## 卸載傳入授權 透過卸載傳入授權，閘道不會自行做出任何授權決策。相反地，它會將授權卸載至另一個元件： + 下游目標服務，授權其收到的請求。 + 連接至閘道的政策引擎，可評估存取政策。 + 攔截器 Lambda 函數，在請求到達您的目標之前執行您的自訂身分驗證或授權邏輯。 AgentCore 提供兩種卸載類型： + **僅限驗證** (`AUTHENTICATE_ONLY`) – 閘道會驗證發起人的 SigV4 簽章以驗證發起人，但不會做出授權決策。必須簽署請求，但任何已驗證的發起人都會轉送至目標。 + **無授權** (`NONE`) – 閘道不會執行傳入身分驗證或授權。請求可以未經驗證，任何發起人都會轉送到目標。 使用任一類型時，您可以決定授權實際強制執行的位置： + **政策引擎** – 將政策引擎連接至閘道，以集中評估存取政策。這是生產閘道的建議模式，經常與 OAuth 搭配使用。 + **Interceptor Lambda 函數** – 在請求到達您的目標之前執行您自己的身分驗證或授權邏輯。當內建傳入授權選項不符合您的需求時，建議用於生產閘道。 + **下游目標** – 讓目標對其收到的請求強制執行授權。這對於實驗和漸進式加入非常有用，例如，在不**變更執行時間的身分驗證和授權的情況下，將**閘道放在現有執行時間前面，因此您可以在執行時間繼續強制執行其信任的身分驗證時逐步採用閘道功能。 **重要** 如果您透過選擇 `AUTHENTICATE_ONLY`或 卸載傳入授權`NONE`，AgentCore Gateway 不會自行強制執行授權。在此案例中，您必須將授權卸載至個別元件：政策引擎、攔截器 Lambda 函數或下游目標，否則任何發起人都可以到達您的目標。 ### 驗證限定授權 透過僅驗證授權 (`AUTHENTICATE_ONLY`)，閘道會驗證發起人的 Signature 第 4 版 (SigV4) 簽章，以確認其身分，但不會自行做出任何授權決定。任何已驗證的 IAM 主體都可以叫用閘道，無論其許可為何，而且請求會轉送到目標。授權會委派給下游目標服務或連接到閘道的政策引擎。 **重要** 使用 時`AUTHENTICATE_ONLY`，閘道不會強制執行任何授權政策。任何有效的 SigV4-signed請求都會轉送到目標。確保您的下游目標實作自己的授權邏輯，或將政策引擎連接到閘道以控制存取。如果沒有目標或閘道政策層級的適當授權，任何已驗證的呼叫者都可以連線到您的後端服務。 ### 無授權 您可以使用 建立在未經授權的情況下設定的閘道`authorizerType=NONE`。閘道不會對傳入的閘道請求執行任何授權，而且請求可以未經驗證。 **重要** 除非您已實作下列所有安全最佳實務，否則請勿對生產工作負載使用無授權閘道。如果您需要自訂身分驗證邏輯，請考慮在請求到達目標之前使用[攔截器 Lambda 函數](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-interceptors.html)來處理身分驗證。 **安全最佳實務** 1. 使用 `bedrock-agentcore:GatewayAuthorizerType` 條件金鑰選擇性地允許/拒絕組織內的存取，以使用 建立閘道 `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 承載傳入類型：JWT 傳入授權或 `NONE`。 它不適用於 `AUTHENTICATE_ONLY`，它是以 SigV4-based且沒有承載字符）。如需詳細資訊，請參閱[字符傳遞](gateway-building-adding-targets-authorization.md#gateway-building-adding-targets-authorization-jwt-passthrough)。 **注意** 權杖傳遞 (`JWT_PASSTHROUGH`) **不是**建議的生產方法。當您轉送未變更的傳入權杖時，閘道和下游目標都會接受相同的權杖，因此應該受到嚴格範圍限制，例如，每個權杖的受眾 (`aud`) 應該僅限於預期的資源。建議的模式是[on-behalf-of(OBO) 權杖交換](on-behalf-of-token-exchange.md)，其中閘道會將發起人的權杖交換為目標的全新對象範圍權杖，而不是重播發起人的權杖。使用權杖傳遞輕鬆實驗、測試和加入，並針對長期生產工作負載移至 OBO。 **警告** 本節中的身分轉送組態僅依賴下游執行時間來授權請求；閘道不會新增自己的授權。它們適用於測試、實驗和低中斷上線。對於生產閘道，在閘道強制執行授權 — 設定 JWT 或 IAM 傳入授權、連接政策引擎，或使用攔截器 Lambda 函數。若要確保呼叫者一旦採用閘道就無法略過閘道，請參閱[透過閘道強制執行流量](gateway-target-http-runtime.md#gateway-target-http-runtime-source-validation)。