Guida introduttiva: Chiamare un'API Web ASP.NET protetta da Microsoft Identity Platform

  • Articolo

La guida introduttiva seguente usa un esempio di codice che illustra come proteggere un'API Web di ASP.NET limitando l'accesso alle risorse solo agli account autorizzati. L'esempio supporta l'autorizzazione di account e account Microsoft personali in qualsiasi organizzazione Microsoft Entra.

L'articolo usa anche un'app Windows Presentation Foundation (WPF) per illustrare come richiedere un token di accesso per accedere a un'API Web.

Prerequisiti

Clonare o scaricare l'esempio

L'esempio di codice può essere ottenuto in due modi:

  • Clonarlo dalla shell o dalla riga di comando:

    git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

  • Scaricarlo come file ZIP.

Suggerimento

Per evitare errori causati da limitazioni di lunghezza del percorso in Windows, è consigliabile estrarre l'archivio o clonare il repository in una directory vicina alla radice dell'unità.

Registrare l'API Web (TodoListService)

Suggerimento

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

Registrare l'API Web in Registrazioni app nel portale di Azure.

  1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione cloud Amministrazione istrator.

  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 e selezionare Nuova registrazione.

  4. In Nome immettere un nome per l'applicazione, ad esempio AppModelv2-NativeClient-DotNet-TodoListService. Tale nome, che potrebbe essere visualizzato dagli utenti dell'app, può essere modificato in un secondo momento.

  5. Per Tipi di account supportati selezionare Account in qualsiasi directory dell'organizzazione.

  6. Selezionare Registra per creare l'applicazione.

  7. Nella pagina Panoramica dell'app cercare il valore del campo ID applicazione (client) e prenderne nota per un uso futuro. Sarà necessario configurare il file di configurazione di Visual Studio per questo progetto, ClientId ovvero nel file TodoListService\appsettings.json .

  8. In Gestisci selezionare Esporre un'API>Aggiungi un ambito. Accettare l'URI dell'ID applicazione proposto (api://{clientId}) selezionando Salva e continua, quindi immettere le informazioni seguenti:

    1. In Nome ambito immettere access_as_user.
    2. Per Utenti che possono fornire il consenso assicurarsi che sia selezionata l'opzione Amministratori e utenti.
    3. Nella casella Amministrazione nome visualizzato del consenso immettere Access TodoListService as a user.
    4. Nella casella Amministrazione descrizione del consenso immettere Accesses the TodoListService web API as a user.
    5. Nella casella Nome visualizzato consenso utente immettere Access TodoListService as a user.
    6. Nella casella Descrizione consenso utente immettere Accesses the TodoListService web API as a user.
    7. Per Stato mantenere Abilitato.

  9. Seleziona Aggiungi ambito.

Configurare il progetto di servizio

Configurare il progetto di servizio in modo che corrisponda all'API Web registrata.

  1. Aprire la soluzione in Visual Studio e quindi aprire il file appsettings.json nella radice del progetto TodoListService.

  2. Sostituire il valore di Enter_the_Application_Id_here in base al valore ID client (ID applicazione) dell'applicazione registrata nel portale di Registrazioni app sia nelle proprietà che in ClientIDAudience .

Aggiungere il nuovo ambito al file app.config

Per aggiungere il nuovo ambito al file TodoListClient app.config , seguire questa procedura:

  1. Nella cartella radice del progetto TodoListClient aprire il file app.config.

  2. Incollare l'ID applicazione dall'applicazione registrata per il progetto TodoListService nel TodoListServiceScope parametro , sostituendo la {Enter the Application ID of your TodoListService from the app registration portal} stringa.

Nota

Assicurarsi che l'ID applicazione sia nel formato api://{TodoListService-Application-ID}/access_as_user, dove{TodoListService-Application-ID} è il GUID che rappresenta l'ID applicazione per l'app TodoListService.

Registrare l'app Web (TodoListClient)

Registrare l'app TodoListClient in Registrazioni app nel portale di Azure e quindi configurare il codice nel progetto TodoListClient. Se il client e il server vengono considerati la stessa applicazione è anche possibile riutilizzare l'applicazione registrata nel passaggio 2. Usare la stessa applicazione per consentire agli utenti di accedere con un account Microsoft personale.

Registrare l'app

Per registrare l'app TodoListClient, seguire questa procedura:

  1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione cloud Amministrazione istrator.

  2. Passare a Applicazioni> di identità>Registrazioni app e selezionare Nuova registrazione.

  3. Seleziona Nuova registrazione.

  4. Nella pagina Registra un'applicazione visualizzata immettere le informazioni di registrazione dell'applicazione:

    1. Nella sezione Nome immettere un nome significativo che verrà visualizzato agli utenti dell'app, ad esempio NativeClient-DotNet-TodoListClient.
    2. Per Tipi di account supportati selezionare Account in qualsiasi directory dell'organizzazione.
    3. Selezionare Registra per creare l'applicazione.

    Nota

    Nel file app.config del progetto TodoListClient il valore predefinito di ida:Tenant è impostato su common. I valori possibili sono:

    • common: è possibile accedere usando un account aziendale o dell'istituto di istruzione o un account Microsoft personale (perché sono stati selezionati account in qualsiasi directory organizzativa in un passaggio precedente).
    • organizations: è possibile accedere usando un account aziendale o dell'istituto di istruzione.
    • consumers: è possibile accedere solo usando un account personale Microsoft.

  5. Nella pagina Panoramica dell'app selezionare Autenticazione e quindi completare questi passaggi per aggiungere una piattaforma:

    1. In Configurazioni della piattaforma selezionare il pulsante Aggiungi una piattaforma.
    2. Per Applicazioni per dispositivi mobili e desktop selezionare Applicazioni per dispositivi mobili e desktop.
    3. Per URI di reindirizzamento selezionare la casella di controllo https://login.microsoftonline.com/common/oauth2/nativeclient.
    4. Seleziona Configura.

  6. Selezionare Autorizzazioni API e quindi completare questi passaggi per aggiungere autorizzazioni:

    1. Selezionare il pulsante Aggiungi un'autorizzazione.
    2. Selezionare la scheda Le mie API.
    3. Nell'elenco di API selezionare l'API AppModelv2-NativeClient-DotNet-TodoListService oppure il nome immesso per l'API Web.
    4. Selezionare la casella di controllo dell'autorizzazione access_as_user se non è già selezionata. Se necessario, usare la casella di ricerca.
    5. Selezionare il pulsante Aggiungi autorizzazioni.

Configurare il progetto

Configurare il progetto TodoListClient aggiungendo l'ID applicazione al file app.config .

  1. Nella pagina Panoramica del portale Registrazioni app copiare il valore di ID applicazione (client).

  2. Nella cartella radice del progetto TodoListClient aprire il file app.config e quindi incollare il valore di ID applicazione nel parametro ida:ClientId.

Eseguire i progetti

Avviare entrambi i progetti. Per gli utenti di Visual Studio;

  1. Fare clic con il pulsante destro del mouse sulla soluzione Visual Studio e scegliere Proprietà

  2. In Proprietà comuni selezionare Progetto di avvio e quindi Più progetti di avvio.

  3. Per entrambi i progetti scegliere Avvia come azione

  4. Assicurarsi che il servizio TodoListService venga avviato per primo spostandolo alla prima posizione nell'elenco, usando la freccia su.

Accedere per eseguire il progetto TodoListClient.

  1. Premere F5 per avviare i progetti. Viene visualizzata la pagina del servizio, nonché l'applicazione desktop.

  2. In TodoListClient, in alto a destra, selezionare Accedi e quindi accedere con le stesse credenziali usate per registrare l'applicazione oppure accedere come utente nella stessa directory.

    La prima volta che si accede è possibile che venga chiesto di fornire il consenso all'API Web TodoListService.

    Per facilitare l'accesso all'API Web TodoListService e manipolare l'elenco To-Do, viene anche richiesto un token di accesso per l'ambito access_as_user.

Pre-autorizzare l'applicazione client

È possibile consentire agli utenti di altre directory di accedere all'API Web preautorendo l'applicazione client per accedere all'API Web. A tale scopo, aggiungere l'ID applicazione dell'app client all'elenco di applicazioni pre-autorizzate per l'API Web. Aggiungendo un client pre-autorizzato, si autorizza l'accesso degli utenti all'API Web senza la necessità di fornire il consenso.

  1. Nel portale Registrazioni app aprire le proprietà dell'app TodoListService.
  2. Nella sezione Esporre un'API selezionare Aggiungi applicazione client in Applicazioni client autorizzate.
  3. Nella casella ID client incollare l'ID applicazione dell'app TodoListClient.
  4. Nella sezione Ambiti autorizzati selezionare l'ambito per l'API Web api://<Application ID>/access_as_user.
  5. Seleziona Aggiungi applicazione.

Eseguire il progetto

  1. Premere F5 per eseguire il progetto. Verrà aperta l'app TodoListClient.
  2. In alto a destra selezionare Accedi e quindi accedere usando un account Microsoft personale, ad esempio un account live.com o hotmail.com o un account aziendale o dell'istituto di istruzione.

Facoltativo: limitare l'accesso a determinati utenti

Per impostazione predefinita, tutti gli account personali, ad esempio outlook.com o live.com account aziendali o dell'istituto di istruzione di organizzazioni integrate con Microsoft Entra ID possono richiedere token e accedere all'API Web.

Per specificare chi può accedere all'applicazione, modificando la TenantId proprietà nel file appsettings.json .

Assistenza e supporto

Se è necessaria assistenza, si vuole segnalare un problema o si vogliono ottenere informazioni sulle opzioni di supporto, vedere Assistenza e supporto per gli sviluppatori.

Passaggi successivi

Per altre informazioni, vedere creare un'API Web ASP.NET Core protetta nella serie di esercitazioni seguente:

Esercitazione per l'API Web protetta