View a markdown version of this page

Ottieni il token di accesso al carico di lavoro - Amazon Bedrock AgentCore
Cos'è un token di accesso al carico di lavoro?In che modo Runtime e Gateway ottengono automaticamente i tokenCome recuperare manualmente i token di accesso al carico di lavoroControlli di sicurezza per l'API GetWorkloadAccessTokenForUserId

Ottieni il token di accesso al carico di lavoro

Comprendere cosa sono i token di accesso al carico di lavoro, come ottenerli e gli aspetti di sicurezza legati al loro utilizzo è essenziale per creare applicazioni per agenti sicure. Questa sezione descrive i concetti chiave e i modelli di implementazione che devi conoscere.

Cos'è un token di accesso al carico di lavoro?

Un token di accesso al carico di lavoro è un token di accesso opaco AWS firmato che consente agli agenti di accedere a AgentCore servizi di prime parti, come i provider di credenziali in uscita. Runtime fornisce automaticamente i token di accesso al carico di lavoro alle istanze di esecuzione degli agenti come intestazioni di payload, eliminando la necessità di una gestione manuale dei token nella maggior parte degli scenari.

Caratteristiche chiave

  • First-party solo servizi: i token di accesso al carico di lavoro servono esclusivamente per accedere a servizi di AWS prime parti e non possono essere utilizzati per servizi esterni AgentCore

  • Distribuzione automatica: Runtime e Gateway forniscono automaticamente questi token agli agenti durante l'esecuzione

  • Sicurezza fin dalla progettazione: le identità degli Runtime-managed agenti non possono recuperare direttamente i token di accesso ai carichi di lavoro, impedendo l'estrazione e l'uso improprio dei token

  • Associazione dell'identità dell'utente e dell'agente: i token contengono sia informazioni sull'identità dell'utente che sull'identità dell'agente per un accesso sicuro alle credenziali

In che modo Runtime e Gateway ottengono automaticamente i token

Quando un agente viene richiamato tramite AgentCore Runtime o Gateway con autenticazione in entrata, il servizio gestisce automaticamente la generazione di token di accesso al carico di lavoro:

  1. Runtime convalida il token OAuth del provider di identità in entrata (emittente, firma)

  2. Runtime estrae le attestazioni emittenti e secondarie dal token OAuth che rappresenta l'identità dell'utente

  3. Runtime recupera l'identità del carico di lavoro associato dell'agente

  4. Runtime richiama sia l'identità dell'utente che GetWorkloadAccessTokenForJWT l'identità del carico di lavoro dell'agente

  5. Runtime passa il token di accesso al carico di lavoro al codice dell'agente come parte dell'intestazione del payload di invocazione

Questo processo automatico garantisce che gli agenti ricevano token con ambito adeguato senza intervento manuale.

Come recuperare manualmente i token di accesso al carico di lavoro

Esistono due modelli da utilizzare per recuperare il token di accesso al carico di lavoro, a seconda di come si è in grado di identificare l'utente finale dell'agente:

Schema 1: JWT-based identificazione (consigliato per la produzione)

Se il chiamante dell'agente ha un JWT emesso da un provider di identità per l'utente finale, richiedi un token di accesso al carico di lavoro utilizzando. GetWorkloadAccessTokenForJWT Quando fornisci un JWT, AgentCore Identity convalida il token per garantire che sia firmato correttamente e che non sia scaduto e utilizza le dichiarazioni «iss» e «sub» per identificare in modo univoco l'utente. Le credenziali archiviate dall'agente per conto dell'utente sono associate a questa identità verificata crittograficamente e i recuperi futuri richiedono un token di accesso al carico di lavoro valido con la stessa identità.

Usa questo schema quando:

  • L'applicazione si integra con un provider di identità (Cognito, Auth0, Okta, ecc.)

  • È necessaria una prova crittografica dell'identità dell'utente finale

  • Stai passando alla produzione

Schema 2: identificazione UserId-based

Se il chiamante dell'agente non dispone di un JWT che identifichi l'utente finale, richiedi un token di accesso al carico di lavoro utilizzando GetWorkloadAccessTokenForUserId una stringa univoca che identifichi l'utente.

Usa questo schema quando:

  • La tua applicazione gestisce i propri identificatori utente e devi passare stringhe UserID gestite dal cliente a Identity AgentCore

  • Ti trovi in uno scenario di sviluppo o di avvio rapido in cui un token IdP non è ancora disponibile

  • L'architettura aziendale risolve l'identità dell'utente a monte e trasmette un identificatore affidabile al carico di lavoro dell'agente

Compromesso: la piattaforma tratta l'UserID come una stringa opaca e non può verificarlo rispetto a un'identità autenticata dell'utente finale. L'associazione di sicurezza si basa sul fatto che il carico di lavoro chiamante passi lo userID corretto e che le policy IAM siano definite in modo appropriato. Vedi per i Controlli di sicurezza per l'API GetWorkloadAccessTokenForUserId controlli consigliati.

Esempi di codice

Gli esempi seguenti illustrano l'utilizzo dell' AgentCore SDK per recuperare un token di accesso al carico di lavoro utilizzando questi due metodi:

from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

Controlli di sicurezza per l'API GetWorkloadAccessTokenForUserId

L'GetWorkloadAccessTokenForUserIdAPI accetta una stringa di identificazione utente fornita dal chiamante ed emette un token di accesso al carico di lavoro relativo a quella coppia utente-agente. Questa API è progettata per supportare i clienti aziendali che devono passare stringhe UserID gestite dal cliente e i builder che non dispongono di token Identity Provider (IdP) disponibili durante lo sviluppo.

Importante

Quando viene utilizzatoGetWorkloadAccessTokenForUserId, la piattaforma tratta il userId valore come una stringa opaca e non lo verifica rispetto all'identità autenticata dell'utente finale. L'associazione di sicurezza si basa interamente sul fatto che il carico di lavoro chiamante trasmetta l'UserID corretto e che le policy IAM vengano definite in modo appropriato. Se l'applicazione ha accesso a un JWT che identifica l'utente finale, utilizza GetWorkloadAccessTokenForJWT invece, che convalida l'emittente, la firma e la scadenza del token prima di emettere un token di accesso al carico di lavoro.

L'GetWorkloadAccessTokenForUserIdAPI implementa diversi controlli di sicurezza per impedire l'accesso non autorizzato:

  • Convalida dell'identità del carico di lavoro: l'API verifica che l'identità richiedente sia autorizzata ad agire per conto dell'identità del carico di lavoro specificata

  • Service-managed restrizione dell'identità: le identità del carico di Gateway-managed lavoro non possono Runtime-managed recuperare direttamente i token. Ciò impedisce agli agenti di estrarre token per uso improprio

  • Requisiti di autorizzazione IAM: i chiamanti devono disporre delle autorizzazioni IAM appropriate, tra cui, e GetWorkloadAccessToken GetWorkloadAccessTokenForUserId GetWorkloadAccessTokenForJWT

  • Ambito dei token: i token sono limitati alla specifica coppia utente-agente, garantendo che le credenziali archiviate in un utente non possano essere accessibili da un altro utente

  • Partizionamento degli ID utente per più provider di identità: quando si utilizzano più provider di identità, partiziona gli ID utente utilizzando lo schema provider_id+user_id per evitare collisioni tra utenti tra diversi provider. Ad esempio, utilizza cognito+user123 e auth0+user123 distingue gli utenti con lo stesso identificatore tra diversi provider di identità

Controlli di sicurezza consigliati

Poiché la piattaforma non è in grado di verificare la stringa userID, sei responsabile di garantire l'integrità del valore passato a questa API. Applica i seguenti controlli:

  • Preferisci GetWorkloadAccessTokenForJWT quando è disponibile un JWT: il JWT-based percorso convalida l'emittente e la firma del token, fornendo una prova crittografica dell'identità dell'utente. Utilizzare GetWorkloadAccessTokenForUserId solo quando un JWT non è disponibile.

  • Deriva lo userID da una fonte attendibile: il valore userID deve essere derivato dal contesto del principale autenticato (ad esempio, l'identità del chiamante IAM, gli attributi di sessione o un livello di risoluzione dell'identità a monte) anziché accettare valori arbitrari forniti dal client. Ciò impedisce a un chiamante autenticato di impersonare un altro utente.

  • Limita l'autorizzazione IAM: solo i responsabili affidabili dovrebbero avere l'autorizzazione. bedrock-agentcore:GetWorkloadAccessTokenForUserId Estendi questa autorizzazione a risorse di identità del carico di lavoro specifiche. Non concederla in modo generalizzato tramite policy gestite o dichiarazioni di risorse wildcard.

  • Nega GetWorkloadAccessTokenForUserId dove non è necessario: per i carichi di lavoro che hanno sempre un JWT disponibile, nega esplicitamente l'azione nelle policy IAM per impedire l'utilizzo del percorso UserID:

    {
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

  • Implementazione della registrazione di controllo: registra la relazione tra il principale IAM autenticato e il valore userID passato. Utilizzato AWS CloudTrail per monitorare GetWorkloadAccessTokenForUserId le chiamate e rilevare valori UserID imprevisti.

Se si verifica l'errore "WorkloadIdentity è collegato a un servizio e non può recuperare un token di accesso dal chiamante», significa che l'identità del carico di lavoro è gestita da Runtime o Gateway e non può recuperare direttamente i token. Questa restrizione aiuta a mantenere i limiti di sicurezza e impedisce l'accesso non autorizzato ai token.

Per ulteriori controlli di sicurezza, puoi implementare policy di accesso granulari per limitare le identità dei carichi di lavoro che possono accedere a provider di credenziali specifici. Per ulteriori informazioni, consulta Ridurre l'accesso ai provider di credenziali in base all'identità del carico di lavoro.