Autorizzare gli account per sviluppatori utilizzando Microsoft Entra ID in Gestione API di Azure

Articolo
03/22/2024

In questo articolo si apprenderà come:

Abilitare l'accesso al portale per sviluppatori per gli utenti da Microsoft Entra ID.
Gestire gruppi di utenti di Microsoft Entra aggiungendo gruppi esterni che contengono gli utenti.

Per una panoramica delle opzioni per proteggere il portale per sviluppatori, vedere Proteggere l'accesso al portale per sviluppatori di Gestione API.

Importante

Questo articolo è stato aggiornato con la procedura per configurare un'app Microsoft Entra usando la libreria di autenticazione Microsoft (MSAL).
Se in precedenza è stata configurata un'app Microsoft Entra per l'accesso utente usando la libreria Autenticazione di Azure AD (ADAL), è consigliabile eseguire la migrazione a MSAL.

Prerequisiti

Completare l'avvio rapido Creare un'istanza di Gestione API di Azure.
Importare e pubblicareun'API in un'istanza di Gestione API di Azure.

Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere la Avvio rapido di Bash in Azure Cloud Shell.
Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
- Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
- Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
- Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

SI APPLICA A: Sviluppatore | Standard | Premium

Passare all'istanza di Gestione API

Nel portale di Azure, cercare e selezionare Servizi Gestione API.
Nella pagina Servizi Gestione API selezionare l'istanza di Gestione API.

Per semplificare la configurazione, Gestione API può abilitare automaticamente un'applicazione Microsoft Entra e un provider di identità per gli utenti del portale per sviluppatori. In alternativa, è possibile abilitare manualmente l'applicazione Microsoft Entra e il provider di identità.

Abilitare automaticamente l'applicazione Microsoft Entra e il provider di identità

Nel menu a sinistra dell'istanza di Gestione API, in Portale per sviluppatoriselezionare Panoramica del portale.
Nella pagina Panoramica del portale scorrere verso il basso fino a Abilita accesso utente con Microsoft Entra ID.
Selezionare Abilita Microsoft Entra ID.
Nella pagina Abilita Microsoft Entra ID selezionare Abilita Microsoft Entra ID.
Selezionare Chiudi.

Dopo l'abilitazione del provider Microsoft Entra:

Gli utenti nell'istanza di Microsoft Entra specificata possono accedere al portale per sviluppatori usando un account Microsoft Entra.
È possibile gestire la configurazione di Microsoft Entra nella pagina Portale per sviluppatori>Identità nel portale.
Facoltativamente, configurare altre impostazioni di accesso selezionando Identità>Impostazioni. Ad esempio, è possibile reindirizzare gli utenti anonimi alla pagina di accesso.
Ripubblicare il portale per sviluppatori dopo qualsiasi modifica della configurazione.

Abilitare manualmente l'applicazione Microsoft Entra e il provider di identità

Nel menu a sinistra dell'istanza di Gestione API, in Portale per sviluppatoriselezionare Identità.
Selezionare +Aggiungi nella parte superiore per aprire il riquadro Aggiungi provider di identità a destra.
In Tipo selezionare Microsoft Entra ID dal menu a discesa. Dopo la selezione, sarà possibile immettere altre informazioni necessarie.
- Nell'elenco a discesa Libreria client selezionare MSAL.
- Per aggiungere ID client e Segreto client, vedere i passaggi più avanti nell'articolo.
Salvare l'URL di reindirizzamento per un secondo momento.
Nota

Esistono due URL di reindirizzamento:
- L'URL di reindirizzamento punta al portale per sviluppatori più recente di Gestione API.
- L'URL di reindirizzamento (portale deprecato) punta al portale per sviluppatori deprecato di Gestione API.
È consigliabile usare l'URL di reindirizzamento più recente del portale per sviluppatori.
Nel browser aprire il portale di Azure in una nuova scheda.
Passare a Registrazioni app per registrare un'app in Active Directory.
Seleziona Nuova registrazione. Nella pagina Registra un'applicazione impostare i valori come segue:
- Impostare Nome su un nome significativo, ad esempio portale per sviluppatori
- Impostare Tipi di account supportati su Account in qualsiasi directory organizzativa.
- In URI di reindirizzamento, selezionare Applicazione a pagina singola e incollare l'URL di reindirizzamento salvato da un passaggio precedente.
- Selezionare Registra.
Dopo aver registrato l'applicazione, copiare l'ID applicazione (client) dalla pagina Panoramica.
Passare alla scheda del browser con l'istanza di Gestione API.
Nella finestra Aggiungi provider di identità incollare il valore di ID applicazione (client) nella casella ID client.
Passare alla scheda del browser con la registrazione dell'app.
Selezionare la registrazione dell'app appropriata.
Nella sezione Gestisci del menu laterale selezionare Certificati e segreti.
Nella pagina Certificati e segreti, selezionare il pulsante Nuovo segreto client in Segreti client.
- Compilare il campo Descrizione.
- Selezionare un'opzione per Scadenza.
- Scegliere Aggiungi.
Copiare il valore del segreto client prima di uscire dalla pagina. Sarà necessario più avanti.
In Gestisci nel menu laterale selezionare Autenticazione.
1. Nella sezione Concessione implicita e flussi ibridi selezionare la casella di controllo Token ID.
2. Seleziona Salva.
In Gestisci nel menu laterale selezionare Configurazione token>+ Aggiungi attestazione facoltativa.
1. In Tipo di tokenselezionare ID.
2. Selezionare (controllare) le attestazioni seguenti: email, family_name, given_name.
3. Selezionare Aggiungi. Se richiesto, selezionare Attiva e-mail di Microsoft Graph, autorizzazione profilo.
Passare alla scheda del browser con l'istanza di Gestione API.
Incollare il segreto nel campo Segreto client nel riquadro Aggiungi provider di identità.

Importante

Aggiornare il segreto client prima della scadenza della chiave.
Nel campo Tenant consentiti del riquadro Aggiungi provider di identità specificare i domini dell'istanza di Microsoft Entra a cui concedere l'accesso alle API dell'istanza del servizio Gestione API.
- È possibile separare più domini con virgole, spazi o caratteri di nuova riga.
Nota

Nella sezione Tenant consentiti si possono specificare più domini. Un'amministrazione globale deve concedere all'applicazione l'accesso ai dati della directory prima che gli utenti possano accedere da un dominio diverso rispetto al dominio di registrazione dell'app originale. A tale scopo, l'amministratore globale deve:
1. Passare a https://<URL of your developer portal>/aadadminconsent (ad esempio, https://contoso.portal.azure-api.net/aadadminconsent).
2. Immettere il nome di dominio del tenant di Microsoft Entra a cui concedere l'accesso.
3. Selezionare Invia.
Dopo aver specificato la configurazione desiderata, selezionare Aggiungi.
Ripubblicare il portale per sviluppatori per rendere effettiva la configurazione di Microsoft Entra. Nel menu a sinistra, in Portale per sviluppatori, selezionare Panoramica del portale>Pubblica.

Dopo l'abilitazione del provider Microsoft Entra:

Gli utenti nell'istanza di Microsoft Entra specificata possono accedere al portale per sviluppatori usando un account Microsoft Entra.
È possibile gestire la configurazione di Microsoft Entra nella pagina Portale per sviluppatori>Identità nel portale.
Facoltativamente, configurare altre impostazioni di accesso selezionando Identità>Impostazioni. Ad esempio, è possibile reindirizzare gli utenti anonimi alla pagina di accesso.
Ripubblicare il portale per sviluppatori dopo qualsiasi modifica della configurazione.

Eseguire la migrazione a MSAL

Se in precedenza è stata configurata un'app Microsoft Entra per l'accesso utente tramite ADAL, è possibile usare il portale per eseguire la migrazione dell'app a MSAL e aggiornare il provider di identità in Gestione API.

Aggiornare l'app Microsoft Entra per la compatibilità MSAL

Per la procedura, vedere Passare gli URI di reindirizzamento al tipo di applicazione a pagina singola.

Aggiornare la configurazione del provider di identità

Nel menu a sinistra dell'istanza di Gestione API, in Portale per sviluppatoriselezionare Identità.
Selezionare Microsoft Entra ID dall'elenco.
Nell'elenco a discesa Libreria client selezionare MSAL.
Selezionare Aggiorna.
Ripubblicare il portale per sviluppatori.

Aggiungere un gruppo Microsoft Entra esterno

Dopo aver abilitato l'accesso per gli utenti in un tenant di Microsoft Entra, è possibile:

Aggiungere gruppi di Microsoft Entra in Gestione API.
Controllare la visibilità dei prodotti usando i gruppi di Microsoft Entra.

Passare alla pagina Registrazione app per l'applicazione registrata nella sezione precedente.
Selezionare Autorizzazioni API.
Aggiungere le autorizzazioni minime seguenti dell'applicazione per l'API Microsoft Graph:
- Autorizzazione dell'applicazione User.Read.All, in modo che Gestione API possa leggere l'appartenenza al gruppo dell'utente per eseguire la sincronizzazione dei gruppi al momento dell'accesso dell'utente.
- Autorizzazione dell'applicazione Group.Read.All, in modo che Gestione API possa leggere i gruppi di Microsoft Entra quando un amministratore tenta di aggiungere il gruppo a Gestione API usando il pannello Gruppi nel portale.
Selezionare Concedi consenso amministratore per {tenantname} in modo da concedere l'accesso a tutti gli utenti in questa directory.

Ora è possibile aggiungere gruppi esterni di Microsoft Entra dalla scheda Gruppi dell'istanza di Gestione API.

In Portale per sviluppatori nel menu laterale selezionare Gruppi.
Selezionare il pulsante Aggiungi gruppo di Microsoft Entra.
Selezionare il tenant dalla casella a discesa.
Cercare e selezionare il gruppo che si vuole aggiungere.
Scegliere il pulsante Seleziona.

Dopo aver aggiunto un gruppo di Microsoft Entra esterno, è possibile esaminarne e configurarne le proprietà:

Nella scheda Gruppi selezionare il nome del gruppo.
Modificare le informazioni del gruppo nelle caselle Nome e Descrizione.

Gli utenti dell'istanza configurata di Microsoft Entra possono ora:

Accedere al portale per sviluppatori.
Visualizzare e sottoscrivere qualsiasi gruppo per cui hanno visibilità.

Nota

Altre informazioni sulla differenza tra tipi di autorizzazioni Delegate e Applicazione nell'articolo Autorizzazioni e consenso in Microsoft Identity Platform.

Sincronizzare gruppi di Microsoft Entra con Gestione API

I gruppi configurati in Microsoft Entra devono eseguire la sincronizzazione con Gestione API in modo che sia possibile aggiungerli all'istanza. Se i gruppi non vengono sincronizzati automaticamente, eseguire una delle operazioni seguenti per sincronizzare manualmente le informazioni sui gruppi:

Disconnettersi e accedere a Microsoft Entra ID. Questa procedura attiva in genere la sincronizzazione dei gruppi.
Assicurarsi che il tenant di accesso di Microsoft Entra sia specificato allo stesso modo (usando un ID tenant o un nome di dominio) nelle impostazioni di configurazione in Gestione API. Specificare il tenant di accesso nel provider di identità Microsoft Entra ID per il portale per sviluppatori e quando si aggiunge un gruppo Microsoft Entra a Gestione API.

Portale per sviluppatori: aggiungere l'autenticazione dell'account Microsoft Entra

Nel portale per sviluppatori è possibile accedere con Microsoft Entra ID usando il widget Pulsante di accesso: OAuth incluso nella pagina di accesso del contenuto predefinito del portale per sviluppatori.

Screenshot che mostra il widget OAuth nel portale per sviluppatori.

Anche se un nuovo account verrà creato automaticamente quando un nuovo utente accede con Microsoft Entra ID, è consigliabile aggiungere lo stesso widget alla pagina di iscrizione. Il widget Modulo di iscrizione: OAuth rappresenta un modulo usato per l'iscrizione a OAuth.