Set up outbound authorization for your gateway

Outbound authorization lets Amazon Bedrock AgentCore gateways securely access gateway targets on behalf of users that were authenticated and authorized during inbound authorization.

AgentCore Gateway supports the following types of outbound authorization:

• IAM-based outbound authorization – Use the gateway service role to authenticate access to the gateway target with AWS Signature Version 4 (Sig V4).

• 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. You can use OAuth 2LO with a built-in identity provider or with a custom one.

• API key – Use the AgentCore service to generate an API key to authenticate access to the gateway target.

The type of outbound authorization that you can set up is dependent on the gateway target type to which you authorize access:

Target Type	Iam Role	Oauth Client	Api Key
Lambda function	Yes	No	No
OpenAPI schema	No	Yes	Yes
Smithy schema	Yes	No	No

Note

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.

Select a topic to learn how to set up that type of authorization:

Set up IAM-based outbound authorization with a gateway service role

IAM-based outbound authorization lets you use the gateway service role's IAM credentials to authorize with AWS Signature Version 4 (Sig V4). This option lets the Amazon Bedrock AgentCore service to authenticate to gateway targets on your gateway callers' behalf.

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.

Set up outbound authorization with an OAuth client

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 or a custom identity provider.

To set up outbound authorization with an OAuth client

1. Register your client application with a supported third-party provider.

2. You'll receive a client ID, client secret, and possibly other values that you'll reference when you set up the outbound authorization.

3. Follow one of the steps below, depending on your requirements:

   • To configure outbound authorization in the console using a built-in identity provider, follow the steps at Add OAuth client using included provider.

   • To configure outbound authorization in the console using a custom identity provider, follow the steps at Add OAuth client using custom provider.

   • To configure outbound authorization using the API, send a CreateOauth2CredentialProvider with one of the AgentCore control plane endpoints. For examples, see Examples for setting OAuth client authorization.

     Note

     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.

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.

5. (If you're using a custom gateway service role) Attach the following identity-based policy to your gateway service role:

   {
       "Version": "2012-10-17",		 	 	 
       "Statement": [
         {
           "Sid": "GetWorkloadAccessToken", 
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetWorkloadAccessToken",
           ],
           "Resource": [
               "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-*"
           ]           
         },
         {
           "Sid": "GetResourceOauth2Token",
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetResourceOauth2Token",
           ],
           "Resource": [
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/oauth2credentialprovider/CredentialName"
           ]       
         },
         {
           "Sid": "GetSecretValue",
           "Effect": "Allow",
           "Action": [
               "secretsmanager:GetSecretValue",
           ],
           "Resource": [
               "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
           ]       
         }
       ]
   }

   Replace the values of the following fields:

   • In the GetWorkloadAccessToken statement, replace the GatewayName in the Resource list with the name of your gateway.

   • In the GetResourceOauth2Token statement, replace the value in the Resource list with the ARN of the credential that you just generated.

   • In the GetSecretValue statement, replace the value in the Resource list with the ARN of the AWS secret returned in the response when you generated the credential.

Examples for setting OAuth client authorization

The following examples show you how to set authorization through an OAuth client for your gateway target:

CLI

aws bedrock-agentcore-control create-oauth2-credential-provider \
  --name oauth-credential-provider \
  --credential-provider-vendor CustomOAuth2 \
  --oauth2-provider-config-input '{
    "customOAuth2ProviderConfig": {
      "oauthDiscovery": {
        "discoveryUrl": "<DiscoveryUrl>"
      },
      "clientId": "<ClientId>",
      "clientSecret": "<ClientSecret>"
    }
  }'

Boto3

import boto3
         
client = boto3.client("bedrock-agentcore-control")

client.create_oauth2_credential_provider(
  name="oauth-credential-provider",
  credentialProviderVendor="CustomOAuth2",
  oauth2ProviderConfigInput={
    "oauthDiscovery": {
      "discoveryUrl": "<DiscoveryUrl>"
    },
    "clientId": "<ClientId>",
    "clientSecret": "<ClientSecret>"
  }
)

Set up outbound authorization with an API key

To set up outbound authorization with an API key, you use the AgentCore Identity service and specify an API key that you receive from a supported identity provider.

To set up outbound authorization with an OAuth client

1. Register your client application with a supported third-party provider.

2. Set up an API key for the provider's service.

3. Follow one of the steps below, depending on your requirements:

   • To create an API key in the AgentCore console, follow the steps at Add API key and specify the value of the API key.

   • To create an API key using the AgentCore API, send a CreateApiKeyCredentialProvider request with one of the AgentCore control plane endpoints and specify the value of the API key in the apiKey field. For examples, see Examples for setting an 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.

5. (If you're using a custom gateway service role) Attach the following identity-based policy to your gateway service role:

   {
       "Version": "2012-10-17",		 	 	 
       "Statement": [
         {
           "Sid": "GetWorkloadAccessToken",
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetWorkloadAccessToken",
           ],
           "Resource": [
               "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-*"
           ]           
         },
         {
           "Sid": "GetResourceApiKey",
           "Effect": "Allow",
           "Action": [
               "bedrock-agentcore:GetResourceApiKey",
           ],
           "Resource": [
               "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/apikeycredentialprovider/Name"
           ]       
         },
         {
           "Sid": "GetSecretValue",
           "Effect": "Allow",
           "Action": [
               "secretsmanager:GetSecretValue",
           ],
           "Resource": [
               "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
           ]       
         }
       ]
   }

   Replace the values of the following fields:

   • In the GetWorkloadAccessToken statement, replace the GatewayName in the Resource list with the name of your gateway.

   • In the GetResourceApiKey statement, replace the value in the Resource list with the ARN of the credential that you just generated.

   • In the GetSecretValue statement, replace the value in the Resource list with the ARN of the AWS secret returned in the response when you generated the credential.

Examples for setting an API key

The following examples show you how to set an API key for your gateway target:

CLI

aws bedrock-agentcore-control create-api-key-credential-provider \
  --name api-key-credential-provider \
  --api-key <API_KEY_VALUE>

Boto3

import boto3
         
client = boto3.client("bedrock-agentcore-control")

client.create_api_key_credential_provider(
  name="api-key-credential-provider",
  apiKey="<API_KEY_VALUE>"
)