Criterio GenerateJWT

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

Cosa

Genera un JWT firmato, con un insieme configurabile di attestazioni. Il JWT 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.

Video

Guarda un breve video per scoprire come generare un JWT firmato.

Esempi

• Genera un JWT firmato con l'algoritmo HS256
• Genera un JWT firmato con l'algoritmo RS256

Genera un JWT firmato con l'algoritmo HS256

Questa norma di esempio genera un nuovo JWT e lo firma utilizzando l'algoritmo HS256. HS256 si basa su un secret condiviso sia per la firma che per la verifica della firma.

Quando viene attivata questa azione della policy, Edge codifica l'intestazione e il payload del JWT, quindi firma digitalmente il JWT. Guarda il video qui sopra per un esempio completo, incluso come effettuare una richiesta relativa alle norme.

La configurazione delle norme qui creerà un JWT con un insieme di attestazioni standard come definito dalle specifiche JWT, inclusa una scadenza di 1 ora, nonché un'attestazione aggiuntiva. Puoi includere tutte le rivendicazioni aggiuntive che vuoi. Per informazioni dettagliate sui requisiti e sulle opzioni per ogni elemento di queste norme di esempio, consulta la documentazione di riferimento sugli elementi.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Il JWT risultante avrà questa intestazione…

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

… e avrà un payload con contenuti simili a questi:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

I valori delle rivendicazioni iat, exp e jti varieranno.

Genera un JWT firmato con l'algoritmo RS256

Questa norma di esempio genera un nuovo JWT 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. Guarda il video qui sopra per un esempio completo, incluso come effettuare una richiesta relativa alle norme.

Quando viene attivata questa azione della policy, Edge codifica e firma digitalmente il JWT, incluse le rivendicazioni. Per informazioni sulle parti di un JWT e su come vengono criptate e firmate, consulta RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Impostazione degli elementi chiave

Gli elementi che utilizzi per specificare la chiave utilizzata per generare il JWT 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 all'elemento per Genera JWT

Il riferimento ai criteri descrive gli elementi e gli attributi dei criteri Genera JWT.

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

<GenerateJWT name="JWT" 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.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

La policy genera un JWT contenente un'attestazione aud impostata sul valore specificato. Questa rivendicazione identifica i destinatari a cui è destinato il JWT. Si tratta di una delle rivendicazioni registrate menzionate nella RFC7519.

<AdditionalClaims/Claim>

<AdditionalClaims>
    <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'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Consente di specificare una o più coppie nome/valore di rivendicazione aggiuntive nel payload del JWT. Puoi specificare l'attestazione in modo esplicito come stringa, numero, valore booleano, mappa o array. Una mappa è semplicemente un insieme di coppie nome/valore.

L'elemento <Claim> prevede i seguenti attributi:

• name: (obbligatorio) il nome della richiesta.
• 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) impostalo su true per indicare se il valore è un array di tipi. Valore predefinito: false.

Quando includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico quando configuri la policy. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle rivendicazioni. Poiché l'oggetto JSON viene passato come variabile, i nomi delle attestazioni nel JWT generato vengono determinati in fase di runtime.

Ad esempio:

<AdditionalClaims ref='json_claims'/>

Dove la variabile json_claims contiene un oggetto JSON nel formato:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

Il JWT generato include tutte le rivendicazioni nell'oggetto JSON.

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

L'elemento <Claim> prevede i seguenti attributi:

• name: (obbligatorio) il nome della richiesta.
• 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) impostalo 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 all'intestazione JWT. L'intestazione crit è un array di nomi di intestazioni che devono essere noti e riconosciuti dal destinatario del JWT. Ad esempio:

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

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

<CustomClaims>

Nota:al momento, viene inserito un elemento CustomClaims quando aggiungi un nuovo criterio GenerateJWT tramite la UI. Questo elemento non è funzionale e viene ignorato. L'elemento corretto da utilizzare è <AdditionalClaims>. L'interfaccia utente verrà aggiornata per inserire gli elementi corretti in un secondo momento.

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

Specifica la durata del JWT in millisecondi, secondi, minuti, ore o giorni.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Genera un JWT con l'attestazione jti specifica. Quando il valore di testo e l'attributo ref sono entrambi vuoti, il criterio genererà un jti contenente un UUID casuale. L'attestazione JWT ID (jti) è un identificatore univoco per il JWT. Per saperne di più su jti, consulta RFC7519.

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

La policy genera un JWT contenente un'attestazione con il nome iss,con un valore impostato sul valore specificato. Un'affermazione che identifica l'emittente del JWT. Si tratta di uno dei set di rivendicazioni registrate menzionate nella RFC7519.

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Specifica l'ora in cui il token diventa valido. Il token non è valido fino all'ora specificata. Puoi specificare un valore temporale assoluto o un orario relativo al momento della generazione del token.

Valori temporali validi per l'elemento NotBefore per i valori temporali assoluti

Per i valori di tempo relativi, specifica un numero intero e un periodo di tempo, ad esempio:

• 10 sec
• 60 min
• 12 ore

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Specifica dove inserire il JWT generato da questa policy. Per impostazione predefinita, viene inserito nella variabile di flusso jwt.POLICYNAME.generated_jwt.

<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 JWT. Utilizzare 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 il criterio deve utilizzare per decriptare la chiave privata. 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.

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Specifica una chiave privata codificata in formato PEM utilizzata per firmare il JWT. 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 JWT di un JWT 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 crittografia meno efficace causa un errore di runtime.

<Subject>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

Ad esempio:

<Subject ref="apigee.developer.email"/>

La policy genera un JWT contenente un'attestazione sub, impostata sul valore specificato.Questa attestazione identifica o fa un'affermazione sul soggetto del JWT. Si tratta di uno dei set di standard di attestazioni menzionati nella RFC7519.

Variabili di flusso

La policy Genera JWT 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 gestire gli 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.

Errori di deployment

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

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Esempio di risposta di errore

Per la gestione degli errori, la best practice è il trap della parte errorcode dell'errore la risposta corretta. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

Esempio di regola di errore

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>