validate-JWT

  • Articolo

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 id="kid-claim" certificate-id="mycertificate" n="modulus" e="exponent">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key certificate-id="mycertificate">Base64 encoded signing key</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.

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
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 (solo chiave di firma dell'autorità di certificazione) Corda. 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 (solo chiave di firma dell'autorità di certificazione) Modulo della chiave pubblica usata per verificare l'autorità emittente di un token firmato con una chiave asimmetrica. Deve essere specificato con il valore dell'esponente e. Le espressioni di criteri non sono consentite. No N/D
e (solo chiave di firma dell'autorità di certificazione) Esponente della chiave pubblica usata per verificare l'autorità emittente di un token firmato con una 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

Note sull'utilizzo

  • Il criterio validate-jwt richiede che l'attestazione exp registrata venga inclusa nel token JWT, a meno che non venga specificato l'attributo require-expiration-time e impostato su false.
  • 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, ES256.
      • 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.
  • 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 usare claims 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'intestazione Authorization.

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>

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: