Share via

Chiamare un'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, si usa 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. 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 cURL.

Prerequisiti

  • Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
  • Questo account Azure deve avere le 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 cURL nel computer workstation.
  • Requisito minimo di .NET 6.0 SDK.

Registrare un'applicazione con Microsoft Identity Platform

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 come almeno uno 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 Applicazioni> di identità>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, 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 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 Amministrazione nome visualizzato del consenso immettere Read forecast data.
    4. Nella casella Amministrazione descrizione del consenso 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, verrà elencato nel riquadro Esporre un'API .

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

Registrare l'app Web

La presenza di un'API Web non è sufficiente, tuttavia, poiché è necessaria anche un'app Web per ottenere un token di accesso per accedere all'API Web creata.

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

  1. Selezionare Home per tornare alla home page. Passare a Applicazioni> di identità>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 come almeno uno 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 Applicazioni> di identità>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, la registrazione dell'app viene visualizzata nel riquadro Panoramica . 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.

Aggiungere autorizzazioni dell'applicazione per consentire l'accesso a un'API Web

Specificando gli ambiti di un'API Web nella registrazione dell'app 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 dell'app Web per l'API Web:

  1. Nel riquadro Panoramica dell'applicazione Web (web-app-that-calls-web-api), in Gestisci selezionare Autorizzazioni>API Aggiungi un'autorizzazione>Api personali.
  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

  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 ms-identity-docs-code-dotnet/web-api cartella e aprire ./appsettings.json il {APPLICATION_CLIENT_ID} file, sostituire e {DIRECTORY_TENANT_ID} con:

    • {APPLICATION_CLIENT_ID}è l'ID applicazione API Web (client) nel riquadro Panoramica dell'app Registrazioni app.
    • {DIRECTORY_TENANT_ID}è l'ID della directory dell'API Web (tenant) 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 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 dell'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 dell'app Web (tenant).
    • {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 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 da {authorization_code} usare nei passaggi seguenti. L'URL ha il formato 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 parametri seguenti nel 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 dell'app Web (tenant).
    • 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 riquadro 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 Richiedere 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 Aggiungere un segreto client.

  2. Eseguire il comando cURL e, se immesso correttamente, si dovrebbe ricevere una risposta JSON simile all'output seguente:

    {
   "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 in una richiesta HTTP per chiamare l'API Web.

  1. Per chiamare l'API Web, copiare il comando cURL seguente, sostituire i valori seguenti 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} valore del token di accesso registrato dall'output JSON nella sezione precedente.
    • {port} numero di porta dell'API Web registrato durante l'esecuzione dell'API nel terminale. Assicurarsi che sia il numero di https porta.

  2. Con un token di accesso valido incluso nella richiesta, la risposta prevista è HTTP/2 200 con output simile all'output 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 altre informazioni sul flusso del codice di autorizzazione OAuth 2.0 e sui tipi di applicazione, vedere: