Differenze dell'endpoint 2.0.

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. Questo documento descrive tali differenze per una maggiore comprensione da parte dell'utente.

Nota

Non tutti gli scenari e le funzionalità di Azure Active Directory sono supportati dall'endpoint 2.0. Per determinare se è consigliabile usare l'endpoint 2.0, leggere l'articolo relativo alle limitazioni della versione 2.0.

Account Microsoft e account Azure AD

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. 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. È ovviamente possibile inserire nell'app informazioni sul tipo di account usato in una determinata sessione, ma è facoltativo.

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. 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.

L'integrazione dell'app con account Microsoft e Azure AD è ora un processo semplice. È 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. Per altre informazioni sull'endpoint 2.0, consultare la panoramica.

Nuovo portale di registrazione delle app

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. Per accedere al portale è sufficiente un account con tecnologia Microsoft, personale oppure dell'azienda o dell'istituto di istruzione.

ID app univoco per tutte le piattaforme

Se si usa Azure Active Directory, è possibile che siano state registrate più app diverse per un unico progetto. Se, ad esempio, sono stati creati sia un sito Web sia un'app per iOS, è stato necessario registrarli separatamente, usando due diversi ID applicazione. Il portale di registrazione delle app Azure AD obbligava a compiere questa distinzione durante la registrazione:

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. In alternativa, se si disponeva di un'app per iOS e di un'app per Android, è possibile che siano state registrate due app diverse. La necessità di registrare ogni singolo componente di un'applicazione determinava tuttavia alcuni comportamenti imprevisti per gli sviluppatori e i rispettivi clienti:

  • Ogni componente veniva visualizzato come un'app separata nel tenant di Azure Active Directory di ogni cliente.
  • 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.
  • Se un cliente rilasciava il consenso per un'applicazione, ogni componente veniva visualizzato nella schermata del consenso come applicazione distinta.

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. È possibile aggiungere più "piattaforme" a un progetto e fornire i dati appropriati per ogni piattaforma aggiunta. Naturalmente, è possibile creare quante app si desidera in base alle esigenze, ma nella maggior parte dei casi è necessario un solo ID applicazione.

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.

Ambiti e non risorse

In Azure Active Directory un'app può comportarsi come una risorsa o come un destinatario di token. 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. Si consideri l'API Graph di Azure AD come esempio di una risorsa:

  • Identificatore della risorsa o AppID URI: https://graph.windows.net/
  • Ambiti o OAuth2Permissions: Directory.Read, Directory.Write e così via

Quanto descritto si applica all'endpoint 2.0. Un'app può comunque comportarsi come una risorsa, definire gli ambiti ed essere identificata da un URI. Le app client possono richiedere ancora l'accesso a questi ambiti, tuttavia, è stata modificata la modalità con cui un client esegue la richiesta delle autorizzazioni. In precedenza, l'aspetto di una richiesta di autorizzazione OAuth 2.0 a Azure AD era simile al seguente:

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. Azure AD calcolava le autorizzazioni obbligatorie per l'app in base alla configurazione statica nel portale di Azure e rilasciava i token di conseguenza. Ora invece, l'aspetto della stessa richiesta di autorizzazione OAuth 2.0 è simile al seguente:

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. La risorsa desiderata è ancora presente nella richiesta, semplicemente è inclusa in ognuno dei valori del parametro di ambito. 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. Consente inoltre alle app di eseguire il consenso incrementaledescritto nella sezione seguente.

Consenso incrementale e dinamico

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:

Interfaccia utente della registrazione delle autorizzazioni

Le autorizzazioni richieste da un'app venivano configurate staticamente. 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:

  • Era necessario definire in fase di creazione tutte le autorizzazioni che sarebbero state necessarie all'app. La possibilità di aggiungere le autorizzazioni in fasi successive era un processo difficile.
  • Era necessario definire in anticipo tutte le risorse a cui l'app avrebbe dovuto accedere. Era difficile creare app che potessero accedere a un numero arbitrario di risorse.
  • Era necessario richiedere al primo accesso dell'utente tutte le autorizzazioni di cui l'app avrebbe avuto bisogno. 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.

Nell'endpoint 2.0 è possibile specificare le autorizzazioni necessarie per l'app dinamicamente, in fase di esecuzione, durante l'utilizzo regolare dell'app. A tale scopo, è possibile specificare gli ambiti necessari per l'app in qualsiasi momento, includendoli nel parametro scope di una richiesta di autorizzazione:

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. 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. Se l'utente non ha acconsentito a nessuna di queste autorizzazioni, l'endpoint 2.0 chiederà all'utente di fornire il consenso. Per altre informazioni, leggere l'argomento relativo ad autorizzazioni, consenso e ambiti.

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. Se si desidera, è possibile scegliere di agire d'anticipo chiedendo il consenso per tutte le autorizzazioni in un'unica richiesta iniziale. 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.

Ambiti conosciuti

Accesso offline

Per le app che usano l'endpoint 2.0 è possibile che sia necessaria una nuova autorizzazione nota per le app: l'ambito offline_access. 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. L'utente visualizzerà l'ambito offline_access in finestre di dialogo di consenso, quali "Accedere ai dati offline", che dovrà accettare. La richiesta dell'autorizzazione offline_access consentirà all'app Web di ricevere token di aggiornamento di OAuth 2.0 dall'endpoint 2.0. 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.

Se l'app non richiede l'ambito offline_access, non riceverà i token di aggiornamento. 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. Tale token di accesso rimarrà valido per un breve periodo di tempo (in genere un'ora), per poi scadere. A questo punto, l'app reindirizza l'utente all'endpoint /authorize per recuperare un nuovo codice di autorizzazione. 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.

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.

OpenID, profilo e indirizzo di posta elettronica

Tradizionalmente, il flusso di accesso più semplice di OpenID Connect in Azure Active Directory fornisce molte informazioni sull'utente nel token ID risultante. 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.

Attualmente vengono limitate le informazioni a cui l'app ha accesso tramite l'ambito openid. L'ambito "openid" consente all'app di far accedere l'utente e di ricevere un identificatore specifico dell'app per l'utente. Per ottenere informazioni personali sull'utente nell'app, questa dovrà richiedere autorizzazioni aggiuntive all'utente. Vengono introdotti due nuovi ambiti, email e profile, che consentono di eseguire questa operazione.

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. 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.

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. Per altre informazioni su questi ambiti, vedere l'articolo relativo al riferimento all'ambito della versione 2.0.

Attestazioni nei token

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. Per altre informazioni sulle attestazioni specifiche generate nei token 2.0, vedere l'articolo relativo al riferimento al token della versione 2.0.

Limitazioni

Esistono alcune limitazioni da tenere in considerazione quando si usa l'endpoint 2.0. Fare riferimento al documento relativo alle limitazioni della versione 2.0 per verificare se una di queste restrizioni si applica a un particolare scenario.