Esercitazione: Creare un daemon multi-tenant che usa Microsoft Identity Platform

  • Articolo

In questa esercitazione verrà scaricata ed eseguita un'app Web daemon ASP.NET che illustra l'uso della concessione di credenziali client OAuth 2.0 per ottenere un token di accesso per chiamare l'API Microsoft Graph.

Contenuto dell'esercitazione:

  • Integrazione di un'app daemon con Microsoft Identity Platform
  • Concedere le autorizzazioni dell'applicazione direttamente all'app da un amministratore
  • Reperimento di un token di accesso per chiamare l'API Microsoft Graph
  • Chiamata all'API Microsoft Graph

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Prerequisiti

  • Visual Studio 2017 o 2019.
  • Un tenant di Microsoft Entra. Per altre informazioni, vedere Come ottenere un tenant di Microsoft Entra.
  • Uno o più account utente nel tenant. Questo esempio non funziona con un account Microsoft. Se è stato eseguito l'accesso con un account Microsoft e non è mai stato creato un account utente nella directory, eseguire questa operazione ora.

Scenario

L'app viene creata come applicazione MVC ASP.NET. Usa il middleware OWIN OpenID Connect per concedere l'accesso agli utenti.

Il componente "daemon" in questo esempio è un controller API, SyncController.cs. Quando viene chiamato il controller, esegue il pull di un elenco di utenti nel tenant di Microsoft Entra del cliente da Microsoft Graph. SyncController.cs viene attivato da una chiamata AJAX nell'applicazione Web. Usa Microsoft Authentication Library (MSAL) per .NET per acquisire un token di accesso per Microsoft Graph.

Poiché l'app è multi-tenant per i clienti aziendali Microsoft, deve fornire un modo per "iscriversi" o "connettere" l'applicazione ai dati aziendali. Durante il flusso di connessione, un Amministrazione istrator globale concede prima le autorizzazioni dell'applicazione direttamente all'app in modo che possa accedere ai dati aziendali in modo non interattivo, senza la presenza di un utente connesso. La maggior parte della logica di questo esempio mostra come ottenere questo flusso di connessione usando l'endpoint del consenso dell'amministratore di Identity Platform.

Diagram shows UserSync App with three local items connecting to Azure, with Start dot Auth acquiring a token interactively to connect to Microsoft Entra ID, AccountController getting admin consent to connect to Microsoft Entra ID, and SyncController reading user to connect to Microsoft Graph.

Per altre informazioni sui concetti usati in questo esempio, vedere la documentazione relativa al protocollo delle credenziali client per Identity Platform.

Clonare o scaricare questo repository

Dalla shell o dalla riga di comando immettere questo comando:

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git

In alternativa scaricare l'esempio in un file ZIP.

Registrare l'applicazione

L'esempio contiene un unico progetto. Per registrare l'applicazione con il tenant di Microsoft Entra, è possibile:

  • Seguire la procedura descritta in Scegliere il tenant e configurare l'esempio per l'uso del tenant.
  • Usare gli script di PowerShell che:
    • Crea automaticamente le applicazioni Microsoft Entra e gli oggetti correlati (password, autorizzazioni, dipendenze) automaticamente.
    • Modificare i file di configurazione dei progetti di Visual Studio.

Se si vuole usare questa automazione:

  1. In Windows eseguire PowerShell e passare alla radice della directory clonata.

  2. Eseguire questo comando:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Eseguire lo script per creare l'applicazione Microsoft Entra e configurare di conseguenza il codice dell'applicazione di esempio:

    .\AppCreationScripts\Configure.ps1

    Altre modalità di esecuzione degli script sono descritte in Script di creazione app.

  4. Aprire la soluzione in Visual Studio e selezionare Avvia per eseguire il codice.

Se non si vuole usare l'automazione, seguire i passaggi delle sezioni seguenti.

Scegliere il tenant

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale da cui si inizia.

  1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno uno sviluppatore di applicazioni.

  2. Se si ha accesso a più tenant, usare l'icona Impostazioni nel menu in alto per passare al tenant in cui si vuole registrare l'applicazione dal menu Directory e sottoscrizioni.

  3. Passare a Applicazioni> di identità>Registrazioni app.

  4. Seleziona Nuova registrazione.

  5. In Nome immettere un nome per l'applicazione, ad esempio dotnet-web-daemon-v2. Tale nome, che potrebbe essere visualizzato dagli utenti dell'app, può essere modificato in un secondo momento.

  6. Nella sezione Tipi di account supportati selezionare Account in qualsiasi directory dell'organizzazione.

  7. Nella sezione URI di reindirizzamento (facoltativo) selezionare Web nella casella combinata e immettere https://localhost:44316/ e https://localhost:44316/Account/GrantPermissions come URI di reindirizzamento.

    Se sono presenti più URI di reindirizzamento, è necessario aggiungerli dalla scheda Autenticazione dopo che l'app sarà stata creata correttamente.

  8. Selezionare Registra per creare l'applicazione.

  9. Nella pagina Panoramica dell'app trovare il valore del campo ID applicazione (client) e prenderne nota per usarlo in seguito. Sarà necessario per configurare il file di configurazione di Visual Studio per questo progetto.

  10. In Gestisci selezionare Autenticazione.

  11. Impostare l'URL di disconnessione del canale anteriore su https://localhost:44316/Account/EndSession.

  12. Nella sezione Concessione implicita e flussi ibridi selezionare Token di accesso e token ID. Per questo esempio è necessario abilitare il flusso di concessione implicita per consentire all'utente di accedere e chiamare un'API.

  13. Seleziona Salva.

  14. In Gestisci, selezionare Certificati e segreti.

  15. Nella sezione Segreti client seleziona Nuovo segreto client.

  16. Immettere una descrizione della chiave, ad esempio segreto dell'app.

  17. Selezionare una durata della chiave scegliendo Tra 1 anno, Tra 2 annio Non scade mai.

  18. Selezionare Aggiungi. Prendere nota del valore della chiave e conservarlo in un luogo sicuro. Questa chiave sarà necessaria in seguito per configurare il progetto in Visual Studio.

  19. In Gestisci selezionare Autorizzazioni API>Aggiungi un'autorizzazione.

  20. Nella sezione API Microsoft più usate selezionare Microsoft Graph.

  21. Nella sezione Autorizzazioni dell'applicazione verificare che siano selezionate le autorizzazioni corrette: User.Read.All.

  22. Selezionare Aggiungi autorizzazioni.

Configurare l'esempio per l'uso del tenant

Nei passaggi seguenti ClientID corrisponde a "ID applicazione" o AppId.

Aprire la soluzione in Visual Studio per configurare i progetti.

Configurare il progetto client

Se sono stati usati gli script di installazione, saranno state applicate automaticamente le modifiche seguenti.

  1. Aprire il file UserSync\Web.Config.
  2. Trovare la chiave dell'app ida:ClientId. Sostituire il valore esistente con l'ID applicazione dell'applicazione dotnet-web-daemon-v2 registrata in precedenza.
  3. Trovare la chiave dell'app ida:ClientSecret. Sostituire il valore esistente con la chiave salvata durante la creazione dell'app dotnet-web-daemon-v2 .

Eseguire l'esempio

Pulire la soluzione, ricompilare la soluzione, eseguire l'applicazione UserSync e quindi accedere come amministratore nel tenant di Microsoft Entra. Se non si ha un tenant di Microsoft Entra per i test, è possibile seguire queste istruzioni per ottenerlo.

Quando si accede, l'app chiede prima di tutto l'autorizzazione per consentire l'accesso e per leggere il profilo utente. Con questo consenso si conferma all'app di essere un utente aziendale.

User consent

L'app tenta quindi di sincronizzare un elenco di utenti dal tenant di Microsoft Entra tramite Microsoft Graph. Se il tentativo non riesce, chiede all'amministratore del tenant di connettere il tenant all'app.

L'app chiede quindi l'autorizzazione per leggere l'elenco di utenti nel tenant.

Admin consent

Dopo aver concesso l'autorizzazione, si viene disconnessi dall'app. La disconnessione assicura che tutti i token di accesso esistenti per Microsoft Graph vengano rimossi dalla cache dei token. Quando si esegue di nuovo l'accesso, il nuovo token ottenuto avrà le autorizzazioni necessarie per effettuare chiamate a Microsoft Graph.

Quando si concede l'autorizzazione, l'app può eseguire query per trovare gli utenti in qualsiasi punto. Per verificarlo, selezionare il pulsante Sincronizza utenti e aggiornare l'elenco di utenti. Provare ad aggiungere o a rimuovere un utente e quindi a risincronizzare l'elenco. Si noti però che l'app sincronizza solo la prima pagina di utenti.

Informazioni sul codice

Il codice pertinente per questo esempio si trova nei file seguenti:

  • App_Start\Startup.Auth.cs, Controllers\AccountController.cs: accesso iniziale. In particolare, le azioni sul controller hanno un attributo Authorize, che forza l'accesso dell'utente. L'applicazione usa il flusso del codice di autorizzazione per far accedere l'utente.
  • Controllers\SyncController.cs: sincronizzazione dell'elenco di utenti nell'archivio locale in memoria.
  • Controllers\UserController.cs: visualizzazione dell'elenco di utenti dall'archivio locale in memoria.
  • Controllers\AccountController.cs: acquisizione delle autorizzazioni dall'amministratore del tenant tramite l'endpoint di consenso amministratore.

Ricreare l'app di esempio

  1. In Visual Studio creare un nuovo progetto di applicazione Web ASP.NET (.NET Framework) in Visual C#.
  2. Nella schermata successiva scegliere il modello di progetto MVC. Aggiungere anche la cartella e i riferimenti principali per API Web, perché in seguito verrà aggiunto un controller API Web. Lasciare la modalità di autenticazione selezionata dal progetto come predefinita: Nessuna autenticazione.
  3. Selezionare il progetto nella finestra Esplora soluzioni e premere F4.
  4. Nelle proprietà del progetto impostare SSL abilitato su True. Prendere nota del valore di URL SSL. Sarà necessario quando si configura la registrazione di questa applicazione nel portale di Azure.
  5. Aggiungere i pacchetti NuGet middleware OWIN seguenti ASP.NET:
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security.Cookies
    • Microsoft.Owin.Host.SystemWeb
    • Microsoft.IdentityModel.Protocol.Extensions
    • Microsoft.Owin.Security.OpenIdConnect
    • Microsoft.Identity.Client
  6. Nella cartella App_Start:
    1. Creare una classe denominata Startup.Auth.cs.
    2. Rimuovere .App_Start dal nome dello spazio dei nomi.
    3. Sostituire il codice della classe Startup con il codice dello stesso file dell'app di esempio. Assicurarsi di inserire l'intera definizione della classe. La definizione cambia da public class Startup a public partial class Startup.
  7. In Startup.Auth.cs risolvere i riferimenti mancanti aggiungendo istruzioni using come suggerito da IntelliSense di Visual Studio.
  8. Fare clic con il pulsante destro del mouse sul progetto, scegliere Aggiungi e quindi selezionare Classe.
  9. Nella casella di ricerca immettere OWIN. Viene visualizzata l'opzione Classe di avvio di OWIN. Selezionarla e assegnare alla classe il nome Startup.cs.
  10. In Startup.cs sostituire il codice della classe Startup con il codice dello stesso file dell'app di esempio. Anche in questo caso, la definizione cambia da public class Startup a public partial class Startup.
  11. Nella cartella Models aggiungere una nuova classe denominata MsGraphUser.cs. Sostituire l'implementazione con il contenuto del file con lo stesso nome dell'esempio.
  12. Aggiungere una nuova istanza di Controller MVC 5 - Vuoto denominata AccountController. Sostituire l'implementazione con il contenuto del file con lo stesso nome dell'esempio.
  13. Aggiungere una nuova istanza di Controller MVC 5 - Vuoto denominata UserController. Sostituire l'implementazione con il contenuto del file con lo stesso nome dell'esempio.
  14. Aggiungere una nuova istanza di Controller Web API 2 - Vuoto denominata SyncController. Sostituire l'implementazione con il contenuto del file con lo stesso nome dell'esempio.
  15. Per l'interfaccia utente, nella cartella Views\Account aggiungere tre istanze di visualizzazioni vuote (senza modello) denominate GrantPermissions, Index e UserMismatch. Aggiungerne una denominata Index nella cartella Views\User. Sostituire l'implementazione con il contenuto del file con lo stesso nome dell'esempio.
  16. Aggiornare Shared_Layout.cshtml e Home\Index.cshtml per collegare correttamente le varie visualizzazioni.

Distribuire l'esempio in Azure

Questo progetto include i progetti di app Web e API Web. Per distribuirli nei siti Web di Azure, seguire questi passaggi per ognuno:

  1. Creare un sito Web di Azure.
  2. Pubblicare l'app Web e le API Web nel sito Web.
  3. Aggiornare i client per chiamare il sito Web invece di IIS Express.

Creare e pubblicare dotnet-web-daemon-v2 in un sito Web di Azure

  1. Accedere al portale di Azure.
  2. Nell'angolo in alto a sinistra della schermata selezionare Crea una risorsa.
  3. Selezionare Web>App Web e quindi assegnare un nome al sito Web, ad esempio dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Selezionare le informazioni per la sottoscrizione, il gruppo di risorse e il piano e la località del servizio app. Per Sistema operativo scegliere Windows e per Pubblica scegliere Codice.
  5. Selezionare Crea e attendere che venga creato il servizio app.
  6. Quando si riceve la notifica Distribuzione riuscita, selezionare Vai alla risorsa per passare al servizio app appena creato.
  7. Dopo aver creato il sito Web, individuarlo nel Dashboard e selezionarlo per aprire la schermata Panoramica del servizio app.
  8. Nella scheda Panoramica del servizio app scaricare il profilo di pubblicazione selezionando il collegamento Recupera profilo di pubblicazione, quindi salvarlo. È possibile usare altri meccanismi di distribuzione, ad esempio dal controllo del codice sorgente.
  9. Passare a Visual Studio e quindi:
    1. Passare al progetto dotnet-web-daemon-v2.
    2. Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e quindi scegliere Pubblica.
    3. Selezionare Importa profilo sulla barra inferiore e importare il profilo di pubblicazione scaricato in precedenza.
  10. Seleziona Configura.
  11. Nella scheda Connessione ion aggiornare l'URL di destinazione in modo che usi "https". Ad esempio, usare https://dotnet-web-daemon-v2-contoso.azurewebsites.net. Seleziona Avanti.
  12. Nella scheda Impostazioni verificare che l'opzione Abilita autenticazione a livello aziendale sia deselezionata.
  13. Seleziona Salva. Selezionare Pubblica nella schermata principale.

Visual Studio pubblicherà il progetto e aprirà automaticamente un browser all'URL corrispondente. Se viene visualizzata la pagina Web predefinita del progetto, la pubblicazione ha avuto esito positivo.

Aggiornare la registrazione dell'applicazione tenant Microsoft Entra per dotnet-web-daemon-v2

  1. Tornare all'interfaccia di amministrazione di Microsoft Entra e quindi selezionare l'applicazione dotnet-web-daemon-v2 in Registrazioni app.
  2. Nella pagina Autenticazione per l'applicazione aggiornare i campi URL di disconnessione del canale anteriore con l'indirizzo del servizio. Ad esempio, usare https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession.
  3. Nel menu Personalizzazione aggiornare il valore di URL pagina iniziale impostandolo sull'indirizzo del servizio. Ad esempio, usare https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Fare clic su Salva per salvare la configurazione.
  5. Aggiungere lo stesso URL nell'elenco di valori del menu Autenticazione>URI di reindirizzamento. Se sono presenti più URL di reindirizzamento, assicurarsi che vi sia una nuova voce che usa l'URI del servizio app per ognuno di essi.

Pulire le risorse

Quando non è più necessario, eliminare l'oggetto app creato nel passaggio Registrare l'applicazione. Per rimuovere l'applicazione, seguire le istruzioni riportate in Rimuovere un'applicazione creata dall'utente o dalla relativa organizzazione.

Come ottenere assistenza

Usare Domande e risposte Microsoft per ottenere supporto dalla community. Porre prima domande su Domande e risposte Microsoft ed esaminare i problemi esistenti per verificare se qualcuno ha posto la domanda in precedenza. Assicurarsi che le domande o i commenti siano contrassegnati con azure-ad-adal-deprecation, azure-ad-msale dotnet-standard".

Se nell'esempio si trova un bug, segnalarlo nella pagina di problemi di GitHub.

Se in MSAL.NET si trova un bug, segnalarlo nella pagina di problemi di GitHub MSAL.NET.

Per inviare suggerimenti, visitare la pagina User Voice.

Passaggi successivi

Altre informazioni sulla creazione di app daemon che usano Microsoft Identity Platform per accedere ad API Web protette:

Scenario: applicazione daemon che chiama le API Web