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

si applica a: locatari del personale locatari esterni (learn more)

In questa guida introduttiva si usa un'app Web di esempio per illustrare come proteggere un'API Web ASP.NET usando Microsoft Identity Platform. L'esempio usa di Microsoft Authentication Library (MSAL) per gestire l'autenticazione.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Crea un account gratuitamente.
• Visual Studio 2022. Scaricare Visual Studio gratuitamente.

Registrare un'applicazione API Web

Per completare la registrazione, specificare un nome dell'applicazione e specificare i tipi di account supportati. Dopo la registrazione, la pagina Panoramica dell'applicazione visualizza gli identificatori necessari nel codice sorgente dell'applicazione.

1. Accedere all'interfaccia di amministrazione di Microsoft Entra almeno un Application Developer.

2. Se si ha accesso a più tenant, utilizzare l'icona impostazioni nel menu in alto per passare al tenant nel quale si desidera registrare l'applicazione, dal menu Directory + sottoscrizioni.

3. Vai a Identity>Applications>Registrazioni app.

4. Selezionare Nuova registrazione.

5. Immettere un Nome per l'applicazione, ad esempio NewWebAPI1.

6. Per Tipi di account supportati, selezionare solo gli account in questa directory organizzativa. Per informazioni sui diversi tipi di account, selezionare l'opzione 'Aiutami a scegliere.

7. Selezionare Registra.

   

8. Al termine della registrazione, viene visualizzato riquadro Panoramica dell'applicazione. Registrare l'ID Directory (tenant) e l'ID Applicazione (client) da usare nel codice sorgente dell'applicazione.

   

Nota

I tipi di account supportati possono essere modificati facendo riferimento a Modificare gli account supportati da un'applicazione.

Esporre un'API

Dopo aver registrato l'API, è possibile configurarne l'autorizzazione definendo gli ambiti esposti dall'API alle applicazioni client. Le applicazioni client richiedono l'autorizzazione per eseguire operazioni passando un token di accesso insieme alle relative richieste all'API Web protetta. L'API Web esegue quindi l'operazione richiesta solo se il token di accesso ricevuto contiene gli ambiti necessari.

ASP.NET

1. In Gestisciselezionare Esporre un'API>Aggiungere un ambito. Accettare l'URI dell'ID applicazione proposto (api://{clientId}) selezionando Salva e continuae quindi immettere le informazioni seguenti:

   1. Per il nome dell'ambito , inserisci access_as_user.
   2. Per Chi può fornire il consenso, assicurarsi che l'opzione amministratori e utenti sia selezionata.
   3. Nella casella nome visualizzato del consenso amministratore, immettere 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 del consenso utente, immettere Access TodoListService as a user.
   6. Nella casella di Descrizione del consenso utente immettere Accesses the TodoListService web API as a user.
   7. Per lo Stato, mantenere Abilitato.

2. Selezionare Aggiungi ambito.

ASP.NET core

1. In Gestione, seleziona Esporre un'API > Aggiungi un ambito. Accettare l'URI dell'ID applicazione proposto(api://{clientId}) selezionando Salva e continua. Il {clientId} è il valore registrato dalla pagina Panoramica . Immettere quindi le informazioni seguenti:

   1. Per Nome ambito, immettere Forecast.Read.
   2. Per Chi può fornire il consenso, assicurarsi che l'opzione amministratori e utenti sia selezionata.
   3. Nella casella nome visualizzato del consenso dell'amministratore, immettere Read forecast data.
   4. Nella casella descrizione del consenso amministrativo, immettere Allows the application to read weather forecast data.
   5. Nella casella Nome visualizzato del consenso utente, immettere Read forecast data.
   6. Nella casella Descrizione del consenso utente, inserire Allows the application to read weather forecast data.
   7. Assicurarsi che lo stato sia impostato su Abilitato.

2. Selezionare Aggiungi ambito. Se l'ambito è stato immesso correttamente, viene elencato nel riquadro Esporre un'API.

   

Clonare o scaricare l'applicazione di esempio

Per ottenere l'applicazione di esempio, è possibile clonarla da GitHub o scaricarla come file .zip.

ASP.NET

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à.

ASP.NET core

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

• Scarica il file .zip. Estrarlo in un percorso di file in cui la lunghezza del nome è inferiore a 260 caratteri.

Configurare l'applicazione di esempio

Configurare l'esempio di codice in modo che corrisponda all'API Web registrata.

ASP.NET

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

2. Sostituire il valore del Enter_the_Application_Id_here con il valore ID client (ID applicazione) dell'applicazione registrata nel portale di Registrazioni app sia nella proprietà ClientID sia in quella Audience.

Aggiungi il nuovo ambito al file app.config

Per aggiungere il nuovo ambito al file di app.config TodoListClient, 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 parametro TodoListServiceScope, sostituendo la stringa {Enter the Application ID of your TodoListService from the app registration portal}.

Nota

Assicurarsi che l'ID applicazione usi il formato seguente: 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)

Registra l'app TodoListClient in Registrazione delle applicazioni nel portale di Azure, e poi configura il codice nel progetto TodoListClient. Se il client e il server sono considerati la stessa applicazione, è 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. Accedi al centro di amministrazione di Microsoft Entra come almeno un amministratore di applicazioni cloud .

2. Passare a Identity>Applicazioni>Registrazioni app e selezionare Nuova registrazione.

3. Selezionare Nuova registrazione.

4. 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 di 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é è stato 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 personale Microsoft.

5. Nella pagina panoramica dell'app, selezionare Autenticazionee quindi completare questi passaggi per aggiungere una piattaforma:

   1. In Configurazioni della piattaformaselezionare 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. Selezionare Configura.

6. Selezionare autorizzazioni APIe quindi completare questi passaggi per aggiungere le autorizzazioni:

   1. Selezionare il pulsante Aggiungi un'autorizzazione.
   2. Selezionare la scheda Le mie API.
   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 dell'autorizzazione access_as_user se non è già selezionata. Usare la casella di ricerca, se necessario.
   5. Selezionare il pulsante Aggiungi autorizzazioni.

Configurare il progetto

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

1. Nel portale di 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 parametro ida:ClientId.

ASP.NET core

1. Nell'IDE aprire la cartella del progetto ms-identity-docs-code-dotnet/web-api, contenente l'esempio.

2. Aprire appsettings.json file contenente il frammento di codice seguente:

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter the tenant ID obtained from the Microsoft Entra admin center",
       "ClientId": "Enter the client ID obtained from the Microsoft Entra admin center",
       "Scopes": "Forecast.Read"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

   Trova i seguenti key:

   • ClientId: identificatore dell'applicazione, detto anche client. Sostituire il testo value tra virgolette con ID applicazione (client) registrato in precedenza dalla pagina Panoramica dell'applicazione registrata.
   • TenantId: identificatore del tenant in cui è registrata l'applicazione. Sostituire il testo value tra virgolette con id directory (tenant) valore registrato in precedenza dalla pagina Panoramica dell'applicazione registrata.

Eseguire l'applicazione di esempio

ASP.NET

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

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

2. Nella 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 Accedie quindi accedere con le stesse credenziali usate per registrare l'applicazione o accedere come utente nella stessa directory.

   Se si accede per la prima volta, potrebbe essere richiesto di fornire il consenso all'API Web TodoListService.

   Per accedere all'API Web TodoListService e modificare l'elenco di to-do, l'accesso richiede anche un token di accesso all'ambito access_as_user.

Pre-autorizza 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 dall'app client all'elenco di applicazioni pre-autorizzate per l'API Web. Aggiungendo un client pre-autorizzato, si consente agli utenti di accedere all'API Web senza dover fornire il consenso.

1. Nel portale di 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 Web api://<Application ID>/access_as_user.
5. Selezionare Aggiungi applicazione.

Esegui il tuo progetto

1. Premere F5 per eseguire il progetto. Verrà aperta l'app TodoListClient.
2. In alto a destra selezionare Accedie 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 determinati utenti

Per impostazione predefinita, tutti gli account personali, ad esempio outlook.com o account di live.com, o 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 proprietà TenantId nel file appsettings.json.

ASP.NET Core

1. Eseguire il comando seguente per avviare l'app:

   dotnet run
   

2. Viene visualizzato un output simile all'esempio seguente:

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: http://localhost:{port}
   ...
   

   Registrare il numero di porta nell'URL di http://localhost:{port}.

3. Per verificare che l'endpoint sia protetto, aggiornare l'URL di base nel comando cURL seguente in modo che corrisponda a quello ricevuto nel passaggio precedente e quindi eseguire il comando:

   curl -X GET https://localhost:5001/weatherforecast -ki
   

   La risposta prevista è 401 Non autorizzata con output simile al seguente:

   user@host:~$ curl -X GET https://localhost:5001/weatherforecast -ki
   HTTP/2 401
   date: Fri, 23 Sep 2023 23:34:24 GMT
   server: Kestrel
   www-authenticate: Bearer
   content-length: 0
   

Passaggi successivi

ASP.NET

Per ulteriori informazioni, scopri come creare un'API Web ASP.NET Core protetta nella seguente serie di esercitazioni:

Esercitazione API Web protetta

ASP.NET Core

Passare all'articolo successivo per informazioni su come chiamare l'API Web protetta usando cURL.

Guida : Chiamare un'API Web ASP.NET Core con cURL