Proteggere un'API di Gestione API di Azure con Azure AD B2CSecure an Azure API Management API with Azure AD B2C

Informazioni su come limitare l'accesso dell'API di Gestione API di Azure ai client che hanno eseguito l'autenticazione con Azure Active Directory B2C (Azure AD B2C).Learn how to restrict access to your Azure API Management (APIM) API to clients that have authenticated with Azure Active Directory B2C (Azure AD B2C). Seguire la procedura descritta in questo articolo per creare e testare un criterio in ingresso in Gestione API che limiti l'accesso solo alle richieste che includono un token di accesso valido emesso da Azure AD B2C.Follow the steps in this article to create and test an inbound policy in APIM that restricts access to only those requests that include a valid Azure AD B2C-issued access token.

PrerequisitiPrerequisites

Per continuare con la procedura descritta in questo articolo, è necessario implementare le risorse seguenti:You need the following resources in place before continuing with the steps in this article:

Ottenere l'ID applicazione di Azure AD B2CGet Azure AD B2C application ID

Per la protezione di un'API in Gestione API di Azure con Azure AD B2C sono necessari alcuni valori per il criterio in ingresso creato in Gestione API.When you secure an API in Azure API Management with Azure AD B2C, you need several values for the inbound policy that you create in APIM. Registrare prima l'ID di un'applicazione creata in precedenza nel tenant di Azure AD B2C.First, record the application ID of an application you've previously created in your Azure AD B2C tenant. Se si usa l'applicazione creata nei prerequisiti, usare l'ID applicazione per webbapp1.If you're using the application you created in the prerequisites, use the application ID for webbapp1.

Per registrare un'applicazione nel tenant di Azure AD B2C, è possibile usare la nuova esperienza unificata Registrazioni app oppure l'esperienza legacy Applicazioni (legacy) .To register an application in your Azure AD B2C tenant, you can use our new unified App registrations experience or our legacy Applications (Legacy) experience. Altre informazioni sulla nuova esperienza.Learn more about the new experience.

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Selezionare il filtro Directory e sottoscrizione nel menu in alto e quindi la directory contenente il tenant di Azure AD B2C.Select the Directory + subscription filter in the top menu, and then select the directory that contains your Azure AD B2C tenant.
  3. Nel menu a sinistra selezionare Azure AD B2C.In the left menu, select Azure AD B2C. In alternativa, selezionare Tutti i servizi e quindi cercare e selezionare Azure AD B2C.Or, select All services and search for and select Azure AD B2C.
  4. Selezionare registrazioni app, quindi selezionare la scheda applicazioni di proprietà .Select App registrations, then select the Owned applications tab.
  5. Registrare il valore presente nella colonna ID client applicazione per webapp1 o un'altra applicazione creata in precedenza.Record the value in the Application (client) ID column for webapp1 or another application you've previously created.

Ottenere l'endpoint dell'autorità emittente di tokenGet token issuer endpoint

Successivamente, ottenere l'URL di configurazione well-known di uno dei flussi utente di Azure AD B2C.Next, get the well-known config URL for one of your Azure AD B2C user flows. È anche necessario l'URI dell'endpoint dell'autorità emittente di token da supportare in Gestione API di Azure.You also need the token issuer endpoint URI you want to support in Azure API Management.

  1. Passare al tenant di Azure AD B2C nel portale di Azure.Browse to your Azure AD B2C tenant in the Azure portal.

  2. In Criteri selezionare Flussi utente.Under Policies, select User flows.

  3. Selezionare un criterio esistente, ad esempio B2C_1_signupsignin1, e quindi Esegui il flusso utente.Select an existing policy, for example B2C_1_signupsignin1, then select Run user flow.

  4. Registrare l'URL nel collegamento ipertestuale visualizzato sotto l'intestazione Esegui il flusso utente nella parte superiore della pagina.Record the URL in hyperlink displayed under the Run user flow heading near the top of the page. Questo URL costituisce l'endpoint di individuazione well-known di OpenID Connect per il flusso utente e verrà usato nella prossima sezione per la configurazione del criterio in ingresso in Gestione API di Azure.This URL is the OpenID Connect well-known discovery endpoint for the user flow, and you use it in the next section when you configure the inbound policy in Azure API Management.

    Collegamento ipertestuale URI well-known nella pagina Esegui adesso del portale di Azure

  5. Selezionare il collegamento ipertestuale per passare alla pagina di configurazione well-known di OpenID Connect.Select the hyperlink to browse to the OpenID Connect well-known configuration page.

  6. Nella pagina visualizzata nel browser registrare il valore di issuer, ad esempio:In the page that opens in your browser, record the issuer value, for example:

    https://<tenant-name>.b2clogin.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0/

    Questo valore verrà usato nella prossima sezione per la configurazione dell'API in Gestione API di Azure.You use this value in the next section when you configure your API in Azure API Management.

A questo punto sono disponibili due URL registrati da usare nella prossima sezione: l'URL dell'endpoint di configurazione well-known di OpenID Connect e l'URI dell'autorità emittente.You should now have two URLs recorded for use in the next section: the OpenID Connect well-known configuration endpoint URL and the issuer URI. Ad esempio:For example:

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/B2C_1_signupsignin1/v2.0/.well-known/openid-configuration
https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/

Configurare il criterio in ingresso in Gestione API di AzureConfigure inbound policy in Azure API Management

A questo punto è possibile aggiungere il criterio in ingresso in Gestione API di Azure per la convalida delle chiamate API.You're now ready to add the inbound policy in Azure API Management that validates API calls. Con l'aggiunta di un criterio di convalida JWT che verifica i destinatari e l'autorità emittente in un token di accesso, è possibile assicurarsi che vengano accettate solo le chiamate API con un token valido.By adding a JWT validation policy that verifies the audience and issuer in an access token, you can ensure that only API calls with a valid token are accepted.

  1. Selezionare l'istanza di Gestione API di Azure nel portale di Azure.Browse to your Azure API Management instance in the Azure portal.

  2. Selezionare API.Select APIs.

  3. Selezionare l'API che si vuole proteggere con Azure AD B2C.Select the API that you want to secure with Azure AD B2C.

  4. Selezionare la scheda Progettazione.Select the Design tab.

  5. In Elaborazione in ingresso selezionare </> per aprire l'editor del codice dei criteri.Under Inbound processing, select </> to open the policy code editor.

  6. Inserire il tag <validate-jwt> seguente all'interno del criterio <inbound>.Place the following <validate-jwt> tag inside the <inbound> policy.

    1. Aggiornare il valore url nell'elemento <openid-config> con l'URL di configurazione well-known del criterio.Update the url value in the <openid-config> element with your policy's well-known configuration URL.
    2. Aggiornare l'elemento <audience> con l'ID dell'applicazione creata in precedenza nel tenant di B2C (ad esempio, webapp1).Update the <audience> element with Application ID of the application you created previously in your B2C tenant (for example, webapp1).
    3. Aggiornare l'elemento <issuer> con l'endpoint dell'autorità emittente di token registrato in precedenza.Update the <issuer> element with the token issuer endpoint you recorded earlier.
    <policies>
        <inbound>
            <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
                <openid-config url="https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/B2C_1_signupsignin1/v2.0/.well-known/openid-configuration" />
                <audiences>
                    <audience>44444444-0000-0000-0000-444444444444</audience>
                </audiences>
                <issuers>
                    <issuer>https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
                </issuers>
            </validate-jwt>
            <base />
        </inbound>
        <backend> <base /> </backend>
        <outbound> <base /> </outbound>
        <on-error> <base /> </on-error>
    </policies>
    

Convalidare l'accesso API sicuroValidate secure API access

Per garantire che solo i chiamanti autenticati possano accedere all'API, è possibile convalidare la configurazione di Gestione API di Azure chiamando l'API con Postman.To ensure only authenticated callers can access your API, you can validate your Azure API Management configuration by calling the API with Postman.

Per chiamare l'API sono necessari un token di accesso emesso da Azure AD B2C e una chiave di sottoscrizione di Gestione API.To call the API, you need both an access token issued by Azure AD B2C, and an APIM subscription key.

Ottenere un token di accessoGet an access token

È prima necessario un token emesso da Azure AD B2C da usare nell'intestazione Authorization in Postman.You first need a token issued by Azure AD B2C to use in the Authorization header in Postman. È possibile ottenerne uno con la funzionalità Esegui adesso del flusso utente di iscrizione/accesso creato come prerequisito.You can get one by using the Run now feature of your sign-up/sign-in user flow you should have created as one of the prerequisites.

  1. Passare al tenant di Azure AD B2C nel portale di Azure.Browse to your Azure AD B2C tenant in the Azure portal.

  2. In Criteri selezionare Flussi utente.Under Policies, select User flows.

  3. Selezionare un flusso utente di iscrizione/accesso esistente, ad esempio B2C_1_signupsignin1.Select an existing sign-up/sign-in user flow, for example B2C_1_signupsignin1.

  4. Per Applicazione selezionare webapp1.For Application, select webapp1.

  5. Per URL di risposta scegliere https://jwt.ms.For Reply URL, choose https://jwt.ms.

  6. Selezionare Esegui il flusso utente.Select Run user flow.

    Pagina Esegui il flusso utente per il flusso utente di iscrizione/accesso nel portale di Azure

  7. Completare il processo di accesso.Complete the sign-in process. Verrà eseguito il reindirizzamento a https://jwt.ms.You should be redirected to https://jwt.ms.

  8. Registrare il valore del token codificato visualizzato nel browser.Record the encoded token value displayed in your browser. Questo valore del token viene usato per l'intestazione Authorization in Postman.You use this token value for the Authorization header in Postman.

    Valore del token codificato visualizzato in jwt.ms

Ottenere la chiave di sottoscrizione dell'APIGet API subscription key

Un'applicazione client (in questo caso, Postman) che chiama un'API pubblicata deve includere nelle richieste HTTP all'API una chiave di sottoscrizione di Gestione API valida.A client application (in this case, Postman) that calls a published API must include a valid API Management subscription key in its HTTP requests to the API. Per ottenere una chiave di sottoscrizione da includere nella richiesta HTTP di Postman:To get a subscription key to include in your Postman HTTP request:

  1. Passare all'istanza del servizio Gestione API di Azure nel portale di Azure.Browse to your Azure API Management service instance in the Azure portal.
  2. Selezionare Sottoscrizioni.Select Subscriptions.
  3. Selezionare i puntini di sospensione per Prodotto: Senza limiti e quindi scegliere Mostra/Nascondi chiavi.Select the ellipsis for Product: Unlimited, then select Show/hide keys.
  4. Registrare la CHIAVE PRIMARIA per il prodotto.Record the PRIMARY KEY for the product. Questa chiave viene usata per l'intestazione Ocp-Apim-Subscription-Key nella richiesta HTTP di Postman.You use this key for the Ocp-Apim-Subscription-Key header in your HTTP request in Postman.

Pagina della chiave di sottoscrizione con l'opzione Mostra/Nascondi chiavi selezionata nel portale di Azure

Testare una chiamata API sicuraTest a secure API call

Con il token di accesso e la chiave di sottoscrizione di Gestione API registrati, è ora possibile verificare se l'accesso sicuro all'API è stato configurato correttamente.With the access token and APIM subscription key recorded, you're now ready to test whether you've correctly configured secure access to the API.

  1. Creare una nuova richiesta GET in Postman.Create a new GET request in Postman. Per l'URL della richiesta, specificare l'endpoint dell'elenco dei relatori dell'API pubblicata come prerequisito.For the request URL, specify the speakers list endpoint of the API you published as one of the prerequisites. Ad esempio:For example:

    https://contosoapim.azure-api.net/conference/speakers

  2. Aggiungere quindi le intestazioni seguenti:Next, add the following headers:

    ChiaveKey valoreValue
    Authorization Valore del token codificato registrato in precedenza, con prefisso Bearer (includere lo spazio dopo "Bearer")Encoded token value you recorded earlier, prefixed with Bearer (include the space after "Bearer")
    Ocp-Apim-Subscription-Key Chiave di sottoscrizione di Gestione API registrata in precedenzaAPIM subscription key you recorded earlier

    Intestazioni e URL della richiesta GET vengono visualizzati nel modo seguente:Your GET request URL and Headers should appear similar to:

    Interfaccia utente di Postman in cui sono visualizzati le intestazioni e l'URL della richiesta GET

  3. Selezionare il pulsante Send (Invia) in Postman per eseguire la richiesta.Select the Send button in Postman to execute the request. Se tutti gli elementi sono stati configurati correttamente, viene visualizzata una risposta JSON con una raccolta di relatori (qui visualizzata parzialmente):If you've configured everything correctly, you should be presented with a JSON response with a collection of conference speakers (shown here truncated):

    {
      "collection": {
        "version": "1.0",
        "href": "https://conferenceapi.azurewebsites.net:443/speakers",
        "links": [],
        "items": [
          {
            "href": "https://conferenceapi.azurewebsites.net/speaker/1",
            "data": [
              {
                "name": "Name",
                "value": "Scott Guthrie"
              }
            ],
            "links": [
              {
                "rel": "http://tavis.net/rels/sessions",
                "href": "https://conferenceapi.azurewebsites.net/speaker/1/sessions"
              }
            ]
          },
    [...]
    

Testare una chiamata API non sicuraTest an insecure API call

Dopo che è stata eseguita una richiesta con esito positivo, testare il caso di errore per verificare che le chiamate all'API con un token non valido vengano rifiutate come previsto.Now that you've made a successful request, test the failure case to ensure that calls to your API with an invalid token are rejected as expected. Per eseguire il test, è ad esempio possibile aggiungere o modificare alcuni caratteri nel valore del token e quindi eseguire la stessa richiesta GET come in precedenza.One way to perform the test is to add or change a few characters in the token value, then execute the same GET request as before.

  1. Aggiungere alcuni caratteri al valore del token per simulare un token non valido.Add several characters to the token value to simulate an invalid token. Ad esempio, aggiungere "INVALID" al valore del token:For example, add "INVALID" to the token value:

    Sezione Headers dell'interfaccia utente di Postman con la dicitura INVALID aggiunta al token

  2. Selezionare il pulsante Send (Invia) per eseguire la richiesta.Select the Send button to execute the request. Con un token non valido, il risultato previsto è un codice di stato non autorizzato 401:With an invalid token, the expected result is a 401 unauthorized status code:

    {
        "statusCode": 401,
        "message": "Unauthorized. Access token is missing or invalid."
    }
    

Se viene visualizzato il codice di stato 401, è stato verificato che solo i chiamanti con un token di accesso valido emesso da Azure AD B2C possono eseguire richieste con esito positivo all'API di Gestione API di Azure.If you see the 401 status code, you've verified that only callers with a valid access token issued by Azure AD B2C can make successful requests to your Azure API Management API.

Supportare più applicazioni e autorità emittentiSupport multiple applications and issuers

Diverse applicazioni interagiscono in genere con una sola API REST.Several applications typically interact with a single REST API. Per consentire all'API di accettare token destinati a più applicazioni, aggiungere i relativi ID applicazione all'elemento <audiences> nel criterio in ingresso di Gestione API.To enable your API to accept tokens intended for multiple applications, add their application IDs to the <audiences> element in the APIM inbound policy.

<!-- Accept tokens intended for these recipient applications -->
<audiences>
    <audience>44444444-0000-0000-0000-444444444444</audience>
    <audience>66666666-0000-0000-0000-666666666666</audience>
</audiences>

Analogamente, per supportare più autorità di emissione di token, aggiungere i relativi URI endpoint all'elemento <issuers> nel criterio in ingresso di Gestione API.Similarly, to support multiple token issuers, add their endpoint URIs to the <issuers> element in the APIM inbound policy.

<!-- Accept tokens from multiple issuers -->
<issuers>
    <issuer>https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
    <issuer>https://login.microsoftonline.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
</issuers>

Eseguire la migrazione a b2clogin.comMigrate to b2clogin.com

Se è presente un'API di Gestione API che convalida i token emessi dall'endpoint login.microsoftonline.com legacy, è necessario eseguire la migrazione dell'API e delle applicazioni che la chiamano per usare i token emessi da b2clogin.com.If you have an APIM API that validates tokens issued by the legacy login.microsoftonline.com endpoint, you should migrate the API and the applications that call it to use tokens issued by b2clogin.com.

Per eseguire una migrazione a fasi, è possibile seguire questa procedura generale:You can follow this general process to perform a staged migration:

  1. Nel criterio in ingresso di Gestione API aggiungere il supporto per i token emessi da b2clogin.com e login.microsoftonline.com.Add support in your APIM inbound policy for tokens issued by both b2clogin.com and login.microsoftonline.com.
  2. Aggiornare le applicazioni una alla volta per ottenere i token dall'endpoint b2clogin.com.Update your applications one at a time to obtain tokens from the b2clogin.com endpoint.
  3. Dopo che tutte le applicazioni hanno correttamente ottenuto i token da b2clogin.com, rimuovere dall'API il supporto per i token emessi da login.microsoftonline.com.Once all of your applications are correctly obtaining tokens from b2clogin.com, remove support for login.microsoftonline.com-issued tokens from the API.

L'esempio seguente del criterio in ingresso di Gestione API illustra come accettare i token emessi da b2clogin.com e login.microsoftonline.com.The following example APIM inbound policy illustrates how to accept tokens issued by both b2clogin.com and login.microsoftonline.com. Supporta inoltre le richieste API di due applicazioni.Additionally, it supports API requests from two applications.

<policies>
    <inbound>
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
            <openid-config url="https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/B2C_1_signupsignin1/v2.0/.well-known/openid-configuration" />
            <audiences>
                <audience>44444444-0000-0000-0000-444444444444</audience>
                <audience>66666666-0000-0000-0000-666666666666</audience>
            </audiences>
            <issuers>
                <issuer>https://login.microsoftonline.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
                <issuer>https://<tenant-name>.b2clogin.com/99999999-0000-0000-0000-999999999999/v2.0/</issuer>
            </issuers>
        </validate-jwt>
        <base />
    </inbound>
    <backend> <base /> </backend>
    <outbound> <base /> </outbound>
    <on-error> <base /> </on-error>
</policies>

Passaggi successiviNext steps

Per altre informazioni sui criteri di Gestione API di Azure, vedere l'indice di riferimento dei criteri di Gestione API.For additional details on Azure API Management policies, see the APIM policy reference index.

Per informazioni sulla migrazione delle API Web basate su OWIN e delle relative applicazioni a b2clogin.com, vedere Eseguire la migrazione di un'API Web basata su OWIN a b2clogin.com.You can find information about migrating OWIN-based web APIs and their applications to b2clogin.com in Migrate an OWIN-based web API to b2clogin.com.