Chiamare un'API Web ASP.NET Core con 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). 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). Seguendo l'esempio dell'Esercitazione: implementare un endpoint protetto nell'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 di applicazioni 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.
- 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 di applicazioni cloud
- Completamento della serie di esercitazioni:
- Scaricare e installare Insonnia.
Registrare un'applicazione
Microsoft Identity Platform richiede la registrazione dell'applicazione prima di poter 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. I destinatari dell'accesso specificano i tipi di account utente autorizzati ad accedere a una determinata applicazione.
Registrare l'API Web
Suggerimento
La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.
Seguire questa procedura per creare la registrazione API Web:
Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Sviluppatore di applicazioni.
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.
Passare a Identità>Applicazioni>Registrazioni app.
Seleziona Nuova registrazione.
Immettere un nome per l'applicazione, ad esempio NewWebAPI1.
Per Tipi di account supportati selezionare Account solo in questa directory dell'organizzazione. Per informazioni sui diversi tipi di account selezionare l'opzione Suggerimenti per la scelta.
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.
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.
In Gestisci selezionare Esporre un'API > Aggiungi un ambito . Accettare l'URI ID applicazione
(api://{clientId})
proposto selezionando Salva e continua.{clientId}
è il valore registrato dalla pagina Panoramica. Immettere quindi le informazioni seguenti:- Per Nome ambito, immettere
Forecast.Read
. - Per Utenti che possono fornire il consenso assicurarsi che sia selezionata l'opzione Amministratori e utenti.
- Nella casella Nome visualizzato del consenso amministratore immettere
Read forecast data
. - Nella casella di Descrizione del consenso amministratore immettere
Allows the application to read weather forecast data
. - Nella casella Nome visualizzato del consenso utente immettere
Read forecast data
. - Nella casella di Descrizione del consenso utente immettere
Allows the application to read weather forecast data
. - Assicurarsi che lo Stato sia impostato su Abilitato.
- Per Nome ambito, immettere
Seleziona Aggiungi ambito. Se l'ambito è stato immesso correttamente, viene visualizzato nel riquadro Esporre 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 una registrazione dell'app Web:
- Selezionare Home per tornare alla pagina iniziale. Passare a Identità>Applicazioni>Registrazioni app.
- Seleziona Nuova registrazione.
- Immettere un nome per l'applicazione, ad esempio web-app-calls-web-api.
- Per Tipi di account supportati selezionare Account solo in questa directory dell'organizzazione. Per informazioni sui diversi tipi di account selezionare l'opzione Suggerimenti per la scelta.
- In URI di reindirizzamento (facoltativo), selezionare Web, quindi immettere
http://localhost
nella casella URL. - Selezionare Registra.
- Accedere all'interfaccia di amministrazione di Microsoft Entra almeno come Sviluppatore di applicazioni.
- 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.
- Passare a Identità>Applicazioni>Registrazioni app.
- Seleziona Nuova registrazione.
- Immettere un nome per l'applicazione, ad esempio web-app-calls-web-api.
- Per Tipi di account supportati selezionare Account solo in questa directory dell'organizzazione. Per informazioni sui diversi tipi di account selezionare l'opzione Suggerimenti per la scelta.
- In URI di reindirizzamento (facoltativo), selezionare Web, quindi immettere
http://localhost
nella casella URL. - 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 identificarsi e a volte viene denominato password dell'applicazione. L'applicazione Web usa il segreto client per dimostrare la propria identità al momento della richiesta dei token.
Seguire questa procedura per configurare un segreto client:
Dal pannello Panoramica, in Gestisci, selezionare Certificati e segreti>Segreti client>Nuovo segreto client.
Aggiungere una descrizione per il segreto clienti, ad esempio Il mio segreto client.
Selezionare una scadenza per il segreto o specificare una durata personalizzata.
- La durata del 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.
Selezionare Aggiungi.
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 accesso basato su autorizzazioni alle relative risorse in base agli ambiti trovati nel token di accesso.
Seguire questa procedura per configurare le autorizzazioni del client per l'API Web:
- Nel riquadro Panoramica dell'applicazione, in Gestisci selezionare Autorizzazioni>API Aggiungere un'API di autorizzazione>usate dall'organizzazione.
- Selezionare NewWebAPI1 o l'API a cui si desidera aggiungere le autorizzazioni.
- 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'applicazione client deve disporre per conto dell'utente che ha effettuato l'accesso.
- Selezionare Aggiungi autorizzazioni per completare il processo.
Dopo aver aggiunto le autorizzazioni per l'API, le autorizzazioni selezionate verranno visualizzate in Autorizzazioni configurate.
È possibile che sia presente anche l'autorizzazione User.Read per l'API di 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:
Clonare il repository ms-identity-docs-code-dotnet.
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
Passare a
ms-identity-docs-code-dotnet/web-api
e aprireappsettings.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.
Eseguire il comando seguente per avviare l'app:
dotnet run
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:
Passare all'API Web creata in Esercitazione: creare un progetto ASP.NET Core e configurare l'API, ad esempio NewWebAPILocal e aprire la cartella.
Aprire una nuova finestra del terminale e passare alla cartella in cui si trova il progetto di API Web.
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:
Avviare l'applicazione Insonnia .
Selezionare Nuova richiesta HTTP oppure premere CTRL+N per creare una nuova richiesta HTTP.
Nel modale Nuova richiesta selezionare un metodo GET dall'elenco a discesa.
Per l'URL della richiesta immettere l'URL dell'endpoint esposto dall'API Web,
https://localhost:{port}/weatherforecast
.Dal menu a discesa Autenticazione selezionare OAuth 2.0. Verrà visualizzato il modulo OAuth 2.0 .
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
- 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.
- 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 ulteriori informazioni sul flusso del codice di autorizzazione OAuth 2.0 e sui tipi di applicazione, consultare: