Criterio GenerateJWS

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

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

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

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

Video

Guarda un breve video per scoprire come generare un JWT firmato. Anche se questo video riguarda specificamente la generazione di un JWT, molti dei concetti sono gli stessi per i JWS.

Esempi

Genera un JWS firmato con HS256

Questo criterio di esempio genera un JWS firmato utilizzando l'algoritmo HS256. HS256 si basa su un segreto condiviso sia per la firma sia per la verifica della firma. Questo JWS utilizza contenuti "allegati", ovvero l'intestazione, il payload e la firma codificati vengono concatenati con un punto per produrre il JWS finale:

[header].[payload].[signature]

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

La configurazione del criterio riportata di seguito crea un JWS da un payload contenuto nella variabile my-payload e memorizza 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 con HS256

Questo esempio genera anche un JWS con contenuti allegati firmati utilizzando l'algoritmo HS256. In questo caso, il payload è JSON. L'impostazione dell'intestazione typ su JWT genera un JWS firmato che è anche un JWT firmato. (reference)

La configurazione del criterio riportata di seguito crea un JWS da un payload contenuto nella variabile json-content e memorizza il JWS risultante nella variabile output-variable. Il risultato sarà un JWT firmato se e solo se la variabile json-content contiene un payload JSON e le proprietà al suo interno sono valide per JWT. Ad esempio, la proprietà exp, se presente, deve contenere un valore numerico. La proprietà aud, se presente, deve essere una stringa o un array di stringhe. e così via. Consulta IETF RFC7519 per dettagli sui valori validi per i claim 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>

Generare 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 privata RSA, che deve essere fornita in forma codificata PEM.

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

[header]..[signature]

Utilizza l'elemento <Payload> per specificare il payload JWS non codificato e non elaborato. 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 JWS serializzato. Questa opzione è utile quando i contenuti firmati sono di grandi dimensioni, binari (ad esempio un'immagine o un PDF) o entrambi. Per consentire la convalida, devi trasmettere alla parte che esegue la verifica entrambi gli elementi, ovvero il JWS e il payload incluso nei contenuti firmati. Se utilizzi il criterio VerifyJWS 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>

Impostazione degli elementi chiave

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

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 saperne di più sui requisiti delle chiavi, consulta Informazioni sugli algoritmi di crittografia delle firme.

Riferimento elemento per Generate JWS

Il riferimento ai criteri descrive gli elementi e gli attributi del criterio Generate JWS.

Nota:la configurazione varia leggermente a seconda dell'algoritmo di crittografia utilizzato. Consulta la sezione Samples per esempi che mostrano le configurazioni per casi d'uso specifici.

Attributi che si applicano all'elemento di primo livello

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

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

Attributo Descrizione Predefinito Presenza
nome 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 limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.

Se vuoi, 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 Obbligatorio
continueOnError Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio.

falso Facoltativo
abilitato 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 è stato ritirato. falso Ritirato

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

Predefinito Se ometti questo elemento, viene utilizzato il valore dell'attributo name 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

<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 dei claim aggiuntivi nell'intestazione del JWS.

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

L'elemento <Claim> prevede i seguenti attributi:

  • name: (obbligatorio) il nome della rivendicazione, noto anche come parametro.
  • ref: (Facoltativo) il nome di una variabile del flusso. Se presente, il criterio utilizzerà il valore di questa variabile come reclamo. Se vengono specificati sia un attributo ref sia un valore esplicito della rivendicazione, il valore esplicito è predefinito e viene utilizzato se la variabile di flusso a cui si fa riferimento non è risolta.
  • type: (facoltativo) Uno dei seguenti: stringa (valore predefinito), numero, booleano o mappa
  • array: (facoltativo) impostato 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 al JWS. L'intestazione crit è un array di nomi di intestazione che devono essere noti e riconosciuti dal destinatario JWS. Ad esempio, puoi utilizzare questo elemento di configurazione per produrre un'intestazione JWS che, una volta decodificata, ha il seguente aspetto:

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

Questa intestazione JWS afferma che il parametro dell'intestazione hyb è di fondamentale importanza e che qualsiasi destinatario del JWS deve comprendere il significato e il valore di questo parametro.

Ai sensi del documento IETF RFC 7515, il destinatario di un JWS deve rifiutarlo come non valido se non comprende uno o più dei parametri a cui si fa riferimento nel parametro crit. In Apigee, il criterio VerifyJWS è conforme a questo comportamento. Per ogni parametro elencato nel parametro crit, viene controllato che anche l'elemento <KnownHeaders> del criterio VerifyJWS lo elenchi. Qualsiasi intestazione trovata dal criterio VerifyJWS in crit che non è elencata anche in <KnownHeaders> fa sì che il criterio VerifyJWS rifiuti il JWS.

Predefinito N/D
Presenza Facoltativo
Tipo Array di una o più stringhe separate da virgole
Valori validi Un array o un riferimento a una variabile contenente l'array.

<DetachContent>

<DetachContent>true|false</DetachContent>

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

Se specifichi false, il valore predefinito, il JWS generato è nel formato:

[header].[payload].[signature]

Se specifichi true per creare un JWS con un payload scollegato, il JWS generato omette il payload ed è nel formato:

[header]..[signature]

Con un JWS che utilizza un payload separato, sta a te passare il payload non codificato originale alla parte che esegue la verifica, insieme al JWS serializzato.

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi true o false

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta su false se vuoi che il criterio generi un errore quando una variabile a cui viene fatto riferimento specificata nel criterio non è risolvibile. Imposta su true per trattare qualsiasi variabile irrisolvibile come una stringa vuota (null).

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi true o false

<OutputVariable>

<OutputVariable>output-variable</OutputVariable>

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

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

<Payload>

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

or

<Payload>payload-value</Payload>

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

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

Elemento <PrivateKey>

Questo parametro è facoltativo e deve essere utilizzato solo se <Algorithm> è una delle opzioni RS*, PS* o ES*. Specifica la chiave privata da utilizzare per la firma, nonché altre informazioni relative alla chiave privata. Viene utilizzato quando l'algoritmo è asimmetrico.

<PrivateKey>
   <Value ref="private.privatekey"</Value>
</PrivateKey>
Valore predefinito: N/D
Presenza: Facoltativo. Tuttavia, devi includere esattamente uno degli elementi <PrivateKey> o <SecretKey>. Utilizza l'elemento <PrivateKey> se l'algoritmo è RS*, PS* o ES* e l'elemento <SecretKey> se l'algoritmo è HS*.
Tipo: N/D

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

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

<PrivateKey/Password>

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

Se necessario, specifica la password che il criterio deve utilizzare per decriptare la chiave privata. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valori validi

Un riferimento a una variabile di flusso. Nota: devi specificare una variabile di flusso con l'attributo ref. Apigee rifiuterà come non valida una configurazione del criterio in cui la password è specificata in testo normale. La variabile di flusso deve avere il prefisso "private". Ad esempio, private.mypassword

<PrivateKey/Value>

<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 la chiave in una variabile di flusso.

Predefinito N/D
Presenza Obbligatorio quando si utilizza il criterio per generare un JWS utilizzando uno degli algoritmi RS*, PS* o ES*.
Tipo Stringa
Valori validi Una variabile di flusso contenente una stringa che rappresenta un valore della chiave privata codificata in PEM.

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

<SecretKey>

<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 segreta da utilizzare per generare un JWS che utilizza un algoritmo simmetrico (HS*), uno tra HS256, HS384 o HS512.

Questo elemento è facoltativo. Tuttavia, devi includere esattamente uno degli elementi <PrivateKey> o <SecretKey>. Utilizza l'elemento <PrivateKey> per generare un JWS firmato con un algoritmo asimmetrico (uno di RS*, PS* o ES*) e l'elemento <SecretKey> per generare un JWS firmato con un algoritmo simmetrico (ad esempio HS*).

Figli di <SecretKey>

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

Figlio Presenza Descrizione
encoding (attributo) Facoltativo

Specifica in che modo la chiave viene codificata nella variabile a cui si fa riferimento. Per impostazione predefinita, se non è presente alcun 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 della variabile private.secretkey sono 494c6f766541504973, la chiave verrà decodificata come un insieme di 9 byte, che in esadecimale sarà 49 4c 6f 76 65 41 50 49 73.

ID (elemento) Facoltativo

L'identificatore della chiave. Il valore può essere una stringa qualsiasi. Puoi specificare il valore come valore di testo letterale o indirettamente, tramite un riferimento a una variabile, con l'attributo 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 della chiave come claim 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, ad esempio private.secret-key .

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

Apigee applica una robustezza minima della chiave per gli algoritmi HS256/HS384/HS512. La lunghezza minima della chiave per HS256 è 32 byte, per HS384 è 48 byte e per HS512 è 64 byte. L'utilizzo di una chiave con un'intensità inferiore causa un errore di runtime.

<Type>

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

Elemento facoltativo il cui unico valore consentito è Signed, che specifica che il criterio genera un JWS firmato. <Type> viene fornito solo per corrispondere all'elemento corrispondente per i criteri GenerateJWT 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 le variabili di flusso.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Si verifica quando
steps.jws.GenerationFailed 401 Il criterio non è stato in grado di generare la JWS.
steps.jws.InsufficientKeyLength 401 Per una chiave di meno di 32 byte per l'algoritmo HS256
steps.jws.InvalidClaim 401 Per una richiesta mancante o una mancata corrispondenza della richiesta oppure per un'intestazione mancante o una mancata corrispondenza dell'intestazione.
steps.jws.InvalidCurve 401 La curva specificata dalla chiave non è valida per l'algoritmo di 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 dei 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 Non è stato possibile analizzare la chiave pubblica dalle informazioni sulla chiave fornite.
steps.jws.MissingPayload 401 Il payload JWS non è presente.
steps.jws.NoAlgorithmFoundInHeader 401 Si verifica quando JWS omette l'intestazione dell'algoritmo.
steps.jws.SigningFailed 401 In GenerateJWS, 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 a curva per un algoritmo RSA.

Errori di deployment

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

Nome dell'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, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'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 è intercettare la parte errorcode della risposta all'errore. 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>