Autorizzare l'accesso alle API nel centro API

Configurare le impostazioni per autorizzare l'accesso alle API nel centro API. Queste impostazioni:

• Abilitare l'autenticazione e l'autorizzazione api usando chiavi API, autorizzazione OAuth 2.0 o un altro schema di sicurezza HTTP
• Associare le configurazioni di autenticazione alle versioni dell'API nell'inventario
• Gestire l'accesso alle versioni api per utenti o gruppi designati tramite criteri di accesso
• Abilitare gli utenti autorizzati a testare le API nel portale di Centro API

Prerequisiti

• Un centro API nella sottoscrizione di Azure. Se non ne è stato creato uno, vedere Guida introduttiva: Creare il centro API.

• Almeno un'API registrata nel centro API. Consulta Esercitazione: Registrare le API nell'inventario delle API.

• Ambiente e distribuzione configurati per l'API. Vedere Esercitazione: Aggiungere ambienti e distribuzioni per le API.

• Configurazione del portale di Centro API. Vedere Configurare il portale di Centro API.

• Un vault di chiavi di Azure per archiviare le chiavi API o i segreti client OAuth 2.0. Vedere Creare un insieme di credenziali delle chiavi. Il Key Vault deve utilizzare il modello di autorizzazione basato sui ruoli (RBAC) di Azure.

• (Per OAuth 2.0 con MICROSOFT Entra ID) Autorizzazioni per creare una registrazione dell'app in un tenant di Microsoft Entra associato alla sottoscrizione.

Opzione 1: Configurare l'autenticazione della chiave API

Per un'API che supporta l'autenticazione con chiave API, completare la procedura seguente.

1. Archiviare la chiave API in Azure Key Vault

Per archiviare la chiave API come segreto in Key Vault, vedere Impostare e recuperare il segreto in Key Vault.

Accedere al Key Vault usando l'identità gestita del Centro API.

Abilitare un'identità gestita nel centro API

Per questo scenario, il centro API usa un'identità gestita per accedere alle risorse di Azure. A seconda delle esigenze, abilitare un'identità gestita assegnata dal sistema o una o più identità gestite assegnate dall'utente.

Gli esempi seguenti illustrano come abilitare un'identità gestita assegnata dal sistema usando il portale di Azure o l'interfaccia della riga di comando di Azure. A livello generale, i passaggi di configurazione sono simili per un'identità gestita assegnata dall'utente.

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Assegnare l'identità gestita al ruolo Utente di Segreti di Key Vault

Per consentire l'importazione degli asset, assegna l'identità gestita del centro API al ruolo Utente dei segreti di Key Vault nel tuo Azure Key Vault. È possibile usare il portale o l'interfaccia della riga di comando di Azure.

2. Aggiungere la configurazione della chiave API

1. Nel portale vai al centro API.

2. In Governance selezionare Autorizzazione (anteprima)>+ Aggiungi configurazione.

3. Nella pagina Aggiungi configurazione impostare i valori seguenti:

   impostazione	Descrizione
   Titolo	Immettere un nome per l'autorizzazione.
   Descrizione	Facoltativamente, immettere una descrizione per l'autorizzazione.
   Schema di sicurezza	Selezionare Chiave API.
   Percorso della chiave API	Selezionare la modalità di presentazione della chiave nelle richieste API. I valori disponibili sono Header (intestazione richiesta) e Query (parametro di query).
   Nome del parametro della chiave API	Immettere il nome dell'intestazione HTTP o del parametro di query che contiene la chiave API. Esempio: x-api-key
   Informazioni di riferimento sul segreto dell'insieme di credenziali delle chiavi API	Seleziona e scegli la sottoscrizione, la cassaforte delle chiavi e il segreto che hai archiviato. Esempio: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

4. Fare clic su Crea.

Dopo aver completato questa configurazione, passare alla sezione Aggiungere la configurazione di autenticazione a una versione dell'API per associare la configurazione della chiave API a una versione dell'API.

Opzione 2: Configurare l'autorizzazione OAuth 2.0

Per un'API che supporta l'autorizzazione OAuth 2.0, completare la procedura seguente. È possibile configurare uno o entrambi i flussi seguenti:

• Flusso del codice di autorizzazione con PKCE (Proof Key for Code Exchange): autenticare gli utenti nel browser, ad esempio nel portale di Centro API.
• Flusso delle credenziali client : per le applicazioni che non richiedono le autorizzazioni di un utente specifico.

1. Creare un'app OAuth 2.0

Creare una registrazione dell'applicazione in un fornitore di identità, come il tenant di Microsoft Entra associato al tuo abbonamento. I passaggi dipendono dal fornitore di identità.

L'esempio seguente illustra come creare una registrazione dell'app in Microsoft Entra ID.

1. Accedere al portale di Azure con autorizzazioni sufficienti nel tenant.
2. Passare a Microsoft Entra ID>+ Nuova registrazione.
3. Nella pagina Registra un'applicazione :
   1. In Nome immettere un nome significativo.
   2. In Tipi di account supportati selezionare un'opzione appropriata, ad esempio Account solo in questa directory organizzativa (tenant singolo).
   3. (Per il flusso del codice di autorizzazione) In URI di reindirizzamento selezionare Applicazione a pagina singola (SPA) e immettere l'URI del portale del Centro API: https://<service-name>.portal.<location>.azure-api-center.ms. Sostituire <service-name> e <location> con il nome del centro API e il percorso di distribuzione. Esempio: https://myapicenter.portal.eastus.azure-api-center.ms
   4. Selezionare Registrazione.
4. In Gestisci selezionare Certificati e segreti>+ Nuovo segreto client.
   1. Immettere una descrizione.
   2. Selezionare un'opzione per Scadenza.
   3. Seleziona Aggiungi.
   4. Copiare il valore del segreto client prima di uscire dalla pagina. È necessario nella sezione successiva.
5. Facoltativamente, aggiungere ambiti API nella registrazione dell'app. Vedere Configurare un'applicazione per esporre un'API Web.

Quando si configura OAuth 2.0 nel centro API, sono necessari i valori seguenti dalla registrazione dell'app:

• ID dell'applicazione cliente dalla pagina Panoramica e il segreto del cliente che hai copiato.
• Gli URL dell'endpoint seguenti da Panoramica>Endpoint:
  • Endpoint di autorizzazione OAuth2.0 (v2)
  • Endpoint del token OAuth 2.0 (v2) (utilizzato anche come endpoint di rigenerazione del token)
• Tutti gli ambiti API configurati.

Passaggio 2: Archiviare il segreto in Azure Key Vault

Per archiviare il segreto del client in Azure Key Vault, vedere Configura e recupera il segreto in Azure Key Vault.

Accedere al Key Vault usando l'identità gestita del Centro API.

Abilitare un'identità gestita nel centro API

Per questo scenario, il centro API usa un'identità gestita per accedere alle risorse di Azure. A seconda delle esigenze, abilitare un'identità gestita assegnata dal sistema o una o più identità gestite assegnate dall'utente.

Gli esempi seguenti illustrano come abilitare un'identità gestita assegnata dal sistema usando il portale di Azure o l'interfaccia della riga di comando di Azure. A livello generale, i passaggi di configurazione sono simili per un'identità gestita assegnata dall'utente.

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Assegnare l'identità gestita al ruolo Utente di Segreti di Key Vault

Per consentire l'importazione degli asset, assegna l'identità gestita del centro API al ruolo Utente dei segreti di Key Vault nel tuo Azure Key Vault. È possibile usare il portale o l'interfaccia della riga di comando di Azure.

3. Aggiungere la configurazione di OAuth 2.0

1. Nel portale vai al centro API.

2. In Governance selezionare Autorizzazione (anteprima)>+ Aggiungi configurazione.

3. Nella pagina Aggiungi configurazione impostare i valori seguenti:

   

   Annotazioni

   Usare i valori della registrazione dell'app creata in precedenza. Per Microsoft Entra ID, trovare l'IS del client nella pagina Panoramica della registrazione dell'app e gli endpoint URL nelle sezioni Panoramica> e Endpoint.

   impostazione	Descrizione
   Titolo	Immettere un nome per l'autorizzazione.
   Descrizione	Facoltativamente, immettere una descrizione per l'autorizzazione.
   Schema di sicurezza	Selezionare OAuth2.
   Client ID	Immettere l'ID client (GUID) dell'app creata nel provider di identità.
   Segreto del cliente	Selezionare la sottoscrizione, il Key Vault e il segreto del client archiviati. Esempio: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
   URL di autorizzazione	Immettere l'endpoint di autorizzazione OAuth 2.0 per il provider di identità. Esempio per Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
   URL del token	Immettere l'endpoint del token OAuth 2.0 per il provider di identità. Esempio per Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Aggiornare l'URL	Immettere l'endpoint di aggiornamento del token OAuth 2.0 per il provider di identità. Per la maggior parte dei provider, uguale all'URL del token Esempio per Microsoft Entra ID: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
   Flusso OAuth2	Selezionare uno o entrambi i flussi OAuth 2.0: Codice di autorizzazione (PKCE) e Credenziali client.
   Ambiti	Immettere uno o più ambiti API configurati per l'API, separati da spazi. Se non sono configurati ambiti, immettere .default.

4. Selezionare Crea per salvare la configurazione.

Dopo aver completato questa configurazione, passare alla sezione Aggiungere la configurazione di autenticazione a una versione dell'API per associare la configurazione OAuth 2.0 a una versione dell'API.

Opzione 3: Configurare le impostazioni per un altro schema di sicurezza HTTP

Per le API che usano un altro schema di sicurezza HTTP, ad esempio l'autenticazione di base o i token di connessione che non usano OAuth 2.0, completare i passaggi seguenti. Potrebbe essere necessario scegliere questa opzione per le API legacy.

Nel portale vai al centro API.

1. In Governance selezionare Autorizzazione (anteprima)>+ Aggiungi configurazione.

2. Nella pagina Aggiungi configurazione impostare i valori seguenti:

   impostazione	Descrizione
   Titolo	Immettere un nome per l'autorizzazione.
   Descrizione	Facoltativamente, immettere una descrizione per l'autorizzazione.
   Schema di sicurezza	Selezionare HTTP.
   Schema di autenticazione	Selezionare lo schema di autenticazione usato dall'API. Gli esempi includono gli schemi nella tabella seguente.

   Schema di autenticazione	Descrizione
   Basic	Invia username:password come stringa con codifica Base64 nell'intestazione Authorization: Basic <credentials> .
   Portatore	Invia un token diverso da un token di accesso OAuth 2.0 nell'intestazione Authorization: Bearer <token> .
   Digest	Un meccanismo di challenge-response in cui il server invia un nonce; il client risponde con un hash delle credenziali e del nonce.
   Personalizzato	Un altro schema di meccanismo, ad esempio uno schema specifico del fornitore.

Dopo aver completato questa configurazione, passare alla sezione successiva per associare la configurazione a una versione dell'API.

Aggiungere la configurazione di autenticazione a una versione dell'API

Dopo aver configurato uno schema di autenticazione, associare la configurazione a una versione dell'API.

1. Nel portale vai al centro API.

2. In Inventario selezionare Asset.

3. Selezionare l'API a cui associare la configurazione.

4. In Dettagli selezionare Versioni e quindi selezionare la versione dell'API di destinazione.

5. Nel menu di scelta rapida per la versione dell'API selezionare Gestisci accesso (anteprima).

6. Nella pagina Gestisci accesso selezionare + Aggiungi autenticazione.

7. Selezionare una configurazione di autenticazione disponibile.

8. Fare clic su Crea.

Gestire l'accesso per utenti o gruppi specifici

Configurare un criterio di accesso che assegna utenti o gruppi al ruolo Lettore di accesso alle credenziali del Centro API , con ambito per configurazioni di autenticazione specifiche in una versione dell'API. Questo ruolo consente solo agli utenti designati di testare un'API nel portale di Centro API.

1. Nel portale vai al centro API.

2. Passare a una versione dell'API con una configurazione di autenticazione.

3. Selezionare Gestisci accesso (anteprima).

4. Selezionare una configurazione di autenticazione da gestire.

5. Nel menu a discesa selezionare Modifica criteri di accesso.

6. Nella pagina Gestisci accesso selezionare + Aggiungi > utenti o + Aggiungi > gruppi.

7. Cercare e selezionare utenti o gruppi. È possibile selezionare più elementi.

8. Seleziona Seleziona.

Testare l'API nel portale di Centro API

Testare un'API configurata per l'autenticazione e l'accesso utente.

1. Nel portale vai al centro API.

2. In Portale di Centro API selezionare Impostazioni> portaleVisualizza portale del Centro API.

3. Selezionare un'API e quindi selezionare una versione con un metodo di autenticazione configurato.

4. In Opzioni selezionare Visualizza documentazione.

5. Selezionare un'operazione, quindi selezionare Prova questa API.

6. Esaminare le impostazioni di autenticazione. Se si ha accesso, selezionare Invia.

7. Un'operazione riuscita restituisce un codice di risposta e un 200 OK corpo della risposta. Un'operazione non riuscita restituisce un messaggio di errore.

Contenuti correlati

• Configurare il portale di Centro API
• Abilitare la visualizzazione del portale del Centro API di Azure in Visual Studio Code
• Autenticazione e autorizzazione alle API in Gestione API di Azure