Differenze dell'endpoint 2.0.What's different about the v2.0 endpoint?

Se si ha familiarità con Azure Active Directory o si sono svolte attività di integrazione di app con Azure AD in passato, si noteranno alcune differenze inaspettate nell'endpoint 2.0.If you're familiar with Azure Active Directory or have integrated apps with Azure AD in the past, there may be some differences in the v2.0 endpoint that you would not expect. Questo documento descrive tali differenze per una maggiore comprensione da parte dell'utente.This document calls out those differences for your understanding.

Nota

Non tutti gli scenari e le funzionalità di Azure Active Directory sono supportati dall'endpoint 2.0.Not all Azure Active Directory scenarios & features are supported by the v2.0 endpoint. Per determinare se è consigliabile usare l'endpoint 2.0, leggere l'articolo relativo alle limitazioni della versione 2.0.To determine if you should use the v2.0 endpoint, read about v2.0 limitations.

Account Microsoft e account Azure ADMicrosoft accounts and Azure AD accounts

L'endpoint 2.0 consente agli sviluppatori di scrivere app che supportano l'accesso da account Microsoft e Azure AD mediante un unico endpoint di autorizzazione.The v2.0 endpoint allow developers to write apps that accept sign-in from both Microsoft Accounts and Azure AD accounts, using a single auth endpoint. In questo modo, è possibile scrivere l'app senza tenere conto dell'account usato per l'accesso. Ossia, l'app non contiene informazioni riguardo al tipo di account con cui accede l'utente.This gives you the ability to write your app completely account-agnostic; it can be ignorant of the type of account that the user signs in with. È ovviamente possibile inserire nell'app informazioni sul tipo di account usato in una determinata sessione, ma è facoltativo.Of course, you can make your app aware of the type of account being used in a particular session, but you don't have to.

Se, ad esempio, l'app chiama Microsoft Graph, per gli utenti aziendali saranno disponibili funzionalità e dati aggiuntivi, quali i siti di SharePoint o i dati di Directory.For instance, if your app calls the Microsoft Graph, some additional functionality and data will be available to enterprise users, such as their SharePoint sites or Directory data. Per numerose azioni, ad esempio la lettura di un messaggio di posta elettronica dell'utente, il codice può tuttavia essere scritto esattamente nello stesso modo per gli account Microsoft e quelli Azure AD.But for many actions, such as Reading a user's mail, the code can be written exactly the same for both Microsoft Accounts and Azure AD accounts.

L'integrazione dell'app con account Microsoft e Azure AD è ora un processo semplice.Integrating your app with Microsoft Accounts and Azure AD accounts is now one simple process. È possibile usare un unico set di endpoint, un'unica libreria e un'unica registrazione dell'app per accedere ai vantaggi di livello consumer e aziendale.You can use a single set of endpoints, a single library, and a single app registration to gain access to both the consumer and enterprise worlds. Per altre informazioni sull'endpoint 2.0, consultare la panoramica.To learn more about the v2.0 endpoint, check out the overview.

Nuovo portale di registrazione delle appNew app registration portal

Per registrare un'app che usa l'endpoint 2.0, è necessario accedere a un nuovo portale di registrazione delle app: apps.dev.microsoft.com. In questo portale è possibile ottenere un ID applicazione, personalizzare l'aspetto della pagina di accesso dell'app ed eseguire molte altre operazioni.To register an app that works with the v2.0 endpoint, you must use a new app registration portal: apps.dev.microsoft.com. This is the portal where you can obtain an application ID, customize the appearance of your app's sign-in page, and more. Per accedere al portale è sufficiente un account con tecnologia Microsoft, personale oppure dell'azienda o dell'istituto di istruzione.All you need to access the portal is a Microsoft powered account - either personal or work/school account.

ID app univoco per tutte le piattaformeOne app ID for all platforms

Se si usa Azure Active Directory, è possibile che siano state registrate più app diverse per un unico progetto.If you've used Azure Active Directory, you've probably registered several different apps for a single project. Se, ad esempio, sono stati creati sia un sito Web sia un'app per iOS, è stato necessario registrarli separatamente, usando due diversi ID applicazione.For example, if you built both a website and an iOS app, you had to register them separately, using two different Application Ids. Il portale di registrazione delle app Azure AD obbligava a compiere questa distinzione durante la registrazione:The Azure AD app registration portal forced you to make this distinction during registration:

Interfaccia utente della registrazione dell'applicazione precedente

Analogamente, se si disponeva di un sito Web e di un'API Web back-end, è possibile che ogni elemento sia stato registrato come un'app separata in Azure AD.Similarly, if you had a website and a backend web api, you might have registered each as a separate app in Azure AD. In alternativa, se si disponeva di un'app per iOS e di un'app per Android, è possibile che siano state registrate due app diverse.Or if you had an iOS app and an Android app, you also might have registered two different apps. La necessità di registrare ogni singolo componente di un'applicazione determinava tuttavia alcuni comportamenti imprevisti per gli sviluppatori e i rispettivi clienti:Registering each component of an application led to some unexpected behaviors for developers and their customers:

  • Ogni componente veniva visualizzato come un'app separata nel tenant di Azure Active Directory di ogni cliente.Each component appeared as a separate app in the Azure Active Directory tenant of each customer.
  • Se un amministratore del tenant tentava di applicare criteri a un'app, gestirne l'accesso o eliminarla, doveva quindi eseguire questa operazione per ogni componente dell'app.When a tenant administrator attempted to apply policy to, manage access to, or delete an app, they would have to do so for each component of the app.
  • Se un cliente rilasciava il consenso per un'applicazione, ogni componente veniva visualizzato nella schermata del consenso come applicazione distinta.When customers consented to an application, each component would appear in the consent screen as a distinct application.

Con l'endpoint 2.0, è ora possibile registrare tutti i componenti del progetto come un'unica app e usare un solo ID applicazione per l'intero progetto.With the v2.0 endpoint, you can now register all components of your project as a single app registration, and use a single Application Id for your entire project. È possibile aggiungere più "piattaforme" a un progetto e fornire i dati appropriati per ogni piattaforma aggiunta.You can add several "platforms" to a each project, and provide the appropriate data for each platform you add. Naturalmente, è possibile creare quante app si desidera in base alle esigenze, ma nella maggior parte dei casi è necessario un solo ID applicazione.Of course, you can create as many apps as you like depending on your requirements, but for the majority of cases only one Application Id should be necessary.

L'obiettivo è ottenere un'esperienza di sviluppo e gestione delle app più semplificata e creare una vista più consolidata del progetto al quale si lavora.Our aim is that this will lead to a more simplified app management and development experience, and create a more consolidated view of a single project that you might be working on.

Ambiti e non risorseScopes, not resources

In Azure Active Directory un'app può comportarsi come una risorsa o come un destinatario di token.In Azure Active Directory, an app can behave as a resource, or a recipient of tokens. Una risorsa può definire diversi ambiti o autorizzazioni oAuth2Permissions che può riconoscere, consentendo alle app client di richiedere token per la risorsa per un determinato set di ambiti.A resource can define a number of scopes or oAuth2Permissions that it understands, allowing client apps to request tokens to that resource for a certain set of scopes. Si consideri l'API Graph di Azure AD come esempio di una risorsa:Consider the Azure AD Graph API as an example of a resource:

  • Identificatore della risorsa o AppID URI: https://graph.windows.net/Resource Identifier, or AppID URI: https://graph.windows.net/
  • Ambiti o OAuth2Permissions: Directory.Read, Directory.Write e così viaScopes, or OAuth2Permissions: Directory.Read, Directory.Write, etc.

Quanto descritto si applica all'endpoint 2.0.All of this holds true for the the v2.0 endpoint. Un'app può comunque comportarsi come una risorsa, definire gli ambiti ed essere identificata da un URI.An app can still behave as resource, define scopes, and be identified by a URI. Le app client possono richiedere ancora l'accesso a questi ambiti,Client apps can still request access to those scopes. tuttavia, è stata modificata la modalità con cui un client esegue la richiesta delle autorizzazioni.However, the way in which a client requests those permissions has changed. In precedenza, l'aspetto di una richiesta di autorizzazione OAuth 2.0 a Azure AD era simile al seguente:In the past, an OAuth 2.0 authorize request to Azure AD might have looked like:

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https%3A%2F%2Fgraph.windows.net%2F
...

dove il parametro della risorsa indicava la risorsa per la quale l'app client richiedeva l'autorizzazione.where the resource parameter indicated which resource the client app is requesting authorization for. Azure AD calcolava le autorizzazioni obbligatorie per l'app in base alla configurazione statica nel portale di Azure e rilasciava i token di conseguenza.Azure AD computed the permissions required by the app based on static configuration in the Azure Portal, and issued tokens accordingly. Ora invece, l'aspetto della stessa richiesta di autorizzazione OAuth 2.0 è simile al seguente:Now, the same OAuth 2.0 authorize request looks like:

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https%3A%2F%2Fgraph.windows.net%2Fdirectory.read%20https%3A%2F%2Fgraph.windows.net%2Fdirectory.write
...

dove il parametro dell' ambito indica per quali risorse e autorizzazioni l'app richiede l'autorizzazione.where the scope parameter indicates which resource and permissions the app is requesting authorization for. La risorsa desiderata è ancora presente nella richiesta, semplicemente è inclusa in ognuno dei valori del parametro di ambito.The desired resource is still very present in the request - it is simply encompassed in each of the values of the scope parameter. Tale uso del parametro di ambito consente all'endpoint 2.0 di essere più conforme alla specifica OAuth 2.0 e alle pratiche comuni del settore.Using the scope parameter in this manner allows the v2.0 endpoint to be more compliant with the OAuth 2.0 specification, and aligns more closely with common industry practices. Consente inoltre alle app di eseguire il consenso incrementaledescritto nella sezione seguente.It also enables apps to perform incremental consent, which is described in the next section.

Per le app registrate in Azure AD, in passato era necessario specificare le autorizzazioni OAuth 2.0 obbligatorie nel portale di Azure al momento della creazione dell'app:Apps registered in Azure AD previously needed to specify their required OAuth 2.0 permissions in the Azure Portal, at app creation time:

Interfaccia utente della registrazione delle autorizzazioni

Le autorizzazioni richieste da un'app venivano configurate staticamente.The permissions an app required were configured statically. Se da un lato ciò consentiva che la configurazione dell'app esistesse nel portale di Azure e che il codice fosse chiaro e semplice, dall'altro presentava alcuni problemi per gli sviluppatori:While this allowed configuration of the app to exist in the Azure Portal and kept the code nice and simple, it presents a few issues for developers:

  • Era necessario definire in fase di creazione tutte le autorizzazioni che sarebbero state necessarie all'app.An app had to know all of the permissions it would ever need at app creation time. La possibilità di aggiungere le autorizzazioni in fasi successive era un processo difficile.Adding permissions over time was a difficult process.
  • Era necessario definire in anticipo tutte le risorse a cui l'app avrebbe dovuto accedere.An app had to know all of the resources it would ever access ahead of time. Era difficile creare app che potessero accedere a un numero arbitrario di risorse.It was difficult to create apps that could access an arbitrary number of resources.
  • Era necessario richiedere al primo accesso dell'utente tutte le autorizzazioni di cui l'app avrebbe avuto bisogno.An app had to request all the permissions it would ever need upon the user's first sign-in. In alcuni casi ciò comportava l'esigenza di creare un lungo elenco di autorizzazioni che dovevano essere approvate dall'utente al primo accesso, causando spesso la rinuncia all'iscrizione da parte di quest'ultimo.In some cases this led to a very long list of permissions, which discouraged end-users from approving the app's access on initial sign-in.

Nell'endpoint 2.0 è possibile specificare le autorizzazioni necessarie per l'app dinamicamente, in fase di esecuzione, durante l'utilizzo regolare dell'app.With the v2.0 endpoint, you can specify the permissions your app needs dynamically, at runtime, during regular usage of your app. A tale scopo, è possibile specificare gli ambiti necessari per l'app in qualsiasi momento, includendoli nel parametro scope di una richiesta di autorizzazione:To do so, you can specify the scopes your app needs at any given point in time by including them in the scope parameter of an authorization request:

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https%3A%2F%2Fgraph.windows.net%2Fdirectory.read%20https%3A%2F%2Fgraph.windows.net%2Fdirectory.write
...

Il codice precedente richiede l'autorizzazione per l'app di leggere i dati di directory di un utente di Azure AD, nonché di scrivere dati in tale directory.The above requests permission for the app to read an Azure AD user's directory data, as well as write data to their directory. Se l'utente ha acconsentito a tali autorizzazioni in precedenza per questa particolare app, sarà sufficiente immettere le proprie credenziali ed eseguire l'accesso all'app.If the user has consented to those permissions in the past for this particular app, they will simply enter their credentials and be signed into the app. Se l'utente non ha acconsentito a nessuna di queste autorizzazioni, l'endpoint 2.0 chiederà all'utente di fornire il consenso.If the user has not consented to any of these permissions, the v2.0 endpoint will ask the user for consent to those permissions. Per altre informazioni, leggere l'argomento relativo ad autorizzazioni, consenso e ambiti.To learn more, you can read up on permissions, consent, and scopes.

Consentendo a un'app di richiedere le autorizzazioni in modo dinamico tramite il parametro scope gli sviluppatori hanno il controllo completo dell'esperienza dell'utente.Allowing an app to request permissions dynamically via the scope parameter gives you full control over your user's experience. Se si desidera, è possibile scegliere di agire d'anticipo chiedendo il consenso per tutte le autorizzazioni in un'unica richiesta iniziale.If you wish, you can choose to frontload your consent experience and ask for all permissions in one initial authorization request. In alternativa, se l'app richiede un numero elevato di autorizzazioni, è possibile scegliere di raccogliere tali autorizzazioni dall'utente in modo incrementale, man mano che determinate funzionalità dell'app vengono usate.Or if your app requires a large number of permissions, you can choose to gather those permissions from the user incrementally, as they attempt to use certain features of your app over time.

Ambiti conosciutiWell-known scopes

Accesso offlineOffline access

Per le app che usano l'endpoint 2.0 è possibile che sia necessaria una nuova autorizzazione nota per le app: l'ambito offline_access.Apps using the v2.0 endpoint may require the use of a new well-known permission for apps - the offline_access scope. Tutte le app dovranno richiedere questa autorizzazione, se devono accedere alle risorse per conto di un utente per un periodo di tempo prolungato, anche se l'utente non sta usando attivamente l'app.All apps will need to request this permission if they need to access resources on the behalf of a user for a prolonged period of time, even when the user may not be actively using the app. L'utente visualizzerà l'ambito offline_access in finestre di dialogo di consenso, quali "Accedere ai dati offline", che dovrà accettare.The offline_access scope will appear to the user in consent dialogs as "Access your data offline", which the user must agree to. La richiesta dell'autorizzazione offline_access consentirà all'app Web di ricevere token di aggiornamento di OAuth 2.0 dall'endpoint 2.0.Requesting the offline_access permission will enable your web app to receive OAuth 2.0 refresh_tokens from the v2.0 endpoint. I token di aggiornamento hanno una durata elevata e possono essere scambiati con nuovi token di accesso di OAuth 2.0 per periodi prolungati di accesso.Refresh_tokens are long-lived, and can be exchanged for new OAuth 2.0 access_tokens for extended periods of access.

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 will not receive refresh_tokens. Pertanto, se si riscatta un codice di autorizzazione nel flusso del codice di autorizzazione di OAuth 2.0, si riceverà 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 will only receive back an access_token from the /token endpoint. Tale token di accesso rimarrà valido per un breve periodo di tempo (in genere un'ora), per poi scadere.That access_token will remain valid for a short period of time (typically one hour), but will eventually expire. A questo punto, l'app reindirizza l'utente all'endpoint /authorize per recuperare un nuovo codice di autorizzazione.At that point in time, your app will need to redirect the user back to the /authorize endpoint to retrieve a new authorization_code. Durante il reindirizzamento, l'utente può o meno avere esigenza di immettere nuovamente le proprie credenziali o fornire il consenso per le autorizzazioni, a seconda del tipo di app.During this redirect, the user may or may not need to enter their credentials again or re-consent to permissions, depending on the the type of app.

Per altre informazioni su OAuth 2.0, token di aggiornamento e token di accesso, vedere le informazioni di riferimento sui protocolli della versione 2.0.To learn more about OAuth 2.0, refresh_tokens, and access_tokens, check out the v2.0 protocol reference.

OpenID, profilo e indirizzo di posta elettronicaOpenID, profile and email

Tradizionalmente, il flusso di accesso più semplice di OpenID Connect in Azure Active Directory fornisce molte informazioni sull'utente nel token ID risultante.Historically, the most basic OpenID Connect sign-in flow with Azure Active Directory would provide a wealth of information about the user in the resulting id_token. Le attestazioni nel token ID includono, ad esempio, il nome dell'utente, il nome utente preferito, l'indirizzo di posta elettronica, l'ID oggetto e altro ancora.The claims in an id_token can include the user's name, preferred username, email address, object ID, and more.

Attualmente vengono limitate le informazioni a cui l'app ha accesso tramite l'ambito openid.We are now restricting the information that the openid scope affords your app access to. L'ambito "openid" consente all'app di far accedere l'utente e di ricevere un identificatore specifico dell'app per l'utente.The ‘openid’ scope will only allow your app to sign the user in, and receive an app-specific identifier for the user. Per ottenere informazioni personali sull'utente nell'app, questa dovrà richiedere autorizzazioni aggiuntive all'utente.If you want to obtain personally identifiable information (PII) about the user in your app, your app will need to request additional permissions from the user. Vengono introdotti due nuovi ambiti, email e profile, che consentono di eseguire questa operazione.We are introducing two new scopes – the email and profile scopes – which allow you to do so.

L'ambito email è molto semplice: consente all'app di accedere all'indirizzo di posta elettronica primario dell'utente tramite l'attestazione email nell'id_token.The email scope is very straightforward – it allows your app access to the user’s primary email address via the email claim in the id_token. L'ambito profile concede all'app l'accesso a tutte le altre informazioni di base sull'utente, vale a dire il nome, il nome utente preferito, l'ID oggetto e così via.The profile scope affords your app access to all other basic information about the user – their name, preferred username, object ID, and so on.

Questo permette di creare il codice dell'app in modo che la divulgazione delle informazioni sia minima, chiedendo all'utente solo il set di informazioni necessario per il funzionamento dell'app.This allows you to code your app in a minimal-disclosure fashion – you can only ask the user for the set of information that your app requires to do its job. Per altre informazioni su questi ambiti, vedere l'articolo relativo al riferimento all'ambito della versione 2.0.For more information on these scopes, refer to the v2.0 scope reference.

Attestazioni nei tokenToken Claims

Le attestazioni nei token rilasciati dall'endpoint 2.0 non sono identiche a quelle nei token rilasciati dagli endpoint di Azure AD disponibile a livello generale. Le app che eseguono la migrazione al nuovo servizio non devono presupporre che esista un'attestazione particolare nei token ID o di accesso.The claims in tokens issued by the v2.0 endpoint will not be identical to tokens issued by the generally available Azure AD endpoints - apps migrating to the new service should not assume a particular claim will exist in id_tokens or access_tokens. Per altre informazioni sulle attestazioni specifiche generate nei token 2.0, vedere l'articolo relativo al riferimento al token della versione 2.0.To learn about the specific claims emitted in v2.0 tokens, see the v2.0 token reference.

LimitazioniLimitations

Esistono alcune limitazioni da tenere in considerazione quando si usa l'endpoint 2.0.There are a few restrictions to be aware of when using the v2.0 point. Fare riferimento al documento relativo alle limitazioni della versione 2.0 per verificare se una di queste restrizioni si applica a un particolare scenario.Please refer to the v2.0 limitations doc to see if any of these restrictions apply to your particular scenario.