Cos'è un token di accesso al carico di lavoro?In che modo Runtime e Gateway ottengono automaticamente i token Come recuperare manualmente i token di accesso al carico di lavoro Controlli di sicurezza per le API GetWorkloadAccessTokenForUserId

Ottieni il token di accesso al carico di lavoro

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

Argomenti

Cos'è un token di accesso al carico di lavoro?
In che modo Runtime e Gateway ottengono automaticamente i token
Come recuperare manualmente i token di accesso al carico di lavoro
Controlli di sicurezza per le API GetWorkloadAccessTokenForUserId

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

Un token di accesso al carico di lavoro è un token AWS di accesso opaco e firmato che consente agli agenti di accedere a AgentCore servizi proprietari, 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 del 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 AWS proprietari 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 al carico di lavoro, prevenendo l'estrazione e l'uso improprio dei token
Associazione dell'identità di utenti e agenti: i token contengono informazioni sull'identità dell'utente e dell'agente per l'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 dei token di accesso al carico di lavoro:

Runtime convalida il token OAuth del provider di identità in entrata (emittente, firma)
Runtime estrae le dichiarazioni emittenti e secondarie dal token OAuth che rappresenta l'identità dell'utente
Runtime recupera l'identità del carico di lavoro associato dell'agente
Runtime richiama GetWorkloadAccessTokenForJWT sia l'identità dell'utente che l'identità del carico di lavoro dell'agente
Runtime passa il token di accesso al carico di lavoro al codice dell'agente come parte dell'intestazione del payload di chiamata

Questo processo automatico garantisce che gli agenti ricevano token con ambito corretto senza interventi manuali.

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 assicurarsi che sia firmato correttamente e non sia scaduto e utilizza le relative 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 modello quando:

L'applicazione si integra con un provider di identità (Cognito, Auth0, Okta, ecc.)
È necessaria una prova crittografica dell'identità dell'utente finale
Stai effettuando la distribuzione in 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 modello quando:

L'applicazione gestisce i propri identificatori utente e devi passare stringhe di ID utente 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

Tradeoff: la piattaforma considera 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 trasmetta l'UserID corretto e che le policy IAM siano definite in modo appropriato. Consulta i controlli consigliati. Controlli di sicurezza per le API GetWorkloadAccessTokenForUserId

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 le API `GetWorkloadAccessTokenForUserId`

L'GetWorkloadAccessTokenForUserIdAPI accetta una stringa identificativa utente fornita dal chiamante ed emette un token di accesso al carico di lavoro con ambito per quella coppia user-agent. 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 si utilizzaGetWorkloadAccessTokenForUserId, la piattaforma considera il userId valore come una stringa opaca e non lo verifica rispetto a un'identità autenticata dell'utente finale. L'associazione di sicurezza si basa interamente sul fatto che il carico di lavoro chiamante trasmetta l'ID utente corretto e che le politiche IAM abbiano un ambito appropriato. Se la tua applicazione ha accesso a un JWT che identifica l'utente finale, usalo 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 accessi non autorizzati:

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à dei carichi di Gateway-managed lavoro non possono Runtime-managed recuperare direttamente i token. Ciò impedisce agli agenti di estrarre i 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 assegnati alla specifica coppia user-agent, garantendo che le credenziali archiviate in un utente non possano essere accessibili da un altro
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 diversi. 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. Usalo GetWorkloadAccessTokenForUserId solo quando un JWT non è disponibile.
Deriva l'ID utente da una fonte attendibile: il valore userID deve essere derivato dal contesto del principale autenticato (ad esempio, l'identità del chiamante IAM, gli attributi della 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 principali fidati dovrebbero avere l'autorizzazione. bedrock-agentcore:GetWorkloadAccessTokenForUserId Ambita questa autorizzazione a specifiche risorse di identità del carico di lavoro. Non concederla in modo generalizzato tramite policy gestite o dichiarazioni di risorse con caratteri jolly.

Nega GetWorkloadAccessTokenForUserId dove non è necessario: per i carichi di lavoro che hanno sempre un JWT disponibile, nega esplicitamente l'azione nelle politiche 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"
      }
   ]
}

Implementa la registrazione di controllo: registra la relazione tra il principale IAM autenticato e il valore userID che viene passato. AWS CloudTrail Da utilizzare per monitorare le GetWorkloadAccessTokenForUserId chiamate e rilevare valori UserID imprevisti.

Se si verifica l'errore «WorkloadIdentity è collegato a un servizio e non è in grado di recuperare un token di accesso dal chiamante», significa che l'identità del carico di lavoro è gestita da Runtime o Gateway e non può recuperare i token direttamente. 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 dettagliate per limitare le identità dei carichi di lavoro che possono accedere a fornitori di credenziali specifici. Per ulteriori informazioni, consulta Scope down access to credencial provider in base all'identità del carico di lavoro.

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

Ottieni le credenziali

Ottieni il token di accesso