Ambiti, autorizzazioni e consenso nell'endpoint di Azure Active Directory v2.0Scopes, permissions, and consent in the Azure Active Directory v2.0 endpoint

Le app che si integrano con Azure Active Directory (Azure AD) seguono un modello di autorizzazione che consente agli utenti di controllare la modalità di accesso ai dati da parte di un'app.Apps that integrate with Azure Active Directory (Azure AD) follow an authorization model that gives users control over how an app can access their data. L'implementazione v2.0 di questo modello di autorizzazione è stata aggiornata, modificando la modalità di interazione di un'app con Azure AD.The v2.0 implementation of the authorization model has been updated, and it changes how an app must interact with Azure AD. Questo articolo illustra i concetti di base di questo modello di autorizzazione, inclusi gli ambiti, le autorizzazioni e il consenso.This article covers the basic concepts of this authorization model, including scopes, permissions, and consent.

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.

Ambiti e autorizzazioniScopes and permissions

Azure AD implementa il protocollo di autorizzazione OAuth 2.0.Azure AD implements the OAuth 2.0 authorization protocol. OAuth 2.0 è un metodo tramite cui un'applicazione di terze parti può accedere alle risorse ospitate sul Web per conto dell'utente.OAuth 2.0 is a method through which a third-party app can access web-hosted resources on behalf of a user. Qualsiasi risorsa ospitata sul Web che si integra con Azure AD dispoen di un identificatore di risorsa o di un URI ID dell'applicazione.Any web-hosted resource that integrates with Azure AD has a resource identifier, or Application ID URI. Ad esempio, alcune delle risorse ospitate sul Web di Microsoft includono:For example, some of Microsoft's web-hosted resources include:

  • L'API di posta unificata di Office 365: https://outlook.office.comThe Office 365 Unified Mail API: https://outlook.office.com
  • L'API Graph di Azure AD: https://graph.windows.netThe Azure AD Graph API: https://graph.windows.net
  • Microsoft Graph: https://graph.microsoft.comMicrosoft Graph: https://graph.microsoft.com

Anche le risorse di terze parti integrate con Azure AD devono disporre di tale identificatore.The same is true for any third-party resources that have integrated with Azure AD. Tali risorse possono anche definire un set di autorizzazioni che può essere usato per suddividere le funzionalità di tale risorsa in blocchi più piccoli.Any of these resources also can define a set of permissions that can be used to divide the functionality of that resource into smaller chunks. Ad esempio, Microsoft Graph ha definito le autorizzazioni per eseguire le attività seguenti, tra le altre:As an example, Microsoft Graph has defined permissions to do the following tasks, among others:

  • Lettura del calendario dell'utenteRead a user's calendar
  • Scrittura nel calendario dell'utenteWrite to a user's calendar
  • Invio di messaggi di posta elettronica come utenteSend mail as a user

Con la definizione di questi tipi di autorizzazioni, la risorsa può avere un controllo accurato dei dati e dell'esposizione degli stessi.By defining these types of permissions, the resource has fine-grained control over its data and how the data is exposed. Un'app di terze parti può richiedere tali autorizzazioni da un utente del'app.A third-party app can request these permissions from an app user. L'utente dell'app deve approvare le autorizzazioni prima che l'applicazione possa agire a suo nome.The app user must approve the permissions before the app can act on the user's behalf. Suddividendo le funzionalità della risorsa in set di autorizzazioni più piccoli, è possibile creare le app di terze parti affinché richiedano solo le autorizzazioni specifiche necessarie per il relativo funzionamento.By chunking the resource's functionality into smaller permission sets, third-party apps can be built to request only the specific permissions that they need to perform their function. Gli utenti dell'app possono sapere esattamente come un'app userà i propri dati e possono essere più sicuri che l'app non agisca per fini dannosi.App users can know exactly how an app will use their data, and they can be more confident that the app is not behaving with malicious intent.

In Azure AD e OAuth queste autorizzazioni vengono definite ambiti oIn Azure AD and OAuth, these types of permissions are called scopes. oAuth2Permissions.They also sometimes are referred to as oAuth2Permissions. Un ambito è rappresentato in Azure AD come valore stringa.A scope is represented in Azure AD as a string value. Nell'esempio relativo a Microsoft Graph il valore di ambito per ogni autorizzazione è:Continuing with the Microsoft Graph example, the scope value for each permission is:

  • Lettura del calendario dell'utente tramite Calendar.ReadRead a user's calendar by using Calendar.Read
  • Scrittura del calendario dell'utente tramite Mail.ReadWriteWrite to a user's calendar by using Mail.ReadWrite
  • Invio di messaggi di posta elettronica come utente tramite Mail.SendSend mail as a user using by Mail.Send

Un'app può richiedere tali autorizzazioni specificando gli ambiti nelle richieste all'endpoint 2.0.An app can request these permissions by specifying the scopes in requests to the v2.0 endpoint.

Ambiti di OpenID ConnectOpenID Connect scopes

L'implementazione della versione 2.0 di OpenID Connect presenta alcuni ambiti ben definiti che non si applicano a una risorsa specifica: openid, email, profile e offline_access.The v2.0 implementation of OpenID Connect has a few well-defined scopes that do not apply to a specific resource: openid, email, profile, and offline_access.

openidopenid

Se un'app esegue l'accesso usando OpenID Connect, deve richiedere l'ambito openid.If an app performs sign-in by using OpenID Connect, it must request the openid scope. L'ambito openid viene visualizzato nella pagina di consenso dell'account aziendale come autorizzazione di accesso e nella pagina di consenso dell'account personale Microsoft come autorizzazione per la visualizzazione del profilo e la connessione ad app e servizi tramite l'account Microsoft.The openid scope shows on the work account consent page as the "Sign you in" permission, and on the personal Microsoft account consent page as the "View your profile and connect to apps and services using your Microsoft account" permission. Questa autorizzazione consente a un'app di ricevere un identificatore univoco per l'utente sotto forma di attestazione subWith this permission, an app can receive a unique identifier for the user in the form of the sub claim. e concede all'app l'accesso all'endpoint delle informazioni utente.It also gives the app access to the UserInfo endpoint. L'ambito openid può essere usato nell'endpoint del token 2.0 per acquisire token ID, che possono essere usati per proteggere le chiamate HTTP tra diversi componenti di un'app.The openid scope can be used at the v2.0 token endpoint to acquire ID tokens, which can be used to secure HTTP calls between different components of an app.

emailemail

L'ambito email può essere usato con l'ambito openid e con tutti gli altri.The email scope can be used with the openid scope and any others. Consente all'applicazione di accedere all'indirizzo di posta elettronica primario dell'utente sotto forma di attestazione email.It gives the app access to the user's primary email address in the form of the email claim. L'attestazione email è inclusa nei token solo quando un indirizzo di posta elettronica è associato all'account utente, condizione che non è sempre vera.The email claim is included in a token only if an email address is associated with the user account, which is not always the case. Se si usa l'ambito email, l'applicazione deve essere pronta per gestire il caso in cui l'attestazione email non esiste nel token.If it uses the email scope, your app should be prepared to handle a case in which the email claim does not exist in the token.

Profiloprofile

L'ambito profile può essere usato con l'ambito openid e con tutti gli altri.The profile scope can be used with the openid scope and any others. Consente all'applicazione di accedere a numerose informazioni sull'utente,It gives the app access to a substantial amount of information about the user. tra cui il nome e il cognome dell'utente, il nome utente preferito, l'ID dell'oggetto e così via.The information it can access includes, but is not limited to, the user's given name, surname, preferred username, and object ID. Per un elenco completo delle attestazioni profilo disponibili nel parametro token ID per un determinato utente, vedere il riferimento al token della versione 2.0.For a complete list of the profile claims available in the id_tokens parameter for a specific user, see the v2.0 tokens reference.

offline_accessoffline_access

L'ambito offline_access consente all'app di accedere alle risorse per conto dell'utente per un periodo di tempo prolungato.The offline_access scope gives your app access to resources on behalf of the user for an extended time. Nella pagina di consenso dell'account aziendale l'ambito viene visualizzato come autorizzazione per l'accesso ai dati in qualsiasi momento.On the work account consent page, this scope appears as the "Access your data anytime" permission. Nella pagina di consenso dell'account personale Microsoft viene visualizzato come autorizzazione per l'accesso alle informazioni in qualsiasi momento.On the personal Microsoft account consent page, it appears as the "Access your info anytime" permission. Quando un utente approva l'ambito offline_access, l'app è in grado di ricevere token di aggiornamento dall'endpoint del token 2.0.When a user approves the offline_access scope, your app can receive refresh tokens from the v2.0 token endpoint. I token di aggiornamento sono di lunga durata.Refresh tokens are long-lived. L'applicazione può ottenere nuovi token di accesso quando i vecchi scadono.Your app can get new access tokens as older ones expire.

Se l'app non richiede l'ambito offline_access, non riceverà i token di aggiornamento.If your app does not request the offline_access scope, it won't receive refresh tokens. Pertanto, se si riscatta un codice di autorizzazione nel flusso del codice di autorizzazione di OAuth 2.0, si riceve solo un token di accesso dall'endpoint /token.This means that when you redeem an authorization code in the OAuth 2.0 authorization code flow, you'll receive only an access token from the /token endpoint. Il token di accesso è valido per un breve periodo.The access token is valid for a short time. Il token di accesso ha in genere una durata di un'ora.The access token usually expires in one hour. A questo punto, l'app reindirizza l'utente all'endpoint /authorize per recuperare un nuovo codice di autorizzazione.At that point, your app needs to redirect the user back to the /authorize endpoint to get a new authorization code. Durante il reindirizzamento, a seconda del tipo di app, l'utente potrebbe dover immettere nuovamente le proprie credenziali o fornire il consenso per le autorizzazioni.During this redirect, depending on the type of app, the user might need to enter their credentials again or consent again to permissions.

Per altre informazioni su come ottenere e usare i token di aggiornamento, vedere il riferimento al protocollo della versione 2.0.For more information about how to get and use refresh tokens, see the v2.0 protocol reference.

In una richiesta di autorizzazione OpenID Connect o OAuth 2.0 un'app può richiedere le autorizzazioni necessarie usando il parametro di query scope.In an OpenID Connect or OAuth 2.0 authorization request, an app can request the permissions it needs by using the scope query parameter. Ad esempio, quando un utente accede a un'app, questa può inviare una richiesta simile alla seguente (con interruzioni di riga aggiunte per leggibilità):For example, when a user signs in to an app, the app sends a request like the following example (with line breaks added for legibility):

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendar.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Il parametro scope è un elenco di ambiti separati da spazi richiesti dall'app.The scope parameter is a space-separated list of scopes that the app is requesting. Ogni ambito è indicato dall'aggiunta del valore dell'ambito all'identificatore della risorsa (URI ID dell'app).Each scope is indicated by appending the scope value to the resource's identifier (the Application ID URI). Nella richiesta di esempio precedente, l'app richiede l'autorizzazione per la lettura del calendario dell'utente e l'invio di messaggi di posta elettronica come utente.In the request example, the app needs permission to read the user's calendar and send mail as the user.

Dopo che l'utente immette le proprie credenziali, l'endpoint 2.0 verifica la disponibilità di un record corrispondente di consenso dell'utente.After the user enters their credentials, the v2.0 endpoint checks for a matching record of user consent. Se l'utente non ha fornito in precedenza il consenso per nessuna delle autorizzazioni necessarie, l'endpoint 2.0 chiede all'utente di fornire il consenso per le autorizzazioni obbligatorie.If the user has not consented to any of the requested permissions in the past, the v2.0 endpoint asks the user to grant the requested permissions.

Consenso dell'account aziendale

Quando l'utente approva l'autorizzazione, il consenso viene registrato in modo che non debba essere fornito nuovamente agli accessi successivi da parte degli account.When the user approves the permission, the consent is recorded so that the user doesn't have to consent again on subsequent account sign-ins.

Quando un'organizzazione acquista una licenza o una sottoscrizione a un'applicazione, desidera fornire accesso completo ai dipendenti.Often, when an organization purchases a license or subscription for an application, the organization wants to fully provision the application for its employees. Come parte di questo processo, un amministratore può concedere il consenso all'applicazione ad agire per conto di qualsiasi dipendente.As part of this process, an administrator can grant consent for the application to act on behalf of any employee. Se l'amministratore concede il consenso per l'intero tenant, i dipendenti dell'organizzazione non visualizzeranno la pagina di consenso per l'applicazione.If the admin grants consent for the entire tenant, the organization's employees won't see a consent page for the application.

Per richiedere il consenso per tutti gli utenti in un tenant, è possibile usare l'applicazione dell'endpoint di consenso dell'amministratore.To request consent for all users in a tenant, your app can use the admin consent endpoint.

Ambiti riservati all'amministratoreAdmin-restricted scopes

Alcune autorizzazioni con privilegi elevati nell'ecosistema Microsoft possono essere impostati come riservati all'amministratore.Some high-privilege permissions in the Microsoft ecosystem can be set to admin-restricted. Gli esempi di questi tipi di ambiti includono le autorizzazioni seguenti:Examples of these kinds of scopes include the following permissions:

  • Lettura di dati in una directory aziendale tramite Directory.ReadRead an organization's directory data by using Directory.Read
  • Scrittura di dati in una directory aziendale tramite Directory.ReadWriteWrite data to an organization's directory by using Directory.ReadWrite
  • Lettura dei gruppi di sicurezza nella directory aziendale tramite Groups.Read.AllRead security groups in an organization's directory by using Groups.Read.All

Sebbene un utente consumer possa concedere a un'applicazione l'accesso a questi tipi di dati, gli utenti aziendali non possono concedere accesso allo stesso set di dati riservati dell'azienda.Although a consumer user might grant an application access to this kind of data, organizational users are restricted from granting access to the same set of sensitive company data. Se l'applicazione richiede l'accesso a una di queste autorizzazioni da un utente aziendale, l'utente riceve un messaggio di errore che indica che non è autorizzato a fornire il consenso alle autorizzazioni dell'applicazione.If your application requests access to one of these permissions from an organizational user, the user receives an error message that says they are not authorized to consent to your app's permissions.

Se l'applicazione richiede accesso ad ambiti riservati all'amministratore delle organizzazioni, è necessario richiederle direttamente all'amministratore dell'azienda anche tramite l'endpoint di consenso dell'amministratore, come descritto di seguito.If your app requires access to admin-restricted scopes for organizations, you should request them directly from a company administrator, also by using the admin consent endpoint, described next.

Quando un amministratore concede le autorizzazioni tramite l'endpoint di consenso dell'amministratore, il consenso viene concesso a tutti gli utenti del tenant.When an administrator grants these permissions via the admin consent endpoint, consent is granted for all users in the tenant.

Seguendo questa procedura, l'applicazione può ottenere le autorizzazioni per tutti gli utenti di un tenant, inclusi gli ambiti riservati all'amministratore.If you follow these steps, your app can gather permissions for all users in a tenant, including admin-restricted scopes. Per un esempio di codice che implementa la procedura, vedere l'esempio sugli ambiti riservati all'amministratore.To see a code sample that implements the steps, see the admin-restricted scopes sample.

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.
  2. Individuare la sezione Autorizzazioni di Microsoft Graph e aggiungere le autorizzazioni richieste dall'applicazione.Locate the Microsoft Graph Permissions section, and then add the permissions that your app requires.
  3. Salvare la registrazione dell'app.Make sure you Save the app registration.

In genere, durante la compilazione di un'applicazione che usa l'endpoint di consenso dell'amministratore, 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 the admin consent endpoint, the app needs a page or view in which the admin can approve the app's permissions. Questa pagina può essere parte del flusso di iscrizione all'app, delle impostazioni dell'applicazione o di un flusso di "connessione" dedicato.This page can be part of the app's sign-up 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 dell'amministratore prima di richiedere l'approvazione delle autorizzazioni necessarie.When you sign the user in to your app, you can identify the organization to which the admin belongs before asking them to approve the necessary permissions. Sebbene non sia strettamente necessario, questo consente di creare un'esperienza più intuitiva per gli utenti dell'organizzazione.Although not strictly necessary, it can help you create a more intuitive experience for your organizational 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 v2.0.When you're ready to request permissions from your 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 below 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.Can be provided in GUID or friendly name format.
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 di registrazione delle applicazioni.It must exactly match one of the redirect URIs that you registered in the app registration portal.
statestate ConsigliatoRecommended Valore incluso nella richiesta che verrà restituito anche nella risposta del token.A value included in the request that will also be returned in the token response. Può trattarsi di una stringa di qualsiasi contenuto.It can be a string of any content you want. Usare questo stato 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.Use the state 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 richiede che solo un amministratore tenant possa accedere per completare la richiesta.At this point, Azure AD requires a tenant administrator to sign in to complete the request. L'amministratore deve approvare tutte le autorizzazioni richieste per l'app nel portale di registrazione delle applicazioni.The administrator is asked to approve all the 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'app, la risposta con esito positivo si presenta come segue:If the admin approves the permissions for your app, 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 it requested, in GUID format.
statestate 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. 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 Verrà impostato su true.Will be set to true.

Risposta di erroreError response

Se l'amministratore non approva le autorizzazioni per l'app, la risposta di errore si presenta come segue:If the admin does not approve the permissions for your app, 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 che si verificano e correggerli.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_descriptionerror_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore.A specific error message that can help a developer identify the root cause of an error.

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

Uso delle autorizzazioniUsing permissions

Dopo che l'utente fornisce il consenso alle autorizzazioni relative all'app, quest'ultima può acquisire token di accesso che rappresentano l'autorizzazione dell'app ad accedere a una risorsa.After the user consents to permissions for your app, your app can acquire access tokens that represent your app's permission to access a resource in some capacity. Un token di accesso può essere usato per una sola risorsa, ma al suo interno saranno codificate tutte le autorizzazioni della risorsa specifica per cui l'app ha ottenuto il consenso.An access token can be used only for a single resource, but encoded inside the access token is every permission that your app has been granted for that resource. Per ottenere un token di accesso, l'app può eseguire una richiesta all'endpoint del token 2.0 come quella seguente:To acquire an access token, your app can make a request to the v2.0 token endpoint, like this:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/mail.read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq..."
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

È possibile usare il token di accesso risultante nelle richieste HTTP per la risorsa.You can use the resulting access token in HTTP requests to the resource. Esso indica alla risorsa, in modo affidabile, che l'applicazione dispone delle autorizzazioni appropriate per eseguire un'attività specifica.It reliably indicates to the resource that your app has the proper permission to perform a specific task.

Per altre informazioni sul protocollo OAuth 2.0 e su come ottenere i token di accesso, vedere il riferimento al protocollo dell'endpoint v2.0.For more information about the OAuth 2.0 protocol and how to get access tokens, see the v2.0 endpoint protocol reference.