Ottieni il token di accesso OAuth 2.0
AgentCore Identity consente agli sviluppatori di ottenere token OAuth per l'accesso delegato dall'utente o per l'autenticazione da macchina a macchina in base ai provider di credenziali OAuth 2.0 configurati. Il servizio orchestrerà il processo di autenticazione tra l'utente o l'applicazione sul server di autorizzazione a valle e recupererà e archivierà il token risultante. Una volta che il token è disponibile nell' AgentCore Identity vault, gli agenti autorizzati possono recuperarlo e utilizzarlo per autorizzare le chiamate ai server di risorse. Ad esempio, il codice di esempio riportato di seguito recupererà un token per interagire con Google Drive per conto di un utente finale. Per ulteriori informazioni, consulta Integrazione con Google Drive utilizzando OAuth2 per l'esempio completo.
# Injects Google Access Token @requires_access_token( # Uses the same credential provider name created above provider_name= "google-provider", # Requires Google OAuth2 scope to access Google Drive scopes= ["https://www.googleapis.com/auth/drive.metadata.readonly"], # Sets to OAuth 2.0 Authorization Code flow auth_flow= "USER_FEDERATION", # Prints authorization URL to console on_auth_url= lambda x: print("\nPlease copy and paste this URL in your browser:\n" + x), # If false, caches obtained access token force_authentication= False, callback_url='insert_oauth2_callback_url_for_session_binding', ) async def write_to_google_drive(*, access_token: str): # Use the token to call Google Drive pass # To invoke: # asyncio.run(write_to_google_drive())
Il processo è simile all'ottenimento di un token per le chiamate da macchina a macchina, come illustrato nell'esempio seguente:
import asyncio from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key @requires_access_token( provider_name= "my-api-key-provider", # replace with your own credential provider name scopes= [], auth_flow= 'M2M', ) async def need_token_2LO_async(*, access_token: str): # Use the access token pass # To invoke: # asyncio.run(need_token_2LO_async())
Argomenti
Archiviazione e utilizzo dei token di aggiornamento automatico
AgentCore archivia e utilizza automaticamente i token di aggiornamento quando disponibili dai provider OAuth2, riducendo la frequenza delle richieste di riautorizzazione degli utenti. Quando gli utenti inizialmente concedono il consenso tramite un flusso di codice di autorizzazione OAuth2 standard, il sistema archivia sia i token di accesso che i token di aggiornamento (se forniti) nell'archivio sicuro dei token. Ciò consente agli agenti di ottenere automaticamente nuovi token di accesso alla scadenza dei token originali, migliorando l'esperienza dell'utente riducendo al minimo le richieste di consenso ripetute.
Importante
Non è garantito che i token di accesso restituiti da AgentCore siano validi. I token possono essere revocati dai clienti del provider federato, che non possono rilevarli. AgentCore Se un token non è valido, utilizzalo forceAuthentication: true per forzare un nuovo flusso di autenticazione e ottenere un token di accesso valido.
I token di aggiornamento hanno in genere una durata di vita più lunga rispetto ai token di accesso, con un periodo di validità predefinito di circa 30 giorni rispetto alla durata più breve dei token di accesso (spesso 1-2 ore). Quando un token di accesso scade, utilizza AgentCore automaticamente il token di aggiornamento memorizzato per richiedere un nuovo token di accesso al provider. Se viene memorizzato un token di aggiornamento valido, AgentCore salta il flusso di federazione degli utenti e restituisce direttamente un nuovo token di accesso. Se anche il token di aggiornamento è scaduto o non è valido, il sistema torna a richiedere all'utente una riautorizzazione completa.
Questa funzionalità non richiede alcuna configurazione interna AgentCore : funziona automaticamente quando i token di aggiornamento sono presenti nella risposta del token del provider OAuth2. Tuttavia, è necessario configurare il provider OAuth2 per includere i token di aggiornamento nel flusso di autorizzazione. La configurazione specifica dipende dal provider:
| Provider | Configurazione richiesta |
|---|---|
|
|
|
|
Microsoft |
|
|
Salesforce |
|
|
Atlassian |
|
|
GitHub |
Non è richiesta alcuna AgentCore configurazione aggiuntiva. Abilita la funzione di scadenza dei User-to-server token nelle impostazioni GitHub dell'app. I token di aggiornamento vengono memorizzati automaticamente quando questa funzionalità è abilitata. |
|
Slack |
Non è richiesta alcuna AgentCore configurazione aggiuntiva. Abilita la funzione di «rotazione dei token» nelle impostazioni dell'app Slack. I token di aggiornamento vengono restituiti automaticamente quando questa funzionalità è abilitata. |
|
|
Non è richiesta alcuna AgentCore configurazione aggiuntiva. Abilita le impostazioni del token di aggiornamento nella configurazione LinkedIn dell'app. |
|
Altri fornitori |
Alcuni provider richiedono la configurazione nelle impostazioni del provider anziché nei parametri API. Consulta la documentazione del tuo provider per i requisiti dei token di aggiornamento. |
Se il tuo provider supporta i token di aggiornamento ed è configurato correttamente, li AgentCore memorizzerà e li gestirà automaticamente senza configurazioni aggiuntive. Per cancellare i token di aggiornamento memorizzati e costringere gli utenti a riautenticarsi, imposta durante la chiamata. forceAuthentication=true GetResourceOauth2Token Questo cancella il token di aggiornamento e forza un flusso di federazione completo. Per informazioni sulla configurazione dei provider OAuth2, consulta Configurazione e configurazione del provider.
Streaming degli URL di autorizzazione ai chiamanti dell'applicazione
Per i flussi OAuth (3LO) a tre vie, l'agente deve fornire l'URL di autorizzazione all'applicazione chiamante in modo che gli utenti possano completare il flusso di consenso. Sebbene gli esempi precedenti mostrino la stampa dell'URL sulla console, le applicazioni di produzione richiedono lo streaming dell'URL al chiamante tramite il meccanismo di risposta dell'applicazione.
Modelli di implementazione comuni
Schema di risposta in streaming: per le applicazioni che supportano lo streaming di risposte, puoi inviare l'URL di autorizzazione come parte del flusso di risposta:
import asyncio from bedrock_agentcore.identity.auth import requires_access_token @requires_access_token( provider_name="google-provider", scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], auth_flow="USER_FEDERATION", # Stream URL back to caller instead of printing on_auth_url=lambda url: stream_to_caller({ "type": "authorization_required", "authorization_url": url, "message": "Please visit this URL to authorize access" }), force_authentication=False, callback_url='insert_oauth2_callback_url_for_session_binding' ) async def agent_with_streaming_auth(*, access_token: str): # Agent logic continues after user completes authorization return {"status": "success", "token_received": True} def stream_to_caller(data): # Implementation depends on your streaming mechanism # Examples: WebSocket, Server-Sent Events, HTTP chunked response response_stream.send(json.dumps(data))
Schema di callback: per le applicazioni che utilizzano callback o webhook, memorizza l'URL di autorizzazione e avvisa il chiamante:
import asyncio from bedrock_agentcore.identity.auth import requires_access_token @requires_access_token( provider_name="google-provider", scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], auth_flow="USER_FEDERATION", # Store URL and trigger callback on_auth_url=lambda url: handle_auth_callback(url), force_authentication=False, callback_url='insert_oauth2_callback_url_for_session_binding' ) async def agent_with_callback_auth(*, access_token: str): return {"status": "success", "data": "processed"} def handle_auth_callback(authorization_url): # Store the URL associated with the request auth_store.save(request_id, { "authorization_url": authorization_url, "status": "pending_authorization" }) # Notify the calling application callback_service.notify(callback_url, { "request_id": request_id, "authorization_url": authorization_url, "action_required": "user_authorization" })
Schema di sondaggio: per le applicazioni che preferiscono il polling, archivia l'URL di autorizzazione in una posizione recuperabile:
import asyncio from bedrock_agentcore.identity.auth import requires_access_token @requires_access_token( provider_name="google-provider", scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], auth_flow="USER_FEDERATION", # Store URL for polling retrieval on_auth_url=lambda url: store_auth_url_for_polling(url), force_authentication=False, callback_url='insert_oauth2_callback_url_for_session_binding' ) async def agent_with_polling_auth(*, access_token: str): return {"status": "success", "data": "processed"} def store_auth_url_for_polling(authorization_url): # Store in database, cache, or session store session_store.set(f"auth_url:{session_id}", { "authorization_url": authorization_url, "created_at": datetime.utcnow(), "status": "pending" }, ttl=300) # 5 minute expiration
Scegliete il pattern che meglio si adatta all'architettura della vostra applicazione. Le risposte in streaming offrono la migliore esperienza utente per le applicazioni in tempo reale, mentre i modelli di callback e polling funzionano bene per scenari di elaborazione asincrona o in batch.
Indicatori di risorse nei flussi OAuth2 AgentCore
Gli indicatori di risorsa forniscono un modo standardizzato per specificare quale server di risorse deve accettare un token di accesso OAuth2. AgentCore utilizza Cognito come provider di autenticazione, che supporta indicatori di risorse conformi a RFC 8707 che consentono di specificare il server di risorse desiderato durante le richieste di token. Per utilizzare gli indicatori di risorse, devi prima configurare il server di autorizzazione per riconoscere server di risorse specifici utilizzando l'API di Cognito. CreateResourceServer Una volta configurato, quando specifichi un indicatore di risorsa nella richiesta di token, Cognito include l'identificatore del server di risorse corrispondente nel claim aud del token risultante, consentendo al server di risorse di verificare che il token sia destinato al suo uso specifico. Ciò offre diversi vantaggi importanti: i server di risorse possono verificare che i token siano destinati specificamente a loro (principio del privilegio minimo), una migliore verificabilità identificando chiaramente a quale server di risorse è destinato ciascun token e una riduzione del rischio di uso improprio dei token tra diversi servizi all'interno dell'ambiente applicativo.
Grazie all'implementazione RFC 8707
Utilizza gli indicatori di risorse quando i tuoi agenti devono accedere a server di risorse con requisiti di sicurezza specifici o quando hai bisogno di un controllo preciso sulla convalida del pubblico dei token. Gli indicatori di risorse sono particolarmente utili per le applicazioni multi-tenant in cui i token devono essere limitati a risorse specifiche del cliente.
