Come consentire l'accesso a qualsiasi utente di Azure Active Directory (AD) usando il modello di applicazione multi-tenant

Se si offre un'applicazione Software as a Service a molte organizzazioni, è possibile configurare l'applicazione in modo da consentire accessi da qualsiasi tenant di Azure AD. In Azure AD questa operazione viene definita impostazione dell'applicazione multi-tenant. Gli utenti in qualsiasi tenant Azure AD saranno in grado di accedere all'applicazione dopo il consenso ad usare il loro account con l'applicazione.

Se si dispone di un'applicazione esistente che ha un proprio sistema di account, o supporta altri tipi di accesso da altri provider di cloud, l'aggiunta dell'accesso di Azure AD da un qualsiasi tenant è semplice. Registrare l'app, aggiungere il codice di accesso tramite OAuth2, OpenID Connect o SAML e inserire un pulsante "Accedi con Microsoft" all'applicazione. Fare clic sul pulsante seguente per ottenere altre informazioni sulla personalizzazione dell'applicazione.

Pulsante di accesso

Questo articolo presuppone che l'utente abbia già familiarità con la creazione di un'applicazione single-tenant per Azure AD. In caso contrario, tornare alla home page della Guida per sviluppatori e provare una delle procedure di avvio rapido.

Quattro semplici passaggi consentono di convertire l'applicazione in un'applicazione multi-tenant di Azure AD:

  1. Aggiornare la registrazione dell'applicazione in modo che sia multi-tenant
  2. Aggiornare il codice per l'invio delle richieste all'endpoint /common
  3. Aggiornare il codice per gestire più valori dell'autorità di certificazione
  4. Informarsi sul consenso dell'utente e dell'amministratore e apportare le modifiche appropriate al codice

Esaminiamo in dettaglio ogni passaggio. È anche possibile passare direttamente a questo elenco di esempi multi-tenant.

Aggiornare la registrazione in modo che sia multi-tenant

Per impostazione predefinita, le registrazioni di API o app Web in Azure AD sono single-tenant. È possibile rendere la registrazione multi-tenant individuando l'opzione corrispondente nella pagina delle proprietà della registrazione dell'applicazione nel portale di Azure e impostandola su "Sì".

Si noti anche che, per poter rendere un'applicazione multi-tenant in Azure AD, l'URI dell'ID app dell'applicazione deve essere univoco a livello globale. L'URI dell'ID App è uno dei modi in cui un'applicazione viene identificata nei messaggi di protocollo. Per un'applicazione single-tenant, è sufficiente che l'URI dell'ID App sia univoco all'interno del tenant. Per un'applicazione multi-tenant, è necessario che sia univoco a livello globale in modo da Azure AD possa trovare l'applicazione in tutti i tenant. L'univocità globale viene applicata richiedendo che l'URI dell'ID App abbia un nome host corrispondente a un dominio verificato del tenant di Azure AD. Ad esempio, se il nome del tenant è contoso.onmicrosoft.com, l'URI ID app sarà https://contoso.onmicrosoft.com/myapp. Se il tenant ha un dominio verificato contoso.com, l'URI ID app valido sarà https://contoso.com/myapp. L'impostazione di un'applicazione come multi-tenant avrà esito negativo se l'URI dell'ID App non segue questo modello.

Per impostazione predefinita, le registrazioni client native sono multi-tenant. Non è necessario intraprendere alcuna azione per rendere multi-tenant una registrazione nativa dell'applicazione client.

Aggiornare il codice per l'invio delle richieste all'endpoint /common

In un'applicazione single-tenant le richieste di accesso vengono inviate all'endpoint di accesso del tenant. Ad esempio, per contoso.onmicrosoft.com l'endpoint sarà:

https://login.microsoftonline.com/contoso.onmicrosoft.com

Le richieste inviate all'endpoint del tenant possono eseguire l'accesso degli utenti (o guest) in questo tenant alle applicazioni in questo tenant. Con un'applicazione multi-tenant, l'applicazione non determina in anticipo il tenant di provienienza dell'utente, pertanto non è possibile inviare richieste all'endpoint del tenant. Al contrario, le richieste vengono inviate a un endpoint che esegue il multiplexing tra tutti i tenant di Azure Active Directory:

https://login.microsoftonline.com/common

Quando Azure AD riceve una richiesta sull'endpoint /common, consente l'accesso dell'utente e quindi individua il tenant di provenienza dell'utente. L'endpoint /common funziona con tutti i protocolli di autenticazione supportati da Azure AD: OpenID Connect, OAuth 2.0, SAML 2.0 e WS-Federation.

La risposta di accesso all'applicazione di accesso contiene un token che rappresenta l'utente. Il valore dell'autorità di certificazione nel token indica a un'applicazione il tenant di provenienza dell'utente. Quando l'endpoint /common restituisce una risposta, il valore dell'autorità di certificazione nel token corrisponderà al tenant dell'utente. È importante notare che l'endpoint /common non è un tenant o un'autorità di certificazione, ma è semplicemente un multiplexer. Quando si usa l'endpoint /common, è necessario aggiornare la logica dell'applicazione per la convalida dei token in modo da tenerne conto.

Come indicato in precedenza, le applicazioni multi-tenant devono offrire anche un'esperienza di accesso coerente per gli utenti, adeguandosi alle linee guida di personalizzazione delle applicazioni di Azure AD. Fare clic sul pulsante seguente per ottenere altre informazioni sulla personalizzazione dell'applicazione.

Pulsante di accesso

È ora possibile esaminare in modo più dettagliato l'uso dell'endpoint /common e l'implementazione del codice.

Aggiornare il codice per gestire più valori dell'autorità di certificazione

Le applicazioni Web e le API Web ricevono e convalidano i token da Azure AD.

Nota

Le applicazioni client native richiedono e ricevono i token da Azure AD e li inviano alle API in cui vengono convalidati. Le applicazioni native non convalidano i token e devono gestirli come opachi.

Passiamo ora al modo in cui un'applicazione convalida i token ricevuti da Azure AD. Un'applicazione single-tenant prende in genere un valore dell'endpoint come:

https://login.microsoftonline.com/contoso.onmicrosoft.com

e lo usa per creare un URL di metadati, in questo caso OpenID Connect, come:

https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration

per scaricare due informazioni critiche che vengono usate per convalidare i token: il valore dell'autorità di certificazione e le chiavi di firma del tenant. Ogni tenant di Azure AD ha un valore univoco dell'autorità di certificazione del formato:

https://sts.windows.net/31537af4-6d77-4bb9-a681-d2394888ea26/

dove il valore GUID è la versione sicura di ridenominazione dell'ID tenant del tenant. Se si fa clic sul collegamento dei metadati precedente per contoso.onmicrosoft.com, è possibile visualizzare il valore dell'autorità di certificazione nel documento.

Quando un'applicazione single-tenant convalida un token, controlla la firma del token con le chiavi di firma del documento di metadati. In questo modo è possibile verificare che il valore dell'autorità di certificazione nel token corrisponda a quello che è stato trovato nel documento di metadati.

Poiché l'endpoint /common non corrisponde a un tenant e non è un'autorità di certificazione, il valore dell'autorità di certificazione nei metadati per /common ha un URL basato su modello anziché un valore effettivo:

https://sts.windows.net/{tenantid}/

Un'applicazione multi-tenant non può quindi convalidare i token semplicemente confrontando il valore dell'autorità di certificazione nei metadati con il valore issuer nel token. Un'applicazione multi-tenant richiede una logica per decidere quali valori di autorità di certificazione sono validi, in base alla parte ID del tenant del valore dell'autorità di certificazione.

Se ad esempio un'applicazione multi-tenant consente l'accesso solo da tenant specifici che hanno eseguito l'accesso ai servizi, è necessario verificare il valore dell'autorità di certificazione o il valore di attestazione tid nel token per assicurarsi che sia incluso nel relativo elenco di sottoscrittori. Se un'applicazione multi-tenant gestisce solo persone e non adotta decisioni di accesso basate su tenant, è possibile ignorare il valore dell'autorità di certificazione.

Negli esempi multi-tenant nella sezione Contenuti correlati alla fine di questo articolo la convalida dell'autorità di certificazione è disattivata per consentire l'accesso a qualsiasi tenant di Azure AD.

Esaminiamo l'esperienza utente per gli utenti che accedono ad applicazioni multi-tenant.

Per fare in modo che un utente possa accedere a un'applicazione in Azure AD, l'applicazione deve essere rappresentata nel tenant dell'utente. Ciò consente alle organizzazioni di eseguire operazioni come applicare criteri univoci quando gli utenti dal tenant accedono all'applicazione. Per un'applicazione single-tenant questa registrazione è semplice. È l'azione che viene eseguita quando si registra l'applicazione nel portale di Azure.

Per un'applicazione multi-tenant, la registrazione iniziale per l'applicazione si trova nel tenant di Azure AD usato dallo sviluppatore. Quando un utente di un tenant diverso accede all'applicazione per la prima volta, Azure AD richiede il consenso alle autorizzazioni richieste dall'applicazione. Se fornisce il consenso, viene creata una rappresentazione dell'applicazione denominata entità servizio nel tenant dell'utente ed è possibile procedere con l'accesso. Viene anche creata una delega nella directory che registra il consenso dell'utente all'applicazione. Vedere Oggetti applicazione e oggetti entità servizio per informazioni dettagliate sugli oggetti applicazione ed entità servizio dell'applicazione e su come interagiscono tra loro.

Consenso per l'app a livello singolo

Questa esperienza di consenso è interessata dalle autorizzazioni richieste dall'applicazione. Azure AD supporta due tipi di autorizzazioni, delegate e solo app:

  • Un'autorizzazione delegata concede a un'applicazione la possibilità di agire come utente connesso per un sottoinsieme di operazioni che l'utente può eseguire. Ad esempio, è possibile concedere a un'applicazione l'autorizzazione delegata per la lettura del calendario dell'utente connesso.
  • Un'autorizzazione solo app viene concessa direttamente all'identità dell'applicazione. Ad esempio, è possibile concedere a un'applicazione l'autorizzazione solo app per leggere l'elenco di utenti in un tenant, indipendentemente dall'utente che ha eseguito l'accesso all'applicazione.

Alcune autorizzazioni possono essere concesse da un utente normale, mentre altre richiedono il consenso dell'amministratore tenant.

Le autorizzazioni solo app richiedono il consenso dell'amministratore tenant. Se l'applicazione richiede un'autorizzazione solo per app e un utente tenta di accedere all'applicazione, verrà visualizzato un messaggio di errore che informa che l'utente non è in grado di fornire il consenso.

Alcune autorizzazioni delegate richiedono anche il consenso dell'amministratore tenant. Ad esempio, il writeback in Azure AD come utente connesso richiede il consenso dell'amministratore tenant. Come le autorizzazioni solo app, se un utente comune tenta di accedere a un'applicazione che richiede un'autorizzazione delegata che necessita del consenso dell'amministratore, verrà visualizzato un errore nell'applicazione. La richiesta del consenso di amministratore da parte di un'applicazione è determinata dallo sviluppatore che ha pubblicato la risorsa ed è presente nella documentazione per la risorsa. Collegamenti ad argomenti che descrivono le autorizzazioni disponibili per le API Graph di Azure AD e API Graph di Microsoft sono disponibili nella sezione Contenuti correlati di questo articolo.

Se l'applicazione usa autorizzazioni che richiedono il consenso dell'amministratore, è necessario che sia presente un movimento, ad esempio un pulsante o un collegamento, con cui l'amministratore può avviare l'azione. La richiesta inviata dall'applicazione per questa azione è una richiesta di autorizzazione OAuth2/OpenID Connect standard, ma che include anche il parametro prompt=admin_consent della stringa di query. Dopo che l'amministratore ha fornito il consenso e l'entità servizio è stata creata nel tenant del cliente, le successive richieste di accesso non richiedono il parametro prompt=admin_consent. Poiché l'amministratore ha deciso che le autorizzazioni richieste sono accettabili, a nessun altro utente nel tenant verrà richiesto il consenso da questo punto in poi.

Il parametro prompt=admin_consent può essere usato anche dalle applicazioni che richiedono autorizzazioni che non necessitano del consenso dell'amministratore. Questa operazione viene eseguita quando l'applicazione richiede un'esperienza in cui il tenant amministratore "si iscrive" una volta e a nessun altro utente viene richiesto il consenso da tale punto in poi.

Se un'applicazione richiede l'autorizzazione dell'amministratore, e un amministratore accede ma il parametro prompt=admin_consent non viene inviato, l'amministratore darà correttamente il consenso all'applicazione solo per l'account utente. Gli utenti normali non saranno ancora in grado di eseguire l'accesso e fornire il consenso all'applicazione. Questa condizione è utile se si vuole assegnare all'amministratore tenant la possibilità di esplorare l'applicazione prima di consentire l'accesso ad altri utenti.

Un amministratore tenant può disabilitare la possibilità che gli utenti normali possano il consenso alle applicazioni. Se questa funzionalità è disabilitata, è necessario impostare il consenso dell'amministratore come obbligatorio sempre per l'applicazione nel tenant. Se si vuole testare l'applicazione con il consenso dell'utente normale disabilitato, è possibile trovare l'opzione di configurazione nella sezione di configurazione del tenant di Azure AD del portale di Azure.

Nota

Alcune applicazioni offrono un'esperienza in cui gli utenti normali sono inizialmente in grado di fornire il consenso e successivamente l'applicazione può coinvolgere l'amministratore e richiedere le autorizzazioni che necessitano del consenso dell'amministratore. Non è attualmente possibile eseguire questa operazione con una singola registrazione all'applicazione in Azure AD. L'imminente endpoint Azure AD v2 consente alle applicazioni di richiedere le autorizzazioni in fase di esecuzione, anziché al momento della registrazione abilitando questo scenario. Per altre informazioni, vedere la Guida per gli sviluppatori del modello di app di Azure AD versione 2.

L'applicazione può avere più livelli, ognuno rappresentato dalla propria registrazione in Azure AD. Un esempio è un'applicazione nativa che esegue una chiamata a un'API Web o un'applicazione Web che esegue una chiamata a un'API Web. In entrambi i casi, il client (app nativa o app Web) richiede le autorizzazioni per eseguire la chiamata alla risorsa (API Web). Per fare in modo il client venga autorizzato correttamente nel tenant del cliente, tutte le risorse a cui richiede le autorizzazioni devono esistere già nel tenant del cliente. Se questa condizione non viene soddisfatta, Azure AD restituirà un errore indicante che prima deve essere aggiunta la risorsa.

Più livelli in un tenant singolo

Può trattarsi di un problema se l'applicazione logica è costituita da due o più registrazioni di applicazioni, ad esempio un client e una risorsa separati. Come ottenere prima la risorsa nel tenant del cliente? Azure AD si occupa di questo caso, concedendo al client e alla risorsa l'autorizzazione in un unico passaggio. L'utente visualizza la somma totale delle autorizzazioni richieste dal client e dalla risorsa nella pagina del consenso. Per abilitare questo comportamento, la registrazione dell'applicazione della risorsa deve includere l'ID app del client come knownClientApplications nel manifesto dell'applicazione. ad esempio:

knownClientApplications": ["94da0930-763f-45c7-8d26-04d5938baab2"]

Questa proprietà può essere aggiornata tramite il manifesto dell'applicazione della risorsa. Ciò viene illustrato in un client nativo multilivello che esegue la chiamata all'esempio di API Web nella sezione Contenuti correlati alla fine di questo articolo. Il diagramma seguente fornisce una panoramica del consenso per un'app multilivello registrata in un singolo tenant:

Consenso per l'app client nota multilivello

Più livelli in tenant multipli

Un caso simile si verifica se i diversi livelli di un'applicazione vengono registrati in tenant diversi. Ad esempio, si consideri il caso della creazione di un'applicazione client nativa che esegue la chiamata all'API di Office 365 Exchange Online. Per sviluppare l'applicazione nativa e successivamente eseguire l'applicazione nativa nel tenant del cliente, è necessario che sia presente l'entità servizio Exchange Online. In questo caso lo sviluppatore e il cliente devono acquistare Exchange Online per creare l'entità servizio nei tenant.

Nel caso di un'API creata da un'organizzazione diversa da Microsoft, lo sviluppatore dell'API deve includere un modo che consenta ai clienti di fornire il consenso per l'applicazione nei tenant dei clienti. La progettazione consigliata è affinché lo sviluppatore di una terza parte compili l'API in modo tale che possa fungere anche da client Web per implementare l'iscrizione:

  1. Seguire le sezioni precedenti per verificare che l'API implementi i requisiti del codice/registrazione dell'applicazione multi-tenant
  2. Oltre a esporre gli ambiti/ruoli dell'API, verificare che la registrazione comprenda l'autorizzazione di Azure AD "Accedi e leggi il profilo di un altro utente" (fornita per impostazione predefinita)
  3. Implementare una pagina di iscrizione/accesso nel client Web, seguendo le linee guida del consenso dell'amministratore descritte in precedenza
  4. Quando l'utente acconsente all'applicazione, vengono creati i collegamenti all'entità servizio e alla delega di consenso nel tenant e l'applicazione nativa è in grado di ottenere i token per l'API

Il diagramma seguente fornisce una panoramica del consenso per un'app multilivello registrata in diversi tenant:

Consenso per l'app di terze parti multilivello

Gli utenti e gli amministratori possono revocare il consenso all'applicazione in qualsiasi momento:

  • Gli utenti revocano l'accesso alle singole applicazioni rimuovendole dall'elenco Applicazioni riquadro di accesso.
  • Gli amministratori revocano l'accesso alle applicazioni rimuovendole da Azure AD usando la sezione di gestione di Azure AD del portale di Azure.

Se un amministratore fornisce il consenso a un'applicazione per tutti gli utenti in un tenant, gli utenti non possono revocare l'accesso singolarmente. Solo l'amministratore può revocare l'accesso e soltanto per l'intera applicazione.

Il consenso è supportato in Azure AD tramite i protocolli OAuth, OpenID Connect, WS-Federation e SAML. I protocolli WS-Federation e SAML non supportano il parametro prompt=admin_consent e il consenso dell'amministratore è possibile solo tramite OAuth e OpenID Connect.

Applicazioni multi-tenant e memorizzazione nella cache dei token di accesso

Le applicazioni multi-tenant possono anche ottenere i token di accesso per eseguire chiamate alle API protette da Azure AD. Un errore comune quando si usa Active Directory Authentication Library (ADAL) con un'applicazione multi-tenant è quello di richiedere inizialmente un token per un utente tramite /common, ricevere una risposta e quindi richiedere un token successivo per lo stesso utente usando sempre /common. Poiché la risposta da Azure AD proviene da un tenant, non /common, la libreria ADAL memorizza nella cache il token come proveniente dal tenant. Nella chiamata successiva a /common per ottenere un token di accesso per l'utente non è presente la voce della cache e all'utente viene richiesto di accedere di nuovo. Per evitare questo errore della cache, assicurarsi che le chiamate successive per un utente già connesso vengano eseguite all'endpoint del tenant.

Passaggi successivi

Questo articolo illustra come compilare un'applicazione che consente a un utente di accedere da qualsiasi tenant Azure Active Directory. Dopo aver abilitato l'accesso Single Sign-On tra l'app e Azure Active Directory, è anche possibile aggiornare l'applicazione per accedere alle API esposte dalle risorse di Microsoft, come Office 365. Pertanto, è possibile offrire un'esperienza personalizzata nell'applicazione, ad esempio mostrando informazioni contestuali per gli utenti, ad esempio l'immagine del profilo o il successivo appuntamento nel calendario. Per altre informazioni sulle chiamate API ai servizi di Azure Active Directory e Office 365 come Exchange, SharePoint, OneDrive, OneNote, pianificazione, Excel e altri ancora, visitare: API di Microsoft Graph.

La sezione dei commenti di seguito consente di fornire commenti e suggerimenti utili per migliorare e organizzare i contenuti disponibili.