Criterio Genera JWS

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

icona norme

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.

Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta Tipi di criteri.

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 firmato con HS256

Questo criterio di esempio genera un JWS firmato utilizzando l'algoritmo HS256. Si basa su HS256 su un secret condiviso sia per la firma che per la verifica della firma. Questo JWS utilizza "collegato" il che significa che l'intestazione, il payload e la firma codificati sono collegati tra loro il JWS finale:

[header].[payload].[signature]

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, Apigee 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 my-payload e archivia il JWS risultante nella variabile output-variable.

<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="my-payload"/>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

Genera un JWT firmato HS256

Questo esempio genera anche un JWS con contenuto allegato firmato utilizzando l'interfaccia HS256. dell'algoritmo. In questo caso, il payload è in formato JSON. Impostazione dell'intestazione typ su JWT genera un JWS firmato che sia anche un JWT firmato. (riferimento)

La configurazione del criterio seguente crea un JWS da un payload contenuto nella variabile json-content e archivia il JWS risultante nella variabile output-variable. Il risultato sarà un JWT firmato solo se La variabile json-content contiene un payload JSON e le proprietà al suo interno che il payload JSON sia valido per JWT. Ad esempio, la proprietà exp, se è devono contenere un valore numerico. La proprietà aud, se presente, deve essere una stringa o un array di stringhe. e così via. Consulenza IETF RFC7519 per i dettagli sui valori validi per le attestazioni JWT.

<GenerateJWS name="JWS-Generate-HS256-JWT">
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Payload ref="json-content"/>
    <AdditionalHeaders>
        <Claim name="typ">JWT</Claim>
    </AdditionalHeaders>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

Genera un JWS scollegato

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

Un JWS con contenuti scollegati omette il payload dal JWS generato:

[header]..[signature]

Utilizza l'elemento <Payload> per specificare il payload JWS non elaborato e non codificato. Quando questo criterio viene attivato, Apigee codifica l'intestazione e il payload JWS, quindi li utilizza per generare la firma codificata. Tuttavia, il JWS generato omette il payload codificato dal il JWS serializzato. Ciò è utile quando il contenuto firmato è di grandi dimensioni o binario (ad esempio, immagine o PDF) o entrambi. Per consentire la convalida, devi passare entrambi gli elementi, il JWS e incluso nei contenuti firmati, alla parte che ha effettuato la verifica. Se utilizzi Verifica il criterio JWS per verificare il JWS. Puoi specificare la variabile contenente il payload con l'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="my-payload"/>
    <DetachContent>true</DetachContent>
    <OutputVariable>output-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 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 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 Predefinito Presenza
nome Il nome interno del criterio. I caratteri utilizzabili nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, la UI di Apigee applica come la rimozione automatica di caratteri non alfanumerici.

Se vuoi, puoi usare l'elemento <displayname></displayname> per etichetta il criterio nell'editor proxy della UI di Apigee con una lingua diversa, .

 N/D Obbligatorio
continueOnError Imposta il valore su false per restituire un errore quando un criterio non funziona. 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
abilitato 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 Ritirato

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare in aggiunta all'attributo name per etichettare il criterio nell'editor proxy della UI di Apigee con un nome diverso in linguaggio naturale.

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Specifica l'algoritmo di crittografia per firmare il token.

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

Predefinito 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 dichiarazione, anche noto come parametro.
  • 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 di 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: puoi utilizzare questo elemento di configurazione per produrre un'intestazione JWS che, una volta decodificata, questo:

{
  "typ": "...",
  "alg" : "...",
  "hyb" : "some-value-here",
  "crit" : [ "hyb" ],
}

Questa intestazione JWS afferma che il parametro dell'intestazione hyb è critico importanza e ogni destinatario del JWS deve comprenderne il significato e il valore .

In base allo standard IETF RFC 7515, il destinatario di un JWS deve rifiutarlo come non valido se il destinatario non comprende uno o più parametri a cui viene fatto riferimento nel crit. In Apigee, il criterioVerifyJWS è conforme a questo comportamento. Per ogni parametro elencato nel parametro crit, viene verificato che la proprietà Anche l'elemento <KnownHeaders> del criterio VerifyJWS elenca questo parametro. Qualsiasi intestazione che il criterio VerifyJWS trova in crit e che non è presente anche nell'elenco in <KnownHeaders> fa sì che il criterio VerifyJWS rifiute il JWS.

Predefinito N/D
Presenza Facoltativo
Tipo Matrice separata da virgole di una o più stringhe
Valori validi Un array o un riferimento a una variabile contenente 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 un JWS con un payload scollegato, il JWS generato omette il parametro payload ed è in forma:

[header]..[signature]

Con un JWS che utilizza un payload scollegato, spetta a te passare il payload non codificato originale a alla parte verificante, insieme al JWS serializzato.

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta il valore su 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).

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

&lt;OutputVariable&gt;

<OutputVariable>output-variable</OutputVariable>

Specifica il nome della variabile di contesto che il criterio verrà impostato con il JWS generato. Per impostazione predefinita, il criterio inserisce JWS nella variabile di contesto denominata jws.POLICYNAME.generated_jws.

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

Predefinito N/D
Presenza Obbligatorio
Tipo Stringa, array di byte, flusso o qualsiasi altra rappresentazione del payload JWS non codificato.
Valori validi Un modello di messaggio o un riferimento a una variabile contenente il payload.

&lt;PrivateKey&gt; elemento

Questa opzione è facoltativa e deve essere utilizzata solo se <Algorithm> è una delle opzioni RS*, PS*, o ES*. Specifica la chiave privata da utilizzare per la firma, nonché altre informazioni e la chiave di accesso alla chiave privata. Viene utilizzato quando l'algoritmo è asimmetrico.

<PrivateKey>
   <Value ref="private.privatekey"</Value>
</PrivateKey>
Predefinita: N/D
Presenza: Facoltativo. Tuttavia, devi includere esattamente uno dei due elementi Elemento <PrivateKey> o <SecretKey>. Utilizza l'elemento <PrivateKey> quando l'algoritmo è RS*, PS* o ES*, e utilizza l'elemento <SecretKey> quando l'algoritmo è HS*.
Tipo: N/D

&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 (bambini) da includere nell'intestazione JWS.

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

Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valori validi

Un riferimento alla variabile di flusso. Nota: devi specificare una variabile di flusso con l'attributo ref. Apigee rifiuterà i criteri come non validi 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.

Predefinito N/D
Presenza Richiesto quando si utilizza il criterio per generare un JWS utilizzando uno dei metodi RS*, PS* o ES*.
Tipo Stringa
Valori validi Una variabile di flusso contenente una stringa che rappresenta un valore di chiave privata con codifica PEM.

Nota: la variabile di flusso deve avere il prefisso "private". Ad esempio: private.mykey

&lt;SecretKey&gt;

<SecretKey encoding="base16|hex|base64|base64url" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

Specifica la chiave secret da utilizzare quando generando un JWS che utilizza un algoritmo simmetrico (HS*), uno di HS256, HS384 o HS512.

Questo elemento è facoltativo. Tuttavia, devi includere esattamente uno dei due elementi Elemento <PrivateKey> o <SecretKey>. Utilizza l'elemento <PrivateKey> quando generi un JWS firmato con un algoritmo asimmetrico (RS*, PS* o ES*), e utilizzare l'elemento <SecretKey> quando generi un JWS firmato con algoritmo simmetrico (algoritmo come HS*).

Elementi secondari di <SecretKey>

La tabella seguente fornisce una descrizione degli elementi e degli attributi secondari <SecretKey>:

Figlio Presenza Descrizione
codifica (attributo) Facoltativo

Specifica in che modo la chiave viene codificata nella variabile di riferimento. Per impostazione predefinita, quando non È presente l'attributo encoding, la codifica della chiave viene trattata come UTF-8. I valori validi per l'attributo sono: esadecimale, base16, base64 o base64url. I valori di codifica esadecimale e base16 sono sinonimi.

<SecretKey encoding="hex" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.secretkey"/>
</SecretKey>

Nell'esempio precedente, poiché la codifica è hex, se i contenuti di la variabile private.secretkey è 494c6f766541504973, la chiave verrà decodificato in un insieme di 9 byte, che in formato esadecimale 49 4c 6f 76 65 41 50 49 73.

ID (elemento) Facoltativo

L'identificatore della chiave. Il valore può essere qualsiasi stringa. Puoi specificare il valore come valore testuale letterale o indirettamente tramite un riferimento a variabile, con ref .

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

or

<SecretKey>
  <Id>your-id-value-here</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

Il criterio includerà questo identificatore chiave come dichiarazione kid nell'intestazione del JWS generato.

Valore (elemento) Obbligatorio

Una chiave segreta codificata. Specifica la chiave segreta utilizzata per firmare il payload. Utilizza l'attributo ref per fornire la chiave indirettamente tramite una variabile, come private.secret-key .

<SecretKey>
  <Id ref="flow-variable-name-here"/>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

Apigee applica un'intensità 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.

&lt;Type&gt;

<Type>type-string-here</Type>

Elemento facoltativo il cui unico valore consentito è Signed, che specifica che il criterio genera un JWS firmato. <Type> fornito solo per corrispondere all'elemento corrispondente per i criteri CreateJWT e VerifyJWT (dove può assumere uno dei valori Signed o Encrypted).

Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valore valido Signed

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 che vengono restituiti e le variabili di errore impostate da Apigee 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 maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è 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 prevede il trap della parte errorcode della risposta di errore. Non fare affidamento sul testo nel 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>