Chiamare un'API Web ASP.NET Core con insonnia

  • Articolo

Questo articolo illustra come chiamare un'API Web ASP.NET Core protetta usando Insonnia. L'insonnia è un'applicazione che consente di inviare richieste HTTP a un'API Web per testare i criteri di autorizzazione e controllo di accesso (autenticazione). In questo articolo viene registrata un'app Web e un'API Web in un tenant. L'app Web viene usata per ottenere un token di accesso generato da Microsoft Identity Platform. Successivamente, si usa il token per effettuare una chiamata autorizzata all'API Web usando Insonnia.

Questo articolo illustra come chiamare un'API Web ASP.NET Core protetta usando Insonnia. L'insonnia è un'applicazione che consente di inviare richieste HTTP a un'API Web per testare i criteri di autorizzazione e controllo di accesso (autenticazione). Come illustrato nell'esercitazione : Implementare un endpoint protetto per l'API, in cui è stata creata un'API protetta, è necessario registrare un'applicazione Web con Microsoft Identity Platform per generare un token di accesso. Successivamente, si usa il token per effettuare una chiamata autorizzata all'API usando Insonnia.

Prerequisiti

  • Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
  • Questo account di Azure deve disporre delle autorizzazioni per gestire le applicazioni. Uno dei seguenti ruoli di Microsoft Entra include le autorizzazioni necessarie:
    • Amministratore di applicazioni
    • Sviluppatore di applicazioni
    • Amministratore applicazione cloud
  • Scaricare e installare Insonnia. Si usa Insonnia per ottenere un token di accesso per le richieste API.
  • Requisito minimo di .NET 8.0 SDK.

Registrare un'applicazione

Microsoft Identity Platform richiede la registrazione dell'applicazione prima di fornire servizi di gestione delle identità e degli accessi. La registrazione dell'applicazione consente di specificare il nome e il tipo dell'applicazione e il gruppo di destinatari dell'accesso. Il gruppo di destinatari dell'accesso specifica i tipi di account utente autorizzati ad accedere a una determinata applicazione.

Registrare l'API Web

Suggerimento

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

Per creare la registrazione dell'API Web, seguire questa procedura:

  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come 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 desidera registrare l’applicazione nel menu Directory e sottoscrizioni.

  3. Passare a Identità>Applicazioni>Registrazioni app.

  4. Seleziona Nuova registrazione.

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

  6. Per Tipi di account supportati selezionare Account solo in questa directory dell'organizzazione. Per informazioni sui diversi tipi di account, selezionare l'opzione ?

  7. Selezionare Registra.

    Screenshot che mostra come immettere un nome e selezionare il tipo di account.

  8. Al termine della registrazione, è possibile visualizzare il riquadro Panoramica dell'applicazione. Registrare l'ID directory (tenant) e l'ID applicazione (client) da usare nei passaggi successivi.

    Screenshot che mostra i valori dell'identificatore nella pagina di panoramica.

Nota

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

Esporre l'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 è valido.

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

    1. In Nome ambito immettere Forecast.Read.
    2. Per Utenti che possono fornire il consenso assicurarsi che sia selezionata l'opzione Amministratori e utenti.
    3. Nella casella Nome visualizzato consenso amministratore immettere Read forecast data.
    4. Nella casella Descrizione del consenso amministratore immettere Allows the application to read weather forecast data.
    5. Nella casella Nome visualizzato consenso utente immettere Read forecast data.
    6. Nella casella Descrizione consenso utente immettere Allows the application to read weather forecast data.
    7. Assicurarsi che Lo stato sia impostato su Abilitato.

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

    Screenshot che mostra i valori dei campi quando si aggiunge l'ambito a un'API.

Registrare l'app Web

Non è sufficiente avere un'API Web, è necessaria anche un'app Web per ottenere un token di accesso per accedere all'API Web.

Seguire questa procedura per creare la registrazione dell'app Web:

  1. Selezionare Home per tornare alla home page. Passare a Identità>Applicazioni>Registrazioni app.
  2. Seleziona Nuova registrazione.
  3. Immettere un nome per l'applicazione, ad esempio web-app-calls-web-api.
  4. Per Tipi di account supportati selezionare Account solo in questa directory dell'organizzazione. Per informazioni sui diversi tipi di account, selezionare l'opzione ?
  5. In URI di reindirizzamento (facoltativo) selezionare Web e quindi immettere http://localhost nella casella di testo URL.
  6. Selezionare Registra.
  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come 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 desidera registrare l’applicazione nel menu Directory e sottoscrizioni.
  3. Passare a Identità>Applicazioni>Registrazioni app.
  4. Seleziona Nuova registrazione.
  5. Immettere un nome per l'applicazione, ad esempio web-app-calls-web-api.
  6. Per Tipi di account supportati selezionare Account solo in questa directory dell'organizzazione. Per informazioni sui diversi tipi di account, selezionare l'opzione ?
  7. In URI di reindirizzamento (facoltativo) selezionare Web e quindi immettere http://localhost nella casella di testo URL.
  8. Selezionare Registra.

Al termine della registrazione, è possibile visualizzare il riquadro Panoramica dell'applicazione. Registrare l'ID directory (tenant) e l'ID applicazione (client) da usare nei passaggi successivi.

Aggiungere un segreto client

Un segreto client è un valore stringa che l'app può usare per l'identità stessa e a volte viene definita password dell'applicazione. L'app Web usa il segreto client per dimostrare la propria identità quando richiede token.

Seguire questa procedura per configurare un segreto client:

  1. Nel riquadro Panoramica, in Gestisci, selezionare Certificati e segreti>Segreti>client Nuovo segreto client.

  2. Aggiungere una descrizione per il segreto client, ad esempio Il segreto client.

  3. Selezionare una scadenza per il segreto o specificare una durata personalizzata.

    • La durata di un segreto client è limitata a due anni (24 mesi) o meno. Non è possibile specificare una durata personalizzata di più di 24 mesi.
    • Microsoft consiglia di impostare un valore di scadenza inferiore a 12 mesi.

  4. Selezionare Aggiungi.

  5. Assicurarsi di registrare il valore del segreto client. Questo valore del segreto non viene mai più visualizzato dopo aver lasciato questa pagina.

Per altre informazioni su come archiviare in modo sicuro il segreto client, vedere Procedure consigliate per la gestione dei segreti in Key Vault.

Aggiungere autorizzazioni per accedere all'API Web

Specificando gli ambiti di un'API Web, l'app Web può ottenere un token di accesso contenente gli ambiti forniti da Microsoft Identity Platform. All'interno del codice, l'API Web può quindi fornire l'accesso basato sulle autorizzazioni alle risorse in base agli ambiti trovati nel token di accesso.

Seguire questa procedura per configurare le autorizzazioni del client per l'API Web:

  1. Nel riquadro Panoramica dell'applicazione, in Gestisci selezionare Autorizzazioni>API Aggiungere un'API di autorizzazione>usate dall'organizzazione.
  2. Selezionare NewWebAPI1 o l'API a cui si desidera aggiungere le autorizzazioni.
  3. In Seleziona autorizzazioni selezionare la casella accanto a Forecast.Read. Potrebbe essere necessario espandere l'elenco Autorizzazioni . In questo modo vengono selezionate le autorizzazioni che l'app client deve avere per conto dell'utente connesso.
  4. Selezionare Aggiungi autorizzazioni per completare il processo.

Dopo aver aggiunto queste autorizzazioni all'API, verranno visualizzate le autorizzazioni selezionate in Autorizzazioni configurate.

È anche possibile notare l'autorizzazione User.Read per l'API Microsoft Graph. Questa autorizzazione viene aggiunta automaticamente quando si registra un'app.

Testare l'API Web

Per assicurarsi che l'API sia operativa e pronta per gestire le richieste, seguire questa procedura:

  1. Clonare il repository ms-identity-docs-code-dotnet .

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

  2. Passare a ms-identity-docs-code-dotnet/web-api e aprire appsettings.json, sostituire {APPLICATION_CLIENT_ID} e {DIRECTORY_TENANT_ID} con i valori seguenti:

    • {APPLICATION_CLIENT_ID}è l'ID applicazione API Web (client) nel riquadro Panoramica dell'app.
    • {DIRECTORY_TENANT_ID}è l'ID directory dell'API Web (tenant) nel riquadro Panoramica dell'app.

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

    dotnet run

  4. Verrà visualizzato un output simile al seguente. Registrare il numero di porta nell'URL https://localhost:{port} .

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

Testare l'API Web

Per assicurarsi che l'API sia operativa e pronta per gestire le richieste, seguire questa procedura:

  1. Passare all'API Web creata in Esercitazione: Creare un progetto ASP.NET Core e configurare l'API, ad esempio NewWebAPILocal e aprire la cartella.

  2. Aprire una nuova finestra del terminale e passare alla cartella in cui si trova il progetto API Web.

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

      dotnet run

  3. Verrà visualizzato un output simile al seguente. Registrare il numero di porta nell'URL https://localhost:{port} .

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

Configurare una richiesta autorizzata all'API Web in Insonnia

Per ottenere un token di accesso per le richieste API, seguire questa procedura:

  1. Avviare l'applicazione Insonnia .

  2. Selezionare Nuova richiesta HTTP oppure premere CTRL+N per creare una nuova richiesta HTTP.

  3. Nel modale Nuova richiesta selezionare un metodo GET dall'elenco a discesa.

  4. Per l'URL della richiesta immettere l'URL dell'endpoint esposto dall'API Web, https://localhost:{port}/weatherforecast.

  5. Dal menu a discesa Autenticazione selezionare OAuth 2.0. Verrà visualizzato il modulo OAuth 2.0 .

  6. Immettere i valori seguenti nel modulo OAuth 2.0 :

    Impostazione Valore
    TIPO GRANT Selezionare Codice di autorizzazione
    URL DI AUTORIZZAZIONE https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    Sostituire {tenantId} con l'ID directory (tenant)
    URL TOKEN DI ACCESSO https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
    Sostituire {tenantId} con l'ID directory (tenant)
    CLIENT ID Valore ID applicazione (client) della registrazione dell'app Web
    SEGRETO CLIENT Valore del segreto client della registrazione dell'app Web
    URL DI REINDIRIZZAMENTO Immettere http://localhost, che imposta l'URL DI REINDIRIZZAMENTo sull'URI di reindirizzamento registrato con Microsoft Entra ID.
    Ambito opzioni>avanzate api://{application_client_id}/Forecast.Read
    Passare alla registrazione dell'app Web, in Gestisci selezionare Autorizzazioni API, quindi selezionare Forecast.Read
    Copiare il valore nella casella di testo che contiene il valore Ambito

Ottenere un token di accesso e inviare una richiesta all'API Web

  1. Dopo aver immesso questi valori, selezionare Recupera token alla fine del modulo. Verrà avviata una finestra del browser Insonnia in cui si esegue l'autenticazione con le credenziali utente. Assicurarsi di consentire popup dall'applicazione Insonnia nel browser.
  2. Dopo l'autenticazione, selezionare Invia per inviare la richiesta all'endpoint dell'API Web protetta.

Con un token di accesso valido incluso nella richiesta, la risposta prevista è 200 OK con output simile al seguente:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Contenuto correlato

Per altre informazioni sul flusso del codice di autorizzazione OAuth 2.0 e sui tipi di applicazione, vedere: