Autorizzare l'accesso alle API nel centro API

È possibile configurare le impostazioni per autorizzare l'accesso alle API nel centro API. Queste impostazioni:

• Abilitare l'autenticazione API usando chiavi API o autorizzazione OAuth 2.0
• Associare metodi di autenticazione specifici a versioni API specifiche nell'inventario
• Gestire l'autenticazione alle versioni api da utenti o gruppi designati tramite criteri di accesso
• Abilitare gli utenti autorizzati a testare le API direttamente nel portale di Centro API

Annotazioni

Questa funzionalità è attualmente disponibile solo in anteprima.

Prerequisiti

• Un centro API nella sottoscrizione di Azure. Se non ne è già stato creato uno, vedere Avvio rapido: Creare il centro API.

• Registrare almeno un'API nel centro API. Per altre informazioni, vedere Esercitazione: Registrare le API nell'inventario API.

• Configurare un ambiente e una distribuzione per l'API. Per altre informazioni, vedere Esercitazione: Aggiungere ambienti e distribuzioni per le API.

• Configurare il portale di Centro API. Per altre informazioni, 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. Per creare l'insieme di credenziali delle chiavi, vedere Creare un insieme di credenziali delle chiavi. Il vault delle chiavi deve usare il modello di autorizzazione di Azure basato sul controllo degli accessi in base al ruolo (RBAC).

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

Opzione 1: Configurare le impostazioni per l'autenticazione con chiave API

Per un'API che supporta l'autenticazione con chiave API, seguire questa procedura per configurare le impostazioni nel centro API.

1. Archiviare la chiave API in Azure Key Vault

Per gestire la chiave API in modo sicuro, memorizzala in Azure Key Vault e accedi all'archivio chiavi utilizzando l'identità gestita del centro API.

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

Abilitare un'identità gestita nel centro API

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

L'esempio seguente illustra come abilitare un'identità gestita assegnata dal sistema usando il portale di Azure. A livello generale, i passaggi di configurazione sono simili per un'identità gestita assegnata dall'utente.

1. Nel portale, passare al centro API.
2. Nel menu a sinistra, in Sicurezzaselezionare Identità gestite.
3. Selezionare Sistema assegnato e impostare lo stato su Sì.
4. Seleziona Salva.

Assegnare il ruolo Utente di Segreti di Key Vault all'identità gestita

Assegnare l'identità gestita del centro API al ruolo Utente segreti di Key Vault nell'insieme di credenziali delle chiavi. Nei passaggi seguenti viene usato il portale di Azure.

1. Nel portale passare all'insieme di credenziali delle chiavi.
2. Nel menu a sinistra selezionare Controllo di accesso (IAM).
3. Selezionare + Aggiungi assegnazione di ruolo.
4. Nella pagina Aggiungi assegnazione di ruolo, impostare i valori come segue:
   1. Nella scheda Ruolo, selezionare Utente dei segreti Key Vault.
   2. Nella scheda Membri, in Assegna accesso a, selezionare Identità> gestita+ Seleziona membri.
   3. Nella pagina Seleziona identità gestite selezionare l'identità gestita assegnata dal sistema del centro API aggiunto nella sezione precedente. Fare clic su Seleziona.
   4. Selezionare nuovamente Rivedi + assegna.

2. Aggiungere la configurazione della chiave API nel centro API

1. Nel portale, passare al centro API.

2. Nel menu a sinistra, in Governance selezionare Autorizzazione (anteprima)>+ Aggiungi configurazione.

3. Nella pagina Aggiungi configurazione impostare i valori come indicato di seguito:

   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	Fare clic su Seleziona e seleziona la sottoscrizione, il Key Vault e il segreto che hai archiviato. Esempio: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

4. Fare clic su Crea.

Opzione 2: Configurare le impostazioni per l'autorizzazione OAuth 2.0

Per un'API che supporta l'autorizzazione OAuth 2.0, seguire questa procedura per configurare le impostazioni di autenticazione nel centro API. È possibile configurare le impostazioni per uno o entrambi i flussi di autorizzazione OAuth 2.0 seguenti:

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

1. Creare un'app OAuth 2.0

Per l'autorizzazione OAuth 2.0, creare una registrazione dell'app in un provider di identità, ad esempio il tenant di Microsoft Entra associato alla sottoscrizione di Azure. I passaggi di creazione esatti dipendono dal provider di identità usato.

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

1. Accedere al portale di Azure con un account con autorizzazioni sufficienti nel tenant.
2. Passare a Microsoft Entra ID>+ Nuova registrazione.
3. Nella pagina Registra un'applicazione immettere le impostazioni di registrazione dell'applicazione:
   1. In Nome immettere un nome significativo per l'app.
   2. In Tipi di account supportatiselezionare un'opzione adatta allo scenario, 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 impostare l'URI. Immettere l'URI della distribuzione del portale di Centro API nel formato seguente: https://<service-name>.portal.<location>.azure-api-center.ms. Sostituire <service name> e <location> con il nome del centro API e il percorso in cui è distribuito, esempio: https://myapicenter.portal.eastus.azure-api-center.ms
   4. Selezionare Registrazione.
4. Nel menu a sinistra, in Gestisci, selezionare Certificati e segreti e quindi selezionare + 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. Sarà necessario nella sezione seguente.
5. Facoltativamente, aggiungere ambiti API nella registrazione dell'app. Per altre informazioni, vedere Configurare un'applicazione per esporre un'API Web.

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

• ID applicazione (client) dalla pagina Panoramica della registrazione dell'app e il Segreto client copiato in precedenza.
• Gli URL di endpoint seguenti nella pagina Panoramica>Endpoint della registrazione dell'app:
  • Endpoint di autorizzazione OAuth2.0 (v2): endpoint di autorizzazione per l'ID Microsoft Entra
  • Endpoint del token OAuth 2.0 (v2): l'endpoint del token e l'endpoint di aggiornamento del token per Microsoft Entra ID
• Tutti gli ambiti api configurati nella registrazione dell'app.

Passaggio 2: Archiviare il segreto in Azure Key Vault

Per gestire il segreto in modo sicuro, conservalo in Azure Key Vault e accedi a Key Vault utilizzando l'identità gestita del tuo centro API.

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

Abilitare un'identità gestita nel centro API

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

L'esempio seguente illustra come abilitare un'identità gestita assegnata dal sistema usando il portale di Azure. A livello generale, i passaggi di configurazione sono simili per un'identità gestita assegnata dall'utente.

1. Nel portale, passare al centro API.
2. Nel menu a sinistra, in Sicurezzaselezionare Identità gestite.
3. Selezionare Sistema assegnato e impostare lo stato su Sì.
4. Seleziona Salva.

Assegnare il ruolo Utente di Segreti di Key Vault all'identità gestita

Assegnare l'identità gestita del centro API al ruolo Utente segreti di Key Vault nell'insieme di credenziali delle chiavi. Nei passaggi seguenti viene usato il portale di Azure.

1. Nel portale passare all'insieme di credenziali delle chiavi.
2. Nel menu a sinistra selezionare Controllo di accesso (IAM).
3. Selezionare + Aggiungi assegnazione di ruolo.
4. Nella pagina Aggiungi assegnazione di ruolo, impostare i valori come segue:
   1. Nella scheda Ruolo, selezionare Utente dei segreti Key Vault.
   2. Nella scheda Membri, in Assegna accesso a, selezionare Identità> gestita+ Seleziona membri.
   3. Nella pagina Seleziona identità gestite selezionare l'identità gestita assegnata dal sistema del centro API aggiunto nella sezione precedente. Fare clic su Seleziona.
   4. Selezionare nuovamente Rivedi + assegna.

3. Aggiungere l'autorizzazione OAuth 2.0 nel centro API

1. Nel portale, passare al centro API.

2. Nel menu a sinistra, in Governance selezionare Autorizzazione (anteprima)>+ Aggiungi configurazione.

3. Nella pagina Aggiungi configurazione impostare i valori come segue:

   

   Annotazioni

   Configurare le impostazioni in base alla registrazione dell'app creata in precedenza nel provider di identità. Se stai usando Microsoft Entra ID, trova l'ID client nella pagina Panoramica della registrazione dell'app e trova gli endpoint URL nella pagina Panoramica>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 presso il tuo provider di identità.
   Segreto del cliente	Fare clic su Seleziona e selezionare l'abbonamento, 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 da usare. I valori disponibili sono 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.

Aggiungere la configurazione di autenticazione a una versione dell'API

Dopo aver configurato le impostazioni per una chiave API o un flusso OAuth 2.0, aggiungere la chiave API o la configurazione OAuth 2.0 a una versione api nel centro API.

1. Nel portale, passare al centro API.
2. Nel menu a sinistra, in Assetselezionare API.
3. Selezionare un'API a cui si vuole associare la configurazione dell'autorizzazione.
4. Nel menu a sinistra, in Dettagli, selezionare Versioni.
5. Selezionare la versione dell'API a cui si vuole aggiungere la configurazione di autenticazione.
6. Nel menu a sinistra, in Dettagli, selezionare Gestisci accesso (anteprima)>+ Aggiungi autenticazione.
7. Nella pagina Aggiungi autenticazione selezionare una configurazione di autenticazione disponibile da associare.
8. Fare clic su Crea.

Annotazioni

È possibile aggiungere più configurazioni di autenticazione a una versione dell'API. Ad esempio, è possibile aggiungere sia la chiave API che le configurazioni OAuth 2.0 alla stessa versione dell'API, se supportata dall'API. Analogamente, è possibile aggiungere le stesse configurazioni a più versioni dell'API.

Gestire l'accesso da utenti o gruppi specifici

È possibile gestire l'accesso da utenti o gruppi specifici dell'organizzazione alla configurazione di autenticazione di una versione dell'API. Lo fai configurando un criterio di accesso che assegna agli utenti o ai gruppi il ruolo Lettore accesso credenziali del Centro API, con ambito limitato a configurazioni di autenticazione specifiche della versione dell'API. Ciò è utile, ad esempio, se si vuole consentire solo a utenti specifici di testare un'API nel portale di Centro API usando una chiave API o un flusso OAuth 2.0.

1. Nel portale, passare al centro API.

2. Passare a una versione dell'API a cui è stata aggiunta una configurazione di autenticazione (vedere la sezione precedente).

3. Nel menu a sinistra, in Dettagli, selezionare Gestisci accesso (anteprima).

4. Selezionare l'elenco a discesa Modifica criteri di accesso alla fine della riga per la configurazione di autenticazione di cui si vuole gestire l'accesso.

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

6. Cercare e selezionare gli utenti (o i gruppi) da aggiungere. È possibile selezionare più elementi.

7. Fare clic su Seleziona.

Suggerimento

È anche possibile rimuovere utenti o gruppi dai criteri di accesso. Nella pagina Gestisci accesso selezionare Elimina nel menu di scelta rapida (...) per l'utente o il gruppo.

Testare l'API nel portale del Centro API

È possibile usare il portale di Centro API per testare un'API configurata per l'autenticazione e l'accesso degli utenti.

Suggerimento

Oltre ad abilitare utenti specifici per testare API specifiche nel portale di Centro API, è possibile configurare le impostazioni di visibilità per le API. Le impostazioni di visibilità nel portale controllano le API visualizzate per tutti gli utenti connessi.

1. Nel portale, passare al centro API.

2. Nel menu a sinistra, in Portale del Centro API selezionare Impostazioni del portale.

3. Selezionare Visualizza portale del Centro API.

4. Nel portale di Centro API selezionare un'API da testare.

5. Selezionare una versione dell'API con un metodo di autenticazione configurato.

6. In Opzioni selezionare Visualizza documentazione.

7. Selezionare un'operazione nell'API e selezionare Prova questa API.

8. Nella finestra visualizzata esaminare le impostazioni di autenticazione. Se si ha accesso all'API, selezionare Invia per provare l'API.

9. Se l'operazione ha esito positivo, viene visualizzato il 200 OK codice di risposta e il corpo della risposta. Se l'operazione non riesce, viene visualizzato 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