Amazon Bedrock AgentCore is in preview release and is subject to change.

Authenticate and authorize with Inbound Auth and Outbound Auth

This section shows you how to implement authentication and authorization for your agent runtime using OAuth and JWT bearer tokens with AgentCore Identity. You'll learn how to set up Cognito user pools, configure your agent runtime for JWT authentication (Inbound Auth), and implement OAuth-based access to third-party resources (outbound Auth).

For a complete example, see https://github.com/awslabs/amazon-bedrock-agentcore-samples/.

For information about using OAuth to with an MCP server, see Deploy MCP servers in AgentCore Runtime.

Amazon Bedrock AgentCore runtime provides two authentication mechanisms for hosted agents:

Prerequisites

Before you begin, make sure you have:

JWT inbound authorization and OAuth outbound access sample

This guide walks you through the process of setting up your agent runtime to be invoked with an OAuth compliant access token using JWT format. The sample agent will be authorized using AWS Cognito access tokens. Later, you'll also learn how the agent code can fetch Google tokens on behalf of the user to check Google Drive and fetch contents.

What you'll learn

In this guide, you'll learn how to:

Step 1: Prepare your agent

Start by creating a basic agent with the following structure:

## Project Folder Structure

your_project_directory/
├── agent_example.py # Your main agent code
├── requirements.txt # Dependencies for your agent
└── __init__.py # Makes the directory a Python package

Create the following files with their respective contents:

agent_example.py

This is your main agent code:

from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp

agent = Agent()
app = BedrockAgentCoreApp()

@app.entrypoint
def invoke(payload):
    """Process user input and return a response"""
    user_message = payload.get("prompt", "Hello")
    response = agent(user_message)
    return str(response) # response should be json serializable

if __name__ == "__main__":
    app.run()

requirements.txt

This file lists the dependencies for your agent:

strands-agents
bedrock-agentcore

Step 2: Set up AWS Cognito user pool and add a user

To set up a Cognito user pool and create a user, you'll use a shell script that automates the process.

For more information, see Step 2: Set up an OAuth 2.0 Credential Provider.

This script creates a Cognito user pool, a user pool client, adds a user, and generates a bearer token for the user. The token is valid for 60 minutes by default.

Step 3: Deploy your agent

Now you'll deploy your agent with JWT authorization using the Cognito user pool you created.

Use starter toolkit

To configure and deploy your agent

1. Configure your agent runtime with the following command, replacing the placeholder values with your actual values:

   agentcore configure --entrypoint agent_example.py \
   --name my-oauth-agent \
   --execution-role your-execution-role-arn \
   --disable-otel \
   --requirements-file requirements.txt \
   --authorizer-config "{\"customJWTAuthorizer\":{\"discoveryUrl\":\"$DISCOVERY_URL\",\"allowedClients\":[\"$CLIENT_ID\"]}}"

   Replace $DISCOVERY_URL with the Discovery URL from Step 2, and $CLIENT_ID with the Client ID from Step 2.

2. Deploy your agent:

   agentcore launch

3. Note the agent runtime ARN from the output. You'll need this in the next step.

Tip

You can also run the configure command with just the entry point file for a fully interactive experience:

agentcore configure --entrypoint agent_example.py

boto SDK

import boto3

# Create the client
client = boto3.client('bedrock-agentcore-control', region_name="us-east-1")


# Call the CreateAgentRuntime operation
response = client.create_agent_runtime(
    agentRuntimeName='hello_agent',
    agentRuntimeArtifact={
        'containerConfiguration': {
            'containerUri': '123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest'
        }
    },
    authorizerConfiguration={
        "customJWTAuthorizer": {
            "discoveryUrl": 'COGNITO_DISCOVERY_URL',
            "allowedClients": ['COGNITO_CLIENT_ID']
        }
    },
    networkConfiguration={"networkMode":"PUBLIC"},
    roleArn='arn:aws:iam::123456789012:role/AgentRuntimeRole'
)

Step 4: Use bearer token to invoke your agent

Now that your agent is deployed with JWT authorization, you can invoke it using the bearer token.

Make sure your agent’s execution role has permissions to access the workload identity.

    "Sid": "GetAgentAccessToken",
    "Effect": "Allow",
    "Action": [
        "bedrock-agentcore:GetWorkloadAccessToken",
        "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
        "bedrock-agentcore:GetWorkloadAccessTokenForUserId"
    ],
    # point to the workload identity for the runtime; the workload identity can be found in
    # the GetAgentRuntime response and has your agent name in it.
    "Resource": [
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/agentname-*"
    ]
}

Fetch a bearer token for the user you created with Amazon Cognito.

# use the password and other details used when you created the cognito user
            export TOKEN=$(aws cognito-idp initiate-auth \
            --client-id "$CLIENT_ID" \
            --auth-flow USER_PASSWORD_AUTH \
            --auth-parameters USERNAME='testuser',PASSWORD='MyPassword123!' \
            --region us-east-1 | jq -r '.AuthenticationResult.AccessToken')

Using Curl

// Invoke with OAuth token
export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://bedrock-agentcore.us-west-2.amazonaws.com"
curl -v -X POST "${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT" \
-H "Authorization: Bearer ${TOKEN}" \
-H "X-Amzn-Trace-Id: your-trace-id" \
-H "Content-Type: application/json" \
-H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: your-session-id" \
-d ${PAYLOAD}

Using Python

Since boto3 doesn't support invocation with bearer tokens, you'll need to use an HTTP client like the requests library in Python.

Step 5: Set up your agent to access tools using OAuth

In this section, you'll learn how to connect your agent code with AgentCore Credential Providers for secure access to external resources using OAuth2 authentication.

The example below demonstrates how your agent running in Agent Runtime can request OAuth consent from users, enabling them to authenticate with their Google account and authorize the agent to access their Google Drive contents.

For more information about setting up identity, see Getting started with Amazon Bedrock AgentCore Identity.

Step 5.1: Set up Credential Providers

To set up a Google Credential Provider, you need to:

Make sure your invocation role has the necessary permissions for accessing the credential provider.

Step 5.2: Enable agent to read Google Drive contents

Create a tool with agent core SDK annotations as shown below to automatically initiate the three-legged OAuth process. When your agent invokes this tool, users will be prompted to open the authorization URL in their browser and grant consent for the agent to access their Google Drive.

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key

# This annotation helps agent developer to obtain access tokens from external applications
@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], # Google OAuth2 scopes
    auth_flow="USER_FEDERATION", # 3LO flow
    on_auth_url=lambda x: print("Copy and paste this authorization url to your browser", x), # prints authorization URL to console
    force_authentication=True,
)
async def read_from_google_drive(*, access_token: str):
    print(access_token) #You can see the access_token 
    # Make API calls...
    main(access_token)

asyncio.run(read_from_google_drive(access_token=""))

What happens behind the scenes

When this code runs, the following process occurs:

Troubleshooting

How to debug token related issues

If you encounter issues with token authentication, you can decode the token to inspect its contents:

echo "$TOKEN" | cut -d '.' -f2 | tr '_-' '/+' | awk '{ l=4 - length($0)%4; if (l<4) printf "%s", $0; for (i=0; i<l; i++) printf "="; print "" }' | base64 -D | jq

This will output the token's payload, which looks similar to:

{
    "sub": "subid",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/userpoolid",
    "client_id": "clientid",
    "origin_jti": "originjti",
    "event_id": "eventid",
    "token_use": "access",
    "scope": "aws.cognito.signin.user.admin",
    "auth_time": 1752275688,
    "exp": 1752279288,
    "iat": 1752275688,
    "jti": "jti",
    "username": "username"
}

When troubleshooting token issues, check the following: