Autentica e autorizza con Inbound Auth e Outbound Auth

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

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

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

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

Limita l'invocazione in entrata di IAM (Sigv4) al tuo gateway

Puoi configurare il tuo AgentCore Runtime con un AgentCore gateway in modo che il gateway diventi l'unico punto di accesso controllato al runtime, con autorizzazione basata su policy, Amazon Bedrock Guardrails, intercettori di richieste e risposte e osservabilità unificata, il tutto applicato all'esterno dell'ambiente dell'agente. Per una spiegazione completa e per sapere 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 tuo runtime utilizza l'autorizzazione in entrata IAM (Sigv4) predefinita, puoi limitare l'invocazione al gateway in modo che il traffico raggiunga il runtime solo attraverso di esso. A tale scopo, allega al runtime una policy basata sulle risorse che limiti l'invocazione al ruolo di esecuzione del gateway. Il gateway assume il ruolo di servizio per firmare le richieste al runtime, quindi il ruolo del gateway è il principale che richiama il runtime. Consenti quel ruolo e aggiungi un 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 sui runtime, consulta le politiche per Amazon Bedrock. Resource-based 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"
                }
            }
        }
    ]
}

Esempio di autorizzazione in entrata JWT e accesso in uscita OAuth

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 sarà autorizzato utilizzando i token di accesso Cognito. AWS 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 come:

Prerequisiti

Prima di iniziare, assicurati di avere:

Fase 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 nel passaggio 2.

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

Questo genera:

Fase 2: Configurazione AWS Crea un pool di utenti di Cognito e aggiungi un utente

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

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

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

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

Passaggio 3 (opzionale): anticipa il tuo runtime con un AgentCore Gateway

Puoi configurare il AgentCore runtime con un AgentCore gateway in modo che il gateway diventi l'unico punto di accesso controllato al runtime, offrendoti un'autorizzazione basata su policy, Amazon Bedrock Guardrails, intercettori di richieste e risposte e osservabilità unificata, il tutto applicato all'esterno dell'ambiente dell'agente. Per una spiegazione completa e per sapere come configurarlo, consulta Front your runtime with an Gateway. AgentCore

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

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

Fase 4: Distribuisci il tuo agente

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

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.

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

consentitoWorkloadConfiguration: limita l'invocazione al tuo gateway

Il allowedWorkloadConfiguration campo sul campo customJWTAuthorizer limita i carichi di lavoro nella catena di identità della richiesta che possono richiamare il runtime. Imposta il carico di lavoro consentito sul tuo 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 nel passaggio 3.

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

La seguente configurazione dell'autorizzatore limita l'invocazione a un gateway specifico AgentCore tramite il relativo ARN. La hostingEnvironments sola specificazione è 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 identificativo del carico di lavoro o specificare entrambi i campi. Quando sono presenti entrambi, è consentita una richiesta se corrisponde a una voce in uno dei due campi. Lo allowedWorkloadConfiguration snippet seguente consente due gateway diversi, uno identificato dal relativo ARN e l'altro 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"
    ]
}

Crea e distribuisci il runtime dell'agente

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

Passaggio 5: utilizza il token al portatore per invocare il tuo agente

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

{
    "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 al portatore 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.

Richiama l'agente con OAuth.

Risposte agli errori 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 (per 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 clienti di scoprire quali server di autorizzazione proteggono questo agente e i relativi URL degli endpoint OAuth.

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

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

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

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

Passaggio 6.1: Configurare i provider di credenziali

Per configurare un fornitore di credenziali Google, devi:

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

Passaggio 6.2: abilita l'agente a leggere i contenuti di Google Drive

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

Cosa succede dietro le quinte

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

Passaggio 7: (Facoltativo) Propaga un token JWT su Runtime AgentCore

Facoltativamente, puoi passare un'intestazione di autorizzazione a un AgentCore Runtime per estrarre i claim. Questa operazione può essere eseguita 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 i claim da un token JWT utilizzando la libreria PyJWT.

Dipendenze 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)

    .....

Passaggio 7.2: Distribuire l'agente aggiornato

Il agentcore add agent comando nel passaggio 4 ha già configurato l'header della Authorization richiesta allowlist. Distribuisci l'aggiornamento del codice:

agentcore deploy

Passaggio 7.3: richiama il tuo agente

Richiamate il vostro agente usando OAuth e dovreste vedere le affermazioni nei log del vostro agente. CloudWatch

Risoluzione dei problemi

Come eseguire il debug dei problemi relativi ai token

Se riscontri problemi con l'autenticazione del 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 produrrà il payload del token, che è simile 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 risolvere i problemi relativi ai token, verifica quanto segue: