Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Cosa
Genera un JWS firmato, con un insieme configurabile di attestazioni. 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.
Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta 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 dei concetti sono gli stessi per JWS.
Esempi
Genera un JWS firmato con HS256
Questa policy di esempio genera una JWS firmata 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 "allegati", ovvero l'intestazione, il payload e la firma codificati sono 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 del criterio,
Apigee codifica l'intestazione e il payload JWS, quindi aggiunge la firma codificata per firmare digitalmente il JWS.
La configurazione dei criteri riportata di seguito 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 con HS256
Questo esempio genera anche un JWS con contenuti allegati firmati utilizzando l'algoritmo HS256. In questo caso, il payload è JSON. Se imposti l'intestazione typ su JWT,
ottieni un JWS firmato che è anche un JWT firmato.
(riferimento)
La configurazione dei criteri riportata di seguito crea una firma JWS da un payload contenuto nella variabile
json-content e memorizza la firma 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à all'interno
di questo 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
informazioni dettagliate sui valori validi per le rivendicazioni 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 una JWS disaccoppiata
Questa policy di esempio genera una JWS con contenuti separati, firmata 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 contenuti separati omette il payload dal JWS generato:
[header]..[signature]
Utilizza l'elemento <Payload> per specificare il payload JWS non codificato non elaborato.
Quando viene attivato questo criterio, 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 grandi o binari (ad esempio
un'immagine o un PDF) o entrambi. Per consentire la convalida, devi trasmettere entrambi gli elementi, ovvero la firma JWS e il
payload incluso nei contenuti firmati, alla parte che esegue la verifica. Se utilizzi il criterio
VerifyJWS per verificare la firma 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 che utilizzi per specificare la chiave utilizzata per generare la firma 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 |
|
| * Per saperne di più sui requisiti delle chiavi, consulta Informazioni sugli algoritmi di crittografia della firma. | ||
Riferimento elemento per Genera JWS
Il riferimento ai criteri descrive gli elementi e gli attributi dei criteri Genera JWS.
Nota: la configurazione varia leggermente a seconda dell'algoritmo di crittografia utilizzato. Consulta gli Esempi per visualizzare 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, la UI di Apigee applica ulteriori
limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.
(Facoltativo) Utilizza l'elemento |
N/D | Obbligatorio |
| continueOnError |
Imposta questo valore su false per restituire un errore quando un criterio non viene rispettato. Questo è il comportamento
previsto per la maggior parte delle norme.
Imposta su |
falso | Facoltativo |
| abilitato |
Imposta true per applicare la policy.
Imposta |
true | Facoltativo |
| asinc | Questo attributo è stato ritirato. | falso | Ritirato |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Utilizza questo attributo in aggiunta 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 delle rivendicazioni aggiuntive nell'intestazione del JWS.
| Predefinito | N/D |
| Presenza | Facoltativo |
| Valori validi | Qualsiasi valore che vuoi utilizzare per un'ulteriore rivendicazione. Puoi specificare l'attestazione in modo esplicito come stringa, numero, valore booleano, mappa o array. |
L'elemento <Claim> prevede i seguenti attributi:
- name: (obbligatorio) il nome dell'attributo, noto anche come parametro.
- ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come rivendicazione. Se vengono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è quello predefinito e viene utilizzato se la variabile di flusso a cui viene fatto riferimento non viene risolta.
- type (facoltativo): uno dei seguenti valori: stringa (impostazione predefinita), 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 intestazioni 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 questo aspetto:
{
"typ": "...",
"alg" : "...",
"hyb" : "some-value-here",
"crit" : [ "hyb" ],
}Questa intestazione JWS afferma che il parametro di intestazione hyb è di importanza critica e qualsiasi destinatario della JWS deve comprendere il significato e il valore di questo parametro.
In base al documento IETF RFC 7515, il destinatario di una JWS deve rifiutarla in quanto
non valida se non comprende uno o più dei parametri a cui viene fatto riferimento nel
parametro crit. In Apigee, il criterio VerifyJWS è conforme a questo comportamento.
Per ogni parametro elencato nel parametro crit, verifica che
anche l'elemento <KnownHeaders> del criterio VerifyJWS elenchi quel parametro.
Qualsiasi intestazione trovata dal criterio VerifyJWS in crit che non è elencata anche
in <KnownHeaders> fa sì che il criterio VerifyJWS rifiuti la JWS.
| Predefinito | N/D |
| Presenza | Facoltativo |
| Tipo | Array separato 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 la firma JWS con un payload separato, <DetachContent>true</DetachContent>,
o meno, <DetachContent>false</DetachContent>.
Se specifichi false, il valore predefinito, il JWS generato ha il seguente formato:
[header].[payload].[signature]
Se specifichi true per creare una JWS con un payload separato, la JWS generata omette il payload e ha il seguente formato:
[header]..[signature]
Con una JWS che utilizza un payload separato, spetta a te trasmettere il payload originale non codificato alla parte che esegue la verifica, insieme alla JWS serializzata.
| Predefinito | falso |
| Presenza | Facoltativo |
| Tipo | Booleano |
| Valori validi | vero o falso |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Imposta su false se vuoi che la policy generi un errore quando qualsiasi variabile a cui viene fatto riferimento specificata nella policy non è risolvibile. Imposta su true per considerare qualsiasi variabile non risolvibile come una stringa vuota (null).
| Predefinito | falso |
| Presenza | Facoltativo |
| Tipo | Booleano |
| Valori validi | vero o falso |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
Specifica il nome della variabile di contesto che la policy imposterà con il JWS generato.
Per impostazione predefinita, il criterio inserisce la firma 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 non elaborato. 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. |
Elemento <PrivateKey>
Questo campo è facoltativo e deve essere utilizzato solo quando <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>
| Predefinito: | N/D |
| 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/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 variabile di flusso o una stringa |
<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 dei criteri in cui la password è specificata in testo normale. 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/D |
| Presenza | Obbligatorio quando utilizzi il criterio per generare una firma 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 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 segreta da utilizzare durante la generazione di una firma JWS che utilizza un algoritmo simmetrico (HS*), ovvero HS256, HS384 o HS512.
Questo elemento è facoltativo. Tuttavia, devi includere esattamente uno degli elementi
<PrivateKey> o <SecretKey>.
Utilizza l'elemento <PrivateKey> quando generi una firma JWS con
un algoritmo asimmetrico (uno tra RS*, PS* o ES*)
e l'elemento <SecretKey> quando generi una firma JWS con un
algoritmo simmetrico (algoritmo come HS*).
Figli di <SecretKey>
La tabella seguente fornisce una descrizione degli elementi secondari e degli attributi di
<SecretKey>:
| Figlio | Presenza | Descrizione |
|---|---|---|
| codifica (attributo) | Facoltativo | Specifica come viene codificata la chiave nella variabile a cui viene fatto riferimento. Per impostazione predefinita, quando non è presente l'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 una 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> Le norme includeranno questo identificatore di chiave come rivendicazione |
| 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 una solidità 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 con una potenza inferiore causa un errore di runtime. |
<Type>
<Type>type-string-here</Type>
Elemento facoltativo il cui unico valore consentito è Signed, che specifica che la policy
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 il 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 alle dimensioni minime 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. |
|
|
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>