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.
Avvertimento
Questo contenuto riguarda l'endpoint di Azure AD v1.0 precedente. Usare l' Microsoft Identity Platform per i nuovi progetti.
Nota
Se non si indica al server quale risorsa si prevede di chiamare, il server non attiverà i criteri di accesso condizionale per tale risorsa. Pertanto, per attivare MFA, dovrai includere una risorsa nel tuo URL.
Azure Active Directory (Azure AD) usa OAuth 2.0 per autorizzare l'accesso alle applicazioni Web e alle API Web nel tenant di Azure AD. Questa guida è indipendente dal linguaggio e descrive come inviare e ricevere messaggi HTTP senza usare alcuna delle librerie open source .
Il flusso del codice di autorizzazione di OAuth 2.0 è descritto nella sezione 4.1 della specifica di OAuth 2.0. Viene usato per eseguire l'autenticazione e l'autorizzazione nella maggior parte dei tipi di applicazioni, incluse le app Web e le app installate in modo nativo.
Registrare un'applicazione con il tenant di Active Directory
Prima di tutto, registrare l'applicazione con il tenant di Azure Active Directory (Azure AD). In questo modo verrà assegnato un ID applicazione per l'applicazione, oltre a abilitarlo per ricevere i token.
Accedere al portale di Azure.
Scegliere il tenant di Azure AD selezionando l'account nell'angolo superiore destro della pagina, quindi navigando su Cambia directory e selezionando il tenant appropriato.
- Ignorare questo passaggio se si ha un solo tenant di Azure AD nell'account o se è già stato selezionato il tenant di Azure AD appropriato.
Nel portale di Azure cercare e selezionare Azure Active Directory.
Nel menu azure Active Directory a sinistra selezionare Registrazioni appe quindi selezionare Nuova registrazione.
Seguire le istruzioni e creare una nuova applicazione. Non importa se si tratta di un'applicazione web o di un client pubblico (mobile & desktop) per questo tutorial, ma se desideri esempi specifici per applicazioni web o client pubblici, consulta le guide rapide .
- Nome è il nome dell'applicazione e descrive l'applicazione agli utenti finali.
- In Tipi di account supportati, seleziona Account in qualsiasi directory organizzativa e account Microsoft personali.
- Specificare l'URI di reindirizzamento . Per le applicazioni Web, si tratta dell'URL di base dell'app in cui gli utenti possono accedere. Ad esempio:
http://localhost:12345. Per il client pubblico (mobile & desktop), Azure AD lo utilizza per restituire le risposte dei token. Immettere un valore specifico per l'applicazione. Ad esempio:http://MyFirstAADApp.
Dopo aver completato la registrazione, Azure AD assegnerà all'applicazione un identificatore client univoco (l'ID applicazione ). Questo valore è necessario nelle sezioni successive, quindi copiarlo dalla pagina dell'applicazione.
Per trovare l'applicazione nel portale di Azure, selezionare Registrazioni appe quindi selezionare Visualizza tutte le applicazioni.
Flusso di autorizzazione OAuth 2.0
A livello generale, l'intero flusso di autorizzazione per un'applicazione ha un aspetto simile al seguente:
Richiedere un codice di autorizzazione
Il flusso del codice di autorizzazione ha inizio con il client che indirizza l'utente all'endpoint /authorize. In questa richiesta, il client indica le autorizzazioni necessarie per l'acquisizione dall'utente. È possibile ottenere l'endpoint di autorizzazione OAuth 2.0 per il tenant selezionando Registrazioni app > Endpoint nel portale di Azure.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
| Parametro | TIPO | Descrizione |
|---|---|---|
| inquilino | Obbligatorio | Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori consentiti sono identificatori del tenant, ad esempio 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 o contoso.onmicrosoft.com o common per i token indipendenti dal tenant |
| ID cliente | Obbligatorio | ID applicazione assegnato all'app quando è stato registrato con Azure AD. È possibile trovarla nel portale di Azure. Fare clic su azure Active Directory nella barra laterale dei servizi, fare clic su Registrazioni appe scegliere l'applicazione. |
| tipo_di_risposta | Obbligatorio | Deve includere un code per il flusso del codice di autorizzazione. |
| uri_di_reindirizzamento | consigliato | L'URI di reindirizzamento della tua app, dove le risposte di autenticazione possono essere inviate e ricevute dalla tua app. Deve corrispondere esattamente a uno dei redirect_uris registrati nel portale, ad eccezione del fatto che deve essere codificato in URL. Per le app native & per dispositivi mobili, è consigliabile usare il valore predefinito di https://login.microsoftonline.com/common/oauth2/nativeclient. |
| modalità_di_risposta | opzionale | Specifica il metodo da usare per inviare il token risultante a un'app. Può essere query, fragment o form_post.
query fornisce il codice come parametro della stringa di query sull'URI di reindirizzamento. Se si richiede un token ID usando il flusso implicito, non è possibile usare query come specificato nella specifica OpenID . Se si richiede solo il codice, è possibile usare query, fragmento form_post.
form_post esegue un'operazione POST che contiene il codice al tuo URI di reindirizzamento. Il valore predefinito è query per un flusso di codice. |
| stato | consigliato | Valore incluso nella richiesta che viene restituito nella risposta del token. Per prevenire gli attacchi di Cross-Site Request Forgery (CSRF), viene generalmente utilizzato un valore univoco generato casualmente. Lo stato viene usato anche per codificare informazioni sullo stato dell'utente nell'app prima che si sia verificata la richiesta di autenticazione, ad esempio la pagina o la visualizzazione in cui si trovavano. |
| risorsa | consigliato | URI ID app dell'API Web di destinazione (risorsa protetta). Per trovare l'URI ID app, nel portale di Azure fare clic su Azure Active Directory, fare clic su Registrazioni dell'applicazione, aprire la pagina Impostazioni dell'applicazione, quindi fare clic su proprietà . Può anche essere una risorsa esterna come https://graph.microsoft.com. Questa operazione è necessaria in una delle richieste di autorizzazione o token. Per garantire un minor numero di richieste di autenticazione, inserirle nella richiesta di autorizzazione per assicurarsi che il consenso venga ricevuto dall'utente. |
| scopo | ignorato | Per le app Azure AD v1, gli ambiti devono essere configurati in modo statico nel portale di Azure nelle applicazioni Impostazioni, Autorizzazioni necessarie. |
| richiesta | opzionale | Indicare il tipo di interazione dell'utente richiesto. I valori validi sono: di accesso: all'utente deve essere richiesto di ripetere l'autenticazione. select_account: all'utente viene richiesto di selezionare un account, interrompendo l'accesso Single Sign-On. L'utente può selezionare un account connesso esistente, immettere le credenziali per un account memorizzato o scegliere di usare completamente un account diverso. Consenso: Il consenso dell'utente è stato concesso, ma deve essere aggiornato. All'utente deve essere richiesto di fornire il consenso. admin_consent: all'amministratore deve essere richiesto di fornire il consenso per conto di tutti gli utenti dell'organizzazione |
| suggerimento di login | opzionale | Può essere usato per pre-compilare il campo nome utente/indirizzo di posta elettronica della pagina di accesso per l'utente, se si conosce il nome utente in anticipo. Spesso le app usano questo parametro durante la riautenticazione, avendo già estratto il nome utente da un accesso precedente usando l'attestazione preferred_username. |
| domain_hint | opzionale | Fornisce un suggerimento sul tenant o sul dominio che l'utente deve usare per accedere. Il valore del domain_hint è un dominio registrato per il tenant. Se il tenant è federato a una directory locale, AAD reindirizza al server di federazione del tenant specificato. |
| metodo_sfida_codice | consigliato | Metodo usato per codificare code_verifier per il parametro code_challenge. Può essere uno dei plain o S256. Se escluso, code_challenge viene considerato testo non crittografato se code_challenge è incluso. Azure AAD v1.0 supporta sia plain che S256. Per altre informazioni, vedere il PKCE RFC. |
| sfida di codice | consigliato | Usato per proteggere le concessioni di codice di autorizzazione tramite proof key for Code Exchange (PKCE) da un client nativo o pubblico. Obbligatorio se code_challenge_method è incluso. Per altre informazioni, vedere il PKCE RFC. |
Nota
Se l'utente fa parte di un'organizzazione, un amministratore dell'organizzazione può acconsentire o rifiutare per conto dell'utente oppure consentire all'utente di fornire il consenso. L'utente ha la possibilità di fornire il consenso solo quando l'amministratore lo consente.
A questo punto, all'utente viene chiesto di immettere le credenziali e di fornire il consenso alle autorizzazioni richieste dall'app nel portale di Azure. Dopo che l'utente esegue l'autenticazione e concede il consenso, Azure AD invia una risposta all'app all'indirizzo redirect_uri nella richiesta con il codice.
Risposta con esito positivo
Una risposta con esito positivo potrebbe essere simile alla seguente:
GET HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
| Parametro | Descrizione |
|---|---|
| consenso_amministratore | Il valore è True se un amministratore ha acconsentito a una richiesta di consenso. |
| codice | Codice di autorizzazione richiesto dall'applicazione. L'applicazione può usare il codice di autorizzazione per richiedere un token di accesso per la risorsa di destinazione. |
| stato_sessione | Valore univoco che identifica la sessione utente corrente. Questo valore è un GUID, ma deve essere trattato come un valore opaco passato senza alcun controllo. |
| stato | Se nella richiesta è incluso un parametro state, lo stesso valore deve essere visualizzato nella risposta. È consigliabile che l'applicazione verifichi che i valori di stato nella richiesta e nella risposta siano identici prima di usare la risposta. Ciò consente di rilevare attacchi CSRF (Cross-Site Request Forgery) contro il cliente. |
Risposta di errore
Le risposte di errore possono anche essere inviate al redirect_uri in modo che l'applicazione possa gestirle in modo appropriato.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
Codici di errore per l'endpoint di autorizzazione
La tabella seguente descrive i diversi codici errore che possono essere restituiti nel parametro error della risposta di errore.
| Codice di errore | Descrizione | Azione del cliente |
|---|---|---|
| richiesta non valida | Errore del protocollo, ad esempio un parametro obbligatorio mancante. | Correggere e inviare di nuovo la richiesta. Si tratta di un errore di sviluppo e viene in genere rilevato durante il test iniziale. |
| cliente non autorizzato | L'applicazione client non è autorizzata a richiedere un codice di autorizzazione. | Ciò si verifica in genere quando l'applicazione client non è registrata in Azure AD o non viene aggiunta al tenant di Azure AD dell'utente. L'applicazione può richiedere all'utente di installare l'applicazione e aggiungerla ad Azure AD. |
| accesso negato | Consenso negato dal proprietario della risorsa | L'applicazione client può notificare all'utente che non può continuare a meno che l'utente non acconsenta. |
| tipo_di_risposta_non_supportato | Il server di autorizzazione non supporta il tipo di risposta nella richiesta. | Correggere e inviare di nuovo la richiesta. Si tratta di un errore di sviluppo e viene in genere rilevato durante il test iniziale. |
| errore del server | Errore imprevisto rilevato dal server. | Ripetere la richiesta. Questi errori possono dipendere da condizioni temporanee. L'applicazione client potrebbe spiegare all'utente che la risposta è ritardata a causa di un errore temporaneo. |
| temporaneamente_non_disponibile | Il server è temporaneamente troppo occupato per gestire la richiesta. | Ripetere la richiesta. L'applicazione client potrebbe spiegare all'utente che la risposta è ritardata a causa di una condizione temporanea. |
| risorsa non valida | La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarlo o non è configurato correttamente. | Indica che la risorsa, se esistente, non è stata configurata nel tenant. L'applicazione può richiedere all'utente di installare l'applicazione e aggiungerla ad Azure AD. |
Usare il codice di autorizzazione per richiedere un token di accesso
Dopo aver acquisito un codice di autorizzazione e aver ottenuto l'autorizzazione dall'utente, è possibile riscattare il codice per un token di accesso alla risorsa desiderata inviando una richiesta POST all'endpoint /token:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd
//NOTE: client_secret only required for web apps
Per trovare l'URI ID app, nel portale di Azure fare clic su Azure Active Directory, fare clic su Registrazioni dell'applicazione, aprire la pagina Impostazioni dell'applicazione, quindi fare clic su proprietà .
Risposta con esito positivo
Azure AD restituisce un token di accesso in caso di risposta corretta. Per ridurre al minimo le chiamate di rete dall'applicazione client e la latenza associata, l'applicazione client deve memorizzare nella cache i token di accesso per la durata del token specificata nella risposta OAuth 2.0. Per determinare la durata del token, usare i valori dei parametri expires_in o expires_on.
Se una risorsa API Web restituisce un codice di errore invalid_token, ciò potrebbe indicare che la risorsa ha determinato che il token è scaduto. Se le ore di clock del client e delle risorse sono diverse (note come "asimmetrie temporali"), la risorsa potrebbe considerare che il token sia scaduto prima che il token venga cancellato dalla cache client. In questo caso, cancellare il token dalla cache, anche se è ancora entro la durata calcolata.
Una risposta con esito positivo potrebbe essere simile alla seguente:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1388444763",
"resource": "https://service.contoso.com/",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
| Parametro | Descrizione |
|---|---|
| token di accesso | Token di accesso richiesto. Si tratta di una stringa opaca: dipende da ciò che la risorsa prevede di ricevere e non è destinata al client a esaminare. L'app può usare questo token per eseguire l'autenticazione nella risorsa protetta, ad esempio un'API Web. |
| tipo_di_token | Indica il valore del tipo di token. L'unico tipo supportato da Azure AD è Bearer. Per altre informazioni sui token di connessione, vedere OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750) |
| scade_in | Tempo di validità del token di accesso (in secondi). |
| scade_il | Ora di scadenza del token di accesso. La data è rappresentata come numero di secondi dal 1970-01-01T0:0:0Z UTC fino all'ora di scadenza. Questo valore viene usato per determinare la durata dei token memorizzati nella cache. |
| risorsa | URI ID app dell'API Web (risorsa protetta). |
| scopo | Autorizzazioni di impersonazione concesse all'applicazione client. L'autorizzazione predefinita è user_impersonation. Il proprietario della risorsa protetta può registrare valori aggiuntivi in Azure AD. |
| token di aggiornamento | Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire token di accesso aggiuntivi dopo la scadenza del token di accesso corrente. I token di aggiornamento hanno durata elevata e possono essere usati per mantenere l'accesso alle risorse per lunghi periodi di tempo. |
| id_token (token di identificazione) | Token Web JSON (JWT) non firmato che rappresenta un ID token . L'app può decodificare i segmenti di questo token in base64Url per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per eventuali limiti di autorizzazione o di sicurezza. |
Per altre informazioni sui token Web JSON, vedere la specifica di bozza JWT IETF. Per ulteriori informazioni su id_tokens, consultare il flusso OpenID Connect v1.0.
Risposta di errore
Gli errori dell'endpoint di rilascio del token sono codici di errore HTTP, perché il client chiama direttamente l'endpoint di rilascio del token. Oltre al codice di stato HTTP, l'endpoint di rilascio dei token di Azure AD restituisce anche un documento JSON con oggetti che descrivono l'errore.
Una risposta di errore di esempio potrebbe essere simile alla seguente:
{
"error": "invalid_grant",
"error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
"error_codes": [
70002,
70008
],
"timestamp": "2016-04-11 18:00:12Z",
"trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
"correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
| Parametro | Descrizione |
|---|---|
| Errore | Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e può essere usata per reagire agli errori. |
| descrizione_errore | Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione. |
| codici_errore | Elenco dei codici di errore specifici STS che possono aiutare nella diagnostica. |
| Marca temporale | Ora in cui si è verificato l'errore. |
| ID di tracciamento | Identificatore univoco per la richiesta utile per la diagnostica. |
| identificatore_di_correlazione | Identificatore univoco per la richiesta utile per la diagnostica tra i componenti. |
Codici di stato HTTP
Nella tabella seguente sono elencati i codici di stato HTTP restituiti dall'endpoint di rilascio del token. In alcuni casi, il codice di errore è sufficiente per descrivere la risposta, ma in caso di errori, è necessario analizzare il documento JSON a cui si accompagna ed esaminarne il codice di errore.
| Codice HTTP | Descrizione |
|---|---|
| 400 | Codice HTTP predefinito. È utilizzato nella maggior parte dei casi ed è in genere dovuto a una richiesta malformata. Correggere e inviare di nuovo la richiesta. |
| 401 | Autenticazione non riuscita. Ad esempio, la richiesta manca il parametro client_secret. |
| 403 | Autorizzazione non riuscita. Ad esempio, l'utente non dispone dell'autorizzazione per accedere alla risorsa. |
| 500 | Si è verificato un errore interno nel servizio. Ripetere la richiesta. |
Codici errore per gli errori dell'endpoint di token
| Codice di errore | Descrizione | Azione del cliente |
|---|---|---|
| richiesta non valida | Errore del protocollo, ad esempio un parametro obbligatorio mancante. | Correggere e inviare di nuovo la richiesta |
| concessione non valida | Il codice di autorizzazione non è valido o è scaduto. | Provare una nuova richiesta all'endpoint /authorize |
| cliente non autorizzato | Il client autenticato non è autorizzato a usare questo tipo di concessione di autorizzazione. | Ciò si verifica in genere quando l'applicazione client non è registrata in Azure AD o non viene aggiunta al tenant di Azure AD dell'utente. L'applicazione può richiedere all'utente di installare l'applicazione e aggiungerla ad Azure AD. |
| cliente_non_valido | Autenticazione client non riuscita. | Le credenziali client non sono valide. Per risolvere il problema, l'amministratore dell'applicazione aggiorna le credenziali. |
| tipo_di_concessione_non_supportata | Il server di autorizzazione non supporta il tipo di concessione di autorizzazione. | Modificare il tipo di concessione nella richiesta. Questo tipo di errore dovrebbe verificarsi solo durante lo sviluppo ed essere rilevato durante il test iniziale. |
| risorsa non valida | La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarlo o non è configurato correttamente. | Indica che la risorsa, se esistente, non è stata configurata nel tenant. L'applicazione può richiedere all'utente di installare l'applicazione e aggiungerla ad Azure AD. |
| interazione_richiesta | La richiesta richiede l'interazione dell'utente. Ad esempio, è necessario un passaggio di autenticazione aggiuntivo. | Anziché una richiesta non interattiva, riprovare con una richiesta di autorizzazione interattiva per la stessa risorsa. |
| temporaneamente_non_disponibile | Il server è temporaneamente troppo occupato per gestire la richiesta. | Ripetere la richiesta. L'applicazione client potrebbe spiegare all'utente che la risposta è ritardata a causa di una condizione temporanea. |
Usare il token di accesso per accedere alla risorsa
Dopo aver acquisito correttamente un access_token, è possibile usare il token nelle richieste alle API Web, includendolo nell'intestazione Authorization. La specifica RFC 6750 illustra come usare i token di connessione nelle richieste HTTP per accedere alle risorse protette.
Esempio di richiesta
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
Risposta di errore
Risorse protette che, implementando l'RFC 6750, emettono codici di stato HTTP. Se la richiesta non include credenziali di autenticazione o manca il token, la risposta include un'intestazione WWW-Authenticate. Quando una richiesta ha esito negativo, il server di risorse risponde con il codice di stato HTTP e un codice di errore.
Di seguito è riportato un esempio di risposta non riuscita quando la richiesta client non include il token di connessione:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize", error="invalid_token", error_description="The access token is missing.",
Parametri di errore
Codici di errore dello schema Bearer
La specifica RFC 6750 definisce gli errori seguenti per le risorse che usano l'intestazione WWW-Authenticate e lo schema Bearer nella risposta.
| Codice di stato HTTP | Codice di errore | Descrizione | Azione del cliente |
|---|---|---|---|
| 400 | richiesta non valida | La richiesta non è ben formata. Ad esempio, potrebbe mancare un parametro o usare due volte lo stesso parametro. | Correggere l'errore e ripetere la richiesta. Questo tipo di errore deve verificarsi solo durante lo sviluppo e deve essere rilevato nei test iniziali. |
| 401 | token non valido | Il token di accesso è mancante, non valido o viene revocato. Il valore del parametro error_description fornisce dettagli aggiuntivi. | Richiedere un nuovo token dal server di autorizzazione. Se il nuovo token ha esito negativo, si è verificato un errore imprevisto. Inviare un messaggio di errore all'utente e riprovare dopo ritardi casuali. |
| 403 | ambito insufficiente | Il token di accesso non contiene le autorizzazioni di impersonificazione necessarie per accedere alla risorsa. | Inviare una nuova richiesta di autorizzazione all'endpoint di autorizzazione. Se la risposta contiene il parametro di ambito, usare il valore di ambito nella richiesta alla risorsa. |
| 403 | accesso insufficiente | L'oggetto del token non dispone delle autorizzazioni necessarie per accedere alla risorsa. | Chiedere all'utente di usare un account diverso o di richiedere le autorizzazioni per la risorsa specificata. |
Aggiornamento dei token di accesso
I token di accesso sono di breve durata e devono essere aggiornati dopo la scadenza per continuare ad accedere alle risorse. È possibile aggiornare il access_token inviando un'altra richiesta di POST all'endpoint /token, ma questa volta specificando il refresh_token anziché il code. I token di aggiornamento sono validi per tutte le risorse a cui il client ha già dato il consenso per l'accesso. Pertanto, un token di aggiornamento emesso in una richiesta di resource=https://graph.microsoft.com può essere usato per richiedere un nuovo token di accesso per resource=https://contoso.com/api.
I token di aggiornamento non hanno durate specificate. In genere, la durata dei token di aggiornamento è relativamente lunga. Tuttavia, in alcuni casi, i token di aggiornamento scadono, vengono revocati o mancano privilegi sufficienti per l'azione desiderata. L'applicazione deve prevedere e gestire correttamente gli errori restituiti dall'endpoint di rilascio del token.
Quando si riceve una risposta con un errore del token di aggiornamento, rimuovere il token di aggiornamento corrente e richiedere un nuovo codice di autorizzazione o un token di accesso. In particolare, quando si usa un token di aggiornamento nel flusso di concessione del codice di autorizzazione, se si riceve una risposta con i codici di errore interaction_required o invalid_grant, rimuovere il token di aggiornamento e richiedere un nuovo codice di autorizzazione.
Una richiesta di esempio all'endpoint specifico del tenant (è anche possibile usare l'endpoint comune) per ottenere un nuovo token di accesso usando un token di aggiornamento è simile al seguente:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Risposta con esito positivo
Una risposta di token con esito positivo sarà simile alla seguente:
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1460404526",
"resource": "https://service.contoso.com/",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
| Parametro | Descrizione |
|---|---|
| tipo_di_token | Tipo di token. L'unico valore supportato è portatore. |
| scade_in | Durata rimanente del token in secondi. Un valore tipico è 3600 (un'ora). |
| scade_il | Data e ora in cui scade il token. La data è rappresentata come numero di secondi dal 1970-01-01T0:0:0Z UTC fino all'ora di scadenza. |
| risorsa | Identifica la risorsa protetta a cui è possibile accedere mediante il token di accesso. |
| scopo | Autorizzazioni di impersonazione concesse all'applicazione client nativa. L'autorizzazione predefinita è user_impersonation. Il proprietario della risorsa di destinazione può registrare valori alternativi in Azure AD. |
| token di accesso | Nuovo token di accesso richiesto. |
| token di aggiornamento | Nuovo refresh_token OAuth 2.0 che può essere usato per richiedere nuovi token di accesso alla scadenza di quella in questa risposta. |
Risposta di errore
Una risposta di errore di esempio potrebbe essere simile alla seguente:
{
"error": "invalid_resource",
"error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
"error_codes": [
50001
],
"timestamp": "2016-04-11 18:59:01Z",
"trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
"correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
| Parametro | Descrizione |
|---|---|
| Errore | Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e può essere usata per reagire agli errori. |
| descrizione_errore | Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione. |
| codici_errore | Elenco dei codici di errore specifici STS che possono aiutare nella diagnostica. |
| Marca temporale | Ora in cui si è verificato l'errore. |
| ID di tracciamento | Identificatore univoco per la richiesta utile per la diagnostica. |
| identificatore_di_correlazione | Identificatore univoco per la richiesta utile per la diagnostica tra i componenti. |
Per una descrizione dei codici di errore e l'azione consigliata per il client, vedere Codici per gli errori degli endpoint di token.
Passaggi successivi
Per altre informazioni sull'endpoint di Azure AD v1.0 e su come aggiungere l'autenticazione e l'autorizzazione alle applicazioni Web e alle API Web, vedere applicazioni di esempio.