Criterio GenerateJWS

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Genera un JWS firmato, con un insieme configurabile di rivendicazioni. Il JWS può quindi essere restituito ai client, trasmesso alle destinazioni 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.

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 allegato firmato con l'algoritmo HS256
• Generare una firma JWS separata con l'algoritmo RS256

Genera un JWS allegato firmato con l'algoritmo HS256

Questa policy di esempio genera un JWS allegato 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 allegato contiene l'intestazione, il payload e la firma codificati:

header.payload.signature

Imposta <DetachContent> su true per generare contenuti separati. Per saperne di più sulla struttura e sul formato di una JWS, consulta la sezione Parti di una JWS/JWT.

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, Edge 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 una firma 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 una firma JWS separata con l'algoritmo RS256

Questa policy di esempio genera una firma JWS separata e la 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 disaccoppiato omette il payload dal JWS:

header..signature

Utilizza l'elemento <Payload> per specificare il payload JWS non codificato e non elaborato. Quando viene attivata questa policy, Edge codifica l'intestazione e il payload JWS e li utilizza per generare la firma codificata. Tuttavia, il JWS generato omette il payload. Spetta a te passare il payload al criterio VerifyJWS utilizzando 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="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-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:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

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

Riferimento elemento per Genera JWS

Il riferimento al criterio descrive gli elementi e gli attributi del criterio 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 delle policy.

<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 gestione con un nome diverso in linguaggio naturale.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Specifica l'algoritmo di crittografia per firmare il token.

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

L'elemento <Claim> prevede i seguenti attributi:

• name: (obbligatorio) il nome dell'attestazione.
• 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:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

In fase di runtime, il criterio VerifyJWS esamina l'intestazione crit. Per ogni intestazione elencata nell'intestazione crit, verifica che anche l'elemento <KnownHeaders> del criterio VerifyJWS elenchi l'intestazione. Qualsiasi intestazione trovata dal criterio VerifyJWS in crit che non è elencata anche in <KnownHeaders> causa l'errore del criterio VerifyJWS.

<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 un payload separato, il JWS generato omette il payload e ha il seguente formato:

header..signature

Con un payload separato, spetta a te passare il payload originale non codificato al criterio VerifyJWS utilizzando l'elemento <DetachedContent> del criterio VerifyJWS.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Specifica dove inserire il JWS generato da questa policy. Per impostazione predefinita, viene inserito nella variabile di flusso jws.POLICYNAME.generated_jws.

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

<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. Utilizza solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<PrivateKey/Password>

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

Se necessario, specifica la password che le norme devono utilizzare per decriptare la chiave privata. Utilizza l'attributo ref per passare la chiave in una variabile di flusso. Utilizza solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<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. Utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<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. Utilizzare solo quando l'algoritmo è HS256/HS384/HS512.

<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. Utilizzare solo quando l'algoritmo è HS256/HS384/HS512. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

Edge impone una lunghezza 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.

Variabili di flusso

Il criterio Genera JWS non imposta le variabili di flusso.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

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.

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>