Come proteggere il back-end di un'API Web con Azure Active Directory e Gestione API

Il video che segue illustra come compilare il back-end di un'API Web e proteggerlo usando il protocollo OAuth 2.0 con Azure Active Directory e Gestione API. Questo articolo fornisce una panoramica e informazioni aggiuntive per le procedure illustrate nel video. Il video della durata di 24 minuti mostra come fare per:

  • Compilare il back-end di un'API Web e proteggerlo con AAD - iniziando all’1:30
  • Importare l'API in Gestione API - iniziando alle 7:10
  • Configurare il portale per sviluppatori per chiamare l'API - iniziando alle 9:09
  • Configurare un'applicazione desktop per chiamare l'API - iniziando alle 18:08
  • Configurare criteri di convalida JWT per preautorizzare le richieste - iniziando alle 20:47

Creare una directory di Azure AD

Per proteggere il back-end dell'API Web con Azure Active Directory, si deve avere prima di tutto un tenant AAD. Questo video usa un tenant denominato APIMDemo . Per creare un tenant AAD, accedere al portale di Azure classico e fare clic su Nuovo->Servizi app->Active Directory->Directory->Creazione personalizzata.

Azure Active Directory

In questo esempio viene creata una directory denominata APIMDemo con un dominio predefinito denominato DemoAPIM.onmicrosoft.com. Questa directory viene usata in tutto il video.

Azure Active Directory

Creare un servizio API Web protetto da Azure Active Directory

In questo passaggio viene creato il back-end di un'API Web con Visual Studio 2013. Questo passaggio del video inizia da 1:30 minuti. Per creare un progetto back-end dell'API Web in Visual Studio, fare clic su File->Nuovo->Progetto e scegliere Applicazione Web ASP.NET dall'elenco di modelli Web. In questo video il progetto è denominato APIMAADDemo. Fare clic su OK per creare il progetto.

Visual Studio

Fare clic su API Web nell'elenco Selezionare un modello per creare un progetto API Web. Per configurare l'autenticazione di Azure Active Directory fare clic su Modifica autenticazione.

Nuovo progetto

Fare clic su Account aziendali e specificare il Dominio del tenant AAD. In questo esempio il dominio è DemoAPIM.onmicrosoft.com. Il dominio della directory può essere rilevato dalla scheda Domini della stessa directory.

Domini

Configurare le impostazioni nella finestra di dialogo Modifica autenticazione e fare clic su OK.

Modifica autenticazione

Quando si fa clic su OK , Visual Studio prova a registrare l'applicazione con la directory di Azure AD e all'utente potrebbe essere richiesto di accedere da Visual Studio. Accedere con un account amministrativo per la directory.

Accesso a Visual Studio

Per configurare questo progetto come un'API Web di Azure, selezionare la casella Ospita nel cloud, quindi fare clic su OK.

Nuovo progetto

Potrebbe venire richiesto di accedere ad Azure, dopo di che si potrà configurare l'app Web.

Configurare

In questo esempio viene specificato un nuovo Piano di servizio app denominato APIMAADDemo.

Fare clic su OK per configurare l'app Web e creare il progetto.

Aggiungere il codice al progetto API Web

Il passaggio successivo del video aggiunge il codice al progetto API Web API. Questo passaggio inizia da 4:35 minuti.

L'API Web in questo esempio implementa un servizio calcolatrice di base usando un modello e un controller. Per aggiungere il modello al servizio, fare clic con il pulsante destro del mouse su Modelli in Esplora soluzioni e scegliere Aggiungi, Classe. Assegnare alla classe il nome CalcInput e fare clic su Aggiungi.

Aggiungere l'istruzione using seguente all'inizio del file CalcInput.cs.

using Newtonsoft.Json;

Sostituire la classe generata con il codice seguente.

public class CalcInput
{
    [JsonProperty(PropertyName = "a")]
    public int a;

    [JsonProperty(PropertyName = "b")]
    public int b;
}

Fare clic con il pulsante destro del mouse su Controller in Esplora soluzioni e scegliere Aggiungi->Controller. Scegliere Web API 2 Controller - Empty e fare clic su Aggiungi. Digitare CalcController come nome del controller e fare clic su Aggiungi.

Aggiungi controller

Aggiungere l'istruzione using seguente all'inizio del file CalcController.cs.

using System.IO;
using System.Web;
using APIMAADDemo.Models;

Sostituire la classe controller generata con il codice seguente. Questo codice implementa le operazioni Add, Subtract, Multiply e Divide dell'API Calculator di base.

[Authorize]
public class CalcController : ApiController
{
    [Route("api/add")]
    [HttpGet]
    public HttpResponseMessage GetSum([FromUri]int a, [FromUri]int b)
    {
        string xml = string.Format("<result><value>{0}</value><broughtToYouBy>Azure API Management - http://azure.microsoft.com/apim/ </broughtToYouBy></result>", a + b);
        HttpResponseMessage response = Request.CreateResponse();
        response.Content = new StringContent(xml, System.Text.Encoding.UTF8, "application/xml");
        return response;
    }

    [Route("api/sub")]
    [HttpGet]
    public HttpResponseMessage GetDiff([FromUri]int a, [FromUri]int b)
    {
        string xml = string.Format("<result><value>{0}</value><broughtToYouBy>Azure API Management - http://azure.microsoft.com/apim/ </broughtToYouBy></result>", a - b);
        HttpResponseMessage response = Request.CreateResponse();
        response.Content = new StringContent(xml, System.Text.Encoding.UTF8, "application/xml");
        return response;
    }

    [Route("api/mul")]
    [HttpGet]
    public HttpResponseMessage GetProduct([FromUri]int a, [FromUri]int b)
    {
        string xml = string.Format("<result><value>{0}</value><broughtToYouBy>Azure API Management - http://azure.microsoft.com/apim/ </broughtToYouBy></result>", a * b);
        HttpResponseMessage response = Request.CreateResponse();
        response.Content = new StringContent(xml, System.Text.Encoding.UTF8, "application/xml");
        return response;
    }

    [Route("api/div")]
    [HttpGet]
    public HttpResponseMessage GetDiv([FromUri]int a, [FromUri]int b)
    {
        string xml = string.Format("<result><value>{0}</value><broughtToYouBy>Azure API Management - http://azure.microsoft.com/apim/ </broughtToYouBy></result>", a / b);
        HttpResponseMessage response = Request.CreateResponse();
        response.Content = new StringContent(xml, System.Text.Encoding.UTF8, "application/xml");
        return response;
    }
}

Premere F6 per compilare e verificare la soluzione.

Pubblicare il progetto in Azure

In questo passaggio il progetto di Visual Studio viene pubblicato in Azure. Questo passaggio del video inizia da 5:45 minuti.

Per pubblicare il progetto in Azure, fare clic con il pulsante destro del mouse sul progetto APIMAADDemo in Visual Studio e scegliere Pubblica. Mantenere le impostazioni predefinite nella finestra di dialogo Pubblica sul Web e fare clic su Pubblica.

Pubblicazione sul Web

Concedere autorizzazioni all'applicazione del servizio back-end di Azure AD

Nella directory di Azure AD viene creata una nuova applicazione per il servizio back-end come parte del processo di configurazione e pubblicazione del progetto API Web. In questo passaggio del video, che inizia da 6:13 minuti, vengono concesse autorizzazioni al back-end dell'API Web.

Applicazione

Fare clic sul nome dell'applicazione per configurare le autorizzazioni necessarie. Passare alla scheda Configura e scorrere verso il basso fino alla sezione Autorizzazioni per altre applicazioni. Fare clic sull'elenco a discesa Autorizzazioni applicazione accanto a Microsoft Azure Active Directory, selezionare la casella Lettura dati directory e fare clic su Salva.

Aggiungere autorizzazioni

Nota

Se Microsoft Azure Active Directory non è nell'elenco in Autorizzazioni per altre applicazioni, fare clic su Aggiungi applicazione e aggiungere la voce all'elenco.

Prendere nota dell' URI ID app che verrà usato in un passaggio successivo durante la configurazione di un'applicazione Azure AD per il portale per sviluppatori di Gestione API.

URI ID app

Importare l'API Web in Gestione API

Le API vengono configurate dal relativo portale di pubblicazione, accessibile dal Portale di Azure. Per accedervi, fare clic su Publisher portal (Portale di pubblicazione) nella barra degli strumenti del servizio Gestione API. Se non è ancora stata creata un'istanza del servizio Gestione API, vedere Creare un'istanza di Gestione API nell'esercitazione Gestire la prima API.

Portale di pubblicazione

Le operazioni possono essere aggiunte alle API manualmenteo possono essere importate. In questo video le operazioni vengono importante in formato Swagger a partire da 6:40 minuti.

Creare un file denominato calcapi.json con il contenuto seguente e salvarlo nel computer. Assicurarsi che l'attributo host punti al back-end dell'API Web. In questo esempio viene usato "host": "apimaaddemo.azurewebsites.net" .

{
  "swagger": "2.0",
  "info": {
    "title": "Calculator",
    "description": "Arithmetics over HTTP!",
    "version": "1.0"
  },
  "host": "apimaaddemo.azurewebsites.net",
  "basePath": "/api",
  "schemes": [
    "http"
  ],
  "paths": {
    "/add?a={a}&b={b}": {
      "get": {
        "description": "Responds with a sum of two numbers.",
        "operationId": "Add two integers",
        "parameters": [
          {
            "name": "a",
            "in": "query",
            "description": "First operand. Default value is <code>51</code>.",
            "required": true,
            "type": "string",
            "default": "51",
            "enum": [
              "51"
            ]
          },
          {
            "name": "b",
            "in": "query",
            "description": "Second operand. Default value is <code>49</code>.",
            "required": true,
            "type": "string",
            "default": "49",
            "enum": [
              "49"
            ]
          }
        ],
        "responses": { }
      }
    },
    "/sub?a={a}&b={b}": {
      "get": {
        "description": "Responds with a difference between two numbers.",
        "operationId": "Subtract two integers",
        "parameters": [
          {
            "name": "a",
            "in": "query",
            "description": "First operand. Default value is <code>100</code>.",
            "required": true,
            "type": "string",
            "default": "100",
            "enum": [
              "100"
            ]
          },
          {
            "name": "b",
            "in": "query",
            "description": "Second operand. Default value is <code>50</code>.",
            "required": true,
            "type": "string",
            "default": "50",
            "enum": [
              "50"
            ]
          }
        ],
        "responses": { }
      }
    },
    "/div?a={a}&b={b}": {
      "get": {
        "description": "Responds with a quotient of two numbers.",
        "operationId": "Divide two integers",
        "parameters": [
          {
            "name": "a",
            "in": "query",
            "description": "First operand. Default value is <code>100</code>.",
            "required": true,
            "type": "string",
            "default": "100",
            "enum": [
              "100"
            ]
          },
          {
            "name": "b",
            "in": "query",
            "description": "Second operand. Default value is <code>20</code>.",
            "required": true,
            "type": "string",
            "default": "20",
            "enum": [
              "20"
            ]
          }
        ],
        "responses": { }
      }
    },
    "/mul?a={a}&b={b}": {
      "get": {
        "description": "Responds with a product of two numbers.",
        "operationId": "Multiply two integers",
        "parameters": [
          {
            "name": "a",
            "in": "query",
            "description": "First operand. Default value is <code>20</code>.",
            "required": true,
            "type": "string",
            "default": "20",
            "enum": [
              "20"
            ]
          },
          {
            "name": "b",
            "in": "query",
            "description": "Second operand. Default value is <code>5</code>.",
            "required": true,
            "type": "string",
            "default": "5",
            "enum": [
              "5"
            ]
          }
        ],
        "responses": { }
      }
    }
  }
}

Per importare l'API Calculator, fare clic su API nel menu Gestione API sulla sinistra e quindi scegliere Importa API.

Pulsante Importa API

Per configurare l'API di calcolatrice, eseguire la procedura seguente:

  1. Fare clic su Da file, passare al file calculator.json salvato e fare clic sul pulsante di opzione Swagger.
  2. Digitare calc nella casella di testo Suffisso URL API Web.
  3. Fare clic sulla casella Products (optional) (Prodotti - facoltativo) e scegliere Starter.
  4. Fare clic su Salva per importare l'API.

Add new API

Una volta importata l'API, la pagina di riepilogo dell'API viene visualizzata nel portale di pubblicazione.

Chiamare l'API con esito negativo dal portale per sviluppatori

A questo punto, l'API è stata importata in Gestione API, ma la chiamata dal portale per sviluppatori non può ancora essere completata perché il servizio back-end è protetto con l'autenticazione di Azure AD. Questa operazione è illustrata nel video a partire da 7:40 minuti usando i passaggi seguenti.

Fare clic su Portale per sviluppatori sul lato in alto a destra del portale di pubblicazione.

Portale per sviluppatori

Fare clic su API e sull'API Calculator.

Portale per sviluppatori

Fare clic su Prova.

Prova

Fare clic su Invia e prendere nota dello stato della risposta 401 Unauthorized.

Invio

La richiesta non è autorizzata perché l'API back-end è protetta da Azure Active Directory. Prima di poter chiamare l'API correttamente, è necessario configurare il portale per sviluppatori impostando l'autorizzazione per l'uso di OAuth 2.0 da parte degli sviluppatori. Questo processo è descritto nelle sezioni seguenti.

Registrare il portale per sviluppatori come un'applicazione AAD

Il primo passaggio per configurare il portale per sviluppatori con l'autorizzazione per l'uso di OAuth 2.0 consiste nel registrare il portale come un'applicazione AAD. Nel video questa operazione è illustrata a partire da 8:27 minuti.

Passare al tenant di Azure AD dal primo passaggio di questo video, in questo esempio APIMDemo, e quindi alla scheda Applicazioni.

Nuova applicazione

Fare clic sul pulsante Aggiungi per creare una nuova applicazione Azure Active Directory e scegliere Aggiungi un'applicazione che l'organizzazione sta sviluppando.

Nuova applicazione

Scegliere Applicazione Web e/o API Web, immettere un nome e fare clic sulla freccia avanti. In questo esempio viene usato APIMDeveloperPortal .

Nuova applicazione

Per URL accesso immettere l'URL del servizio Gestione API e aggiungere /signin. In questo esempio viene usato https://contoso5.portal.azure-api.net/signin .

Per URI ID app immettere l'URL del servizio Gestione API e aggiungere alcuni caratteri univoci. Si può usare qualsiasi carattere. In questo esempio vengono usati https://contoso5.portal.azure-api.net/dp. Dopo aver completato la configurazione delle Proprietà dell'app, fare clic sul segno di spunta per creare l'applicazione.

Nuova applicazione

Configurare un server autorizzazione OAuth 2.0 in Gestione API

Il passaggio successivo consiste nel configurare un server autorizzazione OAuth 2.0 in Gestione API. Questo passaggio è illustrato nel video a partire da 9:43 minuti.

Fare clic su Sicurezza dal menu Gestione API a sinistra, scegliere OAuth 2.0 e fare clic su Add authorization server.

Add authorization server

Immettere un nome ed eventualmente una descrizione nei campi Nome e Descrizione. Questi campi vengono usati per identificare il server autorizzazione OAuth 2.0 all'interno dell'istanza del servizio Gestione API corrente. In questo esempio viene usato Authorization server demo . In un secondo momento quando si specifica un server di OAuth 2.0 da usare per l'autenticazione per un'API, si selezionerà questo nome.

Per Client registration page URL immettere un valore segnaposto, ad esempio http://localhost. Client registration page URL fa riferimento alla pagina che gli utenti possono usare per creare e configurare i propri account per i provider OAuth 2.0 che supportano la gestione degli account da parte degli utenti. In questo esempio gli utenti non creano e configurano i propri account, quindi si usa un segnaposto.

Add authorization server

Successivamente, specificare un valore per Authorization endpoint URL e Token endpoint URL.

Serve autorizzazione

Questi valori possono essere recuperati dalla pagina Endpoint dell'app dell'applicazione AAD creata per il portale per sviluppatori. Per accedere agli endpoint passare alla scheda Configura per l'applicazione di AAD e fare clic su Visualizza endpoint.

Applicazione

Visualizza endpoint

Copiare il valore di Endpoint di autorizzazione OAuth 2.0 e incollarlo nella casella di testo Authorization endpoint URL.

Add authorization server

Copiare il valore di Endpoint token OAuth 2.0 e incollarlo nella casella di testo Token endpoint URL.

Add authorization server

Oltre a incollare il valore nell'endpoint del token, aggiungere un altro parametro del corpo denominato resource e come valore usare l'URI ID App dell'applicazione AAD per il servizio back-end creato durante la pubblicazione del progetto di Visual Studio.

URI ID app

Specificare quindi le credenziali del client. Queste sono le credenziali per la risorsa a cui si vuole accedere, in questo caso il portale per gli sviluppatori.

Credenziali del client

Per ottenere il valore di ID client passare alla scheda Configura dell'applicazione AAD per il portale per gli sviluppatori e copiare il valore di ID client.

Per ottenere il Segreto client fare clic sull'elenco a discesa Seleziona durata nella sezione Chiavi e specificare un intervallo. In questo esempio viene usato 1 anno.

ID Client

Fare clic su Salva per salvare la configurazione e visualizzare la chiave.

Importante

Annotare il valore relativo alla chiave. Una volta chiusa la finestra di configurazione di Azure Active Directory, la chiave non potrà più essere visualizzata.

Copiare la chiave negli Appunti, tornare al portale di pubblicazione, incollare la chiave nella casella di testo Segreto client e fare clic su Salva.

Add authorization server

Subito dopo le credenziali del client è presente una concessione del codice di autorizzazione. Copiare questo codice di autorizzazione e tornare all'applicazione del portale per sviluppatori Azure AD e incollare la concessione di autorizzazione nel campo URL di risposta, quindi fare di nuovo clic su Salva.

URL di risposta

Il passaggio successivo consiste nel configurare le autorizzazioni per l'applicazione AAD nel portale per sviluppatori. Fare clic su Autorizzazioni applicazione e selezionare la casella per Lettura dati directory. Fare clic su Salva per salvare la modifica e quindi scegliere Aggiungi applicazione.

Aggiungere autorizzazioni

Fare clic sull'icona di ricerca digitare APIM nella casella Che inizia con, selezionare APIMAADDemo e fare clic sul segno di spunta per salvare.

Aggiungere autorizzazioni

Fare clic su Autorizzazioni delegate per APIMAADDemo, selezionare la casella Accedi a APIMAADDemo e fare clic su Salva. Questa impostazione consente all'applicazione nel portale per sviluppatori di accedere al servizio back-end.

Aggiungere autorizzazioni

Abilitare l'autorizzazione utente OAuth 2.0 per l'API Calculator

Dopo aver configurato il server OAuth 2.0, è possibile specificarlo nelle impostazioni di sicurezza per l'API. Questo passaggio è illustrato nel video a partire da 14:30 minuti.

Fare clic su API nel menu a sinistra, quindi fare clic su Calculator per visualizzarne e configurarne le impostazioni.

API Calculator

Passare alla scheda Sicurezza, selezionare la casella di controllo OAuth 2.0, selezionare il server di autorizzazione specifico dall'elenco a discesa Authorization server e fare clic su Salva.

API Calculator

Chiamare correttamente l'API Calculator dal portale per sviluppatori

Dopo avere configurato l'autorizzazione OAuth 2.0 nell'API, le relative operazioni possono essere chiamate correttamente dal centro per sviluppatori. Questo passaggio è illustrato nel video a partire da 15:00 minuti.

Tornare all'operazione Aggiungere due Integer del servizio calcolatrice nel portale per sviluppatori e fare clic su Prova. Si noti il nuovo elemento nella sezione Autorizzazione corrispondente al server autorizzazione appena aggiunto.

API Calculator

Selezionare Authorization code dall'elenco a discesa dell'autorizzazione e immettere le credenziali dell'account da usare. Se si è già eseguito l'accesso con l'account, è possibile che non venga richiesto.

API Calculator

Fare clic su Invia e prendere nota del valore 200 OK in Stato della risposta e dei risultati dell'operazione nel contenuto della risposta.

API Calculator

Configurare un'applicazione desktop per chiamare l'API

La procedura successiva del video inizia da 16:30 minuti e configura una semplice applicazione desktop per chiamare l'API. Il primo passaggio consiste nel registrare l'applicazione desktop in Azure AD e nel concedere l'accesso alla directory e al servizio back-end. Da 18:25 minuti è presente una dimostrazione dell'applicazione desktop che chiama un'operazione nell'API Calculator.

Configurare criteri di convalida JWT per preautorizzare le richieste

L'ultima procedura dei video inizia dal minuto 20:48 e illustra come usare i criteri di convalida JWT per preautorizzare le richieste con la convalida dei token di accesso di ogni richiesta in ingresso. Se la richiesta non viene convalidata dai criteri di convalida JWT, viene bloccata da Gestione API e non viene passata al back-end.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/DemoAPIM.onmicrosoft.com/.well-known/openid-configuration" />
    <required-claims>
        <claim name="aud">
            <value>https://DemoAPIM.NOTonmicrosoft.com/APIMAADDemo</value>
        </claim>
    </required-claims>
</validate-jwt>

Per un'altra dimostrazione relativa alla configurazione e all'uso di questi criteri, vedere l' episodio 177 di Cloud Cover su altre funzionalità di Gestione API e passare direttamente al minuto 13:50. Passare a 15:00 minuti per vedere i criteri configurati nell'editor dei criteri e quindi a 18:50 minuti per una dimostrazione della chiamata di un'operazione dal portale per sviluppatori, con e senza il token di autorizzazione richiesto.

Passaggi successivi