Criterio GenerateJWS

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Genera un JWS firmato, con un insieme configurabile di attestazioni. Il JWS può quindi essere restituito trasmessi a destinazioni di backend o utilizzati in altri modi. Per un'introduzione dettagliata, consulta la panoramica delle norme JWS e JWT.

Per informazioni sulle parti di un JWS e su come vengono criptate e firmate, consulta RFC7515.

Video

Guarda un breve video per scoprire come generare un JWT firmato. Mentre il video è specifici per la generazione di un JWT, molti dei concetti sono gli stessi per JWS.

Esempi

Genera un JWS collegato firmato con HS256 algoritmo

Questo criterio di esempio genera un JWS collegato e lo firma utilizzando l'algoritmo HS256. Si basa su HS256 su un secret condiviso sia per la firma che per la verifica della firma.

Un JWS allegato contiene l'intestazione, il payload e la firma codificati:

header.payload.signature

Imposta <DetachContent> su true per generare contenuti scollegati. Consulta la sezione Componenti di un JWS/JWT per ulteriori informazioni nella la struttura e il formato di un JWS.

Utilizza l'elemento <Payload> per specificare il payload JWS non elaborato e non codificato. In questo esempio, una variabile contiene il payload. Quando viene attivata questa azione del criterio, Edge codifica l'intestazione e il payload JWS, quindi aggiunge la firma codificata per firmare digitalmente il JWS.

La configurazione del criterio seguente crea un JWS da un payload contenuto nella variabile private.payload.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Genera un JWS scollegato firmato con RS256 algoritmo

Questo criterio di esempio genera un JWS scollegato e lo firma utilizzando l'algoritmo RS256. La generazione di un La firma RS256 si basa su una chiave privata RSA, che deve essere fornita in formato con codifica PEM.

Un JWS scollegato omette il payload dal JWS:

header..signature

Utilizza l'elemento <Payload> per specificare il payload JWS non elaborato e non codificato. Quando questo criterio viene attivato, Edge codifica l'intestazione e il payload JWS, e le utilizza per generare la firma codificata. Tuttavia, il JWS generato omette il payload. Spetta a te passare il payload al criterio VerifyJWS utilizzando Elemento <DetachedContent> del criterio VerifyJWS.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Impostare gli elementi chiave

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

Algoritmo Elementi principali
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 principali, consulta Informazioni sugli algoritmi di crittografia della firma.

Riferimento elemento per Genera JWS

La guida di riferimento al criterio descrive gli elementi e gli attributi del criterio Genera JWS.

Nota:la configurazione varierà leggermente a seconda della crittografia. l'algoritmo utilizzato. Fai riferimento agli esempi per esempi che dimostrano configurazioni per casi d'uso specifici.

Attributi che applica all'elemento di primo livello

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

I seguenti attributi sono comuni a tutti gli elementi principali del criterio.

Attributo Descrizione Predefinita Presenza
nome Il nome interno del criterio. I caratteri utilizzabili nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di gestione perimetrale applica come la rimozione automatica di caratteri non alfanumerici.

Se vuoi, puoi usare l'elemento <displayname></displayname> per etichetta il criterio nell'editor proxy dell'interfaccia utente di gestione con un linguaggio naturale diverso nome.

 N/D Obbligatorio
continueOnError Imposta il valore su false per restituire un errore quando un criterio non viene eseguito. Si tratta di un comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche dopo un criterio non riesce.

 falso Facoltativo
abilitata Imposta il valore su true per applicare il criterio.

Imposta su false per "disattivare" il criterio. Il criterio non verrà applicato in modo forzato anche se rimane collegato a un flusso.

 true Facoltativo
asinc Questo attributo è obsoleto. falso Deprecato

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare, in aggiunta all'attributo name, per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

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

&lt;Algorithm&gt;

<Algorithm>algorithm-here</Algorithm>

Specifica l'algoritmo di crittografia per firmare il token.

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

&lt;AdditionalHeaders/Claim&gt;

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

Consente di inserire le altre coppie nome/valore della rivendicazione nell'intestazione del JWS.

Predefinita N/D
Presenza Facoltativo
Valori validi Qualsiasi valore che vuoi utilizzare per una rivendicazione aggiuntiva. Puoi specificare la dichiarazione in modo esplicito 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.
  • ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questo come la dichiarazione. Se vengono specificati sia un attributo ref sia un valore di dichiarazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile del flusso di riferimento non è risolta.
  • type: (facoltativo) uno dei seguenti: string (predefinito), numero, booleano o mappa
  • array - (Facoltativo) Imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false.

&lt;CriticalHeaders&gt;

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Aggiunge l'intestazione critica, crit, al JWS. Intestazione crit è un array di nomi di intestazione che devono essere noti e riconosciuti dal ricevitore JWS. Ad esempio:

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

In fase di runtime, il criterioVerifyJWS esamina l'intestazione crit. Per ogni intestazione elencata nell'intestazione crit, viene verificato che l'elemento <KnownHeaders> del criterio VerifyJWS elenca anche quell'intestazione. Qualsiasi intestazione trovata dal criterio VerifyJWS in crit che non è anche elencato in <KnownHeaders>, fa sì che il criterio VerifyJWS non vada a buon fine.

Predefinita N/D
Presenza Facoltativo
Tipo Matrice di stringhe separate da virgole
Valori validi Una matrice o il nome di una variabile che contiene l'array.

&lt;DetachContent&gt;

<DetachContent>true|false</DetachContent>

Specifica se generare il JWS con un payload scollegato, <DetachContent>true</DetachContent>, <DetachContent>false</DetachContent>.

Se specifichi false, il valore predefinito, il JWS generato avrà il seguente formato:

header.payload.signature

Se specifichi true per creare il payload scollegato, il JWS generato omette il payload e presenta il seguente formato:

header..signature

Con un payload scollegato, spetta a te passare il payload originale non codificato al criterio VerifyJWS mediante l'elemento <DetachedContent> del criterio VerifyJWS.

Predefinita falso
Presenza Facoltativo
Tipo Booleano
Valori validi true o false

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta il valore false se vuoi che il criterio generi un errore quando viene specificata una variabile di riferimento. del criterio non è risolvibile. Imposta il valore su true per trattare le variabili irrisolvibili come stringhe vuote (nullo).

Predefinita falso
Presenza Facoltativo
Tipo Booleano
Valori validi true o false

&lt;OutputVariable&gt;

<OutputVariable>JWS-variable</OutputVariable>

Specifica dove posizionare il JWS generato da questo criterio. Per impostazione predefinita, viene posizionata la variabile di flusso jws.POLICYNAME.generated_jws.

Predefinita jws.POLICYNAME.generated_jws
Presenza Facoltativo
Tipo Stringa (nome variabile di flusso)

&lt;Payload&gt;

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

Specifica il payload JWS non elaborato e non codificato. Specifica una variabile contenente il payload o una stringa.

Predefinita N/D
Presenza Obbligatorio
Tipo Stringa, array di byte, flusso o qualsiasi altra rappresentazione del payload JWS non codificato.

&lt;PrivateKey/Id&gt;

<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 JWS. Utilizza solo quando l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

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

&lt;PrivateKey/Password&gt;

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

Specifica la password che il criterio deve utilizzare per decriptare la chiave privata, se necessario. Utilizza la 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.

Predefinita N/D
Presenza Facoltativo
Tipo Stringa
Valori validi Un riferimento alla variabile di flusso.

Nota: devi specificare una variabile di flusso. Edge rifiuterà come non valido un in cui la password è specificata in testo non crittografato. La variabile di flusso deve avere il prefisso "private". Ad esempio, private.mypassword

&lt;PrivateKey/Value&gt;

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

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

Predefinita N/D
Presenza Necessario per generare un JWS 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

&lt;SecretKey/Id&gt;

<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 JWS di un JWS firmato con un HMAC dell'algoritmo. Da utilizzare solo se l'algoritmo è uno dei seguenti: HS256/HS384/HS512.

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

&lt;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 è uno di HS256/HS384/HS512. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

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

Predefinita 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 "private". Per esempio: private.mysecret

Variabili di flusso

Il criterio Genera JWS 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 Edge 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.jws.GenerationFailed 401 The policy was unable to generate the JWS.
steps.jws.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidPayload 401 The JWS payload is invalid.
steps.jws.InvalidSignature 401 <DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not include a kid property in the header.
steps.jws.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.SigningFailed 401 In GenerateJWS, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jws.UnknownException 401 An unknown exception occurred.
steps.jws.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.

Error name Occurs when
InvalidAlgorithm The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 Other possible deployment errors.

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 "TokenExpired"
JWS.failed All JWS policies set the same variable in the case of a failure. jws.JWS-Policy.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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>