Setting up Outbound Auth

Outbound authorization lets Amazon Bedrock AgentCore gateways securely access gateway targets on behalf of users authenticated and authorized during Inbound Auth. For more information on authorization, see Prerequisites to set up a gateway.

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.

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.

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#.

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.

For more information, see Setting up credential providers for Outbound Auth.

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.

Choose your credential provider type from the tabs below:

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.

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:

aws lambda add-permission \
  --function-name "YourLambdaFunction" \
  --statement-id "GatewayInvoke" \
  --action "lambda:InvokeFunction" \
  --principal "arn:aws:iam::{{accountId}}:role/YourGatewayExecutionRole" \
  --region {{region}}
              

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:

To create an API Key credential provider

• Use the following AWS CLI command to create an API Key credential provider:

  
  aws acps create-api-key-credential-provider \
    --region us-east-1 \
    --credential-provider-name api-key-credential-provider \
    --api-key <API_KEY_VALUE>
                    

  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
                    

When creating or updating a gateway target, you can use this credential provider in the credential provider configuration:

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>"
    }
  }
}]
              

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:

{
  "Sid": "GetResourceApiKey",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetResourceApiKey"
  ],
  "Resource": [
    "{{credential-provider-arn}}"
  ]
}
              

For API Key authentication, if the credentials are stored in AWS Secrets Manager, the execution role also needs permission to access those secrets:

{
  "Sid": "GetSecretValue",
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue"
  ],
  "Resource": [
    "{{secrets-manager-arn}}"
  ]
}

{
  "Sid": "GetAgentAccessToken",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetWorkloadAccessToken",
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:workload-identity-directory/default",
    "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:workload-identity-directory/default/workload-identity/{{gatewayName}}-*"
  ]       
}
              

OAuth authentication (OAUTH)

OAuth credential providers allow your gateway to authenticate with services that use OAuth for authentication. Follow these steps to set up an OAuth credential provider:

To create an OAuth credential provider with discovery URL

• Use the following AWS CLI command to create an OAuth credential provider using a discovery URL:

  
  aws acps create-oauth2-credential-provider \
    --region us-east-1 \
    --credential-provider-name oauth-credential-provider \
    --credential-provider-type CustomOAuth2 \
    --o-auth2-provider-config-input '{
      "customOAuth2ProviderConfig": {
        "oauthDiscovery": {
          "discoveryUrl": "<DiscoveryUrl>"
        },
        "clientId": "<ClientId>",
        "clientSecret": "<ClientSecret>"
      }
    }'
                    

  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/oauth2credentialprovider/abcdefghijk
                    

To create an OAuth credential provider with server metadata

• If you don't have a discovery URL, you can create an OAuth credential provider using server metadata:

  
  aws acps create-oauth2-credential-provider \
    --region us-east-1 \
    --credential-provider-name oauth-metadata-provider \
    --credential-provider-type CustomOAuth2 \
    --o-auth2-provider-config-input '{
      "customOAuth2ProviderConfig": {
        "oauthDiscovery": {
          "authorizationServerMetadata": {
            "issuer": "https://example.auth0.com/",
            "authorizationEndpoint": "https://example.auth0.com/authorize",
            "tokenEndpoint": "https://example.auth0.com/oauth/token",
            "responseTypes": ["token"]
          }
        },
        "clientId": "<ClientId>",
        "clientSecret": "<ClientSecret>"
      }
    }'
                    

When creating or updating a gateway target, you can use this credential provider in the credential provider configuration:

credentialProviderConfigurations=[{
  "credentialProviderType": "OAUTH",
  "credentialProvider": {
    "oauthCredentialProvider": {
      "providerArn": "{{credential-provider-arn}}",
      "scopes": ["scope1", "scope2"]
    }
  }
}]
              

The execution role needs permission to obtain OAuth tokens:

{
  "Sid": "GetResourceOauth2Token",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetResourceOauth2Token"
  ],
  "Resource": [
    "{{credential-provider-arn}}"
  ]
}
              

For OAuth authentication, if the credentials are stored in AWS Secrets Manager, the execution role also needs permission to access those secrets:

{
  "Sid": "GetSecretValue",
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue"
  ],
  "Resource": [
    "{{secrets-manager-arn}}"
  ]
}

{
  "Sid": "GetAgentAccessToken",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetWorkloadAccessToken",
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:workload-identity-directory/default",
    "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:workload-identity-directory/default/workload-identity/{{gatewayName}}-*"
  ]       
}