validate-JWT

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il validate-jwt criterio applica l'esistenza e la validità di un token WEB JSON supportato (JWT) estratto da un'intestazione HTTP specificata, estratto da un parametro di query specificato o corrispondente a un valore specifico.

Nota

Per convalidare un token JWT fornito dal servizio Microsoft Entra, Gestione API fornisce anche i criteri di validate-azure-ad-token.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione dei criteri. Per configurare questo criterio, il portale fornisce un editor guidato basato su moduli. Altre informazioni su come impostare o modificare i criteri di Gestione API.

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". 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 di chiavi Web JSON (JWKS) viene estratta dall'endpoint ogni ora e memorizzata nella cache. Se il token convalidato fa riferimento a una chiave di convalida (usando kid l'attestazione) mancante nella configurazione memorizzata nella cache o se il recupero ha esito negativo, Gestione API esegue il pull dall'endpoint al massimo una volta per 5 minuti. Questi 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 di metadati OpenID Connessione configurato nella registrazione dell'app, ad esempio:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- v2 Multi-Tenant 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, in key sottoelementi, usati per convalidare i token firmati. Se sono presenti più chiavi di sicurezza, ogni chiave viene tentata finché non vengono esaurite tutte (in questo caso la convalida ha esito negativo) o una ha esito positivo (utile per il rollover del token).

Facoltativamente, specificare una chiave usando l'attributo per trovare una corrispondenza con un'attestazione idkid . Per convalidare un token firmato con una chiave asimmetrica, specificare facoltativamente la chiave pubblica usando un certificate-id attributo con valore l'identificatore di un certificato caricato in Gestione API o la coppia modulo n RSA e esponente e della chiave di firma in formato con codifica Base64url.		 No
decryption-keys Elenco di chiavi con codifica Base64, in key sottoelementi, usati per decrittografare i token. Se sono presenti più chiavi di sicurezza, ogni chiave viene tentata fino a quando tutte le chiavi non vengono esaurite (nel qual caso la convalida ha esito negativo) o una chiave ha esito positivo.

Facoltativamente, specificare una chiave usando l'attributo per trovare una corrispondenza con un'attestazione idkid . Per decrittografare un token crittografato con una chiave asimmetrica, specificare facoltativamente la chiave pubblica usando un certificate-id attributo con valore l'identificatore di un certificato caricato in Gestione API o la coppia modulo n RSA e esponente e della chiave in formato con codifica Base64url.		 No
audiences Elenco di attestazioni di destinatari accettabili, in audience sottoelementi, 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 issuer sottoelementi, 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 claim sottoelementi, dovrebbe essere presente nel token per essere considerato valido. Quando sono presenti più attestazioni, il token deve corrispondere ai valori attestazioni in base al valore dell'attributo match . No

attributi chiave

Attributo Descrizione Richiesto Valore predefinito
id String. Identificatore usato per trovare la corrispondenza kid con l'attestazione 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 una chiave asimmetrica. No N/D
n 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 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 usato nei criteri, la chiave deve essere specificata inline all'interno dei criteri nel modulo con codifica Base64.
    • Asymmetric : sono supportati gli algortithms di crittografia seguenti: PS256, RS256, RS512.
      • Se usato nei criteri, 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>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</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>d313c4e4-de5f-4197-9470-e509a2f0b806</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 i validate-jwt criteri per autorizzare l'accesso alle operazioni in base al valore delle attestazioni del 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: