Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
Genera un JWS firmato, con un insieme configurabile di rivendicazioni. Il JWS può quindi essere restituito ai client, trasmesso a destinazioni di backend o utilizzato in altri modi. Per un'introduzione dettagliata, consulta la panoramica dei criteri JWS e JWT.
Per saperne di più sulle parti di un JWS e su come vengono criptate e firmate, fai riferimento a RFC7515.
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.
Samples
- Genera un JWS collegato firmato con l'algoritmo HS256
- Genera un JWS scollegato firmato con l'algoritmo RS256
Genera un JWS collegato firmato con l'algoritmo HS256
Questo criterio di esempio genera un JWS collegato e lo firma utilizzando l'algoritmo HS256. HS256 si basa su un secret condiviso sia per la firma che per la verifica della firma.
Un JWS collegato contiene l'intestazione codificata, il payload e la firma:
header.payload.signature
Imposta <DetachContent>
su true per generare contenuti scollegati.
Per saperne di più sulla struttura e sul formato di un JWS, consulta Parti di un JWS/JWT.
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 riportata di seguito 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 l'algoritmo RS256
Questo criterio di esempio genera un JWS scollegato e lo firma 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 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,
quindi li utilizza per generare la firma codificata. Tuttavia, il JWS generato omette il payload.
Spetta a te passare il payload al criterio VerificationJWS utilizzando l'elemento <DetachedContent>
del criterio VerificationJWS.
<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>
Definire gli elementi chiave
Gli elementi utilizzati per specificare la chiave utilizzata per generare il JWS dipendono dall'algoritmo scelto, come mostrato nella seguente tabella:
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 |
|
* 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 del criterio JWS per la generazione.
Nota: la configurazione varierà leggermente in base all'algoritmo di crittografia utilizzato. Consulta gli esempi per alcuni 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 | Predefinita | Presenza |
---|---|---|---|
nome |
Il nome interno della norma. I caratteri utilizzabili nel nome sono limitati a:
A-Z0-9._\-$ % . Tuttavia, l'interfaccia utente di gestione perimetrale applica limitazioni aggiuntive, come la rimozione automatica dei caratteri non alfanumerici.
Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.
Imposta su |
false | Facoltativo |
abilitata |
Imposta il criterio su true per applicare il criterio.
Impostalo su |
true | Facoltativo |
async | Questo attributo è obsoleto. | false | Deprecata |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Utilizzalo in aggiunta all'attributo del nome 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 name del criterio. |
Presenza | Facoltativo |
Digitare | Stringa |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
Specifica l'algoritmo di crittografia per firmare il token.
Predefinita | N/A |
Presenza | Obbligatorio |
Digitare | Stringa |
Valori validi | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Intestazioni aggiuntive/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>
Inserisci le coppie nome/valore aggiuntive nell'intestazione del JWS.
Predefinita | N/A |
Presenza | Facoltativo |
Valori validi | Qualsiasi valore che vuoi utilizzare per una rivendicazione aggiuntiva. Puoi specificare esplicitamente la dichiarazione come stringa, numero, booleano, mappa o array. |
L'elemento <Claim>
prevede i seguenti attributi:
- name: (obbligatorio) il nome del reclamo.
- ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, la norma utilizzerà il valore di questa variabile come attestazione. Se vengono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile di flusso a cui viene fatto riferimento non è risolta.
- type - (Facoltativo) Uno dei seguenti valori: stringa (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 intestazioni che devono essere noti e riconosciuti dal ricevitore JWS. Ad esempio:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
In fase di runtime, il criterio VerificationJWS esamina l'intestazione crit.
Per ogni intestazione elencata nell'intestazione crit, viene controllata che anche l'elemento <KnownHeaders>
del criterio VerificationJWS sia elencata in questa intestazione. Un'intestazione che il criterio VerificationJWS trova in crit e che non è elencata anche in <KnownHeaders>
determina la mancata riuscita del criterio VerificationJWS.
Predefinita | N/A |
Presenza | Facoltativo |
Digitare | Array di stringhe separate da virgole |
Valori validi | Un array o il nome di 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 del JWS generato sarà il seguente:
header.payload.signature
Se specifichi true per creare il payload scollegato, il JWS generato omette il payload ed è nel formato:
header..signature
Con un payload scollegato, spetta a te passare il payload originale non codificato al criterio VerificationJWS utilizzando l'elemento <DetachedContent>
del criterio VerificationJWS.
Predefinita | false |
Presenza | Facoltativo |
Digitare | Booleano |
Valori validi | true o false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Impostalo su false se vuoi che il criterio generi un errore quando una variabile di riferimento specificata nel criterio non è risolvibile. Imposta il valore su true per trattare qualsiasi variabile non risolvibile come stringa vuota (null).
Predefinita | false |
Presenza | Facoltativo |
Digitare | Booleano |
Valori validi | true o false |
<OutputVariable>
<OutputVariable>JWS-variable</OutputVariable>
Specifica dove posizionare il JWS generato da questo criterio. Per impostazione predefinita, viene inserita nella
variabile di flusso jws.POLICYNAME.generated_jws
.
Predefinita | jws.POLICYNAME.generated_jws |
Presenza | Facoltativo |
Digitare | Stringa (nome di 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.
Predefinita | N/A |
Presenza | Obbligatorio |
Digitare | Stringa, array di byte, flusso o qualsiasi altra rappresentazione del payload JWS non codificato. |
<PrivateKey/Id>
<PrivateKey> <Id ref="flow-variable-name-here"/> </PrivateKey> or <PrivateKey> <Id>your-id-value-here</Id> </PrivateKey>
Specifica l'ID chiave (bambino) da includere nell'intestazione JWS. Da utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.
Predefinita | N/A |
Presenza | Facoltativo |
Digitare | Stringa |
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. Da utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.
Predefinita | N/A |
Presenza | Facoltativo |
Digitare | Stringa |
Valori validi |
Un riferimento a una variabile di flusso.
Nota:devi specificare una variabile di flusso. Edge rifiuterà come non valida una configurazione dei 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. Da utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.
Predefinita | N/A |
Presenza | Necessario per generare un JWS utilizzando l'algoritmo RS256. |
Digitare | 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:
|
<SecretKey/Id>
<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 algoritmo HMAC. Da utilizzare solo quando l'algoritmo è HS256/HS384/HS512.
Predefinita | N/A |
Presenza | Facoltativo |
Digitare | Stringa |
Valori validi | Una stringa o una variabile di flusso |
<SecretKey/Value>
<SecretKey> <Value ref="private.your-variable-name"/> </SecretKey>
Fornisce la chiave segreta utilizzata per verificare o firmare i token con un algoritmo HMAC. Utilizzalo solo quando l'algoritmo è 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 con potenza inferiore causa un errore di runtime.
Predefinita | N/A |
Presenza | Obbligatorio per gli algoritmi HMAC. |
Digitare | Stringa |
Valori validi |
Una variabile di flusso che fa riferimento a una stringa
Nota:se si tratta di una variabile di flusso, deve avere il prefisso "private". Ad
esempio, |
Variabili di flusso
Il criterio Genera JWS non imposta le 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. |
|
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>