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

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.

Chi può accedere

• L'endpoint v1.0 consente solo agli account aziendali e dell'istituto di istruzione di accedere all'applicazione (Azure AD)
• L'endpoint della piattaforma di identità Microsoft consente agli account aziendali e scolastici di Microsoft Entra ID e agli account Microsoft personali (MSA), come hotmail.com, outlook.com e msn.com, di accedere.
• Entrambi gli endpoint accettano anche gli accessi degli utenti ospiti di una directory di Microsoft Entra, sia per le applicazioni configurate come tenant singolo, sia per le applicazioni multi-tenant configurate per puntare all'endpoint specifico del tenant (https://login.microsoftonline.com/{TenantId_or_Name}).

L'endpoint di Microsoft Identity Platform consente di scrivere app che accettano accessi da account Microsoft personali e account aziendali e dell'istituto di istruzione. In questo modo puoi scrivere l'app completamente indipendente dall'account. Ad esempio, se l'app chiama Microsoft Graph, alcune funzionalità e dati aggiuntivi saranno disponibili per gli account aziendali, ad esempio i siti di SharePoint o i dati della directory. Tuttavia, per molte azioni, ad esempio la lettura della posta di un utente, lo stesso codice può accedere alla posta elettronica sia per gli account personali che aziendali e dell'istituto di istruzione.

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

Consenso incrementale e dinamico

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

Le autorizzazioni impostate direttamente nella registrazione dell'applicazione sono statiche. 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ò portare a un lungo elenco di autorizzazioni che scoraggia gli utenti finali dall'approvare l'accesso dell'app al primo accesso.

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

Con l'endpoint di Microsoft Identity Platform, è possibile ignorare le autorizzazioni statiche definite nelle informazioni di registrazione dell'app nel portale di Azure e richiedere le autorizzazioni in modo incrementale, il che significa richiedere un set minimo di autorizzazioni prima e aumentare nel tempo man mano che il cliente usa funzionalità aggiuntive dell'app. A tale scopo, è possibile specificare gli ambiti necessari per l'app in qualsiasi momento includendo i nuovi ambiti nel scope parametro quando si richiede un token di accesso, senza la necessità di pre-definirli nelle informazioni di registrazione dell'applicazione. Se l'utente non ha ancora acconsentito ai nuovi ambiti aggiunti alla richiesta, verrà richiesto di fornire il consenso solo alle nuove autorizzazioni. Per altre informazioni, vedere autorizzazioni, consenso e ambiti.

Consentire a un'app di richiedere le autorizzazioni in modo dinamico tramite il scope parametro offre agli sviluppatori il controllo completo sull'esperienza dell'utente. È anche possibile caricare in anticipo l'esperienza di consenso e richiedere tutte le autorizzazioni in una richiesta di autorizzazione iniziale. Se l'app richiede un numero elevato di autorizzazioni, è possibile raccogliere tali autorizzazioni dall'utente in modo incrementale quando provano a usare determinate funzionalità dell'app nel corso del tempo.

Il consenso amministratore eseguito per conto di un'organizzazione richiede comunque le autorizzazioni statiche registrate per l'app, pertanto è necessario impostare tali autorizzazioni per le app nel portale di registrazione delle app se è necessario un amministratore per fornire il consenso per conto dell'intera organizzazione. Questo riduce i cicli richiesti dall'amministratore dell'organizzazione per configurare l'applicazione.

Ambiti, non risorse

Per le app che usano l'endpoint v1.0, un'app può comportarsi come risorsa o come destinatario di token. Una risorsa può definire diversi ambiti o oAuth2Permissions che riconosce, consentendo alle app client di richiedere token da tale risorsa per un determinato set di ambiti. Si consideri l'API Microsoft Graph come esempio di una risorsa:

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

Questo vale per l'endpoint di Microsoft Identity Platform. Un'app può comunque comportarsi come risorsa, definire gli ambiti ed essere identificata da un URI. Le app client possono comunque richiedere l'accesso a tali ambiti. Tuttavia, il modo in cui un client richiede tali autorizzazioni è stato modificato.

Per l'endpoint v1.0, una richiesta di autorizzazione OAuth 2.0 ad Azure AD potrebbe avere un aspetto simile al seguente:

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

In questo caso, il parametro risorsa indica quale risorsa l'app client sta richiedendo per l'autorizzazione. Azure AD ha calcolato le autorizzazioni richieste dall'app in base alla configurazione statica nel portale di Azure e i token rilasciati di conseguenza.

Per le applicazioni che usano l'endpoint di Microsoft Identity Platform, la stessa richiesta di autorizzazione OAuth 2.0 è simile alla 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
...

In questo caso, il parametro di ambito indica quale risorsa e autorizzazioni l'app richiede l'autorizzazione. La risorsa desiderata è ancora presente nella richiesta, che viene incluso 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 si allinea più strettamente alle procedure di settore comuni. Consente anche alle app di eseguire il consenso incrementale , richiedendo autorizzazioni solo quando l'applicazione li richiede anziché in anticipo.

Scopi noti

Accesso offline

Le app che usano l'endpoint di Microsoft Identity Platform possono richiedere l'uso di una nuova autorizzazione nota per le app, ovvero 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 quando l'utente potrebbe non usare attivamente l'app. L'ambito offline_access verrà visualizzato all'utente nelle finestre di dialogo di consenso come Accesso ai dati in qualsiasi momento, a cui 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 sono di lunga durata e possono essere scambiati per i nuovi token di accesso OAuth 2.0 per periodi di accesso estesi.

Se l'app non richiede l'ambito offline_access , non riceverà token di aggiornamento. Ciò significa che quando si riscatta un codice di autorizzazione nel flusso del codice di autorizzazione OAuth 2.0, si riceverà solo un token di accesso dall'endpoint /token . Tale token di accesso rimane valido per un breve periodo di tempo (in genere un'ora), ma alla fine scadrà. A quel punto, l'app dovrà reindirizzare l'utente all'endpoint /authorize per recuperare un nuovo codice di autorizzazione. Durante questo reindirizzamento, l'utente potrebbe o meno dover immettere di nuovo le credenziali o riconfermarsi alle autorizzazioni, a seconda del tipo di app.

Per altre informazioni su OAuth 2.0, refresh_tokense access_tokens, vedere le informazioni di riferimento sul protocollo di Microsoft Identity Platform.

OpenID, profilo e posta elettronica

Storicamente, il flusso di accesso di OpenID Connect più semplice con Microsoft Identity Platform fornirà molte informazioni sull'utente nel id_token risultante. Le attestazioni in un id_token possono includere il nome dell'utente, il nome utente preferito, l'indirizzo di posta elettronica, l'ID oggetto e altro ancora.

Le informazioni a cui l'ambito openid consente l'accesso all'app sono ora limitate. L'ambito openid consentirà all'app di accedere all'utente e di ricevere un identificatore specifico dell'app per l'utente. Se vuoi ottenere dati personali sull'utente nella tua app, l'app 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 principale dell'utente tramite l'attestazione email nel 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 utente, il nome utente preferito, l'ID oggetto e così via, nel id_token.

Questi ambiti consentono di codificare l'app in modo minimo, in modo da poter chiedere all'utente solo il set di informazioni necessarie per l'app. Per altre informazioni su questi ambiti, vedere le informazioni di riferimento sull'ambito di Microsoft Identity Platform.

Attestazioni di token

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

Limitazioni

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

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

Ecco una raccomandazione semplificata per gli sviluppatori:

• Se si vuole o è necessario supportare gli account Microsoft personali nell'applicazione o si sta scrivendo una nuova applicazione, usare Microsoft Identity Platform. Prima di procedere, assicurarsi di comprendere le limitazioni descritte in questo articolo.
• Se si esegue la migrazione o si aggiorna un'applicazione che si basa su SAML, non è possibile usare Microsoft Identity Platform. Fare invece riferimento alla guida di Azure AD v1.0.

L'endpoint di Microsoft Identity Platform si evolverà per eliminare le restrizioni elencate qui, in modo da poter usare solo l'endpoint di 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. Controlla nuovamente per rivalutare i tuoi requisiti rispetto alle funzionalità della piattaforma di identità Microsoft.

Restrizioni relative alle registrazioni delle app

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

Le registrazioni delle app che supportano gli account aziendali e dell'istituto di istruzione e gli account personali presentano le avvertenze seguenti:

• Sono consentiti solo due segreti dell'app per OGNI ID applicazione.
• Un'applicazione non registrata in un tenant può essere gestita solo dall'account che lo ha registrato. Non può essere condivisa con altri sviluppatori. Questo è il caso per la maggior parte delle app registrate usando un account Microsoft personale nel portale di registrazione 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.
• Esistono diverse restrizioni sul formato dell'URL di reindirizzamento consentito. Per altre informazioni sull'URL di reindirizzamento, vedere la sezione successiva.

Restrizioni sugli URL di reindirizzamento

Per le informazioni più up-to-date 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 Registrazioni app.

Restrizioni per librerie e SDK

Attualmente, il supporto della libreria per l'endpoint di Microsoft Identity Platform è limitato. Se si vuole usare l'endpoint di 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. Questi includono il middleware OWIN OpenID Connect per ASP.NET e il plug-in Passport Node.js. Per esempi di codice che usano il middleware Microsoft, vedere la sezione Introduzione a 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 è sicuro usarle nelle applicazioni di produzione. Per altre informazioni sulle 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 di Microsoft Identity Platform inviando e ricevendo 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 di Microsoft Identity Platform. L'endpoint di 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 al linguaggio e alla piattaforma. I siti Web OpenID Connect e OAuth 2.0 mantengono un elenco delle implementazioni più diffuse. Per altre informazioni, vedere Microsoft Identity Platform e librerie di autenticazione e l'elenco di librerie client open source ed esempi testati con l'endpoint di Microsoft Identity Platform.
• Per riferimento, l'endpoint comune della piattaforma Microsoft Identity è .well-known. Sostituire common con l'ID tenant per ottenere dati specifici per il tenant.

Modifiche al protocollo

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

• La dichiarazione email viene restituita se è configurata un'attestazione facoltativa o lo scope=email è stato specificato nella richiesta.
• Il scope parametro è ora supportato al posto del resource parametro .
• Molte risposte sono state modificate per renderle più conformi alla specifica OAuth 2.0, ad esempio, restituendo expires_in correttamente come int invece di una stringa.

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

Utilizzo SAML

Se è stata usata Active Directory Authentication Library (ADAL) nelle applicazioni Windows, è possibile che sia stata sfruttata l'autenticazione integrata di Windows, che usa la concessione di asserzione SAML (Security Assertion Markup Language). Con questa concessione, gli utenti dei tenant federati di 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 è solo per l'uso con le applicazioni OAuth 2.0.

Passaggi successivi

Per altre informazioni, vedere la documentazione di Microsoft Identity Platform.