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 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
-
Open the AgentCore console at https://console.aws.amazon.com/bedrock-agentcore/home#.
-
In the left navigation pane, choose Identity.
-
In Outbound Auth choose Add OAuth client/API
Key then select the outbound authorization that you want to create.
-
If you chose OAuth client, do the following:
-
Enter a name for the OAuth client
-
If an included provider is the provider that you want to use, choose
that provider. Then enter the client ID and client secret.
-
Choose Add OAuth Client
-
If you chose Add API Key, enter name and the API key
that you want to use, and then choose Add.
- SDK
-
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:
JSON
- JSON
-
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AmazonBedrockAgentCoreGatewayLambdaProd",
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:{{region}}:111122223333
:function:[[functionName]]:*"
],
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "111122223333
"
}
}
}
]
}
Additionally, your Lambda function needs a resource-based policy that allows the
Gateway's execution role to invoke it:
JSON
- JSON
-
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333
:role/{{GatewayExecutionRoleName}}"
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:{{region}}:111122223333
:function:{{functionName}}"
}
]
}
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}}-*"
]
}