Condividi tramite

Chiamare un'app API Web ASP.NET Core con cURL

  • Articolo

Questo articolo illustra come chiamare un'API Web ASP.NET Core protetta usando l'URL client (cURL). cURL è uno strumento da riga di comando usato dagli sviluppatori per trasferire i dati da e verso un server. 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, viene usato il token per effettuare una chiamata autorizzata all'API Web usando cURL.

Questo articolo illustra come chiamare un'API Web ASP.NET Core protetta usando l'URL client (cURL). cURL è uno strumento da riga di comando usato dagli sviluppatori per trasferire i dati da e verso un server. 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, viene usato il token per effettuare una chiamata autorizzata all'API usando cURL.

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 cURL sul computer workstation.
  • Requisito minimo di .NET 8.0 SDK.

Registrare un'applicazione con Microsoft Identity Platform

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, 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:

  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 vuole registrare l'applicazione dal 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 Suggerimenti per la scelta.

  7. Selezionare Registra.

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

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

    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(api://{clientId}) proposto selezionando Salva e continua. {clientId} è il valore registrato dalla pagina Panoramica. Immettere quindi le informazioni seguenti:

    1. Per 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 del consenso amministratore immettere Read forecast data.
    4. Nella casella di Descrizione del consenso amministratore immettere Allows the application to read weather forecast data.
    5. Nella casella Nome visualizzato del consenso utente immettere Read forecast data.
    6. Nella casella di Descrizione del 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, verrà elencato nel riquadro Esponi un'API.

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

Registrare l'app Web

La sola presenza di un'API Web non è sufficiente; è necessaria anche un'app Web per ottenere un token di accesso all'API creata.

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

  1. Selezionare Home per tornare alla pagina iniziale. Passare a Identità>Applicazioni>Registrazioni app.
  2. Selezionare 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 Suggerimenti per la scelta.
  5. In URI di reindirizzamento (facoltativo), selezionare Web, quindi immettere http://localhost nella casella 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 vuole registrare l'applicazione dal menu Directory e sottoscrizioni.
  3. Passare a Identità>Applicazioni>Registrazioni app.
  4. Selezionare 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 Suggerimenti per la scelta.
  7. In URI di reindirizzamento (facoltativo), selezionare Web, quindi immettere http://localhost nella casella URL.
  8. Selezionare Registra.

Al termine della registrazione, la registrazione app verrà visualizzata nel riquadro Panoramica. Registrare ID directory (tenant) e 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:

  1. Dal pannello Panoramica, in Gestisci, selezionare Certificati e segreti>Segreti client>Nuovo segreto client.

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

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

  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.

Aggiungere autorizzazioni dell'applicazione per consentire l'accesso ad API Web

Specificando gli ambiti di un'API Web nella registrazione dell'app Web, l'app Web può ottenere da Microsoft Identity Platform un token di accesso contenente gli ambiti. 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 dell'app Web per l'API Web:

  1. Dal riquadro Panoramica dell'applicazione Web (web-app-that-calls-web-api), in Gestisci, selezionare Autorizzazioni API>Aggiungi un'autorizzazione>API 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'applicazione client deve disporre per conto dell'utente che ha effettuato l'accesso.
  4. 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

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

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

  2. Passare alla cartella ms-identity-docs-code-dotnet/web-api e aprire il file ./appsettings.json, sostituire {APPLICATION_CLIENT_ID} e {DIRECTORY_TENANT_ID} con:

    • {APPLICATION_CLIENT_ID} è l'ID applicazione (client) dell'API Web nel riquadro Panoramica dell'app Registrazioni app.
    • {DIRECTORY_TENANT_ID} è l'ID directory (tenant) dell'API Web nel riquadro Panoramica dell'app Registrazioni 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

  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 di API Web.

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

    dotnet run

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

Richiedere un codice di autorizzazione

Il flusso del codice di autorizzazione ha inizio con il client che indirizza l'utente all'endpoint /authorize. In questa richiesta, il client richiede l'autorizzazione Forecast.Read dall'utente.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

  1. Copiare l'URL, sostituire i parametri seguenti e incollarlo nel browser:

    • {tenant_id} è l'ID directory (tenant) dell'app Web.
    • {web-app-calls-web-api_application_client_id} è l'ID applicazione (client) nel riquadro Panoramica dell'app Web (web-app-calls-web-api).
    • {web_API_application_client_id} è l'ID applicazione (client) nel riquadro Panoramica dell'API Web (NewWebAPI1).

  2. Accedere come un utente nel tenant di Microsoft Entra in cui vengono registrate le app. Fornire il consenso a qualsiasi richiesta di accesso, se necessario.

  3. Il browser verrà reindirizzato a http://localhost/. Fare riferimento alla barra di spostamento del browser e copiare {authorization_code} da usare nei passaggi seguenti. L'URL assume la forma del frammento di codice seguente:

    http://localhost/?code={authorization_code}

Usare un codice di autorizzazione e cURL per ottenere un token di accesso

cURL può ora essere usato per richiedere un token di accesso da Microsoft Identity Platform.

  1. Copiare il comando cURL nel frammento di codice seguente. Sostituire i valori tra parentesi con i seguenti parametri del terminale. Assicurarsi di rimuovere le parentesi:

    curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
    • {tenant_id} è l'ID directory (tenant) dell'app Web.
    • client_id={web-app-calls-web-api_application_client_id} e session_state={web-app-calls-web-api_application_client_id} è l'ID applicazione (client) nel pannello Panoramica dell'applicazione Web (web-app-calls-web-api).
    • api://{web_API_application_client_id}/Forecast.Read è l'ID applicazione (client) nel riquadro Panoramica dell'API Web (NewWebAPI1).
    • code={authorization_code} è il codice di autorizzazione ricevuto in Richiedi un codice di autorizzazione. Ciò consente allo strumento cURL di richiedere un token di accesso.
    • client_secret={client_secret} è il Valore del segreto client registrato in Aggiungi un segreto client.

  2. Eseguire il comando cURL e, se inserito correttamente, verrà restituita una risposta JSON simile al seguente output:

    {
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

Chiamare l'API Web con il token di accesso

Eseguendo il comando cURL precedente, Microsoft Identity Platform ha fornito un token di accesso. Il token acquisito può ora essere usato come bearer token in una richiesta HTTP per chiamare l'API Web.

  1. Per chiamare l'API web, copiare il seguente comando cURL, sostituire i valori tra parentesi e incollarlo nel terminale:

    curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
    • {access_token} il valore del token di accesso registrato dall'output JSON nella sezione precedente.
    • {port} il numero di porta dell'API Web registrato durante l'esecuzione dell'API nel terminale. Assicurarsi che sia il numero di porta https.

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

    HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

Passaggi successivi

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