Azure Active Directory v2.0 e il flusso di credenziali client OAuth 2.0Azure Active Directory v2.0 and the OAuth 2.0 client credentials flow

La concessione di credenziali client OAuth 2.0, anche detta OAuth a due vie, può essere usata per accedere alle risorse ospitate sul Web tramite l'identità di un'applicazione.You can use the OAuth 2.0 client credentials grant, sometimes called two-legged OAuth, to access web-hosted resources by using the identity of an application. Viene comunemente impiegata per le interazioni di tutti i server in esecuzione in background senza l'interazione immediata con un utente finale.This type of grant commonly is used for server-to-server interactions that must run in the background, without immediate interaction with a user. Questo tipo di applicazioni vengono spesso definite daemon o account di servizio.These types of applications often are referred to as daemons or service accounts.

Nota

Non tutti gli scenari e le funzionalità di Azure Active Directory sono supportati dall'endpoint v2.0.The v2.0 endpoint doesn't 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.

Nel più comune OAuth a tre vie, a un'applicazione client viene concessa l'autorizzazione per accedere a una risorsa per conto di un determinato utente.In the more typical three-legged OAuth, a client application is granted permission to access a resource on behalf of a specific user. L'autorizzazione è delegata dall'utente all'applicazione, in genere, durante il processo di concessione.The permission is delegated from the user to the application, usually during the consent process. Tuttavia, nel flusso di credenziali client, le autorizzazioni vengono concesse direttamente all'applicazione stessa.However, in the client credentials flow, permissions are granted directly to the application itself. Quando l'applicazione presenta un token a una risorsa, la risorsa obbliga l'applicazione stessa ad avere l'autorizzazione per eseguire un'azione e non l'utente.When the app presents a token to a resource, the resource enforces that the app itself has authorization to perform an action, and not that the user has authorization.

Diagramma di protocolloProtocol diagram

L'intero flusso di credenziali client ha un aspetto simile a quello illustrato nel diagramma seguente.The entire client credentials flow looks similar to the next diagram. Tutti i passaggi vengono descritti in seguito nell'articolo.We describe each of the steps later in this article.

Flusso di credenziali client

Ottenere l'autorizzazione direttaGet direct authorization

Esistono due metodi tramite i quali l'applicazione riceve generalmente autorizzazione diretta per l'accesso alla risorsa: tramite un elenco di controllo di accesso (ACL) alla risorsa o per mezzo dell'assegnazione dell'autorizzazione a un'applicazione in Azure Active Directory (Azure AD).An app typically receives direct authorization to access a resource in one of two ways: through an access control list (ACL) at the resource, or through application permission assignment in Azure Active Directory (Azure AD). Questi due metodi sono i più comuni in Azure AD e sono consigliati per i client e le risorse che eseguono il flusso di credenziali client.These two methods are the most common in Azure AD, and we recommend them for clients and resources that perform the client credentials flow. Una risorsa può comunque scegliere di autorizzare i client in altri modi.A resource can choose to authorize its clients in other ways, however. Ciascun server di risorse può scegliere il metodo più adatto all'applicazione.Each resource server can choose the method that makes the most sense for its application.

Elenchi di controllo di accessoAccess control lists

Un provider di risorse potrebbe imporre un controllo delle autorizzazioni in base a un elenco di ID applicazione che riconosce e concedere uno specifico livello di accesso.A resource provider might enforce an authorization check based on a list of Application IDs that it knows and grants a specific level of access to. Quando la risorsa riceve un token dall'endpoint 2.0, può decodificare il token ed estrarre l'ID dell'applicazione client dalle attestazioni appid e iss.When the resource receives a token from the v2.0 endpoint, it can decode the token and extract the client's Application ID from the appid and iss claims. A quel punto, la risorsa verifica la presenza dell'applicazione nell'elenco di controllo di accesso esistente.Then it compares the application against an ACL that it maintains. La granularità e il metodo relativi all'elenco possono variare in maniera sostanziale da risorsa a risorsa.The ACL's granularity and method might vary substantially between resources.

Un caso di utilizzo comune vede l'uso di un elenco di controllo di accesso per eseguire test per un'applicazione Web o per un'API Web.A common use case is to use an ACL to run tests for a web application or for a Web API. L'API Web potrebbe fornire solo un sottoinsieme delle autorizzazioni complete a un client specifico.The Web API might grant only a subset of full permissions to a specific client. Per eseguire test end-to-end sull'API, è necessario creare un client di prova che acquisisce i token dall'endpoint 2.0 e li invia all'API.To run end-to-end tests on the API, create a test client that acquires tokens from the v2.0 endpoint and then sends them to the API. A quel punto, l'API verifica gli elenchi di controllo di accesso all'ID dell'applicazione del client di prova per concedere accesso completo alle funzionalità dell'API.The API then checks the ACL for the test client's Application ID for full access to the API's entire functionality. Se si utilizza questo tipo di elenco, assicurarsi di convalidare non solo il valore appid del chiamante,If you use this kind of ACL, be sure to validate not only the caller's appid value. ma di verificare anche l'attendibilità del token del valore iss.Also validate that the iss value of the token is trusted.

Questo tipo di autorizzazione è comune per gli account daemon e di servizio che devono accedere ai dati di proprietà di utenti che dispongono di account Microsoft personale.This type of authorization is common for daemons and service accounts that need to access data owned by consumer users who have personal Microsoft accounts. Per i dati appartenenti a organizzazioni, è consigliabile acquisire l'autorizzazione necessaria tramite le autorizzazioni dell'applicazione.For data owned by organizations, we recommend that you get the necessary authorization through application permissions.

Autorizzazioni dell'applicazioneApplication permissions

Anziché utilizzare gli elenchi di controllo di accesso, è possibile utilizzare le API per esporre un set di autorizzazioni per l'applicazione.Instead of using ACLs, you can use APIs to expose a set of application permissions. Un'autorizzazione dell'applicazione viene concessa a un'applicazione da un amministratore dell'organizzazione e può essere usata solo per accedere ai dati di proprietà dell'organizzazione e dei propri dipendenti.An application permission is granted to an application by an organization's administrator, and can be used only to access data owned by that organization and its employees. Ad esempio, Microsoft Graph espone diverse autorizzazioni dell'applicazione per le operazioni seguenti:For example, Microsoft Graph exposes several application permissions to do the following:

  • Lettura di e-mail in tutte le caselle e-mailRead mail in all mailboxes
  • Lettura e scrittura di e-mail in tutte le caselle e-mailRead and write mail in all mailboxes
  • Invio di e-mail come utenteSend mail as any user
  • Leggi i dati della directoryRead directory data

Per ulteriori informazioni sulle autorizzazioni per le applicazioni, vedere Microsoft Graph.For more information about application permissions, go to Microsoft Graph.

Per utilizzare autorizzazioni per le applicazioni nell'app, effettuare i passaggi illustrati nelle sezioni successive.To use application permissions in your app, do the steps we discuss in the next sections.

Richiedere le autorizzazioni nel portale di registrazione dell'appRequest the permissions in the app registration portal

  1. Passare all'applicazione nel portale di registrazione delle applicazioni o creare un'app, se non se ne possiede già una.Go to your application in the Application Registration Portal, or create an app, if you haven't already. È necessario utilizzare almeno un segreto dell'applicazione durante la creazione dell'app.You'll need to use at least one Application Secret when you create your app.
  2. Individuare la sezione Autorizzazioni applicazione dirette e aggiungere le autorizzazioni richieste dall'applicazione.Locate the Direct Application Permissions section, and then add the permissions that your app requires.
  3. Salvare la registrazione dell'app.Save the app registration.

In genere, durante la compilazione di un'applicazione che usa le autorizzazioni, l'app necessita di una pagina o vista che consenta all'amministratore di approvare le autorizzazioni dell'applicazione.Typically, when you build an application that uses application permissions, the app requires a page or view on which the admin approves the app's permissions. Questa pagina può essere parte del flusso di accesso all'app, delle impostazioni dell'applicazione o di un flusso di "connessione" dedicato.This page can be part of the app's sign-in flow, part of the app's settings, or it can be a dedicated "connect" flow. In molti casi, è utile per l'applicazione visualizzare la pagina di "connessione" solo dopo che un utente ha eseguito l'accesso con un account di lavoro o dell'istituto di istruzione Microsoft.In many cases, it makes sense for the app to show this "connect" view only after a user has signed in with a work or school Microsoft account.

L'accesso dell'utente nell'app consente di identificarne l'organizzazione di appartenenza prima di richiedere l'approvazione delle autorizzazioni dell'applicazione.If you sign the user in to your app, you can identify the organization to which the user belongs before you ask the user to approve the application permissions. Sebbene non sia strettamente necessario, questo consente di creare un'esperienza più intuitiva per gli utenti.Although not strictly necessary, it can help you create a more intuitive experience for your users. Per l'accesso utente, seguire le esercitazioni sui protocolli 2.0.To sign the user in, follow our v2.0 protocol tutorials.

Richiedere le autorizzazioni da un amministratore di directoryRequest the permissions from a directory admin

Quando si è pronti per richiedere le autorizzazioni dall'amministratore dell'azienda, è possibile reindirizzare l'utente sull'endpoint di consenso dell'amministratore 2.0.When you're ready to request permissions from the organization's admin, you can redirect the user to the v2.0 admin consent endpoint.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
// Pro tip: Try pasting the following request in a browser!
https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
ParametroParameter CondizioneCondition DescrizioneDescription
tenanttenant ObbligatorioRequired Il tenant della directory da cui si desidera richiedere autorizzazioni.The directory tenant that you want to request permission from. Può essere fornito nel formato di nome descrittivo o GUID.This can be in GUID or friendly name format. Se non si conosce il tenant di appartenenza dell'utente e si desidera consentire l'accesso con qualsiasi tentant, usare common.If you don't know which tenant the user belongs to and you want to let them sign in with any tenant, use common.
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.
redirect_uriredirect_uri ObbligatorioRequired URI di reindirizzamento in cui si desidera che venga inviata la risposta per la gestione da parte dell'app.The redirect URI where you want the response to be sent for your app to handle. Deve corrispondere esattamente a uno degli URI di reindirizzamento registrati nel portale, ad eccezione del fatto che deve essere codificato come URL e disporre di segmenti di percorso aggiuntivi.It must exactly match one of the redirect URIs that you registered in the portal, except that it must be URL encoded, and it can have additional path segments.
statestate ConsigliatoRecommended Valore incluso nella richiesta che verrà restituito anche nella risposta del token.A value that is included in the request that also is returned in the token response. Può trattarsi di una stringa di qualsiasi contenuto.It can be a string of any content that you want. 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 vista in cui si trovava.The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.

A questo punto, Azure AD imporrà che solo un amministratore tenant possa accedere per completare la richiesta.At this point, Azure AD enforces that only a tenant administrator can sign in to complete the request. L'amministratore dovrà approvare tutte le autorizzazioni dirette dell'applicazione richieste per l'app nel portale di registrazione.The administrator will be asked to approve all the direct application permissions that you have requested for your app in the app registration portal.

Risposta con esito positivoSuccessful response

Se l'amministratore approva le autorizzazioni per l'applicazione, la risposta con esito positivo si presenta come segue:If the admin approves the permissions for your application, the successful response looks like this:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
ParametroParameter DescrizioneDescription
tenanttenant Tenant della directory che ha concesso all'applicazione le autorizzazioni richieste, in formato GUID.The directory tenant that granted your application the permissions that it requested, in GUID format.
statestate Valore incluso nella richiesta che verrà restituito anche nella risposta del token.A value that is included in the request that also is returned in the token response. Può trattarsi di una stringa di qualsiasi contenuto.It can be a string of any content that you want. 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 vista in cui si trovava.The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
admin_consentadmin_consent Impostare su true.Set to true.
Risposta di erroreError response

Se l'amministratore non approva le autorizzazioni per l'applicazione, la risposta di errore avrà l'aspetto seguente:If the admin does not approve the permissions for your application, the failed response looks like this:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
ParametroParameter DescrizioneDescription
errorerror Stringa di codice di errore che può essere usata per classificare i tipi di errori e correggerli.An error code string that you can use to classify types of errors, and which you can use to react to errors.
error_descriptionerror_description Messaggio di errore specifico che consente di identificare la causa principale di un errore.A specific error message that can help you identify the root cause of an error.

Dopo aver ricevuto una risposta con esito positivo dall'endpoint di provisioning dell'app, l'applicazione ha ottenuto le autorizzazioni dirette dell'applicazione richieste.After you've received a successful response from the app provisioning endpoint, your app has gained the direct application permissions that it requested. Successivamente, è possibile richiedere un token per la risorsa desiderata.Now you can request a token for the resource that you want.

Acquisizione di un tokenGet a token

Dopo aver acquisito l'autorizzazione necessaria per l'applicazione, è possibile procedere con l'acquisizione dei token di accesso per le API.After you've acquired the necessary authorization for your application, proceed with acquiring access tokens for APIs. Per ottenere un token con concessione delle credenziali client, inviare una richiesta POST all'endpoint /token 2.0:To get a token by using the client credentials grant, send a POST request to the /token v2.0 endpoint:

Primo caso: richiesta del token di accesso con un segreto condivisoFirst case: Access token request with a shared secret

POST /common/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=qWgdYAmab0YSkuL1qKv5bPX&grant_type=client_credentials
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=qWgdYAmab0YSkuL1qKv5bPX&grant_type=client_credentials' 'https://login.microsoftonline.com/common/oauth2/v2.0/token'
ParametroParameter CondizioneCondition DescrizioneDescription
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.
scopescope ObbligatorioRequired Il valore passato per il parametro scope nella richiesta deve essere l'identificatore della risorsa (URI ID Applicazione) della risorsa desiderata, con l'aggiunta del suffisso .default.The value passed for the scope parameter in this request should be the resource identifier (Application ID URI) of the resource you want, affixed with the .default suffix. Per l'esempio di Microsoft Graph, il valore deve essere https://graph.microsoft.com/.default.For the Microsoft Graph example, the value is https://graph.microsoft.com/.default. Questo valore indica all'endpoint 2.0 che, per tutte le autorizzazioni dirette dell'applicazione configurate per l'app, è necessario emettere un token per le autorizzazioni riguardanti la risorsa da usare.This value informs the v2.0 endpoint that of all the direct application permissions you have configured for your app, it should issue a token for the ones associated with the resource you want to use.
client_secretclient_secret ObbligatorioRequired Segreto dell'applicazione generato per l'app nel portale di registrazione.The Application Secret that you generated for your app in the app registration portal.
grant_typegrant_type ObbligatorioRequired Deve essere client_credentials.Must be client_credentials.

Secondo caso: richiesta del token di accesso con un certificatoSecond case: Access token request with a certificate

POST /common/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg&grant_type=client_credentials
ParametroParameter CondizioneCondition DescrizioneDescription
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.
scopescope ObbligatorioRequired Il valore passato per il parametro scope nella richiesta deve essere l'identificatore della risorsa (URI ID Applicazione) della risorsa desiderata, con l'aggiunta del suffisso .default.The value passed for the scope parameter in this request should be the resource identifier (Application ID URI) of the resource you want, affixed with the .default suffix. Per l'esempio di Microsoft Graph, il valore deve essere https://graph.microsoft.com/.default.For the Microsoft Graph example, the value is https://graph.microsoft.com/.default. Questo valore indica all'endpoint 2.0 che, per tutte le autorizzazioni dirette dell'applicazione configurate per l'app, è necessario emettere un token per le autorizzazioni riguardanti la risorsa da usare.This value informs the v2.0 endpoint that of all the direct application permissions you have configured for your app, it should issue a token for the ones associated with the resource you want to use.
client_assertion_typeclient_assertion_type Obbligatoriarequired Il valore deve essere urn:ietf:params:oauth:client-assertion-type:jwt-bearer.The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertionclient_assertion Obbligatoriarequired Un'asserzione (un token JSON Web) che è necessario creare e firmare con il certificato registrato come credenziale per l'applicazione.An assertion (a JSON Web Token) that you need to create and sign with the certificate you registered as credentials for your application. Leggere l'articolo relativo alle credenziali basate su certificato per informazioni sulla registrazione del certificato e il formato dell'asserzione.Read about certificate credentials to learn how to register your certificate and the format of the assertion.
grant_typegrant_type ObbligatorioRequired Deve essere client_credentials.Must be client_credentials.

Si noti che i parametri sono quasi uguali a quelli usati nella richiesta tramite segreto condiviso, con l'eccezione del parametro client_secret che viene sostituito da due parametri: client_assertion_type e client_assertion.Notice that the parameters are almost the same as in the case of the request by shared secret except that the client_secret parameter is replaced by two parameters: a client_assertion_type and client_assertion.

Risposta con esito positivoSuccessful response

Una risposta con esito positivo ha un aspetto simile al seguente:A successful response looks like this:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
ParametroParameter DescrizioneDescription
access_tokenaccess_token Token di accesso richiesto.The requested access token. L'app può usare questo token per l'autenticazione alla risorsa protetta, ad esempio un'API Web.The app can use this token to authenticate to the secured resource, such as to a Web API.
token_typetoken_type Indica il valore del tipo di token.Indicates the token type value. L'unico tipo supportato da Azure AD è bearer.The only type that Azure AD supports is bearer.
expires_inexpires_in Validità del token di accesso (espressa in secondi).How long the access token is valid (in seconds).

Risposta di erroreError response

La risposta di errore è simile alla seguente:An error response looks like this:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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 might help you identify the root cause of an authentication error.
error_codeserror_codes Elenco dei codici di errore specifici del servizio token di sicurezza utile per la diagnostica.A list of STS-specific error codes that might help with diagnostics.
timestamptimestamp Ora in cui si è verificato l'errore.The time at which the error occurred.
trace_idtrace_id Identificatore univoco per la richiesta utile per la diagnostica.A unique identifier for the request that might help with diagnostics.
correlation_idcorrelation_id Identificatore univoco per la richiesta utile per la diagnostica dei componenti.A unique identifier for the request that might help with diagnostics across components.

Usare di un tokenUse a token

Ora che è stato acquisito un token, è possibile usarlo per inoltrare richieste alla risorsa.Now that you've acquired a token, use the token to make requests to the resource. Alla scadenza del token, ripetere la richiesta all'endpoint /token per ottwnere un token di accesso aggiornato.When the token expires, repeat the request to the /token endpoint to acquire a fresh access token.

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
// Pro tip: Try the following command! (Replace the token with your own.)
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q" 'https://graph.microsoft.com/v1.0/me/messages'

Esempio di codiceCode sample

Per un esempio di un'applicazione che implementa la concessione delle credenziali client tramite l'endpoint di consenso dell'amministratore, vedere l'esempio di codice daemon 2.0.To see an example of an application that implements the client credentials grant by using the admin consent endpoint, see our v2.0 daemon code sample.