Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Il codice di autorizzazione OAuth 2.0 concede l'accesso a un utente e ottiene i token con autorizzazioni delegate. L'utente accede tramite un browser, Microsoft Entra ID restituisce un codice di autorizzazione di breve durata e il client riscatta il codice nell'endpoint del token.
Una soluzione ID agente può usare la concessione in due modi:
| Tipo di client | Ruolo tipico | Credenziali client | PKCE |
|---|---|---|---|
| Client pubblico | Un agente locale accede direttamente all'utente. | No | Required |
| Client riservato | Un client Web lato server accede all'utente prima di chiamare un agente ospitato. | Yes | Recommended |
Usare Libreria di Autenticazione Microsoft (MSAL) o Microsoft. Identity.Web invece di creare direttamente queste richieste. Le richieste in questo articolo mostrano i campi del protocollo per riferimento.
Warning
Microsoft consiglia di usare gli SDK approvati, come le librerie Microsoft.Identity.Web e Microsoft Entra ID Auth SDK (sidecar), per implementare questi protocolli. L'implementazione manuale di questi protocolli è complessa e soggetta a errori e l'uso degli SDK consente di garantire la sicurezza e la conformità con le procedure consigliate.
Importante
Il supporto dell'ID agente client pubblico è in anteprima. Questa anteprima viene fornita senza un contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o avere funzionalità vincolate. Per altre informazioni, vedere Condizioni di licenza universali per i servizi online.
Richiesta di autorizzazione
Entrambi i tipi di client inviano l'utente all'endpoint di autorizzazione del tenant:
GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?
client_id={client-id}
&response_type=code
&redirect_uri={encoded-redirect-uri}
&response_mode=query
&scope=openid%20profile%20offline_access%20api://{resource-client-id}/{scope}
&state={random-state}
&nonce={random-nonce}
&code_challenge={pkce-challenge}
&code_challenge_method=S256
-
client_ididentifica il client pubblico o riservato. Un client pubblico basato su CIMD usa l'URL del documento di metadati HTTPS come ID client. -
redirect_urideve corrispondere esattamente a un URI di reindirizzamento configurato per il client. -
scopecontiene le autorizzazioni delegate richieste dal client. Omettere l'ambito della risorsa quando il client deve accedere solo all'utente. -
stateassocia la risposta alla sessione di avvio e consente di evitare la falsificazione della richiesta intersito. -
nonceassocia un token OPENID Connect ID alla sessione di avvio. -
code_challengeè derivato da un verifier PKCE ad alta entropia usando SHA-256.
Dopo l'accesso e il consenso, Microsoft Entra ID reindirizza il browser all'URI di reindirizzamento registrato:
GET {redirect-uri}?code={authorization-code}&state={state}
Prima di riscattare il codice, convalidare state e gestire eventuali errori OAuth restituiti all'URI di reindirizzamento.
Richiesta di token client pubblico
Un client pubblico non può proteggere le credenziali client. Riscatta il codice usando il verifier PKCE:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={agent-id-client-id-or-cimd-url}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{resource-client-id}/{scope}
&code_verifier={pkce-verifier}
Non inviare un segreto client, un'asserzione di certificati o credenziali federate in questa richiesta.
Un ID agente pubblico registrato deve usare la modalità a istanza singola. Un client che usa un documento di metadati ID client può usare l'URL HTTPS del documento come ID client. Per indicazioni sull'implementazione, vedere Accedere agli utenti da un agente locale.
Richiesta di token client riservati
Un client riservato viene eseguito in un server in grado di proteggere le credenziali. Il server, non il codice del browser, riscatta il codice di autorizzazione. La richiesta include una credenziale client e il verificatore PKCE quando la richiesta di autorizzazione usa PKCE:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={confidential-client-id}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{agent-blueprint-client-id}/{scope}
&code_verifier={pkce-verifier}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={signed-client-assertion}
Nell'esempio viene usata un'asserzione client basata su certificati. Un segreto client è supportato anche, ma usare un certificato o una federazione dell'identità del carico di lavoro, quando possibile.
In una soluzione ID agente ospitato, il client riservato è in genere l'applicazione Web upstream, non l'ID agente figlio. Richiedere un token di accesso il cui gruppo di destinatari è il progetto dell'agente ospitato, inviare tale token di accesso all'API dell'agente e usare il flusso on-Behalf-Of per chiamare le API downstream.
Per un'identità dell'agente a istanza singola (anteprima), <agent-blueprint-client-id> indica l'ID client condiviso dal progetto e dall'identità dell'agente. Per una flotta, indica l'ID client del progetto, non l'ID di un singolo agente figlio. Per la modalità a istanza singola, configurare la concessione del client upstream tramite Concedi l'accesso client upstream prima dell'accesso ; il consenso del browser non supporta l'identità dell'agente come risorsa.
Non inviare un codice di autorizzazione o un token ID all'API dell'agente ospitato. Gli ID agente figlio nel modello confidential-client non avviano una richiesta interattiva /authorize .
Risposta del token
Se la richiesta ha esito positivo, Microsoft Entra ID restituisce token come:
{
"token_type": "Bearer",
"scope": "api://<resource-client-id>/<scope>",
"expires_in": 3599,
"access_token": "<access-token>",
"refresh_token": "<refresh-token>",
"id_token": "<id-token>"
}
La risposta esatta dipende dagli ambiti richiesti:
- Usare il token di accesso solo con la risorsa identificata dalla relativa
audattestazione. - Usare il token ID per stabilire la sessione di accesso dell'utente, non per chiamare un'API.
- Un token di aggiornamento viene restituito quando la richiesta e i criteri consentono l'accesso offline.
Requisiti di sicurezza
- Usare PKCE con il
S256metodo challenge per i client pubblici. Usare anche PKCE per i client riservati quando la libreria la supporta. - Trovare la corrispondenza con l'URI di reindirizzamento esattamente nelle richieste di autorizzazione e token.
- Generare un nuovo
stateverificatore ,noncee PKCE per ogni richiesta di autorizzazione. - Riscattare un codice di autorizzazione una sola volta e solo dal client che ha avviato la richiesta.
- Non registrare codici di autorizzazione, credenziali client, token di accesso, token di aggiornamento o token ID.
- Convalidare i token di accesso nell'API. Non considerare il possesso di un codice di autorizzazione o di un token ID come autorizzazione API.
Contenuti correlati
- Microsoft Identity Platform e flusso del codice di autorizzazione di OAuth 2.0
- Client pubblico e applicazioni client riservate
- Restrizioni e limitazioni dell'URI di reindirizzamento
- Credenziali del certificato per l'autenticazione dell'applicazione
- Scegliere un protocollo di autenticazione per un agente