AWS bedrock-agentcore documentation change
Summary
Restructured inbound authorization documentation to focus on IAM-based and JWT-based authorization methods. Removed detailed Cognito/Auth0 setup steps and added security best practices for IAM policies and JWT usage.
Security assessment
The changes add documentation about IAM-based authorization and emphasize security best practices (e.g., scoping IAM policies to specific gateways). It also retains warnings about avoiding PII in JWT tokens logged to CloudTrail. While these are security improvements, there's no evidence of addressing a specific existing vulnerability.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-inbound-auth.md b/bedrock-agentcore/latest/devguide/gateway-inbound-auth.md index eb0f6c3e6..ddf7fff59 100644 --- a//bedrock-agentcore/latest/devguide/gateway-inbound-auth.md +++ b//bedrock-agentcore/latest/devguide/gateway-inbound-auth.md @@ -5 +5 @@ -Setting up identity providers for Inbound Auth +IAM-based inbound authorizationJSON Web Token (JWT)-based inbound authorization @@ -7 +7 @@ Setting up identity providers for Inbound Auth -Amazon Bedrock AgentCore is in preview release and is subject to change. +# Set up inbound authorization for your gateway @@ -9 +9 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -# Setting up inbound Auth +Before you create your gateway, you must set up inbound authorization. Inbound authorization validates users who attempt to access targets through your AgentCore gateway. AgentCore supports the following types of inbound authorization: @@ -11,35 +11 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -Before creating your Gateway, you need to set up inbound authorization to validate callers attempting to access targets through your Amazon Bedrock AgentCore Gateway. - -###### Note - -If you're using the AgentCore SDK, the Cognito EZ Auth can configure this automatically for you, so you can skip the manual inbound Auth setup. - -Inbound authorization works with OAuth authorization, where the client application must authenticate with the OAuth authorizer before using the Gateway. Your client would receive an access token which is used at runtime. - -You need to specify an OAuth discovery server and client IDs/audiences when you create the gateway. You can specify the following: - - * `Discovery Url` — String that must match the pattern `^.+/\.well-known/openid-configuration$` for OpenID Connect discovery URLs - - * At least one of the below options depending on the chosen identity provider. - - * `Allowed audiences` — List of allowed audiences for JWT tokens - - * `Allowed clients` — List of allowed client identifiers - - - - -## Setting up identity providers for Inbound Auth - -For general information about setting up different identity providers, see [Identity provider setup and configuration](./identity-idps.html). - -###### Important - -Using inbound authorization based on JWT tokens will result in logging of some claims of the JWT token in CloudTrail. The entry includes the [Subject](http://openid.net/specs/openid-connect-core-1_0.html#Claims) of the provided web identity token. We recommend that you avoid using any personally identifiable information (PII) in this field. For example, you could instead use a GUID or a pairwise identifier, as [suggested in the OIDC specification](http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes). - -Choose your preferred identity provider from the options below: - -Amazon Cognito EZ Auth with AgentCore SDK - - -You can also set up Cognito EZ Auth with the AgentCore Python SDK. This eliminates the complexity of OAuth setup. You only need to run the following command: + * **JSON Web Token (JWT)** – A secure and compact token used for authorization. After creating the JWT, you specify it as the authorization configuration when you create the gateway. You can create a JWT with any of the identity providers at [Provider setup and configuration](./identity-idps.html). @@ -46,0 +13 @@ You can also set up Cognito EZ Auth with the AgentCore Python SDK. This eliminat + * **IAM identity** – Authorizes through the credentials of the AWS IAM identity trying to access the gateway. @@ -48,9 +14,0 @@ You can also set up Cognito EZ Auth with the AgentCore Python SDK. This eliminat - # Import SDK and set up client - from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient - client = GatewayClient() - - # Retrieve the authorization configuration from the create response. When you create the gateway, specify it in the authorizer_config field - cognito_result = client.create_oauth_authorizer_with_cognito("my-gateway") - authorizer_configuration = cognito_result["authorizer_config"] - -Amazon Cognito @@ -59,9 +16,0 @@ Amazon Cognito -Amazon Cognito provides a fully managed user directory service that can be used to authenticate users for your Gateway. - -###### **To create a Cognito user pool for machine-to-machine authentication** - - 1. Create a user pool: - - aws cognito-idp create-user-pool \ - --region us-west-2 \ - --pool-name "gateway-user-pool" @@ -68,0 +18 @@ Amazon Cognito provides a fully managed user directory service that can be used +###### Note @@ -70 +20 @@ Amazon Cognito provides a fully managed user directory service that can be used - 2. Note the user pool ID from the response or retrieve it using: +If use the AWS Management Console or AgentCore starter toolkit to create your gateway, you can create a default inbound authorization configuration using Amazon Cognito during gateway creation. If you plan to use the default authorization configuration, you can skip this prerequisite. @@ -72,3 +22 @@ Amazon Cognito provides a fully managed user directory service that can be used - aws cognito-idp list-user-pools \ - --region us-west-2 \ - --max-results 60 +If you don't plan to use the default authorization configuration using Amazon Cognito, select the topic that corresponds to the type of authorization that you plan to use to learn how to set it up: @@ -75,0 +24 @@ Amazon Cognito provides a fully managed user directory service that can be used +###### Topics @@ -77 +26 @@ Amazon Cognito provides a fully managed user directory service that can be used - 3. Create a resource server for the user pool: + * IAM-based inbound authorization @@ -79,6 +28 @@ Amazon Cognito provides a fully managed user directory service that can be used - 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"}]' + * JSON Web Token (JWT)-based inbound authorization @@ -87 +30,0 @@ Amazon Cognito provides a fully managed user directory service that can be used - 4. Create a client for the user pool: @@ -89,9 +31,0 @@ Amazon Cognito provides a fully managed user directory service that can be used - 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" @@ -98,0 +33 @@ Amazon Cognito provides a fully managed user directory service that can be used +## IAM-based inbound authorization @@ -100 +35 @@ Amazon Cognito provides a fully managed user directory service that can be used -Note the client ID and client secret from the response. +IAM-based inbound authorization lets you use the gateway caller's IAM credentials for authorization. You can use this option if you want to create an IAM identity through which users that call your gateway can be authenticated. @@ -102 +37 @@ Note the client ID and client secret from the response. - 5. Create a domain for your user pool: +###### To set up IAM-based inbound authorization @@ -104,4 +39 @@ Note the client ID and client secret from the response. - aws cognito-idp create-user-pool-domain \ - --domain ${DomainPrefix} \ - --user-pool-id ${UserPoolId} \ - --region ${Region} + 1. Create or use an existing IAM identity for your gateway callers. @@ -108,0 +41 @@ Note the client ID and client secret from the response. + 2. Create an identity-based IAM policy that contains the following permissions: @@ -110 +43 @@ Note the client ID and client secret from the response. -The token endpoint from which you can retrieve the bearer token can be constructed as follows: + * `bedrock-agentcore:InvokeGateway` – After you create the gateway, you should modify this policy such that the `Resource` field is scoped to the gateway that you create as a security best practice. @@ -112 +45 @@ The token endpoint from which you can retrieve the bearer token can be construct - https://${DomainPrefix}.auth.${Region}.amazoncognito.com/oauth2/token + 3. Attach the policy to the gateway caller identity. @@ -114 +46,0 @@ The token endpoint from which you can retrieve the bearer token can be construct - 6. Construct the discovery URL for your Cognito user pool: @@ -116 +47,0 @@ The token endpoint from which you can retrieve the bearer token can be construct - https://cognito-idp.us-west-2.amazonaws.com/${UserPoolId}/.well-known/openid-configuration @@ -119 +50 @@ The token endpoint from which you can retrieve the bearer token can be construct - 7. Configure the Gateway Inbound authorization with the following values: +###### Example policy @@ -121 +52 @@ The token endpoint from which you can retrieve the bearer token can be construct - * **Discovery URL** : The URL constructed in the previous step +The following example shows a policy you could attach to an identity to allow it to invoke a gateway with the ID `my-gateway-12345` @@ -123 +53,0 @@ The token endpoint from which you can retrieve the bearer token can be construct - * **Allowed clients** : The client ID obtained when creating the user pool client @@ -125,4 +55,12 @@ The token endpoint from which you can retrieve the bearer token can be construct - authorizerConfiguration= { - "customJWTAuthorizer": { - "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/user-pool-id/.well-known/openid-configuration", - "allowedClients": ["client-id"] + { + "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" + ] @@ -129,0 +68 @@ The token endpoint from which you can retrieve the bearer token can be construct + ] @@ -131,0 +71 @@ The token endpoint from which you can retrieve the bearer token can be construct +###### Resources @@ -132,0 +73 @@ The token endpoint from which you can retrieve the bearer token can be construct + * For more information about AWS Identity and Access Management, see [Identity and access management for Amazon Bedrock AgentCore](./security-iam.html). @@ -133,0 +75 @@ The token endpoint from which you can retrieve the bearer token can be construct + * For more information about Amazon Bedrock AgentCore actions, resources, and condition keys that you can specify in IAM policies, see [Actions, resources, and condition keys for Amazon Bedrock AgentCore](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockagentcore.html). @@ -136,2 +77,0 @@ The token endpoint from which you can retrieve the bearer token can be construct -Auth0 - @@ -139 +78,0 @@ Auth0 -Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these steps to set up Auth0 and obtain the necessary configuration values: @@ -141 +80 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these -###### **To set up Auth0 for Gateway authentication** +## JSON Web Token (JWT)-based inbound authorization @@ -143 +82 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these - 1. Create an API in Auth0: +A JSON Web Token (JWT) is a secure and compact token used for authorization. You can create a JWT with a supported identity provider. After you create a JWT, you can retrieve it and specify it as the authorization configuration when you create the gateway. @@ -145,7 +84 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these - 1. Log in to your Auth0 dashboard. - - 2. Navigate to "APIs" and click "Create API". - - 3. Provide a name and identifier for your API (e.g., "gateway-api"). - - 4. Select the signing algorithm (RS256 recommended). +###### Important @@ -153 +86 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these - 5. Click "Create". +Using inbound authorization based on JWT tokens will result in logging of some claims of the JWT token in CloudTrail. The entry includes the [Subject](http://openid.net/specs/openid-connect-core-1_0.html#Claims) of the provided web identity token. We recommend that you avoid using any personally identifiable information (PII) in this field. For example, you could instead use a GUID or a pairwise identifier, as [suggested in the OIDC specification](http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes). @@ -155 +88 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these - 2. Configure API scopes: +You can use the AgentCore starter toolkit to set up a default JWT, or create one manually with a supported identity provider. To learn more about different methods for setting up a JWT, select from the following topics: @@ -157 +90 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these - 1. In the API settings, go to the "Scopes" tab. +###### Topics @@ -159 +92 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these - 2. Add scopes such as "invoke:gateway" and "read:gateway". + * Set up a default JWT @@ -161 +94 @@ Auth0 can be used as an identity provider for Gateway Inbound Auth. Follow these - 3. Create an application: