Convalidare il token Microsoft Entra
SI APPLICA A: Tutti i livelli di Gestione API
Il criterio validate-azure-ad-token
applica l'esistenza e la validità di un token Web JSON (JWT) fornito dal servizio Microsoft Entra (in precedenza denominato Azure Active Directory) per un set specificato di entità nella directory. Il token JWT può essere estratto da un'intestazione HTTP, un parametro di query o un valore specificato usando un'espressione di criteri o una variabile di contesto.
Nota
Per convalidare un token JWT fornito da un altro provider di identità, Gestione API fornisce anche i criteri validate-jwt
generici.
Nota
Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio. Altre informazioni su come impostare o modificare i criteri di API Management.
Istruzione del criterio
<validate-azure-ad-token
tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
failed-validation-httpcode="HTTP status code to return on failure"
failed-validation-error-message="error message to return on failure"
output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
<client-application-ids>
<application-id>Client application ID from Azure Active Directory</application-id>
<!-- If there are multiple client application IDs, then add additional application-id elements -->
</client-application-ids>
<backend-application-ids>
<application-id>Backend application ID from Azure Active Directory</application-id>
<!-- If there are multiple backend application IDs, then add additional application-id elements -->
</backend-application-ids>
<audiences>
<audience>audience string</audience>
<!-- if there are multiple possible audiences, then add additional audience elements -->
</audiences>
<required-claims>
<claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
<value>claim value as it is expected to appear in the token</value>
<!-- if there is more than one allowed value, then add additional value elements -->
</claim>
<!-- if there are multiple possible allowed values, then add additional value elements -->
</required-claims>
<decryption-keys>
<key>Base64 encoded signing key | certificate-id="mycertificate"</key>
<!-- if there are multiple keys, then add additional key elements -->
</decryption-keys>
</validate-azure-ad-token>
Attributi
Attributo | Descrizione | Richiesto | Valore predefinito |
---|---|---|---|
tenant-id | ID tenant o URL del servizio Microsoft Entra. Le espressioni di criteri sono consentite. | Sì | N/D |
header-name | Il nome dell'intestazione HTTP che contiene il token. Le espressioni di criteri sono consentite. | È necessario specificare uno degli elementi header-name , query-parameter-name o token-value . |
Authorization |
query-parameter-name | Nome di parametro di query che contiene il token. Le espressioni di criteri sono consentite. | È necessario specificare uno degli elementi header-name , query-parameter-name o token-value . |
N/D |
token-value | Espressione che restituisce una stringa contenente il token. Non è necessario restituire Bearer come parte del valore del token. Le espressioni di criteri sono consentite. |
È necessario specificare uno degli elementi header-name , query-parameter-name o token-value . |
N/D |
failed-validation-httpcode | Codice di stato HTTP da restituire se il token JWT non supera la convalida. Le espressioni di criteri sono consentite. | No | 401 |
failed-validation-error-message | Messaggio di errore da restituire nel corpo della risposta HTTP se il token JWT non supera la convalida. I caratteri speciali eventualmente contenuti in questo messaggio devono essere adeguatamente preceduti da un carattere di escape. Le espressioni di criteri sono consentite. | No | Il messaggio di errore predefinito dipende dal problema della convalida, ad esempio "JWT not present" ("JWT non presente"). |
output-token-variable-name | String. Nome della variabile di contesto che riceverà il valore del token come oggetto di tipo Jwt al termine della convalida del token. Le espressioni di criteri non sono consentite. |
No | N/D |
Elementi
Elemento | Descrizione | Richiesto |
---|---|---|
audiences | Contiene un elenco di attestazioni "audience" accettabili che possono essere presenti nel token. Se sono presenti più valori audience , viene provato ogni valore fino al completamento di tutti i valori (caso in cui la convalida ha esito negativo) o fino a quando un valore non ha esito positivo. Le espressioni di criteri sono consentite. |
No |
backend-application-ids | Contiene un elenco di ID applicazione back-end accettabili. Questa operazione è necessaria solo nei casi avanzati per la configurazione delle opzioni e in genere può essere rimossa. Le espressioni di criteri non sono consentite. | No |
client-application-ids | Contiene un elenco di ID applicazione client accettabili. Se sono presenti più elementi application-id , viene provato ogni valore fino al completamento di tutti i valori (caso in cui la convalida ha esito negativo) o fino a quando un valore non ha esito positivo. Se non viene specificato un ID applicazione client, è necessario specificare una o più attestazioni audience . Le espressioni di criteri non sono consentite. |
No |
required-claims | Contiene un elenco di elementi claim per i valori attestazioni che devono essere presenti nel token affinché sia considerato valido. Perché la convalida abbia esito positivo, quando l'attributo match è impostato su all ogni valore dell'attestazione nel criterio deve essere presente nel token. Perché la convalida abbia esito positivo, quando l'attributo match è impostato su any almeno un'attestazione deve essere presente nel token. Le espressioni di criteri sono consentite. |
No |
decryption-keys | Elenco di chiavi con codifica Base64, nei sotto-elementi key , usate per decrittografare i token. Se sono presenti più chiavi di sicurezza, viene provata ogni chiave fino al completamento di tutte le chiavi (caso in cui la convalida ha esito negativo) o fino a quando una chiave non ha esito positivo.Per decrittografare un token crittografato con chiave asimmetrica, specificare facoltativamente la chiave pubblica usando un attributo certificate-id con valore impostato sull'identificatore di un certificato caricato in Gestione API. |
No |
attributi attestazione
Attributo | Descrizione | Richiesto | Valore predefinito |
---|---|---|---|
name | Nome dell'attestazione come previsto visualizzato nel token. Le espressioni di criteri sono consentite. | Sì | N/D |
match | Perché la convalida abbia esito positivo, l'attributo match sull'elemento claim specifica se il valore dell'attestazione nel criterio deve essere presente nel token. I valori possibili sono:- all : ogni valore dell'attestazione nel criterio deve essere presente nel token perché la convalida abbia esito positivo.- any : almeno un valore dell'attestazione deve essere presente nel token perché la convalida abbia esito positivo.Le espressioni di criteri sono consentite. |
No | tutto |
separator | String. Specifica un separatore (ad esempio ",") da usare per l'estrazione di un set di valori da un'attestazione multivalore. Le espressioni di criteri sono consentite. | No | N/D |
attributi della chiave
Attributo | Descrizione | Richiesto | Valore predefinito |
---|---|---|---|
certificate-id | Identificatore di un'entità certificato caricata in Gestione API, usata per specificare la chiave pubblica per verificare un token firmato con chiave asimmetrica. | No | N/D |
Utilizzo
- Sezioni del criterio: inbound
- Ambiti del criterio: globale, area di lavoro, prodotto, API, operazione
- Gateway: classico, v2, consumo, self-hosted
Note sull'utilizzo
- È possibile usare i criteri di restrizione di accesso in ambiti diversi per scopi diversi. Ad esempio, è possibile proteggere l'intera API con l'autenticazione Microsoft Entra applicando i criteri
validate-azure-ad-token
a livello di API oppure è possibile applicarla a livello di operazione API e usareclaims
per un controllo più granulare. - L'ID Microsoft Entra per i clienti (anteprima) non è supportato.
Esempi
Convalida semplice dei token
I criteri seguenti sono la forma minima dei criteri validate-azure-ad-token
. Prevede che il token JWT venga fornito nell'intestazione Authorization
predefinita usando lo schema Bearer
. In questo esempio vengono forniti l'ID tenant e l'ID applicazione client di Microsoft Entra usando i valori denominati.
<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
<client-application-ids>
<application-id>{{aad-client-application-id}}</application-id>
</client-application-ids>
</validate-azure-ad-token>
Verificare che il gruppo di destinatari e l'attestazione siano corretti
I criteri seguenti controllano che il gruppo di destinatari sia il nome host dell'istanza di Gestione API e che l'attestazione ctry
sia US
. Il nome host viene fornito usando un'espressione di criteri e vengono forniti l'ID tenant e l'ID applicazione client di Microsoft Entra usando i valori denominati. Il token JWT decodificato viene fornito nella variabile jwt
dopo la convalida.
Per altri dettagli sulle attestazioni facoltative, vedere Fornire attestazioni facoltative all'app.
<validate-azure-ad-token tenant-id="{{aad-tenant-id}}" output-token-variable-name="jwt">
<client-application-ids>
<application-id>{{aad-client-application-id}}</application-id>
</client-application-ids>
<audiences>
<audience>@(context.Request.OriginalUrl.Host)</audience>
</audiences>
<required-claims>
<claim name="ctry" match="any">
<value>US</value>
</claim>
</required-claims>
</validate-azure-ad-token>
Criteri correlati
Contenuto correlato
Per ulteriori informazioni sull'utilizzo dei criteri, vedere:
- Esercitazione: trasformare e proteggere l'API
- Informazioni di riferimento sui criteri per un elenco completo delle istruzioni dei criteri e delle relative impostazioni
- Espressioni di criteri
- Impostare o modificare criteri
- Riutilizzare le configurazioni dei criteri
- Repository dei frammenti di criteri
- Creare criteri usando Microsoft Copilot in Azure
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per