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

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per la gestione degli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Stato HTTP Si verifica quando
steps.jws.GenerationFailed 401 Il criterio non è stato in grado di generare il JWS.
steps.jws.InsufficientKeyLength 401 Per una chiave di dimensioni inferiori a 32 byte per l'algoritmo HS256
steps.jws.InvalidClaim 401 Per una rivendicazione mancante o mancata corrispondenza di una rivendicazione oppure una mancata corrispondenza di intestazione o intestazione.
steps.jws.InvalidCurve 401 La curva specificata dalla chiave non è valida per l'algoritmo Curva ellittica.
steps.jws.InvalidJsonFormat 401 JSON non valido trovato nell'intestazione JWS.
steps.jws.InvalidPayload 401 Il payload JWS non è valido.
steps.jws.InvalidSignature 401 <DetachedContent> viene omesso e il JWS ha un payload di contenuti scollegato.
steps.jws.KeyIdMissing 401 Il criterio di verifica utilizza un JWKS come origine per le chiavi pubbliche, ma il JWS firmato non include una proprietà kid nell'intestazione.
steps.jws.KeyParsingFailed 401 Impossibile analizzare la chiave pubblica a partire dalle informazioni sulla chiave specificate.
steps.jws.MissingPayload 401 Payload JWS mancante.
steps.jws.NoAlgorithmFoundInHeader 401 Si verifica quando il JWS omette l'intestazione dell'algoritmo.
steps.jws.SigningFailed 401 In CreateJWS, per una chiave inferiore alla dimensione minima per gli algoritmi HS384 o HS512
steps.jws.UnknownException 401 Si è verificata un'eccezione sconosciuta.
steps.jws.WrongKeyType 401 Tipo di chiave specificato errato. Ad esempio, se specifichi una chiave RSA per un algoritmo Elliptic Curve o una chiave curva per un algoritmo RSA.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome errore Si verifica quando
InvalidAlgorithm Gli unici valori validi sono: 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

 Altri possibili errori di deployment.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come elencato nella precedente tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice di errore. fault.name Matches "TokenExpired"
JWS.failed Tutti i criteri JWS impostano la stessa variabile in caso di errore. jws.JWS-Policy.failed = true

Esempio di risposta di errore

Per la gestione degli errori, la best practice è il trap della parte errorcode dell'errore risposta. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

Esempio di regola di errore

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