Genera il criterio JWT

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

Cosa

Genera un JWT firmato, con un insieme configurabile di rivendicazioni. Il JWT può quindi essere restituito ai client, trasmesso ai target di backend o utilizzato in altri modi. Per un'introduzione dettagliata, consulta la panoramica sui criteri di JWS e JWT.

Video

Nota: il seguente video mostra l'editor proxy classico nell'interfaccia utente di Apigee. Apigee sta introducendo una nuova versione dell'editor proxy, che ha un design diverso rispetto alla versione classica mostrata nel video.

Guarda un breve video per scoprire come generare un JWT firmato.

Esempi

• Genera un JWT firmato con l'algoritmo HS256
• Genera un JWT firmato con l'algoritmo RS256

Genera un JWT firmato con l'algoritmo HS256

Questo criterio di esempio genera un nuovo JWT e lo firma utilizzando l'algoritmo HS256. HS256 si basa su un secret condiviso per la firma e la verifica della firma.

Quando questa azione dei criteri viene attivata, Apigee codifica l'intestazione e il payload JWT, quindi firma digitalmente JWT. Guarda il video sopra per un esempio completo, incluso come inviare una richiesta alle norme.

La configurazione del criterio creerà un JWT con un set di rivendicazioni standard come definito dalla specifica JWT, inclusa una scadenza di 1 ora e un'ulteriore rivendicazione. Puoi includere tutte le rivendicazioni aggiuntive che vuoi. Consulta la sezione Riferimento elemento per i dettagli sui requisiti e sulle opzioni per ogni elemento in questo criterio di esempio.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Il JWT risultante avrà questa intestazione...

{
  "typ" : "JWT",
  "alg" : "HS256",
  "kid" : "1918290"
}

... e avrà un payload con contenuti simili a questo:

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

Il valore delle rivendicazioni iat, exp e jti varia.

Genera un JWT firmato con l'algoritmo RS256

Nota: utilizza questo stesso esempio per generare un JWT per l'algoritmo PS256 o ES256. Modifica il valore di <Algorithm>RS256</Algorithm> in PS256 o ES256. Per ES256 devi anche specificare una chiave compatibile con l'algoritmo. Per ulteriori informazioni sui requisiti chiave, vedi Informazioni sugli algoritmi di crittografia della firma.

Questo criterio di esempio genera un nuovo JWT e lo firma utilizzando l'algoritmo RS256. La generazione di una firma RS256 si basa su una chiave privata RSA, che deve essere fornita in formato con codifica PEM. Guarda il video sopra per un esempio completo, incluso come inviare una richiesta alle norme.

Quando viene attivata questa azione dei criteri, Apigee codifica e firma digitalmente il JWT, incluse le rivendicazioni. Per informazioni sulle parti di un JWT e su come vengono criptate e firmate, consulta RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Impostare gli elementi chiave

Gli elementi che utilizzi per specificare la chiave utilizzata per generare JWT dipendono dall'algoritmo scelto, come mostrato nella seguente tabella:

Nota: gli algoritmi RS*, PS* ed ES* utilizzano tutti gli stessi elementi per specificare la chiave, ma i dati della chiave ES* sono diversi da quelli utilizzati dagli algoritmi RS* e PS*.

Algoritmo	Elementi chiave
HS{256/384/512}^*	<SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey>
RS/PS/ES{256/384/512}^*	<PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> Gli elementi <Password> e <Id> sono facoltativi.
^* Per ulteriori informazioni sui requisiti chiave, vedi Informazioni sugli algoritmi di crittografia della firma.

Riferimento dell'elemento per Genera JWT

Il riferimento dei criteri descrive gli elementi e gli attributi del criterio Genera JWT.

Nota: la configurazione sarà leggermente diversa a seconda dell'algoritmo di crittografia utilizzato. Fai riferimento agli esempi per esempi che mostrano configurazioni per casi d'uso specifici.

Attributi applicabili all'elemento di primo livello

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

I seguenti attributi sono comuni a tutti gli elementi principali dei criteri.

Attributo	Descrizione	Predefinito	Presenza
name	Il nome interno del criterio. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di Apigee applica ulteriori restrizioni, ad esempio la rimozione automatica dei caratteri non alfanumerici. Facoltativamente, utilizza l'elemento <displayname></displayname> per etichettare il criterio nell'editor proxy dell'interfaccia utente di Apigee con un nome diverso in linguaggio naturale.	N/D	Obbligatorie
continueOnError	Imposta su false per restituire un errore quando un criterio ha esito negativo. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo che un criterio ha esito negativo.	falso	Facoltativo
attiva	Imposta su true per applicare il criterio. Imposta su false per"disattivare"il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
asinc	Questo attributo è obsoleto.	falso	Deprecato

<NomeDisplay>

<DisplayName>Policy Display Name</DisplayName>

Utilizzalo in aggiunta all'attributo del nome per etichettare il criterio nell'editor di proxy dell'interfaccia utente di Apigee con un nome diverso dal linguaggio naturale.

Predefinito	Se ometti questo elemento, viene utilizzato il valore dell'attributo del nome del criterio.
Presenza	Facoltativo
Tipo	Stringa

Algoritmo >

<Algorithm>algorithm-here</Algorithm>

Specifica l'algoritmo di crittografia per firmare il token.

Predefinito	N/D
Presenza	Obbligatorie
Tipo	Stringa
Valori validi	HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Il criterio genera un JWT contenente una dichiarazione aud impostata sul valore specificato. Questa rivendicazione identifica i destinatari a cui è destinato il JWT. Questa è una delle dichiarazioni registrate indicate in RFC7519.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Array (un elenco di valori separati da virgole)
Valori validi	Qualsiasi elemento che identifichi il pubblico.

<AdditionalClaims/Claim>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Consente di specificare coppie di nomi/valori aggiuntivi di rivendicazione nel payload del JWT. Puoi specificare esplicitamente la dichiarazione come stringa, un numero, un valore booleano, una mappa o un array. Una mappa è semplicemente un insieme di coppie nome/valore.

L'elemento <Claim> supporta la funzionalità di sostituzione delle stringhe dinamiche chiamata linguaggio di messaggio quando type=map.

Predefinito	N/D
Presenza	Facoltativo
Valori validi	Qualsiasi valore che vuoi utilizzare per una rivendicazione aggiuntiva. Puoi specificare esplicitamente la dichiarazione come stringa, un numero, un valore booleano, una mappa o un array.

L'elemento <Claim> utilizza i seguenti attributi:

• name (obbligatorio): il nome della rivendicazione.
  Nota: non utilizzare i nomi di rivendicazioni registrati in questo elemento. Le rivendicazioni registrate sono specificate in RFC7519. Tra questi sono inclusi: "iss", "sub", "aud", "iat", "exp", "nbf", "jti".
• ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come dichiarazione. Se sono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile di flusso di riferimento non è risolta.
• type: (facoltativo) una delle seguenti opzioni: stringa (impostazione predefinita), numero, valore booleano o mappa.
• array: (facoltativo) imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false.

Quando includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico durante la configurazione dei criteri. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle rivendicazioni. Poiché l'oggetto JSON viene trasmesso come variabile, i nomi delle rivendicazioni nel JWT generato vengono determinati al momento dell'esecuzione.

Ad esempio:

<AdditionalClaims ref='json_claims'/>

Dove la variabile json_claims contiene un oggetto JSON nel formato:

{
  "sub" : "[e-mail]",
  "iss" : "urn://[e-mail]",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

Il JWT generato include tutte le rivendicazioni nell'oggetto JSON.

È importante notare il seguente comportamento in relazione all'utilizzo di un riferimento variabile e di un valore di dichiarazione esplicita nell'elemento Claim:

Apigee non genererà una rivendicazione nelle seguenti condizioni:

• se è presente un riferimento a una variabile, ma non è stato risolto.
• se non specifichi un valore esplicito (valore predefinito) e
• se l'attributo del criterio IgnoreUnresolvedVariables è true.

Se IgnoreUnresolvedVariables è false, Apigee genera un errore nelle condizioni precedenti.

Apigee genererà una rivendicazione nelle seguenti condizioni:

• se è presente un riferimento a una variabile, ma non è stato risolto.
• Se specifichi un valore esplicito (valore predefinito) e
• se IgnoreUnresolvedVariables è true o false

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Inserisce le coppie nome/valore aggiuntive della rivendicazione nell'intestazione per JWT.

L'elemento <Claim> supporta la funzionalità di sostituzione delle stringhe dinamiche chiamata linguaggio di messaggio quando type=map.

Predefinito	N/D
Presenza	Facoltativo
Valori validi	Qualsiasi valore che vuoi utilizzare per una rivendicazione aggiuntiva. Puoi specificare esplicitamente la dichiarazione come stringa, un numero, un valore booleano, una mappa o un array.

L'elemento <Claim> utilizza i seguenti attributi:

• name (obbligatorio): il nome della rivendicazione.
  Nota: non utilizzare i nomi di rivendicazioni registrati in questo elemento. Le rivendicazioni registrate sono specificate in RFC7519. Tra questi sono inclusi: "iss", "sub", "aud", "iat", "exp", "nbf", "jti".
• ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come dichiarazione. Se sono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile di flusso di riferimento non è risolta.
• type: (facoltativo) una delle seguenti opzioni: stringa (impostazione predefinita), numero, valore booleano o mappa.
• array: (facoltativo) imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Aggiunge l'intestazione critica, crit, all'intestazione JWT. L'intestazione crit è un array di nomi di intestazione che deve essere conosciuto e riconosciuto dal ricevitore JWT. Ad esempio:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

In fase di esecuzione, il criterio VerificationJWT esamina l'intestazione crit. Per ogni elemento elencato nell'intestazione crit, controlla che anche l'elemento <KnownHeaders> del criterio VerificationJWT elenchi quell'intestazione. Qualsiasi intestazione trovata dal criterio VerificationJWT in crit non inclusa anche in <KnownHeaders> fa sì che il criterio VerificationJWT non vada a buon fine.

Nota: <CriticalHeaders> in realtà non aggiunge le intestazioni al JWT. Definisce solo i contenuti dell'intestazione crit. Puoi utilizzare <AdditionalHeader/Claims> per aggiungere le intestazioni.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Array di stringhe separato da virgole
Valori validi	Può essere un array o il nome di una variabile che contiene l'array.

<CustomClaims>

Nota: al momento viene inserito un elemento CustomClaims quando aggiungi un nuovo criterio GeneraJWT tramite l'interfaccia utente. Questo elemento non è funzionale e viene ignorato. L'elemento corretto da utilizzare è <AdditionalClaims>. La UI verrà aggiornata per inserire gli elementi corretti in un secondo momento.

<Scade in>

<ExpiresIn>time-value-here</ExpiresIn>

Specifica la durata del JWT in millisecondi, secondi, minuti, ore o giorni.

Nota: si tratta di un intervallo di tempo, non di un valore di tempo assoluto. La quantità può essere un valore numerico semplice, nel qual caso viene interpretata come millisecondi.

Predefinito	N/A
Presenza	Facoltativo
Tipo	Numero intero
Valori validi	Un valore o un riferimento a una variabile di flusso contenente il valore. Le unità di tempo possono essere specificate come segue: ms = millisecondi (predefinito) s = secondi m = minuti H = ore g = giorni Ad esempio, ExpiresIn=10d equivale a ExpiresIn di 864000s.

<Id&GT;

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Genera un JWT con la rivendicazione jti specifica. Quando il valore di testo e l'attributo ref sono entrambi vuoti, il criterio genera un jti contenente un UUID casuale. La richiesta con ID JWT (jti) è un identificatore univoco della JWT. Per ulteriori informazioni su jti, consulta RFC7519.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Stringa o riferimento.
Valori validi	Può essere una stringa o il nome di una variabile di flusso contenente l'ID.

<IgnoraUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta il valore su falso se vuoi che il criterio restituisca un errore quando una qualsiasi variabile di riferimento specificata nel criterio non è risolvibile. Impostato su true per trattare qualsiasi variabile non risolvibile come una stringa vuota (null).

Predefinito	falso.
Presenza	Facoltativo
Tipo	Booleano
Valori validi	vero o falso

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Il criterio genera un JWT contenente una rivendicazione di nome iss con un valore impostato sul valore specificato. Una rivendicazione che identifica l'emittente del JWT. Questo è uno dell'insieme registrato di dichiarazioni riportato in RFC7519.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Stringa o riferimento
Valori validi	Qualsiasi

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Specifica l'ora in cui il token diventa valido. Il token non è valido fino all'ora specificata. Puoi specificare un valore di tempo assoluto o un'ora relativa a quando viene generato il token.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Stringa
Valori validi	Vedi sotto.

Valori di tempo validi per l'elemento NotBefore per valori di tempo assoluti

Nome	Formato	Esempio
ordinabile	yyyy-MM-dd'T'HH:mm:ss.SSSZ	14-08-2017T11:00:21.269-0700
RFC 1123	EEE, dd MMM yyyy HH:mm:ss zzz	lun, 14 ago 2017 11:00:21 PDT
RFC 850	EEEE, dd-MMM-yy HH:mm:ss zzz	Lunedì 14-agosto-17 11:00:21 PDT
ANCI-C	EEE MMM d HH:mm:ss yyyy	Lun 14 ago 11:00:21 2017

Per i valori di tempo relativi, specifica un numero intero e un periodo di tempo, ad esempio:

• 10s
• 60m
• 12 ore

<OutputVariable&GT;

<OutputVariable>jwt-variable</OutputVariable>

Specifica dove posizionare il JWT generato da questo criterio. Per impostazione predefinita, viene inserito nella variabile di flusso jwt.POLICYNAME.generated_jwt.

Predefinito	jwt.POLICYNAME.generated_jwt
Presenza	Facoltativo
Tipo	Stringa (nome di una variabile di flusso)

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Specifica l'ID chiave (kid) da includere nell'intestazione JWT. Utilizza solo quando l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Stringa
Valori validi	Una variabile di flusso o una stringa

<chiave privata/password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Specifica la password che il criterio deve utilizzare per decriptare la chiave privata, se necessario. Utilizza l'attributo ref per passare la chiave in una variabile di flusso. Utilizza solo quando l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Stringa
Valori validi	Un riferimento a variabile di flusso. Nota: devi specificare una variabile di flusso. Apigee rifiuterà come non valide una configurazione di criteri in cui la password è specificata in testo non crittografato. La variabile di flusso deve avere il prefisso "private". Ad esempio, private.mypassword

<Chiave/Valore privato>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Specifica una chiave privata con codifica PEM utilizzata per firmare il JWT. Utilizza l'attributo ref per passare la chiave in una variabile di flusso. Utilizza l'algoritmo solo quando è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Predefinito	N/D
Presenza	Richiesto per generare un JWT utilizzando l'algoritmo RS256.
Tipo	Stringa
Valori validi	Una variabile di flusso contenente una stringa che rappresenta un valore di chiave privata RSA con codifica PEM. Nota: la variabile di flusso deve avere il prefisso "private". Ad esempio: private.mykey

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Specifica l'ID chiave (kid) da includere nell'intestazione JWT di un JWT firmato con un algoritmo HMAC. Utilizza l'algoritmo solo quando è HS256/HS384/HS512.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Stringa
Valori validi	Una variabile di flusso o una stringa

<SecretKey/Value&GT;

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Fornisce la chiave segreta utilizzata per verificare o firmare i token con un algoritmo HMAC. Utilizza solo quando l'algoritmo è di tipo HS256/HS384/HS512. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

Apigee applica una forza minima della chiave per gli algoritmi HS256/HS384/HS512. La lunghezza minima della chiave per HS256 è 32 byte, per HS384 è di 48 byte e per HS512 è di 64 byte. L'uso di una chiave di potenza inferiore causa un errore di runtime.

Nota: il nome della variabile deve includere il prefisso private, come mostrato nell'esempio precedente.

Predefinito	N/D
Presenza	Obbligatorio per gli algoritmi HMAC.
Tipo	Stringa
Valori validi	Una variabile di flusso che fa riferimento a una stringa Nota: se una variabile di flusso deve avere il prefisso "privato". Ad esempio, private.mysecret

<Oggetto>

<Subject>subject-string-here</Subject>

o

<Subject ref="flow_variable" />

Ad esempio:

<Subject ref="apigee.developer.email"/>

Il criterio genera un JWT contenente una dichiarazione sub impostata sul valore specificato.Questa rivendicazione identifica o fa una dichiarazione sull'oggetto del JWT. Questo è un insieme di rivendicazioni standard menzionato in RFC7519.

Predefinito	N/D
Presenza	Facoltativo
Tipo	Stringa
Valori validi	Qualsiasi valore che identifica in modo univoco un oggetto o una variabile di flusso che fa riferimento a un valore.

Variabili di flusso

Il criterio Genera JWT non imposta variabili di flusso.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration	401	Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch	401	The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.EncryptionFailed	401	Creation of an encrypted JWT failed for a non-specific reason
steps.jwt.FailedToDecode	401	The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed	401	The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength	401	For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim	401	For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration	401	Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve	401	The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidJsonFormat	401	Invalid JSON found in the header or payload.
steps.jwt.InvalidPasswordKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidToken	401	This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch	401	The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch	401	The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch	401	The subject claim failed on token verification.
steps.jwt.KeyIdMissing	401	The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed	401	The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader	401	Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey	401	The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed	401	In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired	401	The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid	401	The token is not yet valid.
steps.jwt.UnhandledCriticalHeader	401	A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException	401	An unknown exception occurred.
steps.jwt.WrongKeyType	401	Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidNameForAdditionalClaim	The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim	If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim	If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader	This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader	If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute	This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidConfigurationForActionAndAlgorithm	If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.
InvalidValueForElement	If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement	This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration	If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration	If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidVariableNameForSecret	This error occurs if the flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidSecretInConfig	This error occurs if the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidTimeFormat	If the value specified in the<NotBefore> element does not use a supported format, the deployment will fail.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "InvalidToken"
JWT.failed	All JWT policies set the same variable in the case of a failure.	JWT.failed = true

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>