Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Ottieni il token di accesso OAuth 2.0
AgentCore L'identità 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 e il server di autorizzazione a valle e recupererà e memorizzerà 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 mostrato 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 automatici dei token di aggiornamento
AgentCore archivia e utilizza automaticamente i token di aggiornamento quando disponibili presso i 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 memorizza 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
La validità dei token di accesso AgentCore restituiti da non è garantita. I token possono essere revocati dai clienti del fornitore federato, che non sono in grado di 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 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 archiviato per richiedere un nuovo token di accesso al provider. Se viene archiviato 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 richiede nuovamente all'utente la 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 tuo provider:
| Provider | Configurazione richiesta |
|---|---|
|
|
|
|
Microsoft |
|
|
Salesforce |
|
|
Atlassian |
|
|
GitHub |
Non è richiesta alcuna AgentCore configurazione aggiuntiva. Abilita la funzione di scadenza del User-to-server token nelle impostazioni GitHub dell'app. I token di aggiornamento vengono archiviati automaticamente quando questa funzione è abilitata. |
|
Slack |
Non è richiesta alcuna AgentCore configurazione aggiuntiva. Abilita la funzione «rotazione dei token» nelle impostazioni dell'app Slack. I token di aggiornamento vengono restituiti automaticamente quando questa funzione è abilitata. |
|
|
Non è richiesta alcuna AgentCore configurazione aggiuntiva. Abilita le impostazioni dei token di aggiornamento nella configurazione LinkedIn dell'app. |
|
Altri provider |
Alcuni provider richiedono una 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 ulteriori configurazioni. Per cancellare i token di aggiornamento archiviati e forzare gli utenti a riautenticarsi, impostalo al momento della chiamata. forceAuthentication=true GetResourceOauth2Token Questo cancella il token di aggiornamento e impone un flusso federativo 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 fasi, 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.
Schemi di implementazione comuni
Modello di risposta in streaming: per le applicazioni che supportano le risposte in streaming, 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))
Pattern di callback: per le applicazioni che utilizzano callback o webhook, memorizza l'URL di autorizzazione e invia una notifica al 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 polling: per le applicazioni che preferiscono il polling, memorizza 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 modello 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 pattern di callback e polling funzionano bene per scenari di elaborazione asincrona o in batch.
Indicatori di risorse nei flussi OAuth2 AgentCore
Gli indicatori di risorse 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 previsto durante le richieste di token. Per utilizzare gli indicatori di risorse, devi prima configurare il server di autorizzazione in modo che riconosca 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 il corrispondente identificatore del server di risorse nella dichiarazione aud del token risultante, consentendo al server di risorse di verificare che il token sia destinato al suo uso specifico. Ciò offre diversi importanti vantaggi: i server di risorse possono convalidare che i token sono specificamente destinati 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.
Tramite l'implementazione
Utilizza gli indicatori delle risorse quando i tuoi agenti devono accedere a server di risorse con requisiti di sicurezza specifici o quando hai bisogno di un controllo dettagliato sulla convalida dell'audience dei token. Gli indicatori delle risorse sono particolarmente utili per le applicazioni multi-tenant in cui i token devono essere limitati a risorse specifiche dei clienti.
