Condividi tramite

Come autorizzare la console di test del portale per sviluppatori configurando l'autorizzazione utente OAuth 2.0

  • Articolo

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

Molte API supportano OAuth 2.0 per proteggere l'API e assicurare che solo gli utenti validi siano autorizzati all'accesso e che possano accedere solo 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 token JWT, o nel servizio back-end.

Prerequisiti

  • Un'istanza di Gestione API.
  • 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.

Se non è ancora stata creata un'istanza del servizio Gestione API, vedere Creare un'istanza del servizio Gestione API.

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 di alto livello:

  1. Registrare un'applicazione (app back-end) 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 pre-autorizzare il token di OAuth 2.0 per ogni richiesta in arrivo. È possibile usare il criterio validate-jwt per qualsiasi provider OAuth 2.0.

Questa configurazione supporta il flusso OAuth seguente:

Immagine panoramica per concettualizzare visivamente il flusso 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 i validate-jwt criteri. Per il provider Microsoft Entra ID, Gestione API fornisce anche i validate-azure-ad-token criteri.

  5. In base al risultato della convalida, lo sviluppatore riceverà 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 OAuth 2.0 e degli scenari.

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

Tipo di concessione Descrizione Scenari
Codice di autorizzazione Scambia il codice di autorizzazione per il token App lato server, ad esempio app Web
Codice di autorizzazione + PKCE Miglioramento del flusso del codice di autorizzazione che crea una richiesta di codice inviata con la richiesta di autorizzazione Client pubblici e mobili che non possono proteggere un segreto o un token
Implicito (deprecato) Restituisce immediatamente il token di accesso senza un passaggio di scambio aggiuntivo del codice di autorizzazione Client che non possono proteggere un segreto o un token, ad esempio app per dispositivi mobili e app a pagina singola

Generalmente sconsigliato a causa di rischi intrinseci di restituzione del token di accesso nel reindirizzamento HTTP senza la conferma di ricezione da parte del client
Resource owner password. (Password del proprietario delle risorse.) Richiede le credenziali utente (nome utente e password), in genere usando un modulo interattivo Per l'uso con applicazioni molto attendibili

Usare questo flusso solo quando non è possibile usare altri flussi più sicuri
Credenziali del client Autentica e autorizza un'app anziché un utente Applicazioni da computer a computer che non richiedono le autorizzazioni di un utente specifico per accedere ai dati, ad esempio interfacce della riga di comando, daemon o servizi in esecuzione nel back-end

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 abilita il flusso 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): GUID dell'applicazione che rappresenta l'API back-end
  • Ambiti 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://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
  • ID applicazione client (client): 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

Sarà necessario registrare due applicazioni con il provider OAuth 2.0: una rappresenta l'API back-end da proteggere e la seconda 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 Guida introduttiva: 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 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. Successivamente, si aggiungerà 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 che verrà 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. Scegliere l'app client. Quindi, nel menu laterale selezionare Autorizzazioni API.

  3. Seleziona + Aggiungi un'autorizzazione.

  4. In Selezionare un'API selezionare API personali e quindi trovare e selezionare l'app back-end (la registrazione dell'app per l'API back-end).

  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 laterale del portale per sviluppatori selezionare OAuth 2.0 e OpenID Connect.

  3. Nella scheda OAuth 2.0 selezionare + Aggiungi.

    Menu di OAuth 2.0

  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.

    Nuovo server OAuth 2.0

  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). Ulteriori informazioni

    • Immettere il valore relativo a 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 sarà simile a uno degli URL seguenti, dove {aad-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/{aad-tenant}/oauth2/v2.0/authorize (v2)

      https://login.microsoftonline.com/{aad-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.

    Specificare le impostazioni di autorizzazione

  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, sarà simile a uno degli URL seguenti, dove {aad-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/{aad-tenant}/oauth2/v2.0/token (v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)

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

    • Se si usano endpoint v2:
      * Immettere l'ambito dell'app back-end creato nel campo Ambito predefinito.
      * Impostare il valore per la proprietà accessTokenAcceptedVersion 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

    Aggiungere le credenziali client per il servizio OAuth 2.0

    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, in quanto le modifiche pertinenti, come una modifica dell'ambito, non possono altrimenti propagarsi nel portale e di conseguenza essere usate 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.

Importante

  • La configurazione delle impostazioni di autorizzazione utente OAuth 2.0 per un'API consente a Gestione API di acquisire un token dal server di autorizzazione quando si usa la console di test nel portale di Azure o nel portale per sviluppatori. Le impostazioni del server di autorizzazione vengono aggiunte anche alla definizione e alla documentazione dell'API.
  • Per l'autorizzazione OAuth 2.0 in fase di esecuzione, l'app client deve acquisire e presentare il token ed è necessario configurare la convalida dei token in Gestione API o nell'API back-end. Per un esempio, vedere Proteggere un'API in Gestione API di Azure usando l'autorizzazione OAuth 2.0 con Microsoft Entra ID.

  1. Selezionare API dal menu Gestione API a sinistra.

  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.

    Configurare il server di autorizzazione OAuth 2.0

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. Passare a qualsiasi operazione nell'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.

    Selezionare Autorizzazione del codice di autorizzazione

  6. Quando viene richiesto, accedere al tenant di Microsoft Entra.

    • Se è già stato effettuato 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 criteri di convalida JWT per preautorizzare le richieste

Nella configurazione corrente Gestione API non convalida il token di accesso. Passa solo il token nell'intestazione dell'autorizzazione all'API back-end.

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 .

Il criterio di esempio seguente, quando viene aggiunto alla sezione dei criteri di <inbound>, controlla il valore dell'attestazione del gruppo di destinatari in un token di accesso ottenuto da Microsoft Entra ID visualizzato nell'intestazione dell'autorizzazione. 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 di token JWT, vedere le informazioni di riferimento su validate-jwt. Per convalidare un token JWT fornito dal servizio Microsoft Entra, Gestione API fornisce anche il criterio validate-azure-ad-token.

Contenuto correlato