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

• Visual Studio 2022. Scaricare Visual Studio gratuitamente.

• Visual Studio Code

1. 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. Per Nome ambito, inserire access_as_user.
   2. Per Utenti che possono fornire il consenso assicurarsi che sia selezionata l'opzione Amministratori e utenti.
   3. Nella casella Nome visualizzato per il consenso dell'amministratore immettere Access TodoListService as a user.
   4. Nella casella di 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 Stato lasciare Abilitato.

2. Seleziona Aggiungi ambito.

Aggiungere autorizzazioni delegate (ambiti di applicazione)

Un'API deve pubblicare almeno un ambito, detto anche autorizzazione delegata, affinché le app client ottengano correttamente un token di accesso per un utente. Per pubblicare un ambito, seguire questa procedura:

1. Nella pagina Registrazioni app selezionare l'applicazione API creata (ciam-ToDoList-api) per aprire la relativa pagina Panoramica.

2. In Gestisci, seleziona Esporre un'API.

3. Nella parte superiore della pagina, accanto a URI ID applicazione, selezionare il collegamento Aggiungi per generare un URI univoco per questa app.

4. Accettare l'URI dell'ID applicazione proposto, ad esempio api://{clientId}e selezionare Salva. Quando l'applicazione Web richiede un token di accesso per l'API Web, aggiunge l'URI come prefisso per ogni ambito definito per l'API.

5. In Ambiti definiti da questa APIselezionare Aggiungi un ambito.

6. Immettere i valori seguenti che definiscono un accesso in lettura all'API, quindi selezionare Aggiungi ambito per salvare le modifiche:

   Proprietà	Valore
   Nome dell'ambito	ToDoList.Read
   Chi può fornire il consenso	Solo per amministratori
   Nome visualizzato per il consenso dell'amministratore	Leggi la lista delle cose da fare degli utenti utilizzando 'TodoListApi'
   Descrizione del consenso dell'amministratore	Consentire all'app di leggere l'elenco ToDo dell'utente utilizzando l'API TodoListApi.
   stato	abilitato

7. Selezionare di nuovo Aggiungi un ambito e immettere i valori seguenti che definiscono un ambito di accesso in lettura e scrittura all'API. Seleziona Aggiungi ambito per salvare le modifiche.

   Proprietà	Valore
   Nome dell'ambito	ToDoList.ReadWrite
   Chi può fornire il consenso	Solo per amministratori
   Nome visualizzato per il consenso dell'amministratore	Leggere e scrivere le liste ToDo degli utenti usando l'API 'ToDoListApi'
   Descrizione del consenso dell'amministratore	Consentire all'app di usare "ToDoListApi" per leggere e scrivere la lista delle cose da fare dell'utente
   stato	abilitato

Scopri di più su il principio del privilegio minimo quando si pubblicano le autorizzazioni per un'API Web.

Aggiungere le autorizzazioni dell'applicazione (ruoli dell'app)

Un'API deve pubblicare almeno un ruolo dell'applicazione, chiamato anche autorizzazione dell'applicazione , affinché le app client ottengano un token di accesso come tali. Le autorizzazioni dell'applicazione sono il tipo di autorizzazioni che le API devono pubblicare quando vogliono consentire alle applicazioni client di eseguire correttamente l'autenticazione come se fossero loro stesse, senza che sia necessario il login degli utenti. Per pubblicare un'autorizzazione dell'applicazione, seguire questa procedura:

1. Nella pagina Registrazioni app, selezionare l'applicazione creata, ad esempio ciam-ToDoList-api, per aprire la relativa pagina Panoramica.

2. In Gestisci selezionare Ruoli app.

3. Selezionare Crea un ruolo app, quindi immettere i valori seguenti e selezionare Applica per salvare le modifiche:

   Proprietà	Valore
   Nome visualizzato	ToDoList.Read.All
   Tipi di membri consentiti	Applicazioni
   Valore	ToDoList.Read.All
   Descrizione	Consentire all'app di leggere l’elenco di attività di ogni utente tramite "ToDoListApi"
   Vuoi abilitare questo ruolo dell'app?	Mantieni selezionato

4. Selezionare di nuovo Crea un ruolo app, immettere i valori seguenti per il secondo ruolo dell'app, quindi selezionare Applica per salvare le modifiche:

   Proprietà	Valore
   Nome visualizzato	ToDoList.ReadWrite.All
   Tipi di membri consentiti	Applicazioni
   Valore	ToDoList.ReadWrite.All
   Descrizione	Consentire all'app di leggere e scrivere le liste ToDo di tutti gli utenti utilizzando l'API "ToDoListApi"
   Vuoi abilitare questo ruolo dell'app?	Mantieni selezionato

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

• Scaricarlo come file ZIP.

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

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

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.

Aggiungere 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 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}.

Registrare l'app Web (TodoListClient)

Registrare l'app TodoListClient nelle registrazioni dell'app nell'interfaccia di amministrazione di Microsoft Entra e quindi configurare 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 Microsoft Entra admin center come almeno un amministratore di applicazioni cloud.

2. Passare aRegistrazioni appEntra ID> 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.

   Annotazioni

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

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 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. 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. Nel portale Registrazioni app, nella pagina Panoramica, copiare il valore dell'Identificativo dell'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.

1. Nell'IDE aprire la cartella del progetto ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI contenente l'esempio.

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

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Trovare i valori seguenti:

   • 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 il valore ID directory (tenant) che era stato registrato in precedenza dalla pagina Panoramica dell'applicazione registrata.
   • Instance - Specifica la directory da cui Microsoft Authentication Library (MSAL) può richiedere i token. Sostituire Enter_the_Authority_URL_Here con uno dei valori seguenti a seconda dello scenario:
     • Per i tenant del personale, utilizzare https://login.microsoftonline.com/ come istanza.
     • Per i tenant esterni, aggiungere un URL di autorità sotto forma di https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

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. 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 come utente della stessa directory.

   Se si accede per la prima volta, potrebbe essere richiesto 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-autorizza 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 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 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.

Esegui il tuo progetto

1. Premere F5 per eseguire il progetto. L'app TodoListClient si apre.
2. In alto a destra selezionare Accedi e quindi accedere usando un account Microsoft personale, come 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, qualsiasi account personale, come outlook.com o live.com, oppure qualsiasi account aziendale o dell'istituto di istruzione di un'organizzazione che abbia eseguito l'integrazione con Microsoft Entra ID può richiedere i token e accedere all'API Web.

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

1. Esegui il seguente comando dalla directory radice del tuo progetto di API Web per avviare l'applicazione.

   dotnet run
   

2. Se tutto funziona correttamente, il terminale visualizza un output simile al seguente:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Registrare il numero di porta nell'URL https://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 -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   La risposta prevista è 401 Non autorizzata.