Perché eseguire l'aggiornamento a Microsoft Identity Platform (v2.0)?

  • Articolo

Quando si sviluppa una nuova applicazione, è importante conoscere le differenze tra gli endpoint di Microsoft Identity Platform (v2.0) e Azure Active Directory (v1.0). Questo articolo illustra le principali differenze tra gli endpoint e alcune limitazioni esistenti per Microsoft Identity Platform.

Utenti autorizzati a effettuare l'accesso

Utenti autorizzati a effettuare l'accesso con gli endpoint v1.0 e v2.0

  • L'endpoint v1.0 consente l'accesso all'applicazione (Azure AD) solo agli account aziendali e dell'istituto di istruzione
  • L'endpoint Microsoft Identity Platform consente agli account aziendali e dell'istituto di istruzione di Microsoft Entra account Microsoft (MSA), ad esempio hotmail.com, outlook.com e msn.com, di accedere.
  • Entrambi gli endpoint accettano anche gli accessi degli utenti guest di una directory Microsoft Entra per le applicazioni configurate come single-tenant o per applicazioni multi-tenant configurate per puntare all'endpoint specifico del tenant (https://login.microsoftonline.com/{TenantId_or_Name}).

L'endpoint Microsoft Identity Platform consente di scrivere app che accettano gli accessi dagli account Microsoft personali e dagli account aziendali e dell'istituto di istruzione. Questo consente di scrivere l'app senza tenere conto dell'account utilizzato per l'accesso. Se, ad esempio, l'app chiama Microsoft Graph, per gli account aziendali saranno disponibili funzionalità e dati aggiuntivi, come i siti di SharePoint o i dati delle directory. Per numerose azioni, ad esempio la lettura di un messaggio di posta elettronica dell'utente, lo stesso codice può tuttavia accedere al messaggio di posta elettronica sia per gli account personali che per quelli aziendali e dell'istituto di istruzione.

Per Microsoft Identity Platform endpoint, è possibile usare Microsoft Authentication Library (MSAL) per ottenere l'accesso ai mondi consumer, didattici e aziendali. L'endpoint v1.0 di Azure AD accetta gli accessi solo da account aziendali e dell'istituto di istruzione.

Le app che usano l'endpoint v1.0 di Azure AD devono specificare in anticipo le autorizzazioni OAuth 2.0 richieste, ad esempio:

Esempio che mostra l'interfaccia utente di registrazione delle autorizzazioni

Le autorizzazioni impostate direttamente nella registrazione dell'applicazione sono di tipo statico. Nonostante la definizione delle autorizzazioni statiche dell'app nel portale di Azure consenta di mantenere il codice chiaro e semplice, questa opzione può presentare problemi per gli sviluppatori:

  • Al primo accesso dell'utente l'app deve richiedere tutte le autorizzazioni di cui potrebbe avere bisogno. Questo può richiedere di creare un lungo elenco di autorizzazioni che dovevano essere approvate dall'utente al primo accesso, causando spesso la rinuncia all'accesso da parte di quest'ultimo.

  • L'app deve conoscere in anticipo tutte le risorse a cui potrebbe dover accedere. Era difficile creare app che potessero accedere a un numero arbitrario di risorse.

Con l'endpoint Microsoft Identity Platform, è possibile ignorare le autorizzazioni statiche definite nelle informazioni di registrazione dell'app nelle portale di Azure e richiedere le autorizzazioni in modo incrementale, che significa richiedere un set minimo minimo di autorizzazioni iniziali e in crescita nel tempo in quanto il cliente usa funzionalità di app aggiuntive. A tale scopo è possibile specificare gli ambiti necessari per l'app in qualsiasi momento, inclusi i nuovi ambiti nel parametro scope quando si richiede un token di accesso, senza doverli definire in precedenza nelle informazioni di registrazione dell'applicazione. Se l'utente non ha ancora fornito il consenso per i nuovi ambiti aggiunti alla richiesta, gli verrà chiesto di farlo solo per le nuove autorizzazioni. 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. È anche possibile scegliere di agire d'anticipo chiedendo il consenso per tutte le autorizzazioni in un'unica richiesta iniziale. Se l'app richiede un numero elevato di autorizzazioni, è possibile raccogliere tali autorizzazioni dall'utente in modo incrementale, man mano che determinate funzionalità dell'app vengono usate.

Il consenso dell'amministratore fornito per conto di un'organizzazione richiede comunque le autorizzazioni statiche registrate per l'app, perciò si deve impostare tali autorizzazioni per le app nel portale di registrazione dell'app se è necessario che un amministratore fornisca il consenso per conto dell'intera organizzazione. Questo riduce i cicli richiesti dall'amministratore dell'organizzazione per configurare l'applicazione.

Ambiti e non risorse

Per le app che usano l'endpoint v1.0, 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 dalla risorsa per un determinato set di ambiti. Considerare microsoft API Graph come esempio di una risorsa:

  • Identificatore della risorsa o AppID URI: https://graph.microsoft.com/
  • Ambiti o oAuth2Permissions: Directory.Read, Directory.Write e così via.

Questo valore è true per l'endpoint di Microsoft Identity Platform. 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, il modo in cui un client richiede che tali autorizzazioni siano state modificate.

Per l'endpoint v1.0, l'aspetto di una richiesta di autorizzazione OAuth 2.0 per Azure AD è simile al seguente:

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

Qui il parametro resource 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.

Per le applicazioni che usano l'endpoint Microsoft Identity Platform, la stessa richiesta di autorizzazione OAuth 2.0 ha un aspetto simile al seguente:

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

Qui il parametro scope indica per quali risorse e autorizzazioni l'app richiede l'autorizzazione. La risorsa desiderata è ancora presente nella richiesta: è inclusa in ognuno dei valori del parametro di ambito. L'uso del parametro di ambito in questo modo consente all'endpoint di Microsoft Identity Platform di essere più conforme alla specifica OAuth 2.0 e allinea più strettamente le procedure di settore comuni. Consente anche alle app di eseguire il consenso incrementale : richiede solo le autorizzazioni quando l'applicazione richiede loro anziché in anticipo.

Ambiti conosciuti

Accesso offline

Le app che usano l'endpoint Microsoft Identity Platform possono richiedere l'uso di una nuova autorizzazione nota per le app, ovvero l'ambitooffline_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'ambito offline_access viene visualizzato all'utente in finestre di dialogo di consenso, come Accedi ai dati personali in qualsiasi momento, che l'utente deve accettare. La richiesta dell'autorizzazione offline_access consentirà all'app Web di ricevere refresh_tokens OAuth 2.0 dall'endpoint di Microsoft Identity Platform. I token di aggiornamento hanno una lunga durata e possono essere scambiati con i 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. Ciò significa che, quando si riscatta un codice di autorizzazione nel flusso del codice di autorizzazione OAuth 2.0, si riceve solo un token di accesso dall'endpoint /token. Tale token di accesso rimane valido per un breve periodo di tempo, in genere un'ora, poi scade. A questo punto, l'app deve reindirizzare l'utente all'endpoint /authorize per recuperare un nuovo codice di autorizzazione. Durante il reindirizzamento l'utente può o meno dover 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, refresh_tokense access_tokens, vedere il riferimento al protocollo di Microsoft Identity Platform.

OpenID, profilo e indirizzo di posta elettronica

Storicamente, il flusso di accesso OpenID Connect più di base con Microsoft Identity Platform fornirebbe molte informazioni sull'utente nel id_token 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.

Le informazioni a cui l'app ha accesso tramite l'ambito openid sono ora limitate. L'ambito openid consente all'app di far accedere l'utente e di ricevere un identificatore specifico dell'app per l'utente. Per ottenere dati personali sull'utente nell'app, questa deve richiedere autorizzazioni aggiuntive all'utente. Due nuovi ambiti, email e profile, consentiranno di richiedere autorizzazioni aggiuntive.

  • L'ambito email consente all'app di accedere all'indirizzo di posta elettronica primario dell'utente tramite l'attestazione email nella id_token, presupponendo che l'utente abbia un indirizzo di posta elettronica indirizzabile.
  • L'ambito profile consente all'app di accedere a tutte le altre informazioni di base sull'utente, ad esempio il nome, il nome utente preferito, l'ID oggetto e così via, nella id_token.

Questi ambiti permettono di creare il codice dell'app in modo che la divulgazione delle informazioni sia minima ed è possibile chiedere all'utente solo il set di informazioni di cui l'app ha bisogno per svolgere le sue funzioni. Per altre informazioni su questi ambiti, vedere il riferimento all'ambito Microsoft Identity Platform.

Attestazioni nei token

L'endpoint Microsoft Identity Platform genera un set ridotto di attestazioni nei relativi token per impostazione predefinita per mantenere i payload di piccole dimensioni. Se si dispone di app e servizi che hanno una dipendenza da un'attestazione specifica in un token v1.0 che non è più fornito per impostazione predefinita in un token di Microsoft Identity Platform, è consigliabile usare la funzionalità attestazioni facoltativa per includere tale attestazione.

Importante

I token v1.0 e v2.0 possono essere emessi sia dagli endpoint v1.0 che v2.0. id_tokens sempre corrispondere all'endpoint richiesto e i token di accesso corrispondono sempre al formato previsto dall'API Web che il client chiamerà usando tale token. Quindi, se l'app usa l'endpoint v2.0 per ottenere un token per chiamare Microsoft Graph, che prevede token di accesso in formato v1.0, l'app riceverà un token nel formato v1.0.

Limitazioni

Esistono alcune restrizioni da tenere presente quando si usa Microsoft Identity Platform.

Quando si compilano applicazioni che si integrano con l'Microsoft Identity Platform, è necessario decidere se gli endpoint e i protocolli di autenticazione di Microsoft Identity Platform soddisfano le esigenze. L'endpoint e la piattaforma v1.0 sono ancora completamente supportati e, in alcuni casi, è più ricca di Microsoft Identity Platform. Tuttavia, Microsoft Identity Platform introduce vantaggi significativi per gli sviluppatori.

Ecco una raccomandazione semplificata per gli sviluppatori ora:

  • Se si vuole o è necessario supportare gli account Microsoft personali nell'applicazione oppure si sta scrivendo una nuova applicazione, usare Microsoft Identity Platform. È necessario tuttavia conoscere i limiti illustrati in questo articolo.
  • Se si esegue la migrazione o si aggiorna un'applicazione basata su SAML, non è possibile usare Microsoft Identity Platform. Fare invece riferimento alla guida di Azure AD v1.0.

L'endpoint Microsoft Identity Platform si evolverà per eliminare le restrizioni elencate qui, in modo che sia necessario usare l'endpoint Microsoft Identity Platform. Nel frattempo, usare questo articolo per determinare se l'endpoint di Microsoft Identity Platform è adatto per l'utente. Questo articolo verrà aggiornato in modo da riflettere lo stato corrente dell'endpoint di Microsoft Identity Platform. Controllare di nuovo per rivalutare i requisiti rispetto alle funzionalità di Microsoft Identity Platform.

Restrizioni relative alle registrazioni di app

Per ogni app che si vuole integrare con l'endpoint Microsoft Identity Platform, è possibile creare una registrazione dell'app nella nuova esperienza di Registrazioni app nell'portale di Azure. Le app dell'account Microsoft esistenti non sono compatibili con il portale, ma tutte le app Microsoft Entra sono, indipendentemente dalla posizione o dalla registrazione.

Le Registrazioni app che supportano gli account aziendali e dell'istituto di istruzione e gli account personali sono soggette alle condizioni seguenti:

  • Per ogni ID applicazione sono consentiti solo due segreti dell'app.
  • Un'applicazione che non è stata registrata in un tenant può essere gestita solo dall'account che l'ha registrata. Non può essere condivisa con altri sviluppatori. Questo è il caso della maggior parte delle app che sono state registrate usando un account Microsoft personale nel portale di registrazione delle app. Se si vuole condividere la registrazione dell'app con più sviluppatori, registrare l'applicazione in un tenant usando la nuova sezione Registrazioni app del portale di Azure.
  • Ci sono diverse restrizioni relative al formato dell'URL di reindirizzamento consentito. Per altre informazioni sull'URL di reindirizzamento, vedere la sezione successiva.

Restrizioni relative agli URL di reindirizzamento

Per informazioni aggiornate sulle restrizioni relative agli URL di reindirizzamento per le app registrate per Microsoft Identity Platform, vedere Restrizioni e limitazioni relative all'URL di reindirizzamento/risposta nella documentazione di Microsoft Identity Platform.

Per informazioni su come registrare un'app da usare con Microsoft Identity Platform, vedere Registrare un'app usando la nuova esperienza di Registrazioni app.

Restrizioni relative alle librerie e agli SDK

Attualmente, il supporto della libreria per l'endpoint Microsoft Identity Platform è limitato. Se si vuole usare l'endpoint Microsoft Identity Platform in un'applicazione di produzione, sono disponibili queste opzioni:

  • Se si sta creando un'applicazione Web, è possibile usare in modo sicuro il middleware lato server disponibile a livello generale per eseguire l'accesso e la convalida dei token. Sono inclusi il middleware OpenID Connect OWIN per ASP.NET e il plug-in Passport per NodeJS. Per esempi di codice che usano il middleware Microsoft, vedere la sezione introduttiva Microsoft Identity Platform.
  • Se si sta creando un'applicazione desktop o per dispositivi mobili, è possibile usare una delle librerie di autenticazione Microsoft (MSAL). Queste librerie sono disponibili a livello generale o in un'anteprima supportata dalla produzione, quindi è possibile usarle in modo sicuro nelle applicazioni di produzione. Per altre informazioni sui termini e condizioni dell'anteprima e sulle librerie disponibili, vedere le informazioni di riferimento sulle librerie di autenticazione.
  • Per le piattaforme non coperte dalle librerie Microsoft, è possibile eseguire l'integrazione con l'endpoint Microsoft Identity Platform inviando e ricevendo direttamente messaggi di protocollo nel codice dell'applicazione. I protocolli OpenID Connect e OAuth sono documentati in modo esplicito per facilitare l'integrazione.
  • Infine, è possibile usare librerie OpenID Connect e OAuth open source per l'integrazione con l'endpoint Microsoft Identity Platform. L'endpoint Microsoft Identity Platform deve essere compatibile con molte librerie di protocolli open source senza modifiche. La disponibilità di questi tipi di librerie varia in base a linguaggio e piattaforma. Nei siti Web di OpenID Connect e OAuth 2.0 è disponibile un elenco delle implementazioni più diffuse. Per altre informazioni, vedere Microsoft Identity Platform e librerie di autenticazione e l'elenco di librerie client e esempi open source testati con l'endpoint Microsoft Identity Platform.
  • Per riferimento, l'endpoint per l'endpoint .well-known Microsoft Identity Platform endpoint comune è https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Sostituire common con l'ID tenant per ottenere i dati specifici del tenant.

Modifiche al protocollo

L'endpoint Microsoft Identity Platform non supporta SAML o WS-Federation. Supporta solo OpenID Connect e OAuth 2.0. Le modifiche degne di nota ai protocolli OAuth 2.0 dall'endpoint v1.0 sono:

  • L'attestazione email viene restituita se un'attestazione facoltativa è configurata o scope=email è stata specificata nella richiesta.
  • Ora il parametro scope è supportato al posto del parametro resource.
  • Molte risposte sono state modificate in modo da renderle più conformi alla specifica OAuth 2.0, ad esempio per ottenere la corretta restituzione di expires_in come valore intero anziché come valore stringa.

Per comprendere meglio l'ambito delle funzionalità del protocollo supportate nell'endpoint Microsoft Identity Platform, vedere Informazioni di riferimento sul protocollo OpenID Connect e OAuth 2.0.

Utilizzo SAML

Se nelle applicazioni Windows è stato usato Active Directory Authentication Library (ADAL), è possibile sfruttare l'autenticazione integrata di Windows, che usa la concessione di asserzione SAML (Security Assertion Markup Language). Con questa concessione, gli utenti di tenant federati Microsoft Entra possono eseguire automaticamente l'autenticazione con l'istanza di Active Directory locale senza immettere le credenziali. Anche se SAML è ancora un protocollo supportato per l'uso con gli utenti aziendali, l'endpoint 2.0 è destinato solo all'uso con le applicazioni OAuth 2.0.

Passaggi successivi

Leggere altre informazioni nella documentazione di Microsoft Identity Platform.