Questa pagina si applica a Apigee e Apigee ibrido.
Visualizza la documentazione di
Apigee Edge.
Cosa
Genera un JWS firmato, con un insieme configurabile di attestazioni. JWS può quindi essere restituito ai client, trasmesso alle destinazioni del backend o utilizzato 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 è un criterio estendibile e il suo utilizzo potrebbe avere 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 la pagina Tipi di criteri.
Video
Guarda un breve video per scoprire come generare un JWT firmato. Sebbene questo video sia specifico per la generazione di un JWT, molti 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. HS256 si basa su un secret condiviso sia per la firma che per la verifica della firma. Questo JWS utilizza contenuti "allegato", il che significa che l'intestazione, il payload e la firma codificati sono concatenati in modo da produrre 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 dei criteri 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'algoritmo
HS256. In questo caso, il payload è in formato JSON. Se imposti l'intestazione typ
su JWT, verrà generato un JWS firmato che sia anche un JWT firmato.
(riferimento)
La configurazione dei criteri 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à all'interno di quel payload JSON 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 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 privata RSA, che deve essere fornita in formato con codifica PEM.
Un JWS con contenuto scollegato 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 JWS serializzato. Ciò è utile quando i contenuti firmati sono di grandi dimensioni, binari (ad esempio un'immagine o PDF) o entrambi. Per consentire la convalida, devi passare entrambi gli elementi, il JWS e il payload incluso nei contenuti firmati, alla parte coinvolta nella verifica. Se utilizzi il
criterio VerifyJWS per verificare il criterio 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 mostrato 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 |
|
* Per ulteriori informazioni sui requisiti delle chiavi, 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 dell'algoritmo di crittografia utilizzato. Fai riferimento agli esempi per esempi che dimostrano 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 del criterio.
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
nome |
Il nome interno del criterio. I caratteri che puoi utilizzare nel nome sono limitati a:
A-Z0-9._\-$ % . Tuttavia, la UI di Apigee applica limitazioni aggiuntive, come la rimozione automatica dei caratteri non alfanumerici.
Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Imposta il valore su false per restituire un errore quando un criterio non viene eseguito. Questo è il comportamento previsto
per la maggior parte dei criteri.
Imposta su |
false | Facoltativo |
abilitato |
Imposta il valore su true per applicare il criterio.
Imposta |
true | Facoltativo |
async | Questo attributo è obsoleto. | false | Deprecato |
<DisplayName>
<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 | String |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
Specifica l'algoritmo di crittografia per firmare il token.
Predefinito | N/A |
Presenza | Obbligatorio |
Tipo | String |
Valori validi | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Intestazione aggiuntiva/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>
Consente di inserire le altre coppie nome/valore della rivendicazione nell'intestazione del JWS.
Predefinito | N/A |
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 questa variabile come dichiarazione. Se sono specificati sia un attributo ref sia un valore esplicito della rivendicazione, 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.
<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 ricevitore JWS. Ad esempio, puoi utilizzare questo elemento di configurazione per produrre un'intestazione JWS che, una volta decodificata, avrà il seguente aspetto:
{ "typ": "...", "alg" : "...", "hyb" : "some-value-here", "crit" : [ "hyb" ], }
Questa intestazione JWS afferma che il parametro di intestazione hyb è di importanza critica e che tutti i destinatari di JWS devono comprenderne il significato e il valore.
In base allo standard IETF RFC 7515, il destinatario di un JWS deve rifiutarlo come non valido se non comprende uno o più parametri a cui si fa riferimento nel parametro crit. In Apigee, il criterioVerifyJWS è conforme a questo comportamento.
Per ogni parametro elencato nel parametro crit, il controllo verifica che venga elencato anche nell'elemento <KnownHeaders>
del criterio VerifyJWS.
Per qualsiasi intestazione che il criterio VerifyJWS trova in crit e che non è elencata anche
in <KnownHeaders>
, il criterio VerifyJWS rifiuterà il JWS.
Predefinito | N/A |
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. |
<DetachContent>
<DetachContent>true|false</DetachContent>
Specifica se generare il JWS con un payload scollegato, <DetachContent>true</DetachContent>
o meno <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 payload e presenta il seguente formato:
[header]..[signature]
Con un JWS che utilizza un payload scollegato, spetta a te passare il payload non codificato originale alla parte verificante, insieme al JWS serializzato.
Predefinito | false |
Presenza | Facoltativo |
Tipo | Booleano |
Valori validi | vero o falso |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Imposta il valore false se vuoi che il criterio generi un errore quando qualsiasi variabile di riferimento specificata nel criterio non è risolvibile. Imposta il valore su true per trattare qualsiasi variabile non risolvibile come una stringa vuota (null).
Predefinito | false |
Presenza | Facoltativo |
Tipo | Booleano |
Valori validi | vero o falso |
<OutputVariable>
<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) |
<Payload>
<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/A |
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. |
Elemento <PrivateKey>
Questa opzione è facoltativa, da utilizzare 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>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere esattamente uno degli elementi <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/A |
<PrivateKey/Id>
<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/A |
Presenza | Facoltativo |
Tipo | String |
Valori validi | Una stringa o una variabile di flusso |
<PrivateKey/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.
Predefinito | N/A |
Presenza | Facoltativo |
Tipo | String |
Valori validi |
Un riferimento alla variabile di flusso. Nota: devi specificare una variabile di flusso con l'attributo ref. Apigee rifiuterà come non valida una configurazione di criteri in cui la password è specificata in testo non crittografato. La variabile di flusso
deve avere il prefisso "private". Ad esempio, |
<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/A |
Presenza | Obbligatorio quando utilizzi il criterio per generare un JWS utilizzando uno degli algoritmi RS*, PS* o ES*. |
Tipo | String |
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,
|
<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 secret da utilizzare durante la generazione di 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>
quando generi un JWS firmato con un algoritmo asimmetrico (RS*, PS* o ES*) e utilizza l'elemento <SecretKey>
quando generi un JWS firmato con un algoritmo simmetrico (algoritmo come HS*).
Elementi secondari di <SecretKey>
La seguente tabella fornisce una descrizione degli elementi e degli attributi secondari di
<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
alcun attributo <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 è |
ID (elemento) | Facoltativo | L'identificatore della chiave. Il valore può essere qualsiasi stringa. Puoi specificare il valore come
valore di testo letterale o indirettamente, tramite un riferimento a una variabile, con l'attributo
<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 di chiave come richiesta |
Valore (elemento) | Obbligatorio | Una chiave segreta codificata. Specifica la chiave segreta utilizzata per firmare il payload.
Utilizza l'attributo <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. |
<Tipo>
<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 CreateJWT e VerifyJWT (dove
può assumere uno dei valori Signed
o Encrypted
).
Predefinito | N/A |
Presenza | Facoltativo |
Tipo | String |
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 . |
|
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>