Condividi tramite

validate-JWT

SI APPLICA A: Tutti i livelli di Gestione API

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

Nota

Usare il criterio validate-azure-ad-token per convalidare un token JWT fornito da Microsoft Entra.

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 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" validate-connectivity="true | false"/>
  <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 di header-nameo query-parameter-nametoken-value . N/D
query-parameter-name Nome di parametro di query che contiene il token. Le espressioni di criteri sono consentite. È necessario specificare uno di header-nameo query-parameter-nametoken-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 di header-nameo query-parameter-nametoken-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 vero
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 vero
asimmetria dell'orologio 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 Stringa 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 endpoint di configurazione OpenID conforme (url attributo) da cui è possibile ottenere le chiavi di firma e l'emittente.

Facoltativamente, impostare validate-connectivity l'attributo su false per disabilitare il controllo della disponibilità degli endpoint se l'URL non può essere risolto tramite DNS pubblico.

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 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. Tali intervalli sono soggetti a modifiche senza preavviso.

La risposta deve essere in base alle specifiche definite in URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Per Microsoft Entra ID usare l'endpoint OpenID Connect metadata 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, 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 la corrispondenza con l'attestazione del kid token. Per convalidare un token firmato con una chiave asimmetrica, specificare facoltativamente la chiave pubblica usando un certificate-id attributo con valore impostato sull'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, 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 una chiave asimmetrica, specificare facoltativamente la chiave pubblica usando un certificate-id attributo con valore impostato sull'identificatore di un certificato caricato in Gestione API.		 NO
Pubblico 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
Emittenti 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
attestazioni richieste 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 della chiave

Attributo Descrizione Richiesto Valore predefinito
Id (solo chiave di firma dell'autorità di certificazione) Corda. Identificatore usato per trovare la corrispondenza kid con l'attestazione presentata in JWT. Se nessuna chiave corrisponde all'attestazione, Gestione API tenterà ogni chiave specificata. Altre informazioni sull'attestazione kid in RFC. 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 (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
fiammifero L'attributo match nell'elemento claim specifica se ogni valore di attestazione nei criteri deve essere presente nel token affinché la convalida abbia esito positivo. I valori possibili sono:

- all : ogni valore dell'attestazione nei criteri deve essere presente nel token affinché la convalida abbia esito positivo.

- any : almeno un valore di attestazione deve essere presente nel token affinché la convalida abbia esito positivo.		 NO tutto
separatore Stringa 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 validate-jwt criterio richiede che l'attestazione registrata sia inclusa nel token JWT, a meno che require-expiration-time l'attributo exp non sia specificato 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.
    • Asimmetrico : 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.
  • Se l'istanza di Gestione API viene inserita o integrata in una rete virtuale e openid-config gli URL degli endpoint vengono configurati nei criteri, impostare l'attributo su false per disabilitare il validate-connectivity controllo della disponibilità degli endpoint.
  • È 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 il criterio validate-jwt a livello di API oppure è possibile applicarlo 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 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>

Microsoft Entra ID convalida del token a tenant singolo

<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>

Microsoft Entra ID convalida del token del tenant del cliente

<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>

Azure Active Directory convalida del token 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>

Importante

A partire dal 1° maggio 2025, Azure AD B2C non sarà più disponibile per l'acquisto per i nuovi clienti. Altre informazioni sono disponibili nelle domande frequenti.

Convalida dei token con la chiave di decrittografia

Questo esempio illustra come usare i validate-jwt criteri per convalidare un token decrittografato usando una chiave di decrittografia. La chiave viene specificata usando l'ID di un certificato caricato (in formato PFX) che contiene la chiave pubblica.

<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>
    <decryption-keys>
        <key certificate-id="my-certificate-in-api-management" /> <!-- decryption key specified as certificate ID -->
    </decryption-keys>
</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:

  • Last updated on