Proteggere un'API in API Management di Azure usando l'autorizzazione OAuth 2.0 con Microsoft Entra ID

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

In questo articolo verranno illustrati i passaggi generali per configurare l'istanza di Gestione API di Azure per proteggere un'API usando il protocollo OAuth 2.0 con l'ID Entra di Microsoft.

Per una panoramica concettuale dell'autorizzazione api, vedere Autenticazione e autorizzazione per le API in Gestione API.

Prerequisiti

Prima di seguire la procedura descritta in questo articolo, è necessario disporre di:

  • Un'istanza di Gestione API
  • Un'API pubblicata usando l'istanza di Gestione API
  • Un tenant di Microsoft Entra

Panoramica

Seguire questa procedura per proteggere un'API in Gestione API usando l'autorizzazione OAuth 2.0 con Microsoft Entra ID.

  1. Registrare un'applicazione (denominata back-end-app in questo articolo) in Microsoft Entra ID per proteggere l'accesso all'API.

    Per accedere all'API, gli utenti o le applicazioni acquisiranno e presenteranno un token OAuth valido che concede l'accesso a questa app con ogni richiesta API.

  2. Configurare il criterio validate-jwt in Gestione API per convalidare il token OAuth presentato in ogni richiesta API in ingresso. Le richieste valide possono essere passate all'API.

I dettagli sui flussi di autorizzazione OAuth e su come generare i token OAuth necessari non rientrano nell'ambito di questo articolo. In genere, un'app client separata viene usata per acquisire token da Microsoft Entra ID che autorizzano l'accesso all'API. Per i collegamenti ad altre informazioni, vedere Passaggi successivi.

Registrare un'applicazione in Microsoft Entra ID per rappresentare l'API

Usando il portale di Azure, proteggere un'API con l'ID Microsoft Entra registrando prima un'applicazione che rappresenta l'API.

Per informazioni dettagliate sulla registrazione delle app, vedere Guida introduttiva: Configurare un'applicazione per esporre un'API Web.

  1. Nel portale di Azure, cerca e seleziona Registrazioni app.

  2. Seleziona Nuova registrazione.

  3. Quando viene visualizzata la pagina Registra un'applicazione, inserire le informazioni di registrazione dell'applicazione:

    • Nella sezione Nome immettere un nome di applicazione significativo che verrà visualizzato agli utenti dell'app, ad esempio back-end-app.
    • Nella sezione Tipi di account supportati selezionare un'opzione adatta allo scenario.

  4. Lasciare vuota la sezione URI di reindirizzamento.

  5. Selezionare Registra per creare l'applicazione.

  6. Nella pagina Panoramica dell'app trovare il valore del campo ID applicazione (client) e prenderne nota.

  7. Nella sezione Gestisci del menu laterale selezionare Esporre un’API e impostare l’URI ID applicazione con il valore predefinito. Se si sviluppa un'app client separata per ottenere token OAuth 2.0 per l'accesso all'app back-end, registrare questo valore per un secondo momento.

  8. Selezionare il pulsante Aggiungi un ambito per visualizzare la pagina Aggiungi un ambito:

    1. Immettere un nuovo nome di ambito, il nome visualizzato del consenso amministratore e la descrizione del consenso amministratore.
    2. Assicurarsi che lo stato dell'ambito Abilitato sia selezionato.

  9. Selezionare il pulsante Aggiungi ambito per creare l'ambito.

  10. Ripetere i due passaggi precedenti per aggiungere tutti gli ambiti supportati dall'API.

  11. Dopo aver creato gli ambiti, prendere nota di tali ambiti per usarli in un secondo momento.

Configurare criteri di convalida JWT per preautorizzare le richieste

I criteri di esempio seguenti, quando vengono aggiunti alla sezione dei criteri di <inbound>, controllano il valore dell'attestazione del gruppo di destinatari in un token di accesso ottenuto dall'ID Microsoft Entra visualizzato nell'intestazione Authorization. Restituisce un messaggio di errore se il token non è valido. Configurare questo criterio in un ambito di criteri appropriato per lo scenario in uso.

  • Nell'URL openid-config, aad-tenant è l'ID tenant in Microsoft Entra ID. Trovare questo valore nel portale di Azure, ad esempio, nella pagina Panoramica della risorsa Microsoft Entra. L'esempio illustrato presuppone un'app Microsoft Entra a tenant singolo e un endpoint di configurazione v2.
  • Il valore di claim è l'ID client dell'app back-end registrata in Microsoft Entra ID.
<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}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Nota

L'URL openid-config precedente corrisponde all'endpoint v2. Per l'endpoint v1 openid-config, usare https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Per informazioni su come configurare i criteri, vedere Impostare o modificare criteri. Per altre personalizzazioni sulle convalide JWT, vedere le informazioni di riferimento su validate-jwt. Per convalidare un token JWT fornito dal servizio Microsoft Entra, Gestione API fornisce anche i criteri di validate-azure-ad-token.

Flusso di lavoro di autorizzazione

  1. Un utente o un'applicazione acquisisce un token da Microsoft Entra ID con autorizzazioni che concedono l'accesso all'app back-end.

  2. Il token viene aggiunto nell'intestazione Autorizzazione delle richieste API a Gestione API.

  3. Gestione API convalida il token usando il criterio di validate-jwt.

    • Se una richiesta non ha un token valido, Gestione API lo blocca.

    • Se una richiesta è accompagnata da un token valido, il gateway può inoltrare la richiesta all'API.

Passaggi successivi