Proteggere un'API usando OAuth 2.0 con Azure Active Directory e Gestione APIProtect an API by using OAuth 2.0 with Azure Active Directory and API Management

Questa guida illustra come configurare l'istanza di Gestione API di Azure per proteggere un'API usando il protocollo OAuth 2.0 con Azure Active Directory (Azure AD).This guide shows you how to configure your Azure API Management instance to protect an API, by using the OAuth 2.0 protocol with Azure Active Directory (Azure AD).

prerequisitiPrerequisites

Per eseguire i passaggi in questo articolo è necessario avere quanto segue:To follow the steps in this article, you must have:

  • Un'istanza di Gestione APIAn API Management instance
  • Un'API in corso di pubblicazione che usa l'istanza di Gestione APIAn API being published that uses the API Management instance
  • Un tenant di Azure ADAn Azure AD tenant

PanoramicaOverview

Ecco una rapida panoramica dei passaggi:Here is a quick overview of the steps:

  1. Registrare un'applicazione (app back-end) in Azure AD per rappresentare l'API.Register an application (backend-app) in Azure AD to represent the API.
  2. Registrare un'altra applicazione (app client) in Azure AD per rappresentare un'applicazione client che deve chiamare l'API.Register another application (client-app) in Azure AD to represent a client application that needs to call the API.
  3. In Azure AD concedere le autorizzazioni per consentire all'app client di chiamare l'app back-end.In Azure AD, grant permissions to allow the client-app to call the backend-app.
  4. Configurare la console per sviluppatori per l'uso dell'autorizzazione utente OAuth 2.0.Configure the Developer Console to use OAuth 2.0 user authorization.
  5. Aggiungere i criteri validate-jwt per convalidare il token OAuth per ogni richiesta in ingresso.Add the validate-jwt policy to validate the OAuth token for every incoming request.

Registrare un'applicazione in Azure AD per rappresentare l'APIRegister an application in Azure AD to represent the API

Per proteggere un'API con Azure AD, il primo passaggio consiste nel registrare un'applicazione in Azure AD che rappresenta l'API.To protect an API with Azure AD, the first step is to register an application in Azure AD that represents the API.

  1. Passare al tenant di Azure AD e quindi a Registrazioni per l'app.Browse to your Azure AD tenant, and then browse to App registrations.

  2. Selezionare Registrazione nuova applicazione.Select New application registration.

  3. Specificare un nome per l'applicazione.Provide a name of the application. In questo esempio il nome è backend-app.(For this example, the name is backend-app.)

  4. Scegliere App Web/API come Tipo di applicazione.Choose Web app / API as the Application type.

  5. Per URL accesso è possibile usare https://localhost come segnaposto.For Sign-on URL, you can use https://localhost as a placeholder.

  6. Selezionare Create.Select Create.

Dopo aver creato l'applicazione, prendere nota dell'ID applicazione, che verrà usato in un passaggio successivo.When the application is created, make a note of the Application ID, for use in a subsequent step.

Registrare un'altra applicazione in Azure AD per rappresentare un'applicazione clientRegister another application in Azure AD to represent a client application

Ogni applicazione client che chiama l'API deve anche essere registrata come applicazione in Azure AD.Every client application that calls the API needs to be registered as an application in Azure AD as well. In questo caso, l'applicazione client di esempio è la console per sviluppatori nel portale per sviluppatori di Gestione API.For this example, the sample client application is the Developer Console in the API Management developer portal. Ecco come registrare un'altra applicazione in Azure AD per rappresentare la console per sviluppatori.Here's how to register another application in Azure AD to represent the Developer Console.

  1. Selezionare Registrazione nuova applicazione.Select New application registration.

  2. Specificare un nome per l'applicazione.Provide a name of the application. In questo esempio il nome è client-app.(For this example, the name is client-app.)

  3. Scegliere App Web/API come Tipo di applicazione.Choose Web app / API as the Application type.

  4. Per URL accesso è possibile usare https://localhost come segnaposto oppure l'URL di accesso dell'istanza di Gestione API.For Sign-on URL, you can use https://localhost as a placeholder, or use the sign-in URL of your API Management instance. In questo esempio l'URL è https://contoso5.portal.azure-api.net/signin.(For this example, the URL is https://contoso5.portal.azure-api.net/signin.)

  5. Selezionare Create.Select Create.

Dopo aver creato l'applicazione, prendere nota dell'ID applicazione, che verrà usato in un passaggio successivo.When the application is created, make a note of the Application ID, for use in a subsequent step.

Creare ora un segreto client per l'applicazione, che verrà usato in un passaggio successivo.Now, create a client secret for this application, for use in a subsequent step.

  1. Selezionare di nuovo Impostazioni e passare a Chiavi.Select Settings again, and go to Keys.

  2. In Password specificare una descrizione in Descrizione chiave.Under Passwords, provide a Key description. Scegliere quando la chiave deve scadere e selezionare Salva.Choose when the key should expire, and select Save.

Prendere nota del valore della chiave.Make a note of the key value.

Concedere le autorizzazioni in Azure ADGrant permissions in Azure AD

Ora che sono state registrate due applicazioni per rappresentare l'API e la console per sviluppatori, è necessario concedere le autorizzazioni per consentire all'app client di chiamare l'app back-end.Now that you have registered two applications to represent the API and the Developer Console, you need to grant permissions to allow the client-app to call the backend-app.

  1. Passare a Registrazioni per l'app.Browse to Application registrations.

  2. Selezionare client-app e passare a Impostazioni.Select client-app, and go to Settings.

  3. Selezionare Autorizzazioni necessarie > Aggiungi.Select Required permissions > Add.

  4. Fare clic su Selezionare un'API e cercare backend-app.Select Select an API, and search for backend-app.

  5. In Autorizzazioni delegate selezionare Access backend-app.Under Delegated Permissions, select Access backend-app.

  6. Fare clic su Seleziona e quindi su Fine.Select Select, and then select Done.

Nota

Se Azure Active Directory non è presente nell'elenco di autorizzazioni per altre applicazioni, selezionare Aggiungi per aggiungere la voce all'elenco.If Azure Active Directory is not listed under permissions to other applications, select Add to add it from the list.

Abilitare l'autorizzazione utente OAuth 2.0 nella console per sviluppatoriEnable OAuth 2.0 user authorization in the Developer Console

A questo punto sono state create le applicazioni in Azure AD e sono state concesse le autorizzazioni appropriate per consentire all'app client di chiamare l'app back-end.At this point, you have created your applications in Azure AD, and have granted proper permissions to allow the client-app to call the backend-app.

In questo esempio la console per sviluppatori è l'app client.In this example, the Developer Console is the client-app. La procedura seguente descrive come abilitare l'autorizzazione utente OAuth 2.0 nella console per sviluppatori.The following steps describe how to enable OAuth 2.0 user authorization in the Developer Console.

  1. Passare all'istanza di Gestione API.Browse to your API Management instance.

  2. Selezionare OAuth 2.0 > Aggiungi.Select OAuth 2.0 > Add.

  3. Specificare i valori per i campi Nome visualizzato e Descrizione.Provide a Display name and Description.

  4. Per URL della pagina di registrazione del client immettere un valore segnaposto, ad esempio http://localhost.For the Client registration page URL, enter a placeholder value, such as http://localhost. L'URL della pagina di registrazione del client punta alla pagina che gli utenti possono usare per creare e configurare i propri account per i provider OAuth 2.0 che supportano questa operazione.The Client registration page URL points to the page that users can use to create and configure their own accounts for OAuth 2.0 providers that support this. In questo esempio gli utenti non creano e configurano i propri account, quindi si usa un segnaposto.In this example, users do not create and configure their own accounts, so you use a placeholder instead.

  5. Per Tipi di concessione di autorizzazione selezionare Codice di autorizzazione.For Authorization grant types, select Authorization code.

  6. Specificare URL dell'endpoint autorizzazione e URL dell'endpoint token.Specify the Authorization endpoint URL and Token endpoint URL. Recuperare questi valori nella pagina Endpoint nel tenant di Azure AD.Retrieve these values from the Endpoints page in your Azure AD tenant. Passare di nuovo alla pagina Registrazioni per l'app e selezionare Endpoint.Browse to the App registrations page again, and select Endpoints.

  7. Copiare il valore di Endpoint di autorizzazione OAuth 2.0 e incollarlo nella casella di testo URL dell'endpoint autorizzazione.Copy the OAuth 2.0 Authorization Endpoint, and paste it into the Authorization endpoint URL text box.

  8. Copiare il valore di Endpoint token OAuth 2.0 e incollarlo nella casella di testo URL dell'endpoint token.Copy the OAuth 2.0 Token Endpoint, and paste it into the Token endpoint URL text box. Oltre a incollare il valore nell'endpoint del token, aggiungere un parametro del corpo denominato risorsa.In addition to pasting in the token endpoint, add a body parameter named resource. Come valore di questo parametro usare l'ID applicazione per l'app back-end.For the value of this parameter, use the Application ID for the back-end app.

  9. Specificare quindi le credenziali del client.Next, specify the client credentials. Queste sono le credenziali per l'app client.These are the credentials for the client-app.

  10. Per ID client usare l'ID applicazione per l'app client.For Client ID, use the Application ID for the client-app.

  11. Per Segreto client usare la chiave creata in precedenza per l'app client.For Client secret, use the key you created for the client-app earlier.

  12. Immediatamente dopo il segreto client è riportato il valore di redirect_url per il tipo di concessione con codice di autorizzazione.Immediately following the client secret is the redirect_url for the authorization code grant type. Prendere nota dell'URL.Make a note of this URL.

  13. Selezionare Create.Select Create.

  14. Tornare alla pagina Impostazioni dell'app client.Go back to the Settings page of your client-app.

  15. Selezionare URL di risposta e incollare il valore di redirect_url nella prima riga.Select Reply URLs, and paste the redirect_url in the first row. In questo esempio è stato sostituito https://localhost con l'URL nella prima riga.In this example, you replaced https://localhost with the URL in the first row.

Ora che è stato configurato un server di autorizzazione OAuth 2.0, la console per sviluppatori può ottenere i token di accesso da Azure AD.Now that you have configured an OAuth 2.0 authorization server, the Developer Console can obtain access tokens from Azure AD.

Il passaggio successivo consiste nell'abilitare l'autorizzazione utente OAuth 2.0 per l'API.The next step is to enable OAuth 2.0 user authorization for your API. In questo modo, la console per sviluppatori sa che deve ottenere un token di accesso per conto dell'utente prima di eseguire le chiamate all'API.This enables the Developer Console to know that it needs to obtain an access token on behalf of the user, before making calls to your API.

  1. Passare all'istanza di Gestione API e quindi ad API.Browse to your API Management instance, and go to APIs.

  2. Selezionare l'API da proteggere.Select the API you want to protect. In questo esempio si usa Echo API.In this example, you use the Echo API.

  3. Passare a Impostazioni.Go to Settings.

  4. In Sicurezza scegliere OAuth 2.0 e selezionare il server OAuth 2.0 configurato in precedenza.Under Security, choose OAuth 2.0, and select the OAuth 2.0 server you configured earlier.

  5. Selezionare Salva.Select Save.

Eseguire la chiamata all'API dal portale per sviluppatoriSuccessfully call the API from the developer portal

Ora che l'autorizzazione utente OAuth 2.0 è stata abilitata su Echo API, la console per sviluppatori ottiene un token di accesso per conto dell'utente prima di chiamare l'API.Now that the OAuth 2.0 user authorization is enabled on the Echo API, the Developer Console obtains an access token on behalf of the user, before calling the API.

  1. Passare a qualsiasi operazione in Echo API nel portale per sviluppatori e selezionare Prova.Browse to any operation under the Echo API in the developer portal, and select Try it. Verrà visualizzata la console per sviluppatori.This brings you to the Developer Console.

  2. Nella sezione Autorizzazione è presente un nuovo elemento che corrisponde al server di autorizzazione appena aggiunto.Note a new item in the Authorization section, corresponding to the authorization server you just added.

  3. Selezionare Codice di autorizzazione nell'elenco a discesa delle autorizzazioni. Verrà chiesto di accedere al tenant di Azure AD.Select Authorization code from the authorization drop-down list, and you are prompted to sign in to the Azure AD tenant. Se si è già eseguito l'accesso con l'account, è possibile che la richiesta non venga visualizzata.If you are already signed in with the account, you might not be prompted.

  4. Dopo l'accesso, alla richiesta viene aggiunta un'intestazione Authorization con un token di accesso di Azure AD.After successful sign-in, an Authorization header is added to the request, with an access token from Azure AD. Di seguito è riportato un token di esempio (con codifica Base64):The following is a sample token (Base64 encoded):

    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IlNTUWRoSTFjS3ZoUUVEU0p4RTJnR1lzNDBRMCIsImtpZCI6IlNTUWRoSTFjS3ZoUUVEU0p4RTJnR1lzNDBRMCJ9.eyJhdWQiOiIxYzg2ZWVmNC1jMjZkLTRiNGUtODEzNy0wYjBiZTEyM2NhMGMiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC80NDc4ODkyMC05Yjk3LTRmOGItODIwYS0yMTFiMTMzZDk1MzgvIiwiaWF0IjoxNTIxMTUyNjMzLCJuYmYiOjE1MjExNTI2MzMsImV4cCI6MTUyMTE1NjUzMywiYWNyIjoiMSIsImFpbyI6IkFWUUFxLzhHQUFBQUptVzkzTFd6dVArcGF4ZzJPeGE1cGp2V1NXV1ZSVnd1ZXZ5QU5yMlNkc0tkQmFWNnNjcHZsbUpmT1dDOThscUJJMDhXdlB6cDdlenpJdzJLai9MdWdXWWdydHhkM1lmaDlYSGpXeFVaWk9JPSIsImFtciI6WyJyc2EiXSwiYXBwaWQiOiJhYTY5ODM1OC0yMWEzLTRhYTQtYjI3OC1mMzI2NTMzMDUzZTkiLCJhcHBpZGFjciI6IjEiLCJlbWFpbCI6Im1pamlhbmdAbWljcm9zb2Z0LmNvbSIsImZhbWlseV9uYW1lIjoiSmlhbmciLCJnaXZlbl9uYW1lIjoiTWlhbyIsImlkcCI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0Ny8iLCJpcGFkZHIiOiIxMzEuMTA3LjE3NC4xNDAiLCJuYW1lIjoiTWlhbyBKaWFuZyIsIm9pZCI6IjhiMTU4ZDEwLWVmZGItNDUxMS1iOTQzLTczOWZkYjMxNzAyZSIsInNjcCI6InVzZXJfaW1wZXJzb25hdGlvbiIsInN1YiI6IkFGaWtvWFk1TEV1LTNkbk1pa3Z3MUJzQUx4SGIybV9IaVJjaHVfSEM1aGciLCJ0aWQiOiI0NDc4ODkyMC05Yjk3LTRmOGItODIwYS0yMTFiMTMzZDk1MzgiLCJ1bmlxdWVfbmFtZSI6Im1pamlhbmdAbWljcm9zb2Z0LmNvbSIsInV0aSI6ImFQaTJxOVZ6ODBXdHNsYjRBMzBCQUEiLCJ2ZXIiOiIxLjAifQ.agGfaegYRnGj6DM_-N_eYulnQdXHhrsus45QDuApirETDR2P2aMRxRioOCR2YVwn8pmpQ1LoAhddcYMWisrw_qhaQr0AYsDPWRtJ6x0hDk5teUgbix3gazb7F-TVcC1gXpc9y7j77Ujxcq9z0r5lF65Y9bpNSefn9Te6GZYG7BgKEixqC4W6LqjtcjuOuW-ouy6LSSox71Fj4Ni3zkGfxX1T_jiOvQTd6BBltSrShDm0bTMefoyX8oqfMEA2ziKjwvBFrOjO0uK4rJLgLYH4qvkR0bdF9etdstqKMo5gecarWHNzWi_tghQu9aE3Z3EZdYNI_ZGM-Bbe3pkCfvEOyA
    
  5. Selezionare Invia e quindi sarà possibile chiamare l'API.Select Send, and you can call the API successfully.

Configurare criteri di convalida JWT per preautorizzare le richiesteConfigure a JWT validation policy to pre-authorize requests

A questo punto, quando un utente prova a eseguire una chiamata dalla console per sviluppatori, viene chiesto di eseguire l'accesso.At this point, when a user tries to make a call from the Developer Console, the user is prompted to sign in. La console per sviluppatori ottiene un token di accesso per conto dell'utente.The Developer Console obtains an access token on behalf of the user.

Ma che cosa accade se un utente chiama l'API senza un token o con un token non valido?But what if someone calls your API without a token or with an invalid token? È ad esempio possibile chiamare comunque l'API anche se si elimina l'intestazione Authorization.For example, you can still call the API even if you delete the Authorization header. Questo avviene perché Gestione API non convalida il token di accesso a questo punto.The reason is that API Management does not validate the access token at this point. Passa invece semplicemente l'intestazione Authorization all'API back-end.It simply passes the Authorization header to the back-end API.

È possibile usare i criteri di convalida JWT per pre-autorizzare le richieste in Gestione API convalidando i token di accesso di ogni richiesta in ingresso.You can use the Validate JWT policy to pre-authorize requests in API Management, by validating the access tokens of each incoming request. Se una richiesta non ha un token valido, Gestione API la blocca.If a request does not have a valid token, API Management blocks it. È ad esempio possibile aggiungere i criteri seguenti alla sezione <inbound> di Echo API.For example, you can add the following policy to the <inbound> policy section of the Echo API. In questo modo, viene verificata l'attestazione dei destinatari in un token di accesso e viene restituito un messaggio di errore se il token non è valido.It checks the audience claim in an access token, and returns an error message if the token is not valid. Per informazioni su come configurare i criteri, vedere Impostare o modificare criteri.For information on how to configure policies, see Set or edit policies.

<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/{aad-tenant}/.well-known/openid-configuration" />
    <required-claims>
        <claim name="aud">
            <value>{Application ID of backend-app}</value>
        </claim>
    </required-claims>
</validate-jwt>

Creare un'applicazione per chiamare l'APIBuild an application to call the API

In questa guida è stata usata la console per sviluppatori di Gestione API come applicazione client di esempio per chiamare Echo API a cui è applicata la protezione tramite OAuth 2.0.In this guide, you used the Developer Console in API Management as the sample client application to call the Echo API protected by OAuth 2.0. Per altre informazioni su come creare un'applicazione e implementare OAuth 2.0, vedere Esempi di codice di Azure Active Directory.To learn more about how to build an application and implement OAuth 2.0, see Azure Active Directory code samples.

Passaggi successiviNext steps