validate-JWT
SI APPLICA A: Tutti i livelli di Gestione API
Il criterio validate-jwt
impone l'esistenza e la validità di un token Web JSON supportato (JWT) estratto da un'intestazione HTTP specificata, da un parametro di query specificato o corrispondente a un valore specifico.
Nota
Per convalidare un token JWT fornito dal servizio Microsoft Entra, API Management fornisce anche il criterio validate-azure-ad-token
.
Nota
Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio. Per configurare questo criterio, il portale fornisce un editor guidato basato su moduli. Altre informazioni su come impostare o modificare i criteri di API Management.
Istruzione del criterio
<validate-jwt
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"
require-expiration-time="true | false"
require-scheme="scheme"
require-signed-tokens="true | false"
clock-skew="allowed clock skew in seconds"
output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
<openid-config url="full URL of the configuration endpoint, for example, https://login.constoso.com/openid-configuration" />
<issuer-signing-keys>
<key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
<!-- if there are multiple keys, then add additional key elements -->
</issuer-signing-keys>
<decryption-keys>
<key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </key>
<!-- if there are multiple keys, then add additional key elements -->
</decryption-keys>
<audiences>
<audience>audience string</audience>
<!-- if there are multiple possible audiences, then add additional audience elements -->
</audiences>
<issuers>
<issuer>issuer string</issuer>
<!-- if there are multiple possible issuers, then add additional issuer elements -->
</issuers>
<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 claim, then add additional claim elements -->
</required-claims>
</validate-jwt>
Attributi
Attributo | Descrizione | Richiesto | Valore predefinito |
---|---|---|---|
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 . |
N/D |
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"). |
require-expiration-time | Booleano. Specifica se è necessaria un'attestazione di scadenza nel token. Le espressioni di criteri sono consentite. | No | true |
require-scheme | Nome dello schema di token, ad esempio "Bearer token". Quando questo attributo è impostato, il criterio assicura che lo schema specificato sia presente nel valore dell'intestazione di autorizzazione. Le espressioni di criteri sono consentite. | No | N/D |
require-signed-tokens | Booleano. Specifica se è necessario firmare un token. Le espressioni di criteri sono consentite. | No | true |
clock-skew | Intervallo di tempo. Usare per specificare la differenza massima di tempo previsto tra gli orologi di sistema dell'autorità emittente di token e l'istanza di Gestione API. Le espressioni di criteri sono consentite. | No | 0 secondi |
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 |
---|---|---|
openid-config | Aggiungere uno o più di questi elementi per specificare un URL dell'endpoint di configurazione OpenID conforme da cui è possibile ottenere le chiavi di firma e l'autorità emittente. La configurazione che include il set JSON Web Key (JWKS) viene estratta dall'endpoint ogni ora e memorizzata nella cache. Se il token convalidato fa riferimento a una chiave di convalida (usando l'attestazione kid ) mancante nella configurazione memorizzata nella cache o se il recupero ha esito negativo, API Management esegue il pull dall'endpoint al massimo una volta per 5 minuti. Tali intervalli sono soggetti a modifiche senza preavviso. La risposta deve essere conforme alle specifiche, come definito nell'URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata . Per Microsoft Entra ID usare l'endpoint dei metadati OpenID Connect configurato nella registrazione dell'app, ad esempio: - v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration - Multi-tenant: v2 https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration - v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration - Tenant del cliente (anteprima) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration Sostituzione del nome o dell'ID del tenant della directory, ad esempio contoso.onmicrosoft.com , per {tenant-name} . |
No |
issuer-signing-keys | Elenco di chiavi di sicurezza con codifica Base64, nei sotto-elementi key , usate per convalidare i token firmati. 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. Facoltativamente, specificare una chiave usando l'attributo id per trovare una corrispondenza con un'attestazione kid . Per convalidare un token firmato con chiave asimmetrica, specificare facoltativamente la chiave pubblica usando un attributo certificate-id con valore impostato sull'identificatore di un certificato caricato in API Management o la coppia modulo n ed esponente e RSA della chiave di firma in formato con codifica Base64url. |
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.Facoltativamente, specificare una chiave usando l'attributo id per trovare una corrispondenza con un'attestazione kid . 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 API Management o la coppia modulo n ed esponente e RSA della chiave in formato con codifica Base64url. |
No |
audiences | Contiene un elenco di attestazioni "audience" accettabili, in audience sotto-elementi, 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. È necessario specificare almeno un "audience". |
No |
issuers | Elenco di entità accettabili, in sotto-elementi issuer , che hanno emesso il token. Se sono presenti più valori emittenti, 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. |
No |
required-claims | Un elenco di attestazioni in sotto-elementi claim da includere nel token affinché possa essere considerato valido. Quando sono presenti più attestazioni, il token deve corrispondere ai valori attestazioni in base al valore dell'attributo match . |
No |
attributi della chiave
Attributo | Descrizione | Richiesto | Valore predefinito |
---|---|---|---|
id | String. Identificatore usato per trovare la corrispondenza con l'attestazione kid presentata in JWT. |
No | N/D |
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 |
n | Modulo della chiave pubblica usata per verificare l'autorità emittente di un token firmato con chiave asimmetrica. Deve essere specificato con il valore dell'esponente e . Le espressioni di criteri non sono consentite. |
No | N/D |
e | Esponente della chiave pubblica usata per verificare l'autorità emittente di un token firmato con chiave asimmetrica. Deve essere specificato con il valore del modulo n . Le espressioni di criteri non sono consentite. |
No | N/D |
attributi attestazione
Attributo | Descrizione | Richiesto | Valore predefinito |
---|---|---|---|
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. |
No | tutto |
separator | String. Specifica un separatore (ad esempio ",") da usare per l'estrazione di un set di valori da un'attestazione multivalore. | No | N/D |
Utilizzo
- Sezioni del criterio: inbound
- Ambiti del criterio: globale, area di lavoro, prodotto, API, operazione
- Gateway: classico, v2, consumo, self-hosted, area di lavoro
Note sull'utilizzo
- Il criterio
validate-jwt
richiede che l'attestazioneexp
registrata venga inclusa nel token JWT, a meno che non venga specificato l'attributorequire-expiration-time
e impostato sufalse
. - I criteri supportano algoritmi di firma simmetrica e asimmetrica:
- Simmetrica: sono supportati gli algoritmi di crittografia seguenti: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
- Se usata nel criterio, la chiave deve essere fornita incorporata all'interno del criterio nel formato con codifica Base64.
- Asimmetrica: sono supportati gli algoritmi di crittografia seguenti: PS256, RS256, RS512.
- Se usata nel criterio, la chiave può essere fornita tramite un endpoint di configurazione OpenID o specificando l'ID di un certificato caricato (in formato PFX) che contiene la chiave pubblica o la coppia modulo-esponente della chiave pubblica.
- Simmetrica: sono supportati gli algoritmi di crittografia seguenti: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
- Per configurare i criteri con uno o più endpoint di configurazione OpenID da usare con un gateway self-hosted, è necessario che gli URL di configurazione OpenID siano accessibili anche dal gateway cloud.
- È 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-jwt
a livello di API oppure è possibile applicarla a livello di operazione API e usareclaims
per un controllo più granulare. - Quando si usa un'intestazione personalizzata (
header-name
), lo schema obbligatorio configurato (require-scheme
) verrà ignorato. Per usare uno schema obbligatorio, è necessario specificare i token JWT nell'intestazioneAuthorization
.
Esempi
Convalida semplice dei token
<validate-jwt header-name="Authorization" require-scheme="Bearer">
<issuer-signing-keys>
<key>{{jwt-signing-key}}</key> <!-- signing key specified as a named value -->
</issuer-signing-keys>
<audiences>
<audience>@(context.Request.OriginalUrl.Host)</audience> <!-- audience is set to API Management host name -->
</audiences>
<issuers>
<issuer>http://contoso.com/</issuer>
</issuers>
</validate-jwt>
Convalida dei token con certificato RSA
<validate-jwt header-name="Authorization" require-scheme="Bearer">
<issuer-signing-keys>
<key certificate-id="my-rsa-cert" /> <!-- signing key specified as certificate ID, enclosed in double-quotes -->
</issuer-signing-keys>
<audiences>
<audience>@(context.Request.OriginalUrl.Host)</audience> <!-- audience is set to API Management host name -->
</audiences>
<issuers>
<issuer>http://contoso.com/</issuer>
</issuers>
</validate-jwt>
Convalida del token a tenant singolo con ID Microsoft Entra
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
<openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
<audiences>
<audience>00001111-aaaa-2222-bbbb-3333cccc4444</audience>
</audiences>
<required-claims>
<claim name="id" match="all">
<value>insert claim here</value>
</claim>
</required-claims>
</validate-jwt>
Convalida del token del tenant del cliente di Microsoft Entra ID
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
<required-claims>
<claim name="azp" match="all">
<value>insert claim here</value>
</claim>
</required-claims>
</validate-jwt>
Convalida del token di Azure Active Directory B2C
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
<openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
<audiences>
<audience>11112222-bbbb-3333-cccc-4444dddd5555</audience>
</audiences>
<required-claims>
<claim name="id" match="all">
<value>insert claim here</value>
</claim>
</required-claims>
</validate-jwt>
Autorizzare l'accesso a operazioni basate su attestazioni dei token
Questo esempio illustra come usare il criterio validate-jwt
per autorizzare l'accesso alle operazioni in base al valore delle attestazioni dei token.
<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
<issuer-signing-keys>
<key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
</issuer-signing-keys>
<audiences>
<audience>@(context.Request.OriginalUrl.Host)</audience>
</audiences>
<issuers>
<issuer>contoso.com</issuer>
</issuers>
<required-claims>
<claim name="group" match="any">
<value>finance</value>
<value>logistics</value>
</claim>
</required-claims>
</validate-jwt>
<choose>
<when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
<return-response>
<set-status code="403" reason="Forbidden" />
</return-response>
</when>
</choose>
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