Accedere in modo sicuro a prodotti e API con le applicazioni Microsoft Entra

SI APPLICA A: Sviluppatore | Base | Standard | Premium

La gestione delle API supporta ora l'accesso integrato basato su applicazioni OAuth 2.0 alle API dei prodotti utilizzando la modalità delle credenziali client. Questa funzionalità consente ai responsabili API di registrare le applicazioni MICROSOFT Entra ID, semplificando l'accesso sicuro alle API per gli sviluppatori tramite l'autorizzazione OAuth 2.0.

Annotazioni

Le applicazioni sono attualmente in anteprima limitata. Per iscriversi, compilare il modulo.

Con questa funzionalità:

• I responsabili API impostano una proprietà del prodotto per abilitare l'accesso basato su applicazioni.
• I gestori API registrano le applicazioni client in Microsoft Entra ID per limitare l'accesso a prodotti specifici.
• Gli sviluppatori possono accedere alle credenziali dell'applicazione client usando il portale per sviluppatori di Gestione API.
• Usando il flusso di credenziali client OAuth 2.0, gli sviluppatori o le app ottengono token che possono includere nelle richieste API
• I token presentati nelle richieste API vengono convalidati dal gateway di Gestione API per autorizzare l'accesso alle API del prodotto.

Prerequisiti

• Istanza di Gestione API distribuita nel livello Premium, Standard, Basic o Developer . Se è necessario distribuire un'istanza, vedere Creare un'istanza del servizio Gestione API.

• Almeno un prodotto nell'istanza di Gestione API, con almeno un'API assegnata.

  • Il prodotto deve trovarsi nello stato Pubblicato in modo che sia accessibile dagli sviluppatori tramite il portale per sviluppatori.
  • Per i test, è possibile usare il prodotto Starter predefinito e l'API Echo aggiunta.
  • Per creare un prodotto, vedere Creare e pubblicare un prodotto.

• Autorizzazioni sufficienti nel tenant di Microsoft Entra per assegnare il ruolo Amministratore dell'applicazione, che richiede almeno il ruolo Amministratore del ruolo con privilegi.

• Facoltativamente, aggiungere uno o più utenti nell'istanza di Gestione API.

• Se scegli di utilizzare Azure PowerShell localmente:
  • Installare la versione più recente del modulo Az PowerShell.
  • Connettersi all'account Azure con il cmdlet Connect-AzAccount.
• Se si sceglie di usare Azure Cloud Shell:
  • Vedi Panoramica di Azure Cloud Shell per ulteriori informazioni.

Configurare identità gestita

1. Abilitare un'identità gestita assegnata dal sistema per Gestione API nell'istanza di Gestione API.

2. Assegnare l'identità al ruolo Controllo degli accessi in base al ruolo dell'amministratore applicazione in Microsoft Entra ID. Per assegnare il ruolo:

   1. Accedere al portale e passare a Microsoft Entra ID.
   2. Nel menu a sinistra selezionare Gestisci>ruoli e amministratori.
   3. Selezionare Amministratore applicazione.
   4. Nel menu a sinistra selezionare Gestisci>assegnazioni>+ Aggiungi assegnazioni.
   5. Nella pagina Aggiungi assegnazioni cercare l'identità gestita dell'istanza di Gestione API in base al nome (il nome dell'istanza di Gestione API). Selezionare l'identità gestita e quindi selezionare Aggiungi.

Abilitare l'accesso basato su applicazioni per il prodotto

Seguire questa procedura per abilitare l'accesso basato su applicazioni per un prodotto. Un prodotto deve avere questa impostazione abilitata per essere associata a un'applicazione client nei passaggi successivi.

Nell'esempio seguente viene usato il prodotto Starter , ma si sceglie qualsiasi prodotto pubblicato con almeno un'API assegnata.

1. Accedere al portale all'URL personalizzato seguente per la funzionalità delle applicazioni: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=applications
2. Accedere all'istanza di gestione delle API.
3. Nel menu a sinistra, in API, selezionare Prodotti.
4. Scegliere il prodotto da configurare, ad esempio il prodotto Starter .
5. Nel menu a sinistra, in Prodotto, selezionare Proprietà.
6. Nella sezione Accesso basato su applicazioni abilitare l'impostazione token OAuth 2.0 (più sicura).
7. Facoltativamente, abilitare l'impostazione Chiave di sottoscrizione . Se si abilita l'accesso basato su applicazioni e un requisito di sottoscrizione, il gateway di Gestione API può accettare un token OAuth 2.0 o una chiave di sottoscrizione per l'accesso alle API del prodotto.
8. Seleziona Salva.

Suggerimento

È anche possibile abilitare l'impostazione del token OAuth 2.0 durante la creazione di un nuovo prodotto.

L'abilitazione dell'accesso basato su applicazioni crea un'applicazione aziendale back-end in Microsoft Entra ID per rappresentare il prodotto. L'ID applicazione back-end viene visualizzato nella pagina Proprietà del prodotto.

Annotazioni

Questo ID applicazione viene impostato come valore Audience quando si crea un'applicazione client per accedere al prodotto. Usare anche questo valore quando si genera un token per chiamare l'API del prodotto.

(Facoltativo) Esaminare le impostazioni dell'applicazione del prodotto in Microsoft Entra ID

Facoltativamente, esaminare le impostazioni dell'applicazione aziendale back-end creata in Microsoft Entra ID per rappresentare il prodotto.

L'applicazione viene denominata con il formato seguente: APIMProductApplication<product-name>. Ad esempio, se il nome del prodotto è Starter, il nome dell'applicazione è APIMProductApplicationStarter. L'applicazione ha un ruolo App definito.

Per esaminare le impostazioni dell'applicazione nelle registrazioni dell'app:

1. Accedere al portale e passare a Microsoft Entra ID>Gestire>registrazioni delle app.
2. Selezionare Tutte le applicazioni.
3. Cercare e selezionare l'applicazione creata da Gestione API.
4. Nel menu a sinistra, in Gestisci, selezionare Ruoli app.
5. Verificare il ruolo applicazione impostato da Gestione API di Azure, come illustrato nello screenshot seguente:

Registrare l'applicazione client per accedere al prodotto

Registrare ora un'applicazione client che limita l'accesso a uno o più prodotti.

• Un prodotto deve avere l'accesso basato su applicazione abilitato per essere associato a un'applicazione client.
• Ogni applicazione client ha un singolo utente (proprietario) nell'istanza di Gestione API. Solo il proprietario può accedere alle API del prodotto tramite l'applicazione.
• Un prodotto può essere associato a più di un'applicazione client.

Per registrare un'applicazione client:

1. Accedere al portale all'URL personalizzato seguente per la funzionalità delle applicazioni: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=applications

2. Accedere all'istanza di gestione delle API.

3. Nel menu a sinistra, in API, selezionare Applicazioni>+ Registra applicazione.

4. Nella pagina Registra un'applicazione immettere le impostazioni dell'applicazione seguenti:

   • Nome: immettere un nome per l'applicazione.
   • Proprietario: selezionare il proprietario dell'applicazione dall'elenco a discesa degli utenti nell'istanza di Gestione API.
   • Concedere l'accesso ai prodotti selezionati: selezionare uno o più prodotti nell'istanza di Gestione API abilitata in precedenza per l'accesso basato su applicazioni.
   • Descrizione: immettere facoltativamente una descrizione.

   

5. Selezionare Registrazione.

L'applicazione viene aggiunta all'elenco di applicazioni nella pagina Applicazioni . Selezionare l'applicazione per visualizzare i dettagli, ad esempio l'ID client. È necessario questo ID per generare un token per chiamare l'API del prodotto.

Suggerimento

• Dopo aver creato un'applicazione, associarla facoltativamente ad altri prodotti. Selezionare l'applicazione nella pagina Applicazioni e quindi selezionare Dettagli>Prodotti>+ Aggiungi prodotto.
• È anche possibile creare o associare un'applicazione modificando un prodotto dalla pagina Prodotti .

Generare un segreto client

È necessario generare un segreto client per consentire all'applicazione client di usare il flusso di credenziali client OAuth 2.0. Il segreto è valido per un anno, ma può essere rigenerato in qualsiasi momento.

1. Nella pagina Applicazioni selezionare l'applicazione creata.

2. Nella pagina Panoramica dell'applicazione, accanto a Segreto client, selezionare Aggiungi segreto.

3. Nella pagina Nuovo segreto client selezionare Genera.

   Un segreto client viene generato e visualizzato nel campo Segreto client . Assicurarsi di copiare il valore del segreto e archiviarlo in modo sicuro. Non sarà possibile recuperarlo di nuovo dopo aver chiuso la pagina.

4. Seleziona Chiudi.

(Facoltativo) Esaminare le impostazioni dell'applicazione client in Microsoft Entra ID

Se si desidera, esaminare le impostazioni dell'applicazione client in Microsoft Entra ID.

L'applicazione viene denominata con il formato seguente: APIMApplication<product-name>. Ad esempio, se il nome del prodotto è Starter, il nome dell'applicazione è simile a APIMApplicationStarter.

Per esaminare le impostazioni dell'applicazione nelle registrazioni dell'app:

1. Accedere al portale e passare a Microsoft Entra ID>Gestire>registrazioni delle app.

2. Selezionare Tutte le applicazioni.

3. Cercare e selezionare l'applicazione client creata da Gestione API.

4. Nel menu a sinistra, in Gestisci, selezionare Autorizzazioni API.

5. Verificare che l'applicazione disponga delle autorizzazioni per accedere all'applicazione o alle applicazioni back-end.

   Ad esempio, se l'applicazione client concede l'accesso al prodotto Starter , l'applicazione dispone delle autorizzazioni Product.Starter.All per accedere all'applicazione APIMProductApplicationStarter .

   

Ottenere le impostazioni dell'applicazione nel portale per sviluppatori

Gli utenti possono accedere al portale per sviluppatori per visualizzare le applicazioni client di cui sono proprietari.

1. Accedere al portale per sviluppatori (https://<your-apim-instance-name>.developer.azure-api.net) usando un account utente impostato come proprietario di un'applicazione client.

2. Nel menu di spostamento in alto selezionare Applicazioni.

3. Le applicazioni di proprietà dell'utente vengono visualizzate nell'elenco.

4. Selezionare un'applicazione per visualizzarne i dettagli, ad esempio l'ID client, il segreto client e l'ambito. Questi valori sono necessari per generare un token per chiamare le API del prodotto.

   

Creare un token e usarlo con la chiamata API

Dopo aver abilitato l'accesso basato su applicazioni per un prodotto e aver registrato un'applicazione client, uno sviluppatore o un'app può generare un token per chiamare le API del prodotto. Il token deve essere incluso nell'intestazione Authorization di una richiesta.

Ad esempio, uno sviluppatore o un'app può eseguire gli script di Azure PowerShell seguenti per chiamare l'applicazione client per generare un token e quindi usare il token per chiamare un'API del prodotto in Gestione API.

Attenzione

Gli script seguenti sono esempi solo a scopo di test. Nell'ambiente di produzione usare un metodo sicuro per archiviare e recuperare il segreto client.

Chiamare l'applicazione client per generare il token

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Chiamare l'API del prodotto usando il token

Il token generato nel passaggio precedente viene usato per chiamare un'API del prodotto. Il token viene passato nell'intestazione Authorization della richiesta. L'istanza di Gestione API convalida il token e autorizza l'accesso all'API.

Lo script seguente mostra una chiamata di esempio all'API echo.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Risoluzione dei problemi

Errore interno del server durante la registrazione delle applicazioni nel portale

Se non è possibile elencare le applicazioni o si riceve un errore interno del server durante la registrazione delle applicazioni nel portale, verificare quanto segue:

• Il ruolo Amministratore applicazione viene assegnato all'identità gestita dell'istanza di Gestione API in Microsoft Entra ID.
• È stato eseguito l'accesso al portale all'URL personalizzato seguente per la funzionalità delle applicazioni: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=applications. Questo URL è necessario per accedere alla funzionalità delle applicazioni in Gestione API.

Contenuti correlati

• Creare e pubblicare un prodotto
• Autenticazione e autorizzazione per le API in Gestione API