Limita le chiamate in entrata IAM (SigV4) al tuo gateway Esempio di autorizzazione JWT in entrata e accesso OAuth in uscita Prerequisiti Passaggio 1: crea il tuo progetto di agente Passaggio 2: configurare il pool di utenti Amazon Cognito e aggiungere un utente Passaggio 3 (opzionale): avvia il runtime con un AgentCore gateway Fase 4: Implementa il tuo agente Passaggio 5: Usa il token bearer per invocare il tuo agente Risposte di errore OAuth Passaggio 6: configura il tuo agente per accedere agli strumenti tramite OAuth Passaggio 7: (Facoltativo) Propagazione di un token JWT a Runtime AgentCore Risoluzione dei problemi

Autenticazione e autorizzazione con Autenticazione in entrata e Autenticazione in uscita

Questa sezione mostra come implementare l'autenticazione e l'autorizzazione per il runtime dell'agente utilizzando i token OAuth e JWT bearer con Identity. AgentCore Imparerai come configurare i pool di utenti di Cognito, configurare il runtime dell'agente per l'autenticazione JWT (autenticazione in entrata) e implementare l' OAuth-based accesso a risorse di terze parti (autenticazione in uscita).

Per un esempio completo, consulta. https://github.com/awslabs/amazon-bedrock-agentcore-samples/

Per informazioni sull'utilizzo di OAuth con un server MCP, consulta Distribuire i server MCP in Runtime. AgentCore

Il AgentCore runtime di Amazon Bedrock offre due meccanismi di autenticazione per gli agenti ospitati:

Autenticazione IAM SigV4

Il meccanismo di autenticazione e autorizzazione predefinito che funziona automaticamente senza configurazioni aggiuntive, in modo simile ad altre AWS API.

X-Amzn-Bedrock-AgentCore-Runtime-User-Id Intestazione

Se la tua soluzione richiede che l'agente ospitato recuperi i token OAuth per conto degli utenti finali (utilizzando Authorization Code Grant), puoi specificare l'identificatore utente includendo l'intestazione nelle tue richieste. X-Amzn-Bedrock-AgentCore-Runtime-User-Id Questa intestazione utilizza il percorso internamente. GetWorkloadAccessTokenForUserId

Nota

L'invocazione InvokeAgentRuntime con the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header richiederà una nuova azione IAM:bedrock-agentcore:InvokeAgentRuntimeForUser, oltre all'azione esistente. bedrock-agentcore:InvokeAgentRuntime

Quando utilizzare questa intestazione rispetto all'autenticazione JWT Bearer Token

Questa intestazione è progettata per i seguenti casi d'uso:

Clienti aziendali con identificatori utente gestiti dal cliente: Organizzazioni che mantengono le proprie stringhe di identità utente e devono passarle a AgentCore Identity for credenziali.
Scenari di sviluppo e avvio rapido: costruttori che non dispongono ancora di un token IdP e necessitano di un percorso rapido per testare i flussi di credenziali con ambito utente.

Per le implementazioni di produzione in cui è configurato un provider di identità, utilizza invece l'autenticazione JWT Bearer Token. Il percorso JWT (GetWorkloadAccessTokenForJWT) convalida l'emittente, la firma e la scadenza del token, fornendo una prova crittografica dell'identità dell'utente. Il percorso dell'X-Amzn-Bedrock-AgentCore-Runtime-User-Idintestazione non verifica l'UserID rispetto all'identità autenticata dell'utente finale: si basa sul carico di lavoro chiamante per passare il valore corretto e sulle policy IAM per limitare chi può fornirlo.

X-Amzn-Bedrock-AgentCore-Runtime-User-Id Best practice di sicurezza per Header

Suggerimento
Per una visione consolidata di tutti i consigli sulla sicurezza di Runtime, consulta le best practice di sicurezza per AgentCore Runtime.

Poiché AgentCore considera il valore dell'intestazione come un identificatore opaco senza verificarlo rispetto a un'identità autenticata, è necessario applicare i seguenti controlli per mantenere il limite di sicurezza:
Limita l'autorizzazione IAM: solo i responsabili affidabili dovrebbero avere l'autorizzazione. bedrock-agentcore:InvokeAgentRuntimeForUser Ambita questa autorizzazione a risorse di runtime specifiche utilizzando le condizioni delle risorse IAM. Non concedetelo in modo generalizzato tramite policy gestite o dichiarazioni di risorse wildcard.
Deriva l'ID utente dal principale autenticato: il valore dell'ID utente deve essere derivato dal contesto del principale autenticato (ad esempio, l'identità del chiamante IAM o le dichiarazioni del token utente) anziché accettare valori arbitrari forniti dal client. Ciò impedisce a un utente autenticato di impersonare un altro utente specificandone manualmente uno diverso. user-id
Implementa la registrazione degli audit: registra la relazione tra il principale IAM autenticato (dal contesto SigV4) e il valore passato. user-id AWS CloudTrail Da utilizzare per monitorare le InvokeAgentRuntime chiamate che includono il parametro. runtimeUserId

Nega l'intestazione in contesti non attendibili: per i runtime in cui non è necessaria la delega degli ID utente, nega esplicitamente l'azione nelle policy IAM per impedire che l'bedrock-agentcore:InvokeAgentRuntimeForUserintestazione venga accettata:


{
   "Statement": [
      {
         "Sid": "DenyUserIdDelegation",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
      }
   ]
}

Autenticazione con token JWT Bearer

È possibile configurare il runtime dell'agente per accettare i token JWT bearer fornendo la configurazione dell'autorizzatore durante la creazione dell'agente.

Questa configurazione include:

Discovery URL: una stringa che deve corrispondere allo schema ^.+/\.well-known/openid-configuration$ per gli URL di rilevamento di OpenID Connect
Gruppi di destinatari consentiti: un elenco di destinatari consentiti che verranno convalidati in base alla dichiarazione di audit nel token JWT
Client consentiti: un elenco di identificatori client consentiti che verranno convalidati in base all'affermazione client_id nel token JWT
Ambiti consentiti: un elenco di ambiti consentiti che verranno convalidati in base all'indicazione di ambito nel token JWT. Il campo di allowedScopes autorizzazione verrà configurato come un elenco di stringhe.
Dichiarazioni personalizzate obbligatorie: un elenco di attestazioni obbligatorie che verranno convalidate in base al nome e al valore dell'attestazione contenuti nel token JWT in entrata. Per i dettagli sulla configurazione dell'autorizzatore, consulta Configurare l'autorizzatore JWT in entrata

Nota

Un AgentCore Runtime può supportare l'autenticazione in entrata basata su IAM SigV4 o JWT Bearer Token, ma non entrambe contemporaneamente. Puoi sempre creare versioni diverse del tuo AgentCore Runtime e configurarle per diversi tipi di autorizzazione in entrata. Quando crei un runtime con Amazon Bedrock AgentCore, viene creata automaticamente un'identità del carico di lavoro per il tuo runtime con il servizio AgentCore Identity.

Argomenti

Limita le chiamate in entrata IAM (SigV4) al tuo gateway
Esempio di autorizzazione JWT in entrata e accesso OAuth in uscita
Prerequisiti
Passaggio 1: crea il tuo progetto di agente
Passaggio 2: configurare il pool di utenti Amazon Cognito e aggiungere un utente
Passaggio 3 (opzionale): avvia il runtime con un AgentCore gateway
Fase 4: Implementa il tuo agente
Passaggio 5: Usa il token bearer per invocare il tuo agente
Risposte di errore OAuth
Passaggio 6: configura il tuo agente per accedere agli strumenti tramite OAuth
Passaggio 7: (Facoltativo) Propagazione di un token JWT a Runtime AgentCore
Risoluzione dei problemi

Limita le chiamate in entrata IAM (SigV4) al tuo gateway

Puoi integrare il tuo AgentCore Runtime con un AgentCore gateway in modo che il gateway diventi l'unico punto di accesso gestito al runtime, offrendoti autorizzazioni basate su policy, Amazon Bedrock Guardrails, intercettori di richieste e risposte e osservabilità unificata, il tutto applicato al di fuori dell'ambiente dell'agente. Per maggiori informazioni sulla logica e su come configurarlo, consulta Front your runtime with an Gateway. AgentCore

Ma questo è utile solo se i chiamanti non riescono a raggiungere il runtime bypassando direttamente il gateway. Se il runtime utilizza l'autorizzazione in entrata IAM (SigV4) predefinita, è possibile limitare la chiamata al gateway in modo che il traffico raggiunga il runtime solo attraverso di esso. A tal fine, allegate al runtime una policy basata sulle risorse che limiti l'invocazione al ruolo di esecuzione del gateway. Il gateway assume il ruolo di servizio di firmare le richieste al runtime, quindi il ruolo gateway è il principale che richiama il runtime. Consenti tale ruolo e aggiungi un valore esplicito Deny per ogni altro principale in modo che nessun'altra identità possa richiamare il runtime anche con una policy permissiva basata sull'identità. Per ulteriori informazioni sulle politiche basate sulle risorse relative ai runtime, consulta le politiche Resource-based per Amazon Bedrock. AgentCore


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowOnlyGatewayRole",
            "Effect": "Allow",
            "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
        },
        {
            "Sid": "DenyOtherPrincipals",
            "Effect": "Deny",
            "Principal": { "AWS": "*" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
            "Condition": {
                "ArnNotEquals": {
                    "aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole"
                }
            }
        }
    ]
}

Suggerimento

Una politica esplicita ha Deny sempre la precedenza su qualsiasi politica, inclusa quella basata sull'identitàAllow, nello stesso account. L'attivazione aws:PrincipalArn garantisce che solo Deny il ruolo di esecuzione del gateway possa richiamare il runtime, indipendentemente dalle altre autorizzazioni presenti nell'account.

Importante

Limitare il runtime al ruolo di esecuzione del gateway è tanto efficace quanto i controlli su chi può assumere quel ruolo. Qualsiasi principale che possa assumere il ruolo di esecuzione del gateway può richiamare il runtime come se fosse il gateway. Blocca il ruolo aggiungendo aws:SourceArn aws:SourceAccount condizioni alla policy di fiducia del ruolo di esecuzione del gateway in modo che solo il gateway possa assumerlo. La guida alla prevenzione di Confused Deputy mostra la stessa tecnica applicata al ruolo di esecuzione di un runtime; applica lo stesso schema qui, ma imposta la policy di fiducia sul ruolo e l'ambito aws:SourceArn di esecuzione del gateway sull'ARN del gateway.

Esempio di autorizzazione JWT in entrata e accesso OAuth in uscita

Questa guida illustra il processo di configurazione del runtime dell'agente in modo che venga richiamato con un token di accesso conforme a OAuth utilizzando il formato JWT. L'agente di esempio verrà autorizzato utilizzando i token di accesso di Amazon Cognito. Successivamente, scoprirai anche come il codice dell'agente può recuperare i token Google per conto dell'utente per controllare Google Drive e recuperare i contenuti.

Cosa imparerai

In questa guida, imparerai a:

Configura il pool di utenti di Cognito, aggiungi un utente e ottieni un token portatore per l'utente
Configura il runtime dell'agente per utilizzare il pool di utenti di Cognito per l'autorizzazione
Imposta il codice dell'agente per recuperare i token OAuth per conto dell'utente per chiamare gli strumenti

Prerequisiti

Prima di iniziare, assicurati di avere:

Un AWS account con le autorizzazioni appropriate
Conoscenza di base della programmazione Python
Familiarità con i contenitori Docker (per l'implementazione avanzata)
Configura correttamente un agente di base con runtime
La AWS CLI più recente e installata jq
Conoscenza di base dell'autorizzazione OAuth, principalmente dei token JWT bearer, dei reclami e dei vari flussi di sovvenzioni

Passaggio 1: crea il tuo progetto di agente

Usa il agentcore create comando per impostare un progetto vuoto. L' JWT-authorized agente viene aggiunto dopo aver creato le risorse Cognito nella Fase 2.


agentcore create --project-name OAuthAgentProject --no-agent
cd OAuthAgentProject

Questo genera:

File di configurazione agentcore/agentcore.json
agentcore/aws-targets.jsonfile di destinazione di distribuzione
agentcore/cdk/progetto di infrastruttura

Nota

Mantieni questo terminale acceso OAuthAgentProject per i restanti comandi AgentCore CLI.

Passaggio 2: configurare il pool di utenti Amazon Cognito e aggiungere un utente

Per configurare un pool di utenti di Cognito e creare un utente, utilizzerai uno script di shell che automatizza il processo.

Per ulteriori informazioni, consulta Fase 2: Importazione dei moduli Identity and Auth.

Per configurare il pool di utenti di Cognito e creare un utente

Crea un file denominato setup_cognito.sh con i seguenti contenuti:


#!/bin/bash

# Create User Pool and capture Pool ID directly
export POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name "MyUserPool" \
  --policies '{"PasswordPolicy":{"MinimumLength":8}}' \
  --region $REGION | jq -r '.UserPool.Id')

# Create App Client and capture Client ID directly
export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
  --user-pool-id $POOL_ID \
  --client-name "MyClient" \
  --no-generate-secret \
  --explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
  --region $REGION | jq -r '.UserPoolClient.ClientId')

# Create User
aws cognito-idp admin-create-user \
  --user-pool-id $POOL_ID \
  --username $USERNAME \
  --region $REGION \
  --message-action SUPPRESS > /dev/null

# Set Permanent Password
aws cognito-idp admin-set-user-password \
  --user-pool-id $POOL_ID \
  --username $USERNAME \
  --password $PASSWORD \
  --region $REGION \
  --permanent > /dev/null

# Authenticate User and capture Access Token
export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
  --client-id "$CLIENT_ID" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=$USERNAME,PASSWORD=$PASSWORD \
  --region $REGION | jq -r '.AuthenticationResult.AccessToken')

# Output the required values
echo "Pool id: $POOL_ID"
echo "Discovery URL: https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
echo "Client ID: $CLIENT_ID"
echo "Bearer Token: $BEARER_TOKEN"

Apri una finestra di terminale e imposta le seguenti variabili di ambiente:

REGION— la AWS regione che vuoi usare
USERNAME— il nome utente per il nuovo utente
PASSWORD— la password per il nuovo utente
```
export REGION=us-east-1 # Set your desired Region
export USERNAME="user-name"
export PASSWORD="password"
```
Nella finestra del terminale, esegui lo script:
```
source setup_cognito.sh
```
Annotate l'output dello script. Avrai bisogno di questi valori nei passaggi successivi.

Questo script crea un pool di utenti Cognito, un client per il pool di utenti, aggiunge un utente e genera un token bearer per l'utente. Per impostazione predefinita, il token è valido per 60 minuti.

Passaggio 3 (opzionale): avvia il runtime con un AgentCore gateway

Se desideri eseguire il front di questo runtime, crea subito il gateway, prima di distribuirlo nel passaggio successivo. Dopo la distribuzione, aggiungerai il runtime come destinazione del gateway.

Per assicurarti che i chiamanti non possano aggirare il gateway, limita il runtime in modo che accetti le chiamate solo da quel gateway. Usa allowedWorkloadConfiguration come descritto in consentitoWorkloadConfiguration: limita la chiamata al gateway. La AgentCore CLI non configura questo campo. Usa l'API del piano di AgentCore controllo.

Fase 4: Implementa il tuo agente

Importante

A partire dal 13 ottobre 2025, Amazon Bedrock AgentCore utilizza un Service-Linked ruolo (SLR) per le autorizzazioni relative all'identità dei carichi di lavoro anziché richiedere la configurazione manuale delle policy IAM per i nuovi agenti.

I Service-Linked dettagli del ruolo:

Nome: AWSServiceRoleForBedrockAgentCoreRuntimeIdentity
Responsabile del servizio: runtime-identity.bedrock-agentcore.amazonaws.com
Scopo: gestisce i token di accesso all'identità del carico di lavoro e le credenziali OAuth

Assicurati che il ruolo che usi per richiamare le API di AgentCore controllo sia autorizzato a creare il ruolo: Service-Linked


{
    "Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions",
    "Effect": "Allow",
    "Action": "iam:CreateServiceLinkedRole",
    "Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
    "Condition": {
        "StringEquals": {
            "iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
        }
    }
}

Vantaggio: il Service-Linked ruolo fornisce automaticamente le autorizzazioni necessarie per l'accesso all'identità del carico di lavoro senza richiedere la configurazione manuale delle policy.

Per informazioni dettagliate sul ruolo collegato al servizio, consulta Identity service-linked role.

Ora distribuirai il tuo agente con l'autorizzazione JWT utilizzando il pool di utenti Cognito che hai creato. Dovrai creare un agente con configurazione di autorizzazione. La tabella seguente rappresenta i vari parametri di configurazione dell'autorizzatore e il modo in cui li utilizziamo per convalidare il token in entrata.

authorizer_configuration	reclamo in token decodificato	Note
url di scoperta → emittente	iss	L'URL di scoperta deve puntare a un URL dell'emittente. Dovrebbe corrispondere all'affermazione iss nel token decodificato.
Clienti consentiti	client_id	client_id nel token deve corrispondere a uno dei client consentiti specificati nell'autorizzazione
Pubblico consentito	aud	Uno dei valori in aud claim del token deve corrispondere a uno dei destinatari consentiti specificati nell'autorizzazione
consentito WorkloadConfiguration	`internal`	Opzionale. All'avvio, utilizzato per consentire solo al AgentCore Gateway di richiamare il runtime. Vedi Limita l'invocazione al tuo gateway.

Se vengono forniti sia client_id che aud, l'agente runtime authorizer verificherà entrambi.

consentitoWorkloadConfiguration: limita l'invocazione al gateway

Il allowedWorkloadConfiguration campo relativo customJWTAuthorizer limita i carichi di lavoro della catena di identità della richiesta a cui è consentito richiamare il runtime. Imposta il carico di lavoro consentito sul gateway in modo che il runtime accetti una richiesta solo quando la catena di identità include quel gateway: in questo modo un runtime OAuth (JWT) impone che il traffico arrivi solo attraverso il gateway configurato nella Fase 3.

Fornisci i carichi di lavoro consentiti utilizzando uno dei seguenti campi. Puoi specificarne uno o entrambi: una richiesta viene accettata se la relativa catena di identità corrisponde a una voce in uno dei campi, quindi non è necessario fornire entrambi.

HostingEnvironments: un elenco di ambienti di hosting i cui carichi di lavoro possono richiamare la destinazione. Ogni voce è un oggetto con un. arn Al momento del lancio, l'unico ambiente di hosting supportato è AgentCore Gateway, quindi ogni ambiente arn deve essere un AgentCore Gateway ARN.
WorkloadIdEntities: un elenco di nomi di identità del carico di lavoro autorizzati a richiamare la destinazione. Un nome di identità del carico di lavoro non è un ARN. È il segmento finale dell'ARN dell'identità del carico di lavoro del gateway, che puoi trovare nel campo workloadIdentityDetails della GetGateway risposta. Ad esempio, se workloadIdentityDetails.workloadIdentityArn è cosìarn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-gateway-workload-identity, il nome dell'identità del carico di lavoro è. my-gateway-workload-identity

La seguente configurazione dell'autorizzatore limita la chiamata a un gateway specifico AgentCore tramite il relativo ARN. Specificare hostingEnvironments da solo è il modo più semplice per consentire un gateway:


{
    "authorizerConfiguration": {
        "customJWTAuthorizer": {
            "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/openid-configuration",
            "allowedClients": ["your-client-id"],
            "allowedWorkloadConfiguration": {
                "hostingEnvironments": [
                    {
                        "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id"
                    }
                ]
            }
        }
    }
}

In alternativa, puoi identificare il gateway in base al nome di identità del carico di lavoro o specificare entrambi i campi. Quando entrambi sono presenti, una richiesta è consentita se corrisponde a una voce in uno dei campi. Lo allowedWorkloadConfiguration snippet seguente consente due gateway diversi, uno identificato dal relativo ARN e uno dal nome identificativo del carico di lavoro:


"allowedWorkloadConfiguration": {
    "hostingEnvironments": [
        {
            "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
        }
    ],
    "workloadIdentities": [
        "my-gateway-2-workload-identity"
    ]
}

Nota

Al momento del lancio, allowedWorkloadConfiguration è supportato solo per gli obiettivi AgentCore Runtime e i carichi di lavoro consentiti sono i Gateway. AgentCore

Crea e distribuisci il runtime dell'agente

Una volta pronta la configurazione dell'autorizzatore, crea e distribuisci il runtime dell'agente. Gli esempi seguenti mostrano come eseguire questa operazione con la AgentCore CLI o l' AWS SDK for Python (Boto3). Annota l'ARN di runtime dell'agente dall'output: ti servirà per richiamare l'agente nel passaggio successivo.

Esempio

AgentCore CLI

Per configurare e distribuire il tuo agente

Aggiungi l'agente al progetto che hai creato nel passaggio 1. Il comando configura l'URL di rilevamento di Cognito, l'ID client e la lista consentita dell'Authorizationintestazione della richiesta:


agentcore add agent \
  --name OAuthAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration" \
  --allowed-clients "$CLIENT_ID" \
  --request-header-allowlist Authorization

Implementa il tuo agente:
```
agentcore deploy
```
Annotate l'ARN del runtime dell'agente dall'output. Ne avrai bisogno nel passaggio successivo.

Python


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='HelloAgent',
    agentRuntimeArtifact={
        'containerConfiguration': {
            'containerUri': '111122223333.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::111122223333:role/AgentRuntimeRole',
    lifecycleConfiguration={
        'idleRuntimeSessionTimeout': 300,  # 5 min, configurable
        'maxLifetime': 1800                # 30 minutes, configurable
    },
)

Nota

L'esempio AgentCore CLI configura l'autorizzazione JWT, ma non la configura. allowedWorkloadConfiguration Se esegui il runtime con un gateway, utilizza l'API AgentCore control-plane per aggiungere quel campo.

Passaggio 5: Usa il token bearer per invocare il tuo agente

Ora che il tuo agente è distribuito con l'autorizzazione JWT, puoi richiamarlo utilizzando il token bearer.

Nota

Se al runtime hai utilizzato un gateway nel passaggio 3, aggiungi il runtime distribuito come destinazione del gateway prima di richiamare il runtime (vedi AgentCore Runtime targets) e quindi richiama tramite l'endpoint gateway mostrato negli esempi che seguono, anziché l'endpoint di runtime.

Importante

Importante per gli utenti esistenti: gli agenti creati prima del 13 ottobre 2025 continueranno a utilizzare il ruolo di esecuzione dell'agente per le autorizzazioni di identità e richiederanno che la politica precedente sia associata al ruolo di esecuzione dell'agente.

Nuovi agenti: per gli agenti creati il 13 ottobre 2025 o dopo tale data, questa politica non è richiesta in quanto le autorizzazioni vengono gestite automaticamente dal ruolo. Service-Linked


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

Richiama l'agente

Recupera un token bearer per l'utente che hai creato con 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='PASSWORD' \
    --region us-east-1 | jq -r '.AuthenticationResult.AccessToken')

Procedi a richiamare l'agente con il resto delle seguenti istruzioni.

Invoca l'agente con OAuth.

Esempio

Use cURL


// Invoke with OAuth token
export PAYLOAD='{"prompt": "hello what is 1+1?"}'

export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://bedrock-agentcore.us-east-1.amazonaws.com"
# If you fronted the runtime with a gateway (Step 3), the core endpoint URL is now your gateway URL
# export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://${GATEWAY_ID}.gateway.bedrock-agentcore.us-east-1.amazonaws.com/${TARGET_NAME}"

export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT"
# If you fronted the runtime with a gateway (Step 3), the preceding URL works but there is also a simpler alternative:
# export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/invocations"

curl -v -X POST "${INVOKE_URL}" \
-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}

Use Python

Poiché boto3 non supporta l'invocazione con token bearer, dovrai utilizzare un client HTTP come la libreria delle richieste in Python.

Per invocare il tuo agente con un token bearer

Crea uno script Python denominato invoke_agent.py con il seguente contenuto:


import requests
import urllib.parse
import json
import os

# Configuration Constants
REGION_NAME = "AWS_REGION"

# === Agent Invocation Demo ===
invoke_agent_arn = "YOUR_AGENT_ARN_HERE"
auth_token = os.environ.get('TOKEN')
print(f"Using Agent ARN from environment: {invoke_agent_arn}")

# URL encode the agent ARN
escaped_agent_arn = urllib.parse.quote(invoke_agent_arn, safe='')

# Construct the URL — invoke the runtime directly
url = f"https://bedrock-agentcore.{REGION_NAME}.amazonaws.com/runtimes/{escaped_agent_arn}/invocations?qualifier=DEFAULT"

# If you are fronting the runtime with a gateway (see Step 3), invoke through
# the gateway target instead (replace GATEWAY_ID and my-target):
# url = f"https://GATEWAY_ID.gateway.bedrock-agentcore.{REGION_NAME}.amazonaws.com/my-target/invocations"

# Set up headers
headers = {
    "Authorization": f"Bearer {auth_token}",
    "X-Amzn-Trace-Id": "your-trace-id",
    "Content-Type": "application/json",
    "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": "testsession123"
}

# Enable verbose logging for requests
import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)

invoke_response = requests.post(
    url,
    headers=headers,
    data=json.dumps({"prompt": "Hello what is 1+1?"})
)

# Print response in a safe manner
print(f"Status Code: {invoke_response.status_code}")
print(f"Response Headers: {dict(invoke_response.headers)}")

# Handle response based on status code
if invoke_response.status_code == 200:
    response_data = invoke_response.json()
    print("Response JSON:")
    print(json.dumps(response_data, indent=2))
elif invoke_response.status_code >= 400:
    print(f"Error Response ({invoke_response.status_code}):")
    error_data = invoke_response.json()
    print(json.dumps(error_data, indent=2))

else:
    print(f"Unexpected status code: {invoke_response.status_code}")
    print("Response text:")
    print(invoke_response.text[:500])

Sostituisci AWS_REGION con la AWS regione che stai utilizzando. dal passaggio 3.
Sostituisci YOUR_AGENT_ARN_HERE con l'ARN di runtime dell'agente effettivo del passaggio 3.
Esegui lo script :
```
python invoke_agent.py
```

Risposte di errore OAuth

OAuth-configured gli agenti seguono gli standard di autenticazione RFC 6749 (OAuth 2.0). Quando manca l'autenticazione, il servizio restituisce una risposta 401 Unauthorized con un' WWW-Authenticate intestazione (secondo RFC 7235), che consente ai client di scoprire gli endpoint del server di autorizzazione tramite l'API. GetRuntimeProtectedResourceMetadata

401 Non autorizzato: autenticazione mancante

Quando non viene fornito alcun token Bearer nell'intestazione di autorizzazione, la risposta è:


HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"

L'resource_metadataURL nell' WWW-Authenticate intestazione punta all'API Protected Resource Metadata (PRM). L'API PRM consente ai client di scoprire quali server di autorizzazione proteggono questo agente e i relativi URL degli endpoint OAuth.

Nota

È necessario pre-registrare il client OAuth in Cognito (tramite Console AWS o CLI) per ottenerne una prima di utilizzare gli endpoint rilevati. client_id Amazon Cognito non supporta la registrazione dinamica dei client (RFC 7591).

Passaggio 6: configura il tuo agente per accedere agli strumenti tramite OAuth

In questa sezione, imparerai come connettere il codice del tuo agente con i fornitori di AgentCore credenziali per un accesso sicuro a risorse esterne utilizzando l'autenticazione OAuth2.

L'esempio seguente mostra come l'agente in esecuzione in Agent Runtime può richiedere il consenso OAuth agli utenti, consentendogli di autenticarsi con il proprio account Google e autorizzare l'agente ad accedere ai contenuti di Google Drive.

Per ulteriori informazioni sulla configurazione dell'identità, consulta Guida introduttiva all'identità. AgentCore

Passaggio 6.1: Configurare i fornitori di credenziali

Per configurare un Google Credential Provider, devi:

Registra la tua applicazione con Google per ottenere l'ID cliente e il segreto del cliente

Crea un provider di credenziali OAuth utilizzando la CLI. AWS Sostituisci your-client-id e your-client-secret con l'ID client e il segreto del client Google OAuth2 effettivi:


OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
  --name "google-provider" \
  --credential-provider-vendor "GoogleOauth2" \
  --oauth2-provider-config-input '{
      "googleOauth2ProviderConfig": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret"
      }
    }' \
--output json)

OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')

echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"

Nota

Ottieni il codice callbackUrl dalla CreateOauth2CredentialProviderrisposta e aggiungi l'URI all'elenco degli URI di reindirizzamento dell'applicazione Google. L'URL di callback dovrebbe avere il seguente aspetto: ********-****-******-************ https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/

Assicurati che il tuo ruolo di invocazione disponga delle autorizzazioni necessarie per accedere al provider di credenziali.

Passaggio 6.2: consentire all'agente di leggere i contenuti di Google Drive

Crea uno strumento con le annotazioni SDK di base dell'agente, come mostrato nell'esempio seguente, per avviare automaticamente il processo OAuth a tre fasi. Quando il tuo agente richiama questo strumento, agli utenti verrà richiesto di aprire l'URL di autorizzazione nel browser e concedere il consenso all'agente per accedere a 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,
    callback_url='insert_oauth2_callback_url_for_session_binding'
)
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=""))

Nota

Per un esempio di implementazione del server di callback locale per gestire l'associazione delle sessioni, consulta oauth2_callback_server.py su GitHub

Cosa succede dietro le quinte

Quando viene eseguito questo codice, si verifica il seguente processo:

Agent Runtime autorizza il token in entrata in base all'autorizzatore configurato.
Agent Runtime scambia questo token con un token di accesso al carico di lavoro tramite bedrock-agentcore:GetWorkloadAccessTokenForJWT API e lo consegna al codice dell'agente tramite l'intestazione del payload. WorkloadAccessToken
Durante l'invocazione dello strumento, l'agente utilizza questo token di accesso al carico di lavoro per chiamare l'API bedrock-agentcore:GetResourceOauth2Token Token Vault e generare un URL di autenticazione 3LO.
L'agente invia questo URL all'applicazione client come specificato nel metodo. on_auth_url
L'applicazione client presenta questo URL all'utente, che concede il consenso all'agente per accedere al proprio Google Drive.
AgentCore Il servizio Identity riceve e memorizza nella cache in modo sicuro il token di accesso di Google fino alla sua scadenza, consentendo alle successive richieste dell'utente di utilizzare questo token senza che l'utente fornisca il consenso per ogni richiesta.

Nota

AgentCore Identity Service archivia il token di accesso di Google in AgentCore Token Vault utilizzando l'identità del carico di lavoro dell'agente e l'ID utente (dal token JWT in entrata, come il token Amazon Cognito) come chiave vincolante, eliminando le richieste di consenso ripetute fino alla scadenza del token Google.

Passaggio 7: (Facoltativo) Propagazione di un token JWT a Runtime AgentCore

Facoltativamente, puoi passare un'intestazione di autorizzazione a un AgentCore Runtime per estrarre le attestazioni. Questo può essere fatto utilizzando la configurazione allowlist dell'intestazione della richiesta. Per ulteriori informazioni, consulta RequestHeaderConfiguration.

Passaggio 7.1: Modifica il codice dell'agente per leggere le intestazioni

In questo passaggio apporti modifiche al codice del tuo agente in modo da poter decodificare ed estrarre le affermazioni da un token JWT utilizzando la libreria PyJWT.

Dipendenze in Python

Aggiungi PyJWT all'agente generato: pyproject.toml


cd app/OAuthAgent
uv add PyJWT
cd ../..

Aggiorna il codice del tuo agente

Modifica app/OAuthAgent/main.py come mostrato nel codice seguente. Puoi saltare la convalida della firma del token qui perché AgentCore Runtime ha già convalidato il token durante l'autorizzazione in entrata.


import jwt
import json
....

@app.entrypoint
def invoke(payload, context):
    auth_header = context.request_headers.get('Authorization')
    if not auth_header:
        return None

    # Remove "Bearer " prefix if present
    token = auth_header.replace('Bearer ', '') if auth_header.startswith('Bearer ') else auth_header
    try:
        # Skip signature validation as agent runtime has validated the token already.
        claims = jwt.decode(token, options={"verify_signature": False})
        app.logger.info("Claims: %s", json.dumps(claims))
    except jwt.InvalidTokenError as e:
        app.logger.exception("Invalid JWT token: %s", e)

    .....

Fase 7.2: Implementazione dell'agente aggiornato

Il agentcore add agent comando nel passaggio 4 ha già configurato la lista dei permessi dell'intestazione della Authorization richiesta. Distribuisci l'aggiornamento del codice:


agentcore deploy

Passaggio 7.3: richiama il tuo agente

Invoca il tuo agente utilizzando OAuth e dovresti vedere le affermazioni nei log del tuo agente in Logs. CloudWatch

Risoluzione dei problemi

Come eseguire il debug dei problemi relativi ai token

Se riscontri problemi con l'autenticazione tramite token, puoi decodificare il token per controllarne il contenuto:


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

Questo genererà il payload del token, che assomiglia a:


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

Per la risoluzione dei problemi relativi ai token, controlla quanto segue:

L'URL dell'emittente a cui fa riferimento l'URL di rilevamento nell'autorizzatore dell'agente deve corrispondere all'attestazione dell'emittente contenuta nel token. Effettua le seguenti operazioni per confermare che corrispondono:
- Seleziona l'URL di scoperta che hai fornito nella configurazione dell'autorizzatore quando hai creato l'agente, ad esempio: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_nnnnnnnnn/.well-known/openid-configuration
  - Controlla l'URL dell'emittente -. "issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_12345566" Dovrebbe corrispondere al valore del claim iss nel token.
client_idil claim nel token deve corrispondere a una delle voci dell'autorizzatore AllowedClients, se fornite
- Annota l'ID client che hai fornito quando hai creato l'agente
- Verifica che corrisponda all'affermazione client_id nel token decodificato
audl'affermazione nel token deve corrispondere a una delle voci dell'autorizzazione, se fornita allowedAudience
- Annota l'elenco dei destinatari che hai fornito quando hai creato l'agente
- Verifica che corrisponda all'audaffermazione nel token decodificato
I token sono validi solo per alcuni minuti (la scadenza predefinita di Amazon Cognito è di 60 minuti). Se necessario, recupera un nuovo token.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Passa intestazioni personalizzate

AgentCore Controllo delle versioni e degli endpoint in fase di esecuzione