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

Articolo
04/01/2024

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 Azure Gestione API 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

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 nella 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 illustra un esempio di uso dell'ID Microsoft Entra come provider OAuth 2.0.

Di seguito sono riportati i passaggi di configurazione di alto livello:

Registrare un'applicazione (app back-end) in Microsoft Entra ID per rappresentare l'API.
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.
Configurare la console di test nel portale per sviluppatori per chiamare un'API usando l'autorizzazione utente OAuth 2.0.
Configurare un'API per l'uso di un'autorizzazione utente OAuth 2.0.
Aggiungere un criterio per pre-autorizzare il token di OAuth 2.0 per ogni richiesta in arrivo. È possibile usare i validate-jwt criteri per qualsiasi provider OAuth 2.0.

Questa configurazione supporta il flusso OAuth seguente:

Immagine panoramica per concettualizzare visivamente il flusso seguente.

Il portale per sviluppatori richiede un token dall'ID Microsoft Entra usando le credenziali client-app.
Dopo la convalida, Microsoft Entra ID rilascia il token di accesso/aggiornamento.
Uno sviluppatore (utente del portale per sviluppatori) effettua una chiamata API con l'intestazione di autorizzazione.
Il token viene convalidato usando i validate-jwt criteri in Gestione API da Microsoft Entra ID.
In base al risultato della convalida, lo sviluppatore riceverà la risposta nel portale per sviluppatori.

Tipi di concessione di autorizzazione

Azure Gestione API supporta i tipi di concessione OAuth 2.0 seguenti (flussi). Un tipo di concessione fa riferimento a un modo per 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 Il framework di autorizzazione OAuth 2.0 e i 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 aggiuntivo di scambio 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 In genere non è consigliabile a causa di rischi intrinseci di restituzione del token di accesso nel reindirizzamento HTTP senza confermare che viene ricevuto dal 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 altamente attendibili Deve essere usato 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 CLI, daemon o servizi in esecuzione nel back-end

Considerazioni sulla sicurezza

Si consideri 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 attore 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 gli sviluppatori per 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.

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 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 registrare le informazioni sulla chiave a cui 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 segreto applicazione client: GUID che funge da segreto per l'interazione con l'applicazione client in Microsoft Entra ID

Registrare applicazioni con il server OAuth

Sarà 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 Guida introduttiva: Configurare un'applicazione per esporre un'API Web.

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

Nel portale di Azure, cerca e seleziona Registrazioni app.
Seleziona Nuova registrazione.
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.
Lasciare vuota la sezione URI di reindirizzamento. Successivamente si aggiungerà un URI di reindirizzamento generato nella configurazione di OAuth 2.0 in Gestione API.
Selezionare Registra per creare l'applicazione.
Nella pagina Panoramica dell'app trovare il valore del campo ID applicazione (client) e prenderne nota.
Nella sezione Gestisci del menu laterale selezionare Esporre un’API e impostare l’URI ID applicazione con il valore predefinito. Registrare questo valore per un secondo momento.
Selezionare il pulsante Aggiungi un ambito per visualizzare la pagina Aggiungi un ambito:
1. Immettere un nome ambito per un ambito supportato dall'API , ad esempio Files.Read.
2. In Chi può fornire il consenso? effettuare una selezione per lo scenario, ad esempio Amministrazione e utenti. Selezionare Amministrazione solo per scenari con privilegi più elevati.
3. Immettere Amministrazione nome visualizzato del consenso e Amministrazione descrizione del consenso.
4. Assicurarsi che lo stato dell'ambito Abilitato sia selezionato.
Selezionare il pulsante Aggiungi ambito per creare l'ambito.
Ripetere i due passaggi precedenti per aggiungere tutti gli ambiti supportati dall'API.
Dopo aver creato gli ambiti, prendere nota di essi per l'uso 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.

Nel portale di Azure, cerca e seleziona Registrazioni app.
Seleziona Nuova registrazione.
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.
Nella sezione URI di reindirizzamento selezionare Web e lasciare vuoto il campo URL per il momento.
Selezionare Registra per creare l'applicazione.
Nella pagina Panoramica dell'app trovare il valore del campo ID applicazione (client) e prenderne nota.
Creare un segreto client per l'applicazione da usare 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 scegliere quando deve scadere la chiave.
4. Selezionare Aggiungi.

Quando viene creato il segreto, prendere nota del valore della chiave da usare 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.

Nel portale di Azure, cerca e seleziona Registrazioni app.
Scegliere l'app client. Quindi, nel menu laterale selezionare Autorizzazioni API.
Selezionare + Aggiungi un'autorizzazione.
In Selezionare un'API selezionare API personali e quindi trovare e selezionare l'app back-end.
Selezionare Autorizzazioni delegate, quindi selezionare le autorizzazioni appropriate per l'app back-end.
Selezionare Aggiungi autorizzazioni.

Facoltativamente:

Passare alla pagina delle autorizzazioni API dell'app client.
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

Nel portale di Azure accedere all'istanza di Gestione API.
Nel menu laterale del portale per sviluppatori selezionare OAuth 2.0 + OpenID Connessione.
Nella scheda OAuth 2.0 selezionare + Aggiungi.
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.
Immettere l'URL della pagina Registrazione client, https://contoso.com/loginad esempio . Questa pagina consente agli utenti di creare e gestire i propri account, se il provider OAuth 2.0 supporta la gestione degli account utente. La pagina varia a seconda del provider OAuth 2.0 usato.

Se il provider OAuth 2.0 non dispone della gestione utenti degli account configurati, immettere un URL segnaposto qui, ad esempio l'URL della società o un URL, http://localhostad esempio .
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 dell'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 endpoint sia 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 l'URL dell'endpoint del token, i metodi di autenticazione client, il metodo di invio del token di accesso e l'ambito predefinito.
- Immettere l'URL dell'endpoint del 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 body:
  * 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 della accessTokenAcceptedVersion proprietà su 2 nel manifesto dell'applicazione sia per le registrazioni back-end-app che per le registrazioni client-app.
- Accettare le impostazioni predefinite per i metodi di autenticazione client e il metodo di invio del token di accesso.
In Credenziali client immettere l'ID client e il segreto client ottenuti durante il processo di creazione e configurazione dell'app client.
Dopo aver specificato l'ID client e il segreto client, viene generato l'URIdi 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 è nel 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 dell'app selezionare Autenticazione>+ Aggiungi un Web della piattaforma>e quindi immettere l'URI di reindirizzamento.
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.
Selezionare Crea per salvare il Gestione API configurazione del server di autorizzazione OAuth 2.0.
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 un'API o api per usare questa configurazione.

Importante

La configurazione delle impostazioni di autorizzazione utente OAuth 2.0 per un'API consente 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 Azure Gestione API usando l'autorizzazione OAuth 2.0 con l'ID Microsoft Entra.

Selezionare API dal menu Gestione API a sinistra.
Selezionare il nome dell'API desiderata e selezionare la scheda Impostazioni. Scorrere fino alla sezione Sicurezza e quindi selezionare OAuth 2.0.
Selezionare il server di autorizzazione desiderato nell'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 aver configurato l'API per l'uso di tale server, è possibile testarla passando al portale per sviluppatori e chiamando un'API.

Selezionare Portale per sviluppatori nel menu in alto nella pagina Panoramica dell'istanza di Azure Gestione API.
Passare a qualsiasi operazione nell'API nel portale per sviluppatori.
Selezionare Prova per passare alla console per sviluppatori.
Nella sezione Autorizzazione è presente un nuovo elemento che corrisponde al server di autorizzazione appena aggiunto.
Selezionare Codice di autorizzazione nell'elenco a discesa autorizzazione.
Una volta richiesto, accedere al tenant di Microsoft Entra.
- Se è già stato effettuato l'accesso all'account, potrebbe non essere richiesto.
Dopo l'accesso, alla richiesta viene aggiunta un'intestazione Authorization con un token di accesso da Microsoft Entra ID. Di seguito è riportato un token di esempio abbreviato (con codifica Base64):
```
Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
```
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 finora Gestione API non convalida il token di accesso. Passa solo il token nell'intestazione di autorizzazione all'API back-end.

Per pre-autorizzare 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 lo blocca.

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.

Per altre informazioni sull'uso di OAuth 2.0 e Gestione API, vedere Proteggere un back-end dell'API Web in Azure Gestione API usando l'autorizzazione OAuth 2.0 con Microsoft Entra ID.
Altre informazioni sul flusso del codice di autorizzazione OAuth 2.0 e Microsoft Identity Platform