Azure Active Directory v2.0 e il protocollo OpenID ConnectAzure Active Directory v2.0 and the OpenID Connect protocol

OpenID Connect è un protocollo di autenticazione basato su OAuth 2.0 che può essere usato per fare in modo che gli utenti accedano in modo protetto a un'applicazione Web.OpenID Connect is an authentication protocol built on OAuth 2.0 that you can use to securely sign in a user to a web application. Quando si usa l'implementazione dell'endpoint v2.0 di OpenID Connect, è possibile aggiungere l'accesso e l'accesso all'API alle app basate sul Web.When you use the v2.0 endpoint's implementation of OpenID Connect, you can add sign-in and API access to your web-based apps. In questo articolo viene illustrato come eseguire l'operazione indipendentemente dal linguaggio.In this article, we show you how to do this independent of language. Verrà descritto come inviare e ricevere messaggi HTTP senza usare alcuna libreria open source Microsoft.We describe how to send and receive HTTP messages without using any Microsoft open-source libraries.

Nota

Non tutti gli scenari e le funzionalità di Azure Active Directory sono supportati dall'endpoint v2.0.The v2.0 endpoint does not support all Azure Active Directory scenarios and features. Per determinare se è necessario usare l'endpoint 2.0, vedere l'articolo relativo alle limitazioni della versione 2.0.To determine whether you should use the v2.0 endpoint, read about v2.0 limitations.

OpenID Connect estende il protocollo di autorizzazione OAuth 2.0 da usare come protocollo di autenticazione per consentire di eseguire l'accesso Single Sign-On tramite OAuth.OpenID Connect extends the OAuth 2.0 authorization protocol to use as an authentication protocol, so that you can perform single sign-on using OAuth. OpenID Connect introduce il concetto di token ID, ovvero un token di sicurezza che consente al client di verificare l'identità dell'utente.OpenID Connect introduces the concept of an ID token, which is a security token that allows the client to verify the identity of the user. Il token ID consente anche di ottenere informazioni di base sul profilo dell'utente.The ID token also gets basic profile information about the user. Poiché OpenID Connect estende OAuth 2.0, le app potranno acquisire in modo sicuro token di accesso che possono essere usati per accedere alle risorse protette da un server di autorizzazione.Because OpenID Connect extends OAuth 2.0, apps can securely acquire access tokens, which can be used to access resources that are secured by an authorization server. È consigliabile usare OpenID Connect per la compilazione di un'applicazione Web ospitata su un server e accessibile tramite browser.We recommend that you use OpenID Connect if you are building a web application that is hosted on a server and accessed via a browser.

Diagramma di protocollo: accessoProtocol diagram: Sign-in

Il flusso di accesso di base include i passaggi illustrati nella figura seguente.The most basic sign-in flow has the steps shown in the next diagram. Questo articolo descrive dettagliatamente i singoli passaggi.We describe each step in detail in this article.

Protocollo OpenID Connect: accesso

Recuperare il documento di metadati OpenID ConnectFetch the OpenID Connect metadata document

OpenID Connect descrive un documento di metadati che contiene la maggior parte delle informazioni necessarie perché un'applicazione esegua l'accesso.OpenID Connect describes a metadata document that contains most of the information required for an app to perform sign-in. Il documento include informazioni come gli URL da usare e il percorso delle chiavi di firma pubbliche del servizio.This includes information such as the URLs to use and the location of the service's public signing keys. Per l'endpoint v2.0, usare il documento di metadati OpenID Connect seguente:For the v2.0 endpoint, this is the OpenID Connect metadata document you should use:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration

{tenant} può assumere uno dei quattro valori seguenti:The {tenant} can take one of four values:

ValoreValue DescrizioneDescription
common Possono accedere all'applicazione gli utenti con account Microsoft e account aziendali o dell'istituto d'istruzione di Azure Active Directory (Azure AD).Users with both a personal Microsoft account and a work or school account from Azure Active Directory (Azure AD) can sign in to the application.
organizations Possono accedere all'applicazione solo gli utenti con account aziendali o dell'istituto d'istruzione di Azure AD.Only users with work or school accounts from Azure AD can sign in to the application.
consumers Possono accedere all'applicazione solo gli utenti con account Microsoft personali.Only users with a personal Microsoft account can sign in to the application.
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 oppure contoso.onmicrosoft.com8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com Possono accedere all'applicazione solo gli utenti con account aziendali o dell'istituto d'istruzione di un tenant specifico di Azure AD.Only users with a work or school account from a specific Azure AD tenant can sign in to the application. È possibile usare il nome di dominio descrittivo del tenant di Azure AD o l'identificatore GUID.Either the friendly domain name of the Azure AD tenant or the tenant's GUID identifier can be used.

I metadati sono un semplice documento JavaScript Object Notation (JSON).The metadata is a simple JavaScript Object Notation (JSON) document. Per un esempio, vedere il frammento di codice seguente.See the following snippet for an example. Il contenuto del frammento di codice è descritto dettagliatamente nelle specifiche di OpenID Connect.The snippet's contents are fully described in the OpenID Connect specification.

{
  "authorization_endpoint": "https:\/\/login.microsoftonline.com\/common\/oauth2\/v2.0\/authorize",
  "token_endpoint": "https:\/\/login.microsoftonline.com\/common\/oauth2\/v2.0\/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https:\/\/login.microsoftonline.com\/common\/discovery\/v2.0\/keys",

  ...

}

In genere, si usa questo documento di metadati per configurare una libreria di OpenID Connect o un SDK. La libreria usa i metadati per le proprie operazioni.Typically, you would use this metadata document to configure an OpenID Connect library or SDK; the library would use the metadata to do its work. Tuttavia, se non si usa una libreria OpenID Connect precompilata, è possibile seguire i passaggi nella parte restante di questo articolo per eseguire l'accesso in un'app Web tramite l'endpoint v 2.0.However, if you're not using a pre-build OpenID Connect library, you can follow the steps in the remainder of this article to perform sign-in in a web app by using the v2.0 endpoint.

Inviare la richiesta di accessoSend the sign-in request

Quando l'app Web deve autenticare l'utente, può indirizzarlo all'endpoint /authorize .When your web app needs to authenticate the user, it can direct the user to the /authorize endpoint. Questa richiesta è simile a quella della prima parte del flusso del codice di autorizzazione di OAuth 2.0, con alcune importanti differenze:This request is similar to the first leg of the OAuth 2.0 authorization code flow, with these important distinctions:

  • La richiesta deve includere l'ambito openid nel parametro scope.The request must include the openid scope in the scope parameter.
  • Il parametro response_type deve includere id_token.The response_type parameter must include id_token.
  • La richiesta deve includere il parametro nonce .The request must include the nonce parameter.

Ad esempio:For example:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

Suggerimento

Fare clic sul collegamento seguente per eseguire la richiesta.Click the following link to execute this request. Dopo l'accesso, il browser verrà reindirizzato a https://localhost/myapp/ con un token ID nella barra degli indirizzi.After you sign in, your browser will be redirected to https://localhost/myapp/, with an ID token in the address bar. Si noti che questa richiesta usa response_mode=query (solo a scopo dimostrativo).Note that this request uses response_mode=query (for demonstration purposes only). È consigliabile usare response_mode=form_post.We recommend that you use response_mode=form_post. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

ParametroParameter CondizioneCondition DescrizioneDescription
tenanttenant ObbligatorioRequired È possibile usare il valore {tenant} nel percorso della richiesta per controllare chi può accedere all'applicazione.You can use the {tenant} value in the path of the request to control who can sign in to the application. I valori consentiti sono common, organizations, consumers e gli identificatori del tenant.The allowed values are common, organizations, consumers, and tenant identifiers. Per altre informazioni, vedere le nozioni di base sui protocolli.For more information, see protocol basics.
client_idclient_id ObbligatorioRequired ID applicazione che il portale di registrazione delle applicazioni ha assegnato all'app.The Application ID that the Application Registration Portal assigned to your app.
response_typeresponse_type ObbligatorioRequired Deve includere id_token per l'accesso a OpenID Connect.Must include id_token for OpenID Connect sign-in. Può anche includere altri valori response_types, ad esempio code.It might also include other response_types values, such as code.
redirect_uriredirect_uri ConsigliatoRecommended URI di reindirizzamento dell'app dove le risposte di autenticazione possono essere inviate e ricevute dall'app.The redirect URI of your app, where authentication responses can be sent and received by your app. Deve corrispondere esattamente a uno degli URI di reindirizzamento registrati nel portale, ad eccezione del fatto che deve essere codificato come URL.It must exactly match one of the redirect URIs you registered in the portal, except that it must be URL encoded.
scopescope ObbligatorioRequired Elenco di ambiti separati da spazi.A space-separated list of scopes. Per OpenID Connect, deve includere l'ambito openidche esegue la conversione all'autorizzazione per l'accesso nell'interfaccia utente di consenso.For OpenID Connect, it must include the scope openid, which translates to the "Sign you in" permission in the consent UI. È anche possibile includere in questa richiesta altri ambiti per richiedere il consenso.You might also include other scopes in this request for requesting consent.
noncenonce ObbligatorioRequired Valore incluso nella richiesta, generato dall'app, che verrà incluso nel token ID risultante come attestazione.A value included in the request, generated by the app, that will be included in the resulting id_token value as a claim. L'app può verificare questo valore per ridurre gli attacchi di riproduzione del token.The app can verify this value to mitigate token replay attacks. Il valore è in genere una stringa casuale univoca che può essere usata per identificare l'origine della richiesta.The value typically is a randomized, unique string that can be used to identify the origin of the request.
response_moderesponse_mode ConsigliatoRecommended Specifica il metodo che deve essere usato per inviare il codice di autorizzazione risultante all'app.Specifies the method that should be used to send the resulting authorization code back to your app. Può essere uno di query, form_post o fragment.Can be one of query, form_post, or fragment. Per le applicazioni Web è consigliabile usare response_mode=form_post per assicurare il trasferimento più sicuro dei token nell'applicazione.For web applications, we recommend using response_mode=form_post, to ensure the most secure transfer of tokens to your application.
statestate ConsigliatoRecommended Valore incluso nella richiesta che verrà restituito anche nella risposta del token.A value included in the request that also will be returned in the token response. Può trattarsi di una stringa di qualsiasi contenuto.It can be a string of any content you want. Per evitare gli attacchi di richiesta intersito falsa, viene in genere usato un valore univoco generato casualmente.A randomly generated unique value typically is used to prevent cross-site request forgery attacks. Anche lo stato viene usato per codificare le informazioni sullo stato dell'utente nell'app prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la visualizzazione corrente dell'utente.The state also is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view the user was on.
promptprompt FacoltativoOptional Indica il tipo di interazione obbligatoria dell'utente.Indicates the type of user interaction that is required. Gli unici valori validi al momento sono login, none e consent.The only valid values at this time are login, none, and consent. L'attestazione prompt=login forza l'utente a immettere le sue credenziali alla richiesta, negando l'accesso Single Sign-On.The prompt=login claim forces the user to enter their credentials on that request, which negates single sign-on. L'attestazione prompt=none è l'opposto,The prompt=none claim is the opposite. ovvero garantisce che all'utente non venga visualizzata alcuna richiesta interattiva.This claim ensures that the user is not presented with any interactive prompt whatsoever. Se la richiesta non può essere completata automaticamente tramite Single-Sign-On, l'endpoint v2.0 restituisce un errore.If the request cannot be completed silently via single sign-on, the v2.0 endpoint returns an error. L'attestazione prompt=consent attiva la finestra di dialogo di consenso di OAuth dopo l'accesso dell'utente.The prompt=consent claim triggers the OAuth consent dialog after the user signs in. La finestra di dialogo chiede all'utente di concedere le autorizzazioni per l'app.The dialog asks the user to grant permissions to the app.
login_hintlogin_hint FacoltativoOptional È possibile usare questo parametro per pre-compilare i campi nome utente e indirizzo di posta elettronica nella pagina di accesso, se già si conosce il nome utente.You can use this parameter to pre-fill the username and email address field of the sign-in page for the user, if you know the username ahead of time. Le app usano spesso questo parametro durante la riautenticazione, dopo aver estratto il nome utente da un accesso precedente tramite l'attestazione preferred_username.Often, apps use this parameter during re-authentication, after already extracting the username from an earlier sign-in by using the preferred_username claim.
domain_hintdomain_hint FacoltativoOptional Questo valore può essere consumers o organizations.This value can be consumers or organizations. Se incluso, non viene eseguito il processo di individuazione basato sulla posta elettronica a cui viene sottoposto l'utente nella pagina di accesso della versione 2.0 per garantire un'esperienza utente più semplice.If included, it skips the email-based discovery process that the user goes through on the v2.0 sign-in page, for a slightly more streamlined user experience. Le app usano spesso questo parametro durante la riautenticazione, estraendo l'attestazione tid dal token ID.Often, apps use this parameter during re-authentication by extracting the tid claim from the ID token. Se il valore dell'attestazione tid è 9188040d-6c67-4c5b-b112-36a304b66dad, usare domain_hint=consumers.If the tid claim value is 9188040d-6c67-4c5b-b112-36a304b66dad, use domain_hint=consumers. In caso contrario, usare domain_hint=organizations.Otherwise, use domain_hint=organizations.

A questo punto, all'utente viene chiesto di immettere le credenziali e completare l'autenticazione.At this point, the user is prompted to enter their credentials and complete the authentication. L'endpoint v2.0 verifica anche che l'utente abbia dato il consenso per le autorizzazioni indicate nel parametro di query scope.The v2.0 endpoint verifies that the user has consented to the permissions indicated in the scope query parameter. Se l'utente non ha dato il consenso per nessuna di queste autorizzazioni, l'endpoint v2.0 chiederà all'utente di dare il consenso per le autorizzazioni obbligatorie.If the user has not consented to any of those permissions, the v2.0 endpoint prompts the user to consent to the required permissions. Sono disponibili altre informazioni su autorizzazioni, consenso e app multi-tenant.You can read more about permissions, consent, and multitenant apps.

Dopo che l'utente ha eseguito l'autenticazione e dato il consenso, l'endpoint v2.0 restituisce una risposta all'app nell'URI di reindirizzamento indicato usando il metodo specificato nel parametro response_mode.After the user authenticates and grants consent, the v2.0 endpoint returns a response to your app at the indicated redirect URI by using the method specified in the response_mode parameter.

Risposta con esito positivoSuccessful response

La risposta con esito positivo quando si usa response_mode=form_post è simile alla seguente:A successful response when you use response_mode=form_post looks like this:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
ParametroParameter DescrizioneDescription
id_tokenid_token Token ID richiesto dall'app.The ID token that the app requested. È possibile usare il parametro id_token per verificare l'identità dell'utente e avviare una sessione con l'utente.You can use the id_token parameter to verify the user's identity and begin a session with the user. Per altre informazioni sui token ID e il relativo contenuto, vedere il riferimento ai token dell'endpoint v2.0.For more details about ID tokens and their contents, see the v2.0 endpoint tokens reference.
statestate Se un parametro state è incluso nella richiesta, lo stesso valore deve essere visualizzato nella risposta.If a state parameter is included in the request, the same value should appear in the response. L'app deve verificare che i valori dello stato nella richiesta e nella risposta siano identici.The app should verify that the state values in the request and response are identical.

Risposta di erroreError response

Le risposte di errore possono essere inviate anche all'URI di reindirizzamento in modo che l'app possa gestirle.Error responses might also be sent to the redirect URI so that the app can handle them. La risposta di errore è simile alla seguente:An error response looks like this:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
ParametroParameter DescrizioneDescription
errorerror Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e correggerli.An error code string that you can use to classify types of errors that occur, and to react to errors.
error_descriptionerror_description Messaggio di errore specifico che consente di identificare la causa principale di un errore di autenticazione.A specific error message that can help you identify the root cause of an authentication error.

Codici per gli errori dell'endpoint di autorizzazioneError codes for authorization endpoint errors

La tabella seguente descrive i codici di errore che possono essere restituiti nel parametro error della risposta di errore:The following table describes error codes that can be returned in the error parameter of the error response:

Codice di erroreError code DescrizioneDescription Azione clientClient action
invalid_requestinvalid_request Errore del protocollo, ad esempio un parametro obbligatorio mancante.Protocol error, such as a missing, required parameter. Correggere e inviare di nuovo la richiesta.Fix and resubmit the request. Si tratta di un errore di sviluppo rilevato in genere durante il test iniziale.This is a development error that typically is caught during initial testing.
unauthorized_clientunauthorized_client L'applicazione client non può richiedere un codice di autorizzazione.The client application cannot request an authorization code. Si verifica in genere quando l'applicazione client non è registrata in Azure AD o non è stata aggiunta al tenant di Azure AD dell'utente.This usually occurs when the client application is not registered in Azure AD or is not added to the user's Azure AD tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.The application can prompt the user with instructions to install the application and add it to Azure AD.
access_deniedaccess_denied Il proprietario della risorsa ha negato il consenso.The resource owner denied consent. L'applicazione client può notificare all'utente che non può proseguire a meno che l'utente non acconsenta.The client application can notify the user that it cannot proceed unless the user consents.
unsupported_response_typeunsupported_response_type Il server di autorizzazione non supporta il tipo di risposta nella richiesta.The authorization server does not support the response type in the request. Correggere e inviare di nuovo la richiesta.Fix and resubmit the request. Si tratta di un errore di sviluppo rilevato in genere durante il test iniziale.This is a development error that typically is caught during initial testing.
server_errorserver_error Errore imprevisto rilevato dal server.The server encountered an unexpected error. ripetere la richiesta.Retry the request. Questi errori possono dipendere da condizioni temporanee.These errors can result from temporary conditions. L'applicazione client può comunicare all'utente che la risposta è stata ritardata a causa di un errore temporaneo.The client application might explain to the user that its response is delayed due to a temporary error.
temporarily_unavailabletemporarily_unavailable Il server è temporaneamente troppo occupato per gestire la richiesta.The server is temporarily too busy to handle the request. ripetere la richiesta.Retry the request. L'applicazione client può comunicare all'utente che la risposta è stata ritardata a causa di una condizione temporanea.The client application might explain to the user that its response is delayed due to a temporary condition.
invalid_resourceinvalid_resource La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarla o non è configurata correttamente.The target resource is invalid because either it does not exist, Azure AD cannot find it, or it is not correctly configured. Indica che la risorsa, se presente, non è stata configurata nel tenant.This indicates that the resource, if it exists, has not been configured in the tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.The application can prompt the user with instructions for installing the application and adding it to Azure AD.

Convalidare il token IDValidate the ID token

La ricezione di un token ID non è sufficiente per autenticare l'utente.Receiving an ID token is not sufficient to authenticate the user. È anche necessario convalidare la firma del token ID e verificare se le attestazioni nel token soddisfano i requisiti dell'app.You must also validate the ID token's signature and verify the claims in the token per your app's requirements. L'endpoint 2.0 usa i token Web JSON e la crittografia a chiave pubblica per firmare i token e verificarne la validità.The v2.0 endpoint uses JSON Web Tokens (JWTs) and public key cryptography to sign tokens and verify that they are valid.

È possibile scegliere di convalidare il token ID nel codice client, ma una procedura comune consiste nell'inviare il token ID a un server back-end in cui eseguire la convalida.You can choose to validate the ID token in client code, but a common practice is to send the ID token to a back-end server and perform the validation there. Dopo aver convalidato la firma del token ID, è necessario verificare alcune attestazioni.After you've validated the signature of the ID token, you'll need to verify a few claims. Per altre informazioni, ad esempio relative alla convalida del token e al rollover della chiave di firma, vedere il riferimento ai token della versione 2.0.For more information, including more about validating tokens and important information about signing key rollover, see the v2.0 tokens reference. È consigliabile usare una libreria per analizzare e convalidare i token.We recommend using a library to parse and validate tokens. È disponibile almeno una libreria per la maggior parte dei linguaggi e delle piattaforme.There's at least one of these libraries available for most languages and platforms.

È anche possibile convalidare attestazioni aggiuntive, a seconda dello scenario.You also might want to validate additional claims, depending on your scenario. Alcune convalide comuni includono:Some common validations include:

  • Verificare che l'utente o l'organizzazione abbia eseguito la registrazione per l'app.Ensure that the user or organization has signed up for the app.
  • Assicurarsi che l'utente abbia l'autorizzazione o i privilegi necessari.Ensure that the user has required authorization or privileges.
  • Verificare che sia stato applicato un determinato livello di autenticazione, ad esempio l'autenticazione a più fattori.Ensure that a certain strength of authentication has occurred, such as multi-factor authentication.

Per altre informazioni sulle attestazioni di un token ID, vedere il riferimento ai token dell'endpoint v2.0.For more information about the claims in an ID token, see the v2.0 endpoint tokens reference.

Dopo aver convalidato il token ID, è possibile avviare una sessione con l'utente.After you have completely validated the ID token, you can begin a session with the user. Usare le attestazioni del token ID per ottenere informazioni sull'utente nell'app.Use the claims in the ID token to get information about the user in your app. Queste informazioni possono essere usate per la visualizzazione, i record, le autorizzazioni e così via.You can use this information for display, records, authorizations, and so on.

Inviare una richiesta di disconnessioneSend a sign-out request

Durante la disconnessione di un utente dall'app, non basta cancellare i cookie dell'app o terminare la sessione dell'utente.When you want to sign out the user from your app, it isn't sufficient to clear your app's cookies or otherwise end the user's session. È anche necessario reindirizzare l'utente all'endpoint v2.0 per la disconnessione. In caso contrario, l'utente esegue nuovamente l'autenticazione all'app senza immettere di nuovo le credenziali, poiché disporrà di una sessione Single Sign-On valida con l'endpoint v2.0.You must also redirect the user to the v2.0 endpoint to sign out. If you don't do this, the user re-authenticates to your app without entering their credentials again, because they will have a valid single sign-in session with the v2.0 endpoint.

È possibile reindirizzare l'utente all'end_session_endpoint riportato nel documento dei metadati di OpenID Connect:You can redirect the user to the end_session_endpoint listed in the OpenID Connect metadata document:

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
ParametroParameter CondizioneCondition DescrizioneDescription
post_logout_redirect_uripost_logout_redirect_uri ConsigliatoRecommended L'URL di destinazione al quale l'utente viene reindirizzato dopo la disconnessione. Se il parametro non è incluso, viene visualizzato un messaggio generico generato dall'endpoint v2.0.The URL that the user is redirected to after successfully signing out. If the parameter is not included, the user is shown a generic message that's generated by the v2.0 endpoint. Questo URL deve corrispondere esattamente a uno degli URI di reindirizzamento registrati per l'applicazione nel portale di registrazione delle app.This URL must match one of the redirect URIs registered for your application in the app registration portal.

Single Sign-OutSingle sign-out

Quando si reindirizza l'utente a end_session_endpoint, l'endpoint v2.0 cancella la sessione dell'utente dal browser.When you redirect the user to the end_session_endpoint, the v2.0 endpoint clears the user's session from the browser. L'utente può tuttavia essere ancora connesso ad altre applicazioni che usano account Microsoft per l'autenticazione.However, the user may still be signed in to other applications that use Microsoft accounts for authentication. Per consentire che tutte le applicazioni eseguano la disconnessione dell'utente simultaneamente, l'endpoint v2.0 invia una richiesta HTTP GET all'oggetto LogoutUrl registrato di tutte le applicazioni a cui l'utente è attualmente connesso.To enable those applications to sign the user out simultaneously, the v2.0 endpoint sends an HTTP GET request to the registered LogoutUrl of all the applications that the user is currently signed in to. Le applicazioni devono rispondere a questa richiesta cancellando qualsiasi sessione che identifica l'utente e restituendo una risposta 200.Applications must respond to this request by clearing any session that identifies the user and returning a 200 response. Se si vuole supportare l'accesso Single Sign-Out nell'applicazione, è necessario implementare questo tipo di oggetto LogoutUrl nel codice dell'applicazione.If you wish to support single sign out in your application, you must implement such a LogoutUrl in your application's code. È possibile impostare LogoutUrl dal portale di registrazione delle app.You can set the LogoutUrl from the app registration portal.

Diagramma di protocollo: acquisizione dei tokenProtocol diagram: Token acquisition

Molte app Web non richiedono soltanto l'accesso dell'utente, ma necessitano anche di accedere a un servizio Web per conto dell'utente tramite OAuth.Many web apps need to not only sign the user in, but also to access a web service on behalf of the user by using OAuth. In questo scenario viene usato OpenID Connect per l'autenticazione utente e contemporaneamente viene acquisito un codice di autorizzazione che può essere usato per ottenere i token di accesso quando si usa il flusso del codice di autorizzazione di OAuth.This scenario combines OpenID Connect for user authentication while simultaneously getting an authorization code that you can use to get access tokens if you are using the OAuth authorization code flow.

Il flusso completo di accesso OpenID Connect e di acquisizione dei token è simile a quello illustrato nella figura seguente.The full OpenID Connect sign-in and token acquisition flow looks similar to the next diagram. Le sezioni seguenti dell'articolo descrivono i singoli passaggi.We describe each step in detail in the next sections of the article.

Protocollo OpenID Connect: acquisizione dei token

Ottenere i token di accessoGet access tokens

Per acquisire i token di accesso, modificare la richiesta di accesso:To acquire access tokens, modify the sign-in request:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token%20code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your registered redirect URI, URL encoded
&response_mode=form_post                              // 'query', 'form_post', or 'fragment'
&scope=openid%20                                      // Include both 'openid' and scopes that your app needs  
offline_access%20                                         
https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Suggerimento

Fare clic sul collegamento seguente per eseguire la richiesta.Click the following link to execute this request. Dopo l'accesso, il browser viene reindirizzato a https://localhost/myapp/ con un token ID e un codice nella barra degli indirizzi.After you sign in, your browser is redirected to https://localhost/myapp/, with an ID token and a code in the address bar. Si noti che questa richiesta usa response_mode=query (solo a scopo dimostrativo).Note that this request uses response_mode=query (for demonstration purposes only). È consigliabile usare response_mode=form_post.We recommend that you use response_mode=form_post. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Includendo gli ambiti di autorizzazione nella richiesta e usando response_type=id_token code, l'endpoint v2.0 verificherà che l'utente abbia dato il consenso alle autorizzazioni indicate nel parametro di query scope.By including permission scopes in the request and by using response_type=id_token code, the v2.0 endpoint ensures that the user has consented to the permissions indicated in the scope query parameter. Verrà restituito nell'app un codice di autorizzazione da scambiare con un token di accesso.It returns an authorization code to your app to exchange for an access token.

Risposta con esito positivoSuccessful response

La risposta con esito positivo quando si usa response_mode=form_post è simile alla seguente:A successful response from using response_mode=form_post looks like this:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
ParametroParameter DescrizioneDescription
id_tokenid_token Token ID richiesto dall'app.The ID token that the app requested. È possibile usare il token ID per verificare l'identità dell'utente e avviare una sessione con l'utente.You can use the ID token to verify the user's identity and begin a session with the user. Altre informazioni sui token ID e il relativo contenuto sono disponibili nel riferimento ai token dell'endpoint v2.0.You'll find more details about ID tokens and their contents in the v2.0 endpoint tokens reference.
codecode Codice di autorizzazione richiesto dall'app.The authorization code that the app requested. L'app può usare il codice di autorizzazione per richiedere un token di accesso per la risorsa di destinazione.The app can use the authorization code to request an access token for the target resource. La durata del codice di autorizzazione è molto breve.An authorization code is very short-lived. In genere, un codice di autorizzazione scade dopo circa 10 minuti.Typically, an authorization code expires in about 10 minutes.
statestate Se un parametro di stato è incluso nella richiesta, lo stesso valore viene visualizzato nella risposta.If a state parameter is included in the request, the same value should appear in the response. L'app deve verificare che i valori dello stato nella richiesta e nella risposta siano identici.The app should verify that the state values in the request and response are identical.

Risposta di erroreError response

Le risposte di errore possono essere inviate anche all'URI di reindirizzamento in modo che l'app possa gestirle adeguatamente.Error responses might also be sent to the redirect URI so that the app can handle them appropriately. La risposta di errore è simile alla seguente:An error response looks like this:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
ParametroParameter DescrizioneDescription
errorerror Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e correggerli.An error code string that you can use to classify types of errors that occur, and to react to errors.
error_descriptionerror_description Messaggio di errore specifico che consente di identificare la causa principale di un errore di autenticazione.A specific error message that can help you identify the root cause of an authentication error.

Per una descrizione dei possibili codici di errore e delle risposte client consigliate, vedere Codici per gli errori dell'endpoint di autorizzazione.For a description of possible error codes and recommended client responses, see Error codes for authorization endpoint errors.

Dopo aver ottenuto un codice di autorizzazione e un token ID, è possibile far accedere l'utente e ottenere i token di accesso per suo conto.When you have an authorization code and an ID token, you can sign the user in and get access tokens on their behalf. Per far accedere l'utente, è necessario convalidare il token ID esattamente come descritto.To sign the user in, you must validate the ID token exactly as described. Per ottenere i token di accesso, seguire i passaggi descritti nella documentazione del protocollo OAuth.To get access tokens, follow the steps described in our OAuth protocol documentation.