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

Benvenuto! Questa probabilmente non è la pagina che ci si aspettava. Mentre lavoriamo a una correzione, questo collegamento dovrebbe portare all'articolo corretto:

Guida introduttiva: Chiamare un'API Web ASP.NET protetta

Ci scusiamo per l'inconveniente e ringraziamo per la pazienza mentre lavoriamo per risolvere il problema.

In questa guida di avvio rapido si scarica e si esegue un esempio di codice che illustra come proteggere un'API Web ASP.NET limitando l'accesso alle risorse solo agli account autorizzati. L'esempio supporta l'autorizzazione di account Microsoft personali e di account presenti in qualsiasi organizzazione Microsoft Entra.

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

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare gratuitamente un account.
• Visual Studio 2017 o 2019. Scaricare Visual Studio gratuitamente.

Clonare o scaricare l'esempio

È possibile ottenere l'esempio in uno dei due modi seguenti:

• 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)

Registrare l'API Web nelle registrazioni dell'app nel portale di Azure.

1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un amministratore dell'applicazione.

2. Passare a Entra ID>Registrazioni app.

3. Selezionare Nuova registrazione.

4. 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 organizzativa.

6. Selezionare Registra per creare l'applicazione.

7. Nella pagina Panoramica dell'app cercare il valore ID applicazione (client) e quindi registrarlo per usarlo in un secondo momento. Sarà necessario configurare il file di configurazione di Visual Studio per questo progetto, ClientId ovvero nel file TodoListService\Web.config .

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

   1. Per il Nome ambito, inserisci access_as_user.
   2. Per Chi può fornire il consenso, verificare che l'opzione Admins and users (Amministratori e utenti ) sia selezionata.
   3. Nella casella Nome visualizzato consenso amministratore inserire Access TodoListService as a user.
   4. Nella casella Descrizione del consenso amministratore 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 State, mantieni Abilitato.

9. Selezionare Aggiungi ambito.

Configurare il progetto di servizio

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

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

2. Sostituire il valore del ida:ClientId parametro con il valore ID client (ID applicazione) dell'applicazione registrata nel portale Registrazioni app .

Aggiungere il nuovo ambito al file app.config

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

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

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

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 se si vuole che gli utenti accedano con un account Microsoft personale.

Registrare l'app

Per registrare l'app TodoListClient, seguire questi passaggi:

1. Accedi al portale di Registrazioni app della Microsoft Identity Platform per sviluppatori.

2. Selezionare Nuova registrazione.

3. Quando si apre la pagina Registra un'applicazione , immettere le informazioni di registrazione dell'applicazione:

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

   Nota

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

   • common: Puoi accedere usando un account aziendale o dell'istituto di istruzione o un account Microsoft personale (perché hai selezionato 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 Microsoft personale.

4. 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 https://login.microsoftonline.com/common/oauth2/nativeclient casella di controllo.
   4. Seleziona Configura.

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

   1. Selezionare il pulsante Aggiungi un'autorizzazione .
   2. Selezionare la scheda API personali .
   3. Nell'elenco delle API selezionare AppModelv2-NativeClient-DotNet-TodoListService API o il nome immesso per l'API Web.
   4. Selezionare la casella di controllo access_as_user autorizzazione 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 dell'applicazione al file app.config.

1. Nel portale Registrazioni app, nella pagina Panoramica, copiare il valore dell'ID applicazione (client).

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

Eseguire i progetti

Avviare entrambi i progetti. Se si usa 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 aiutarti ad accedere all'API Web di TodoListService e a modificare l'elenco Attività, è necessario anche 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 preautorizzando 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 , in Applicazioni client autorizzate selezionare Aggiungi un'applicazione client.
3. Nella casella ID client incollare l'ID applicazione dell'app TodoListClient.
4. Nella sezione Ambiti autorizzati selezionare l'ambito per l'API api://<Application ID>/access_as_user Web.
5. Selezionare Aggiungi applicazione.

Eseguire il progetto

1. Premere F5 per eseguire il progetto. Si aprirà 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 oppure un account aziendale o dell'istituto di istruzione.

Facoltativo: Limitare l'accesso a specifici 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, usare una delle opzioni seguenti:

Opzione 1: Limitare l'accesso a una singola organizzazione (singolo tenant)

È possibile limitare l'accesso all'applicazione ai soli account utente inclusi in un singolo tenant di Microsoft Entra, inclusi gli account guest di tale tenant. Questo scenario è comune per le applicazioni line-of-business.

1. Aprire il file App_Start\Startup.Auth e quindi modificare il valore dell'endpoint dei metadati passato a OpenIdConnectSecurityTokenProvider su https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration. È anche possibile usare il nome del tenant, ad esempio contoso.onmicrosoft.com.
2. Nello stesso file impostare la proprietà ValidIssuer in TokenValidationParameters su https://sts.windows.net/{Tenant ID}/ e l'argomento ValidateIssuer su true.

Opzione 2: usare un metodo personalizzato per convalidare le autorità di certificazione

È possibile implementare un metodo personalizzato per convalidare gli emittenti usando il parametro IssuerValidator. Per altre informazioni su questo parametro, vedere Classe TokenValidationParameters.

Assistenza e supporto

Per assistenza, per segnalare un problema o per informazioni sulle opzioni di supporto, vedere Guida e supporto per gli sviluppatori.

Passaggi successivi

Per saperne di più, costruisci un'API web ASP.NET Core protetta nella seguente serie di esercitazioni:

Esercitazione per l'API Web protetta