Come configurare l'autorizzazione utente OAuth 2.0 nella console di test del portale per sviluppatori

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Molte API supportano OAuth 2.0 per garantire che solo gli utenti validi abbiano accesso e limitare gli utenti alle risorse a cui hanno diritto. Per usare la console per sviluppatori interattiva di Gestione API di Azure con tali API, il servizio consente di configurare un provider esterno per l'autorizzazione utente OAuth 2.0.

La configurazione dell'autorizzazione utente OAuth 2.0 nella console di test del portale per sviluppatori offre agli sviluppatori un modo pratico per acquisire un token di accesso OAuth 2.0. Dalla console di test il token viene quindi passato al back-end con la chiamata API. La convalida dei token deve essere configurata separatamente, usando un criterio di convalida JWT o nel servizio back-end.

Prerequisiti

• Creare un'istanza del servizio Gestione API di Azure.
• Un provider OAuth 2.0.

Questo articolo illustra come configurare l'istanza del servizio Gestione API per l'uso dell'autorizzazione OAuth 2.0 nella console di test del portale per sviluppatori, ma non illustra come configurare un provider OAuth 2.0.

Panoramica dello scenario

La configurazione dell'autorizzazione utente OAuth 2.0 in Gestione API abilita solo la console di test del portale per sviluppatori (e la console di test nel portale di Azure) come client per acquisire un token dal server di autorizzazione. La configurazione cambia in base al provider OAuth 2.0, sebbene le procedure siano simili e le informazioni necessarie usate per configurare OAuth 2.0 nell'istanza del servizio Gestione API siano le stesse. Questo articolo mostra un esempio che usa Microsoft Entra ID come provider OAuth 2.0.

Di seguito sono riportati i passaggi di configurazione generali:

1. Registrare un'applicazione (backend-app) in Microsoft Entra ID per rappresentare l'API.

2. Registrare un'altra applicazione (client-app) in Microsoft Entra ID per rappresentare un'applicazione client che deve chiamare l'API, in questo caso la console di test del portale per sviluppatori.

   In Microsoft Entra ID, concedere le autorizzazioni per consentire all'app client di chiamare l'app back-end.

3. Configurare la console di test nel portale per sviluppatori per chiamare un'API usando l'autorizzazione utente OAuth 2.0.

4. Configurare un'API per l'uso di un'autorizzazione utente OAuth 2.0.

5. Aggiungere un criterio per preautorizzare il token OAuth 2.0 per ogni richiesta in ingresso. È possibile usare il criterio validate-jwt per qualsiasi provider OAuth 2.0.

Questa configurazione supporta il flusso OAuth seguente:

1. Il portale per sviluppatori richiede un token a Microsoft Entra ID usando le credenziali client-app.

2. Dopo la convalida, Microsoft Entra ID rilascia il token di accesso/aggiornamento.

3. Uno sviluppatore (utente del portale per sviluppatori) effettua una chiamata API con l'intestazione dell'autorizzazione.

4. Il token viene convalidato con il provider OAuth 2.0 usando la validate-jwt policy. Per il provider Microsoft Entra ID, la Gestione delle API fornisce anche i criteri validate-azure-ad-token.

5. In base al risultato della convalida, lo sviluppatore riceve la risposta nel portale per sviluppatori.

Tipi di concessione di autorizzazione

Gestione API di Azure supporta i tipi di concessione (flussi) OAuth 2.0 seguenti. Un tipo di concessione fa riferimento alla modalità usata da un'applicazione client (in questo contesto, la console di test nel portale per sviluppatori) per ottenere un token di accesso all'API back-end. È possibile configurare uno o più tipi di concessione, a seconda del provider e degli scenari OAuth 2.0.

Di seguito è riportato un riepilogo generale. Per altre informazioni sui tipi di concessione, vedere OAuth 2.0 Authorization Framework e Tipi di concessione OAuth.

Considerazioni sulla sicurezza

Valutare il modo in cui il tipo di concessione genera un token, l'ambito del token e il modo in cui il token può essere esposto. Un token compromesso può essere usato da un soggetto malintenzionato per accedere a risorse aggiuntive all'interno dell'ambito del token.

Quando si configura l'autorizzazione utente OAuth 2.0 nella console di test del portale per sviluppatori:

• Limitare l'ambito del token al minimo necessario per consentire agli sviluppatori di testare le API. Limitare l'ambito alla console di test o alle API interessate. I passaggi per configurare l'ambito del token dipendono dal provider OAuth 2.0. Un esempio è illustrato più avanti in questo articolo usando Microsoft Entra ID.

  A seconda degli scenari, è possibile configurare ambiti di token più o meno restrittivi per altre applicazioni client create per accedere alle API back-end.

• Prestare particolare attenzione se si attiva il flusso delle credenziali client. La console di test nel portale per sviluppatori, quando si usa il flusso Credenziali client, non richiede le credenziali. Un token di accesso potrebbe essere inavvertitamente esposto agli sviluppatori o agli utenti anonimi della console per sviluppatori.

Tenere traccia delle informazioni chiave

In questa esercitazione verrà chiesto di prendere nota di alcune informazioni importanti a cui si dovrà fare riferimento più avanti:

• ID applicazione back-end (client): Il GUID dell'applicazione client che rappresenta l'API del back-end.
• Ambiti dell'applicazione back-end: uno o più ambiti che è possibile creare per accedere all'API. Il formato dell'ambito è api://<Backend Application (client) ID>/<Scope Name> (ad esempio, api://a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/Read)
• ID applicazione client(client): il GUID dell'applicazione che rappresenta il portale per sviluppatori
• Valore del segreto dell'applicazione client: GUID che funge da segreto per l'interazione con l'applicazione client in Microsoft Entra ID

Registrare le applicazioni con il server OAuth

È necessario registrare due applicazioni con il provider OAuth 2.0: uno rappresenta l'API back-end da proteggere e un secondo rappresenta l'applicazione client che chiama l'API, in questo caso, la console di test del portale per sviluppatori.

Di seguito sono riportati alcuni passaggi di esempio che usano Microsoft Entra ID come provider OAuth 2.0. Per informazioni dettagliate sulla registrazione delle app, vedere Configurare un'applicazione per esporre un'API Web.

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

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 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. Successivamente, si aggiunge un URI di reindirizzamento generato nella configurazione di OAuth 2.0 in Gestione API.

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 URI ID applicazione con il valore predefinito. Prendere nota del valore per usarlo in seguito.

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

   1. Specificare un Nome ambito per un ambito supportato dall'API, ad esempio Files.Read.
   2. In Utenti autorizzati al consenso effettuare una selezione in base allo scenario, ad esempio Amministratori e utenti. Selezionare Solo amministratori per gli scenari con privilegi più elevati.
   3. Specificare un Nome visualizzato per il consenso amministratore e una Descrizione del consenso amministratore.
   4. 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, prenderne nota in quanto sarà necessario usarli in un passaggio successivo.

Registrare un'altra applicazione in Microsoft Entra ID per rappresentare un'applicazione client

Registrare ogni applicazione client che chiama l'API come applicazione in Microsoft Entra ID.

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 visualizzato agli utenti dell'app, ad esempio client-app.
   • Nella sezione Tipi di account supportati selezionare un'opzione adatta allo scenario.

4. Nella sezione URI di reindirizzamento selezionare Web e lasciare vuoto il campo URL per il momento.

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. Creare un segreto client per l'applicazione, che verrà usato in un passaggio successivo.

   1. Nella sezione Gestisci del menu laterale selezionare Certificati e segreti.
   2. In Segreti client selezionare + Nuovo segreto client.
   3. In Aggiungi un segreto client specificare una Descrizione e definire la scadenza della chiave.
   4. Selezionare Aggiungi.

Quando viene creato il segreto, prendere nota del valore della chiave in quanto sarà necessario in un passaggio successivo. Non è possibile accedere di nuovo al segreto nel portale.

Concedere le autorizzazioni in Microsoft Entra ID

Dopo aver registrato due applicazioni per rappresentare l'API e la console di test, concedere le autorizzazioni per consentire all'app client di chiamare l'app back-end.

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

2. Scegli l'app client. Quindi, nel menu della barra laterale, in Gestisci selezionare Autorizzazioni API.

3. Seleziona + Aggiungi un'autorizzazione.

4. In Selezionare un'API, selezionare Le mie API e quindi trovare e selezionare l'app di backend (la registrazione dell'app per l'API di backend).

5. Selezionare Autorizzazioni delegate, quindi selezionare le autorizzazioni appropriate per l'app back-end.

6. Selezionare Aggiungi autorizzazioni.

Facoltativamente:

1. Passare alla pagina Autorizzazioni API dell'app client.

2. Selezionare Concedi consenso amministratore per <nome-tenant> per concedere il consenso per conto di tutti gli utenti in questa directory.

Configurare un server autorizzazione OAuth 2.0 in Gestione API

1. Nel portale di Azure accedere all'istanza di Gestione API.

2. Nel menu della barra laterale del portale per sviluppatori selezionare OAuth 2.0 + OpenID Connect.

3. Nella scheda OAuth 2.0 selezionare + Aggiungi.

   

4. Immettere un nome ed eventualmente una descrizione nei campi Nome e Descrizione.

   Nota

   Questi campi identificano il server di autorizzazione OAuth 2.0 all'interno del servizio Gestione API corrente. I valori non provengono dal server OAuth 2.0.

5. Immettere l'URL della pagina di registrazione del client, ad esempio, https://contoso.com/login. Questa pagina consente agli utenti di creare e gestire i propri account, se il provider OAuth 2.0 supporta la gestione degli account da parte degli utenti. La pagina varia a seconda del provider OAuth 2.0 usato.

   Se nel provider OAuth 2.0 non è stata configurata la gestione degli account da parte degli utenti, immettere qui un URL segnaposto, ad esempio l'URL della propria azienda, oppure un URL analogo a http://localhost.

   

6. La sezione successiva del modulo contiene le impostazioni relative a Tipi di concessione di autorizzazione, URL dell'endpoint di autorizzazione e Metodo di richiesta dell'autorizzazione.

   • Selezionare uno o più tipi di concessione di autorizzazione desiderati. Per questo esempio, selezionare Codice di autorizzazione (impostazione predefinita). Per altre informazioni, vedere Tipi di concessione di autorizzazioni.

   • Immettere l'URL dell'endpoint di autorizzazione Authorization endpoint URL. È possibile ottenere l'URL dell'endpoint dalla pagina Endpoint di una delle registrazioni app. Per un'app a tenant singolo in Microsoft Entra ID, questo URL è simile a uno degli URL seguenti, dove <your-tenant> viene sostituito con l'ID del tenant di Microsoft Entra.

     È consigliabile usare l'endpoint v2, tuttavia Gestione API supporta sia gli endpoint v1 che v2.

     https://login.microsoftonline.com/<your-tenant>/oauth2/v2.0/authorize (v2)

     https://login.microsoftonline.com/<your-tenant>/oauth2/authorize (v1)

   • L'impostazione Authorization request method specifica la modalità di invio della richiesta di autorizzazione al server OAuth 2.0. Selezionare POST.

     

7. Specificare i valori per URL dell'endpoint token, Metodi di autenticazione client, Metodo di invio del token di accesso e Ambito predefinito.

   • Immettere l'URL dell'endpoint token. Per un'app a tenant singolo in Microsoft Entra ID, è simile a uno dei seguenti URL, dove <your-tenant> viene sostituito con l'ID del tenant di Microsoft Entra. Usare la stessa versione dell'endpoint (v2 o v1) scelta in precedenza.

     https://login.microsoftonline.com/<your-tenant>/oauth2/v2.0/token (v2)

     https://login.microsoftonline.com/<your-tenant>/oauth2/token (v1)

   • Se si usano endpoint v1, aggiungere un parametro del corpo:
     * Nome: risorsa.
     * Valore: l'app back-end ID applicazione (client).

   • Se si usano gli endpoint v2:
     * Immettere l'ambito dell'app back-end creato nel campo Ambito predefinito.
     * Impostare il valore per la proprietà requestedAccessTokenVersion su 2 nel manifesto dell'applicazione sia per l'app back-end che per le registrazioni dell'app client.

   • Accettare le impostazioni predefinite per Metodi di autenticazione client e Metodo di invio del token di accesso.

8. In Credenziali client specificare i valori per ID client e Segreto client, ottenuti durante il processo di creazione e configurazione dell'app client.

9. Una volta specificati ii valori per ID client e Segreto client, viene generato l'URI di reindirizzamento per il Codice di autorizzazione. Questo URI viene usato per configurare l'URI di reindirizzamento nella configurazione del server OAuth 2.0.

   Nel portale per sviluppatori il suffisso URI presenta il formato seguente:

   • /signin-oauth/code/callback/<authServerName> per il flusso di concessione del codice di autorizzazione
   • /signin-oauth/implicit/callback per il flusso di concessione implicita

   

   Copiare l'URI di reindirizzamento appropriato nella pagina Autenticazione della registrazione dell'app client. Nella registrazione app selezionare Autenticazione>+ Aggiungi una piattaforma>Web quindi immettere l'URI di reindirizzamento.

10. Se Tipi di concessione di autorizzazione è impostato su Password del proprietario della risorsa, la sezione Credenziali password del proprietario della risorsa viene usata per specificare le credenziali; in caso contrario è possibile lasciarla vuota.

11. Selezionare Crea per salvare la configurazione del server di autorizzazione OAuth 2.0 di Gestione API.

12. Ripubblicare il portale per sviluppatori.

    Importante

    Quando si apportano modifiche correlate a OAuth 2.0, assicurarsi di ripubblicare il portale per sviluppatori dopo ogni modifica, ad esempio la modifica dell'ambito, altrimenti non può propagarsi nel portale e successivamente essere usata per provare le API.

Configurare un'API per l'uso di un'autorizzazione utente OAuth 2.0

Dopo aver salvato la configurazione del server OAuth 2.0, configurare una o più API per usare questa configurazione.

1. In API nel menu della barra laterale selezionare API.

2. Selezionare il nome dell'API desiderata e selezionare la scheda Impostazioni. Scorrere verso il basso fino alla sezione Sicurezza e quindi selezionare OAuth 2.0.

3. Selezionare il Server autorizzazione desiderato dall'elenco a discesa e selezionare Salva.

   

Portale per sviluppatori: testare l'autorizzazione utente OAuth 2.0

Dopo aver configurato il server di autorizzazione OAuth 2.0 e l'API per l'uso di tale server, è possibile testare l'autorizzazione passando al portale per sviluppatori e chiamando un'API.

1. Selezionare Portale per sviluppatori nel menu in alto dalla pagina Panoramica dell'istanza di Gestione API di Azure.

2. Accedere a qualsiasi operazione via API nel portale per sviluppatori.

3. Selezionare Prova per passare alla console per sviluppatori.

4. Nella sezione Autorizzazione è presente un nuovo elemento che corrisponde al server di autorizzazione appena aggiunto.

5. Selezionare Codice di autorizzazione nell'elenco a discesa Autorizzazione.

   

6. Quando ti viene richiesto, effettua l'accesso al tenant Microsoft Entra.

   • Se si è già eseguito l'accesso all'account, è possibile che la richiesta non venga visualizzata.

7. Dopo l'accesso, alla richiesta viene aggiunta un'intestazione Authorization con un token di accesso di Microsoft Entra ID. Di seguito è riportato un token di esempio abbreviato (con codifica Base64):

   Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
   

8. Configurare i valori desiderati per i parametri rimanenti e selezionare Invia per chiamare l'API.

Configurare un criterio di convalida JWT per preautorizzare le richieste

Nella configurazione corrente Gestione API non convalida il token di accesso. Passa solo il token nell'header di autorizzazione all'API di backend.

Per preautorizzare le richieste, configurare un criterio validate-jwt per convalidare il token di accesso di ogni richiesta in ingresso. Se una richiesta non ha un token valido, Gestione API la blocca. Quando si usa il provider Microsoft Entra ID, è anche possibile usare i criteri validate-azure-ad-token.

I criteri di esempio seguenti, se aggiunti alla sezione dei criteri <inbound>, controllano il valore della dichiarazione del destinatario in un token di accesso ottenuto da Microsoft Entra ID presentato nell'intestazione dell'autorizzazione. Restituisce un messaggio di errore se il token non è valido. Configurare questi criteri in un ambito criteri appropriato per lo scenario.

• Nell'URL openid-config, aad-tenant è l'ID tenant in Microsoft Entra ID. Trova questo valore nel portale di Azure, ad esempio, nella pagina Panoramica della tua 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>

Per informazioni su come configurare i criteri, vedere Impostare o modificare criteri. Consultare il riferimento a validate-jwt per ulteriori personalizzazioni delle convalide dei token JWT. Per convalidare un token JWT fornito dal servizio Microsoft Entra, Gestione API fornisce anche il criterio validate-azure-ad-token.

Contenuto correlato

• Proteggere un'API in API Management di Azure usando l'autorizzazione OAuth 2.0 con Microsoft Entra ID
• Piattaforma di identità Microsoft e flusso del codice di autorizzazione OAuth 2.0