AWS bedrock-agentcore documentation change
Summary
Restructured outbound authorization documentation to clarify IAM role, OAuth 2LO, and API key methods. Added target type compatibility matrix, service role automation details, and concrete IAM policy examples for secure credential access.
Security assessment
The changes add detailed security configuration guidance (e.g., IAM policies with least-privilege permissions for secrets access) but do not address a specific disclosed vulnerability. The focus is on improving documentation of secure authorization methods rather than patching a security flaw.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-outbound-auth.md b/bedrock-agentcore/latest/devguide/gateway-outbound-auth.md index 1e8930cb2..43a920bcd 100644 --- a//bedrock-agentcore/latest/devguide/gateway-outbound-auth.md +++ b//bedrock-agentcore/latest/devguide/gateway-outbound-auth.md @@ -5 +5 @@ -Creating an Outbound AuthSetting up credential providers for Outbound Auth +Set up IAM-based outbound authorization with a gateway service roleSet up outbound authorization with an OAuth clientSet up outbound authorization with an API key @@ -7 +7 @@ Creating an Outbound AuthSetting up credential providers for Outbound Auth -Amazon Bedrock AgentCore is in preview release and is subject to change. +# Set up outbound authorization for your gateway @@ -9 +9 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -# Setting up Outbound Auth +Outbound authorization lets Amazon Bedrock AgentCore gateways securely access gateway targets on behalf of users that were authenticated and authorized during inbound authorization. @@ -11 +11 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -Outbound authorization lets Amazon Bedrock AgentCore gateways securely access gateway targets on behalf of users authenticated and authorized during [Inbound Auth](./gateway-inbound-auth.html). For more information on authorization, see [Prerequisites to set up a gateway](./gateway-prerequisites-permissions.html). +AgentCore Gateway supports the following types of outbound authorization: @@ -13,47 +13 @@ Outbound authorization lets Amazon Bedrock AgentCore gateways securely access ga -Similar to AWS resources or Lambda functions, you authenticate by using IAM credentials. With other resources, you can use OAuth 2LO or API keys. OAuth 2LO is a type of OAuth 2.0 where a client application accesses resources on it's behalf, instead of on behalf of the user. For more information, see [OAuth 2LO](https://oauth.net/2/). - -First, you register your client application with third-party providers and then create an outbound authorization with the client ID and secret. Then configure a gateway target with the outbound authorization that you created. - -###### Topics - - * Creating an Outbound Auth - - * Setting up credential providers for Outbound Auth - - - - -## Creating an Outbound Auth - -When a user wants to access Gateway target, the gateway confirms that the access tokens (provided by Incoming Auth) are valid and if so, allows access to the target. - -Console - - -###### To create an Outbound Auth - - 1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home#](https://console.aws.amazon.com/bedrock-agentcore/home#). - - 2. In the left navigation pane, choose **Identity**. - - 3. In **Outbound Auth** choose **Add OAuth client/API Key** then select the outbound authorization that you want to create. - - 4. If you chose OAuth client, do the following: - - 1. Enter a name for the OAuth client - - 2. If an included provider is the provider that you want to use, choose that provider. Then enter the client ID and client secret. - - 3. Choose **Add OAuth Client** - - 5. If you chose **Add API Key** , enter name and the API key that you want to use, and then choose **Add**. - - - - -SDK - - - * Use the `CreateOauth2CredentialProvider` operation to add an OAuth outbound authorization. - - * Use the `CreateApiKeyCredentialProvider` operation to add an API Key outbound authorization. + * **IAM-based outbound authorization** – Use the [gateway service role](./gateway-prerequisites-permissions.html#gateway-execution-permissions) to authenticate access to the gateway target with [AWS Signature Version 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html). @@ -60,0 +15 @@ SDK + * **2-legged OAuth (OAuth 2LO)** – An open authorization framework that allows a client application to access resources on the application's behalf, rather than on behalf of the user. For more information, see [OAuth 2.0](https://oauth.net/2/). You can use OAuth 2LO with a [built-in identity provider](./identity-idps.html) or with a custom one. @@ -61,0 +17 @@ SDK + * **API key** – Use the AgentCore service to generate an API key to authenticate access to the gateway target. @@ -64 +19,0 @@ SDK -For more information, see Setting up credential providers for Outbound Auth. @@ -66 +20,0 @@ For more information, see Setting up credential providers for Outbound Auth. -## Setting up credential providers for Outbound Auth @@ -68 +22 @@ For more information, see Setting up credential providers for Outbound Auth. -This section provides step-by-step instructions for setting up credential providers for Gateway Outbound Auth. These credential providers allow your gateway to authenticate with target services on behalf of users. For more information on setting up credential providers, see [Manage credential providers with AgentCore Identity](./identity-outbound-credential-provider.html). +The type of outbound authorization that you can set up is dependent on the gateway target type to which you authorize access: @@ -70 +24,5 @@ This section provides step-by-step instructions for setting up credential provid -Choose your credential provider type from the tabs below: +Target Type | Iam Role | Oauth Client | Api Key +---|---|---|--- +Lambda function | Yes | No | No +OpenAPI schema | No | Yes | Yes +Smithy schema | Yes | No | No @@ -72 +30 @@ Choose your credential provider type from the tabs below: -IAM Role-based authentication (GATEWAY_IAM_ROLE) +###### Note @@ -73,0 +32 @@ IAM Role-based authentication (GATEWAY_IAM_ROLE) +You can skip this prerequisite if you plan to use the AWS Management Console or AgentCore starter toolkit to create your gateway. If you use either of these tools, you can let AgentCore automatically create a service role for you with the necessary permissions to access the target. Each time you add a target, the necessary permissions will be automatically attached to your service role. @@ -75 +34 @@ IAM Role-based authentication (GATEWAY_IAM_ROLE) -When the tools registered with the gateway are AWS resources like Lambda functions, the Gateway's execution role needs appropriate permissions to access those resources. +Select a topic to learn how to set up that type of authorization: @@ -77,15 +36 @@ When the tools registered with the gateway are AWS resources like Lambda functio -For AWS services, use the `GATEWAY_IAM_ROLE` credential provider type in your target configuration while creating the gateway target: - - - credentialProviderConfigurations=[{ - "credentialProviderType": "GATEWAY_IAM_ROLE" - }] - - -This uses the Gateway's execution role to authenticate with AWS services. - -The execution role must have permissions to access the respective resource. For example, to invoke a Lambda function, the execution role needs the `lambda:InvokeFunction` permission: - -Additionally, your Lambda function needs a resource-based policy that allows the Gateway's execution role to invoke it: - -You can add this policy using the AWS CLI: +###### Topics @@ -92,0 +38 @@ You can add this policy using the AWS CLI: + * Set up IAM-based outbound authorization with a gateway service role @@ -94,6 +40 @@ You can add this policy using the AWS CLI: - aws lambda add-permission \ - --function-name "YourLambdaFunction" \ - --statement-id "GatewayInvoke" \ - --action "lambda:InvokeFunction" \ - --principal "arn:aws:iam::{{accountId}}:role/YourGatewayExecutionRole" \ - --region {{region}} + * Set up outbound authorization with an OAuth client @@ -100,0 +42 @@ You can add this policy using the AWS CLI: + * Set up outbound authorization with an API key @@ -102 +43,0 @@ You can add this policy using the AWS CLI: -API Key authentication (API_KEY) @@ -105 +45,0 @@ API Key authentication (API_KEY) -API Key credential providers allow your gateway to authenticate with services that use API keys for authentication. Follow these steps to set up an API Key credential provider: @@ -107 +47 @@ API Key credential providers allow your gateway to authenticate with services th -###### To create an API Key credential provider +## Set up IAM-based outbound authorization with a gateway service role @@ -109 +49 @@ API Key credential providers allow your gateway to authenticate with services th - * Use the following AWS CLI command to create an API Key credential provider: +IAM-based outbound authorization lets you use the gateway service role's IAM credentials to authorize with [AWS Signature Version 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html). This option lets the Amazon Bedrock AgentCore service to authenticate to gateway targets on your gateway callers' behalf. @@ -111,4 +51 @@ API Key credential providers allow your gateway to authenticate with services th - aws acps create-api-key-credential-provider \ - --region us-east-1 \ - --credential-provider-name api-key-credential-provider \ - --api-key <API_KEY_VALUE> +If you use this option, you don't need to do any additional set up. The service role's credentials will be used for authentication during gateway invocation. @@ -115,0 +53 @@ API Key credential providers allow your gateway to authenticate with services th +## Set up outbound authorization with an OAuth client @@ -117 +55 @@ API Key credential providers allow your gateway to authenticate with services th -Note the provider ARN from the response. It will have a format similar to: +To set up outbound authorization with an OAuth client, you use the AgentCore Identity service and specify client credentials that you receive from creating a client in either a built-in identity provider (see [Provider setup and configuration](./identity-idps.html) or a custom identity provider. @@ -119 +57 @@ Note the provider ARN from the response. It will have a format similar to: - arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk +###### To set up outbound authorization with an OAuth client @@ -120,0 +59 @@ Note the provider ARN from the response. It will have a format similar to: + 1. Register your client application with a supported third-party provider. @@ -121,0 +61 @@ Note the provider ARN from the response. It will have a format similar to: + 2. You'll receive a client ID, client secret, and possibly other values that you'll reference when you set up the outbound authorization. @@ -122,0 +63 @@ Note the provider ARN from the response. It will have a format similar to: + 3. Follow one of the steps below, depending on your requirements: @@ -123,0 +65 @@ Note the provider ARN from the response. It will have a format similar to: + * To configure outbound authorization in the console using a built-in identity provider, follow the steps at [Add OAuth client using included provider](./identity-add-oauth-client-included.html). @@ -125 +67 @@ Note the provider ARN from the response. It will have a format similar to: -When creating or updating a gateway target, you can use this credential provider in the credential provider configuration: + * To configure outbound authorization in the console using a custom identity provider, follow the steps at [Add OAuth client using custom provider](./identity-add-oauth-client-custom.html). @@ -126,0 +69 @@ When creating or updating a gateway target, you can use this credential provider + * To configure outbound authorization using the API, send a [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html) with one of the [AgentCore control plane endpoints](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp). For examples, see Examples for setting OAuth client authorization. @@ -128,10 +71 @@ When creating or updating a gateway target, you can use this credential provider - credentialProviderConfigurations=[{ - "credentialProviderType": "API_KEY", - "credentialProvider": { - "apiKeyCredentialProvider": { - "providerArn": "{{credential-provider-arn}}", - "credentialLocation": "<either HEADER OR BODY, in this case HEADER>", - "credentialParameterName": "<name of the parameter, in this case: X-Subscription-Token>" - } - } - }] +###### Note @@ -138,0 +73 @@ When creating or updating a gateway target, you can use this credential provider +The shape of the JSON object that the `oauth2ProviderConfigInput` field maps to depends on the provider that you use and must be congruent with the `credentialProviderVendor` value that you specify. To see examples of different configurations for different credential providers, see the outbound authorization examples in your credential provider of choice at [Provider setup and configuration](./identity-idps.html). @@ -140,3 +75 @@ When creating or updating a gateway target, you can use this credential provider -The `credentialLocation` can be either `HEADER` or `QUERY_PARAMETER`, depending on how the target service expects to receive the API key. - -The execution role needs permission to access the API key: + 4. Take note of the generated credential ARN (`credentialProviderArn` in the API) and the AWS Secrets Manager secret ARN (`secretArn` in the API). You'll use these values when you create your gateway target. @@ -143,0 +77 @@ The execution role needs permission to access the API key: + 5. (If you're using a custom gateway service role) Attach the following identity-based policy to your gateway service role: @@ -146 +80,4 @@ The execution role needs permission to access the API key: - "Sid": "GetResourceApiKey", + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "GetWorkloadAccessToken", @@ -149 +86 @@ The execution role needs permission to access the API key: - "bedrock-agentcore:GetResourceApiKey" + "bedrock-agentcore:GetWorkloadAccessToken", @@ -152 +89,2 @@ The execution role needs permission to access the API key: - "{{credential-provider-arn}}" + "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-*" @@ -154,6 +92 @@ The execution role needs permission to access the API key: - } - - -For API Key authentication, if the credentials are stored in AWS Secrets Manager, the execution role also needs permission to access those secrets: - - + }, @@ -161 +94 @@ For API Key authentication, if the credentials are stored in AWS Secrets Manager