Genera GenerateJWT

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Qué

Genera un JWT firmado o un JWT encriptado, con un conjunto configurable de reclamaciones. El JWS se puede mostrar a los clientes, transmitido a los objetivos de backend o usarse de otras formas. Consulta la descripción general de las políticas de JWS y JWT para obtener una introducción detallada.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Cómo

La política que genera un JWT firmado o encriptado depende del elemento que usas para especificar el algoritmo que genera el JWT:

• Si usas el elemento <Algorithm>, la política genera un JWT firmado.
• Si usas el elemento <Algorithms>, la política genera un JWT encriptado.

Video

Nota: En el siguiente video, se muestra el Editor de proxies clásico en la IU de Apigee. Apigee presenta una versión nueva del Editor de proxies, que tiene un diseño diferente al de la versión clásica que se muestra en el video.

Mira un video breve para aprender a generar un JWT firmado.

Genera un JWT firmado

En esta sección, se explica cómo generar un JWT firmado. Para un JWT firmado, usa el elemento <Algorithm> a fin de especificar el algoritmo para firmar la clave.

Muestras de un JWT firmado

En los siguientes ejemplos, se ilustra cómo generar un JWT firmado.

Algoritmo HS256

Esta política de ejemplo genera un JWT nuevo y lo firma con el algoritmo HS256. HS256 se basa en un secreto compartido para firmar y verificar la firma.

Cuando se activa esta acción de política, Apigee codifica el encabezado JWT y la carga útil y, luego, firma el JWT de forma digital. Mira el video anterior para ver un ejemplo completo, que incluye cómo realizar una solicitud a la política.

Aquí, la configuración de política creará un JWT con un conjunto de reclamaciones estándar según lo definido por la especificación JWT, que incluye un vencimiento de 1 hora y un reclamo adicional. Puedes incluir tantos reclamos adicionales como desees. Consulta la referencia del elemento para obtener detalles sobre los requisitos y las opciones de cada elemento en esta política de muestra.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Type>Signed</Type>
    <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-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>

El JWT resultante tendrá este encabezado …

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

…y tendrá una carga útil con contenido similar al siguiente:

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

Los valores de las reclamaciones iat, exp y jti variarán.

Algoritmo RS256

Nota: Usa este mismo ejemplo a fin de verificar un JWT para el algoritmo PS256 o ES256. Cambia el valor de <Algorithm>RS256</Algorithm> a PS256 o ES256. Para ES256 también debes especificar una clave compatible con el algoritmo. Para obtener más información sobre los requisitos de las claves, consulta Información sobre los algoritmos de encriptación de firmas.

Esta política de ejemplo generará un JWT nuevo y lo firmará con el algoritmo RS256. La generación de una firma RS256 se basa en una clave privada RSA, que se debe proporcionar en formato de codificación PEM y que puede encriptarse con contraseña. Mira el video anterior para ver un ejemplo completo, que incluye cómo realizar una solicitud a la política.

Cuando se activa esta acción de la política, Apigee codifica y firma digitalmente el JWT, incluidas las reclamaciones. Para obtener información sobre las partes de un JWT y cómo se encriptan y firman, consulta RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <Type>Signed</Type>
    <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-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>

En los ejemplos anteriores, se usa el elemento <Algorithm>, por lo que generan un JWT firmado. El elemento <PrivateKey> especifica la clave criptográfica usada para firmar el JWT. También hay otros elementos clave. El que uses depende del algoritmo que especifica el valor de <Algorithm>, como se describe en la sección siguiente.

Configura los elementos clave para un JWT firmado

Usa exactamente uno de los siguientes elementos para especificar la clave que se usa para generar un JWT firmado:

• <SecretKey>
• <PrivateKey>

El elemento que uses depende del algoritmo elegido, como se muestra en la siguiente tabla:

Nota: Los algoritmos RS*, PS* y ES* usan los mismos elementos para especificar la clave, pero los datos de la clave ES* son diferentes de los que usan algoritmos RS* y PS*.

Algoritmo	Elementos clave
HS{256/384/512}^*	<SecretKey> <Value ref="private.secretkey"/> <Id ref="secretkey-id">key-1918290</Id> </SecretKey>
RS/PS/ES{256/384/512}^*	<PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="privatekey-id">key-1918290</Id> </PrivateKey>

En los ejemplos anteriores, los elementos <Password> y <Id> son opcionales.

Para obtener más información sobre los requisitos de las claves, consulta Información sobre los algoritmos de encriptación de firmas.

Genera un JWT encriptado

En esta sección, se explica cómo generar un JWT encriptado. En el caso de un JWT encriptado, usa el elemento <Algorithms> para especificar los algoritmos de firma de clave y contenido.

Muestra de un JWT encriptado

En el siguiente ejemplo, se muestra cómo generar un JWT encriptado. En la muestra, se usa el elemento <Algorithms>, por lo que se genera un JWT encriptado.

RSA-OAEP-256

En el ejemplo que se muestra a continuación, se ilustra lo siguiente:

• La clave se encripta con el algoritmo RSA-OAEP-256.
• El contenido se encripta con el algoritmo A128GCM.

El elemento <PublicKey> especifica la clave usada para la encriptación de claves.

<GenerateJWT name="gjwt-1">
  <Type>Encrypted</Type>
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <PublicKey>
    <Value ref="rsa_publickey"/>
  </PublicKey>
  <Subject>[e-mail]</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

A128KW

En el ejemplo que se muestra a continuación, se ilustra lo siguiente:

• La clave se encripta con el algoritmo A128KW.
• El contenido se encripta con el algoritmo A128GCM.

El elemento <SecretKey> especifica la clave usada para la encriptación de claves.

<GenerateJWT name='gjwt-2'>
  <Algorithms>
    <Key>A128KW</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey>
    <Value ref='private.secretkey'/>
  </SecretKey>
  <Subject>[e-mail]</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

Configura los elementos clave para un JWT encriptado

Usa exactamente uno de los siguientes elementos para especificar la clave de encriptación de GenerateJWT cuando desees generar un JWT encriptado:

• <PublicKey>
• <SecretKey>
• <PasswordKey>
• <DirectKey>

El elemento que uses depende del algoritmo de encriptación de clave elegido, como se muestra en la siguiente tabla:

Algoritmo de encriptación de claves	Elementos clave
RSA-OAEP-256	<PublicKey> <Value ref="rsa_publickey"/> </PublicKey> Nota: La clave se debe resolver como una clave pública de RSA.
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> <Value ref="ec_publickey"/> </PublicKey> Nota: La clave debe resolverse en una clave pública de curva elíptica.
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey> <Id>optional key identifier here</Id> <Value ref="private.secretkey"/> </SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey> <Id>optional key identifier here</Id> <Value ref="private.passwordkey"/> <SaltLength> <PBKDF2Iterations> </PasswordKey>
dir	<DirectKey> <Id>optional key identifier here</Id> <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/> </DirectKey>

Para obtener más información sobre los requisitos de las claves, consulta Información sobre los algoritmos de encriptación de firmas.

Referencia del elemento para Generar JWT

La referencia de política describe los elementos y atributos de la política de decodificación de JWS.

Nota: La configuración variará en función del algoritmo de encriptación que uses. Consulta Muestras para un JWT firmado o Muestra para un JWT encriptado a fin de ver ejemplos que muestran configuraciones para casos de uso específicos.

Atributos que se aplican al elemento de nivel superior

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

Los siguientes atributos son comunes a todos los elementos superiores de la política.

Atributo	Descripción	Valor predeterminado	Presence
name	El nombre interno de la política. Los caracteres que puede usar en el nombre están restringidos a: A-Z0-9._\-$ %. Sin embargo, la IU de Apigee aplica restricciones adicionales, como quitar automáticamente los caracteres que no son alfanuméricos. De forma opcional, usa el elemento <displayname></displayname> para etiquetar la política en el editor de proxy de IU de Apigee con un nombre de lenguaje natural diferente.	N/A	Obligatorio
continueOnError	Configúralo como false para devolver un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle.	false	Opcional
habilitado	Configúralo como true para aplicar la política. Configúralo como false para “desactivar” la política. La política no se aplicará, incluso si permanece conectada a un flujo.	true	Opcional
async	Este atributo dejó de estar disponible.	false	Obsoleto

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Además de usar el atributo de nombre para etiquetar la política en el editor de proxy de IU de Apigee con un nombre diferente y con lenguaje natural.

Valor predeterminado	Si omites este elemento, se usa el valor del atributo de nombre de la política.
Presence	Opcional
Tipo	String

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica el algoritmo criptográfico que se usa para firmar el token. Usa el elemento <Algorithm> para generar un JWT firmado.

Nota: Usa exactamente uno de los elementos <Algorithm> y <Algorithms>.

Valor predeterminado	N/A
Presence	Opcional. Se requiere <Algorithm> o <Algorithms>.
Tipo	String
Valores válidos	HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Especifica los algoritmos criptográficos para la clave y la encriptación de contenido. Usa el elemento <Algorithms> para generar un JWT encriptado.

Nota: Usa exactamente uno de los elementos <Algorithm> y <Algorithms>.

Valor predeterminado	N/A
Opcional. Se requiere <Algorithm> o <Algorithms>.	Obligatorio
Tipo	String

Elementos secundarios de <Algorithms>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <Algorithms>:

Elemento secundario	¿Es obligatorio?	Descripción
<Key>	Obligatorio	Especifica el algoritmo de encriptación de la clave.
<Content>	Obligatorio	Especifica el algoritmo de encriptación para el contenido.

Algoritmos de encriptación de claves

En la siguiente tabla, se enumeran los algoritmos disponibles para la encriptación de claves.

Valor de <Key> (algoritmo de encriptación de claves)	Elemento de clave obligatorio
dir	<DirectKey>
RSA-OAEP-256	<PublicKey> (que se debe resolver en una clave pública de RSA)
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey>
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> (que se debe resolver en una clave pública de curva elíptica)

Consulta Genera un JWT encriptado para ver un ejemplo en el que el algoritmo de encriptación de claves es RSA-OAEP-256, por lo que debes usar el elemento <PublicKey> con lo siguiente valor que se resuelve en una clave pública de RSA.

Algoritmos de encriptación de contenido

Los siguientes algoritmos (simétricos, basados en AES) están disponibles para la encriptación de contenido:

• A128CBC-HS256
• A192CBC-HS384
• A256CBC-HS512
• A128GCM
• A192GCM
• A256GCM

Para obtener más información sobre todos estos algoritmos, consulta RFC7518.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

La política genera un JWT que contiene una reclamación aud configurada en el valor especificado. Esta reclamación identifica a los destinatarios para los que está destinado el JWT. Esta es una de las reclamaciones registradas que se mencionan en RFC7519.

Valor predeterminado	N/A
Presence	Opcional
Tipo	Arreglo (una lista de valores separados por comas)
Valores válidos	Todo lo que identifique al público.

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

Te permite especificar pares de nombre/valor de reclamo adicional en la carga útil del JWT. Puedes especificar las reclamaciones de forma explícita como una string, un número, un valor booleano, un mapa o un arreglo. Un mapa es simplemente un conjunto de pares nombre-valor.

El elemento <Claim> admite la función de sustitución de strings dinámicas llamada plantillas de mensajes cuando type=map.

Valor predeterminado	N/A
Presence	Opcional
Valores válidos	Cualquier valor que desees usar para una reclamación adicional. Puedes especificar las reclamaciones de forma explícita como una string, un número, un valor booleano, un mapa o un arreglo.

El elemento <Claim> incluye los siguientes atributos:

• name: El nombre del reclamo (obligatorio).
  Nota: No uses ninguno de los nombres de las reclamaciones registradas en este elemento. Las reclamaciones registradas se especifican en RFC7519. Estas incluyen: “iss”, “sub”, “aud”, “iat”, “exp”, “nbf” y “jti”.
• ref: El nombre de una variable de flujo (opcional). Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican un atributo ref y un valor de reclamación explícito, el valor explícito es el predeterminado y se usa si la variable de flujo a la que se hace referencia no se resuelve.
• type: (Opcional) uno de los siguientes: string, (predeterminado), número, booleano o mapa.
• arreglo: (Opcional) Establece en true para indicar si el valor es un arreglo de tipos. Valor predeterminado: false

Cuando incluyes el elemento <Claim>, los nombres de la reclamación se configuran de forma estática cuando configuras la política. Como alternativa, puedes pasar un objeto JSON para especificar los nombres de la reclamación. Debido a que el objeto JSON se pasa como una variable, los nombres de reclamación en el JWT generado se determinan durante el entorno de ejecución.

Por ejemplo:

<AdditionalClaims ref='json_claims'/>

En el que la variable json_claims contiene un objeto JSON en el siguiente formato:

{
  "sub" : "[e-mail]",
  "iss" : "urn://[e-mail]",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

El JWT generado incluye todas las reclamaciones en el objeto JSON.

Es importante tener en cuenta el siguiente comportamiento con respecto al uso de una referencia de variable y de valor explícito del reclamo en el elemento Claim:

Apigee no generará un reclamo en las siguientes condiciones:

• si hay una referencia de variable presente, pero no se resuelve, y
• si no especificas un valor explícito (un valor predeterminado)
• si el atributo IgnoreUnresolvedVariables de la política es true.

Si IgnoreUnresolvedVariables es false, Apigee genera un error en las condiciones anteriores.

Apigee generará una reclamación en las siguientes condiciones:

• si hay una referencia de variable presente, pero no se resuelve, y
• si especifica un valor explícito (un valor predeterminado) y
• si IgnoreUnresolvedVariables es true o false

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

Coloca los pares nombre-valor de reclamo adicionales en el encabezado de la JWS.

El elemento <Claim> admite la función de sustitución de strings dinámicas llamada plantillas de mensajes cuando type=map.

Valor predeterminado	N/A
Presence	Opcional
Valores válidos	Cualquier valor que desees usar para una reclamación adicional. Puedes especificar las reclamaciones de forma explícita como una string, un número, un valor booleano, un mapa o un arreglo.

El elemento <Claim> incluye los siguientes atributos:

• name: El nombre del reclamo (obligatorio).
  Nota: No uses ninguno de los nombres de las reclamaciones registradas en este elemento. Las reclamaciones registradas se especifican en RFC7519. Estas incluyen: “iss”, “sub”, “aud”, “iat”, “exp”, “nbf” y “jti”.
• ref: El nombre de una variable de flujo (opcional). Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican un atributo ref y un valor de reclamación explícito, el valor explícito es el predeterminado y se usa si la variable de flujo a la que se hace referencia no se resuelve.
• type: (Opcional) uno de los siguientes: string, (predeterminado), número, booleano o mapa.
• arreglo: (Opcional) Establece en true para indicar si el valor es un arreglo de tipos. Valor predeterminado: false

<Compress>

<Compress>true</Compress>

Especifica si el texto está comprimido antes de la encriptación. Este elemento solo es válido cuando se genera un JWT encriptado.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Agrega el encabezado crítico, crit, al encabezado JWT. El encabezado crit es un arreglo de nombres de encabezados que el receptor JWT debe conocer y reconocer. Por ejemplo:

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

Según la especificación, las partes que verifican deben examinar el encabezado crit y verificar que se comprenda cada uno de esos encabezados. Por ejemplo, la política VerifyJWT examina el encabezado crit. Para cada encabezado enumerado en el encabezado crit, verifica que el elemento <KnownHeaders> de la política VerifyJWS también enumere ese encabezado. Cualquier encabezado que la política encuentre en crit que no esté incluido en <KnownHeaders> genera que la política VerifyJWT falle.

Nota: El <CriticalHeaders> no agrega los encabezados al JWT. Solo define el contenido del encabezado crit. Puedes usar el <AdditionalHeader/Claims> para agregar los encabezados.

Valor predeterminado	N/A
Presence	Opcional
Tipo	Arreglo de strings separadas por comas
Valores válidos	Un arreglo o el nombre de una variable que contiene el arreglo.

<CustomClaims>

Nota: Por el momento, se inserta un elemento CustomClaims cuando agregas una política GenerateJWT nueva a través de la IU. Este elemento no es funcional y se ignora. El elemento correcto que debe usarse es <AdditionalClaims>. La IU se actualizará para insertar los elementos correctos más adelante.

<DirectKey>

<DirectKey>
  <Id>A12345</Id>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

Especifica una clave directa para encriptar un JWT cuando el algoritmo de encriptación es dir ("encriptación directa").

Elementos secundarios de <DirectKey>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <DirectKey>:

Elemento secundario	¿Es obligatorio?	Descripción
ID	Opcional	Identificador de clave
Valor	Obligatorio	Especifica una referencia a una variable con el atributo ref. El contenido de la variable a la que se hace referencia debe ser una codificación de cadena de un array de bytes, codificada a través de uno de los formatos hexadecimales (base16), base64 o base64url.

Con la encriptación de claves directas, puedes proporcionar directamente una serie de bytes que actuarán como la clave de encriptación de contenido (CEK). Debes especificar el array de bytes como una cadena codificada. La longitud requerida del array de bytes depende de la intensidad del algoritmo de encriptación de contenido seleccionado. Por ejemplo, para A256CBC-HS512, debes proporcionar una clave de 512 bits o 64 bytes.

El contenido de la variable private.directkey debe ser una cadena codificada en formato hexadecimal (base16), base64 o base64url. Por ejemplo, esta es una clave de 32 bytes codificada en hexadecimal:

96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11

Para la codificación hexadecimal, se acepta el espacio en blanco, pero no es obligatorio, y se aceptan mayúsculas o minúsculas (B7 es lo mismo que b7).

El equivalente codificado en base64url del ejemplo anterior es el siguiente:

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

Para las variantes en base64*, no se aceptan espacios en blanco, y las mayúsculas y minúsculas importan. Si no especificas una codificación, la política supone que la codificación es base64.

A continuación, se describe la longitud requerida de las claves:

Algoritmo de encriptación de contenido	Requisito de longitud de la clave
A128CBC-HS256	256 bits (32 bytes)
A192CBC-HS384	384 (48)
A256CBC-HS512	512 (64)
A128GCM	128 (16)
A192GCM	192 (24)
A256GCM	256 (32)

Nota: La clave de encriptación de contenido que se proporciona a través del elemento <DirectKey> debe tener la longitud correcta para el algoritmo de encriptación de contenido especificado. Para cualquier algoritmo de encriptación de claves que no sea dir, la política genera un CEK aleatorio que tiene la longitud correcta, pero para dir, la configuración debe proporcionar una clave con el tamaño correcto.

<ExpiresIn>

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

or:

<ExpiresIn ref='time-value-here'/>

Especifica la duración del JWT en milisegundos, segundos, minutos, horas o días. Especifica el vencimiento con el elemento XML o el atributo ref, pero no ambos.

Nota: Se trata de un período, no un valor de tiempo absoluto. La cantidad puede ser un valor numérico simple, en cuyo caso se interpreta como milisegundos.

Valor predeterminado	N/A
Presence	Opcional
Tipo	Entero
Valores válidos	Un valor o una referencia a una variable de flujo que contiene el valor. Las unidades de tiempo se pueden especificar de la siguiente manera: ms = milisegundos (predeterminado) s = segundos m = minutos h = horas d = días Por ejemplo, un ExpiresIn=10d es equivalente a un ExpiresIn de 864000s.

<Id>

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

Genera un JWT con la reclamación jti específica. Cuando el valor de texto y el atributo ref están vacíos, la política generará un jti que contiene un UUID aleatorio. La reclamación de ID de JWT (jti) es un identificador único para el JWT. Para obtener más información sobre jti, consulta RFC7519.

Valor predeterminado	N/A
Presence	Opcional
Tipo	String o referencia.
Valores válidos	Una string o el nombre de una variable de flujo que contiene el ID.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Configúralo como false si deseas que la política muestre un error cuando no se pueda resolver cualquier variable a la que se especifica en la política. Se establece como true para tratar cualquier variable no recuperable como una string vacía (null).

Valor predeterminado	Falso
Presence	Opcional
Tipo	Booleano
Valores válidos	True o False

<Issuer>

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

La política genera un JWT que contiene una reclamación con el nombre iss, con un valor establecido en el valor especificado. Un reclamo que identifica a la entidad emisora del JWT. Este es uno de los conjuntos de reclamaciones registradas que se mencionan en RFC7519.

Valor predeterminado	N/A
Presence	Opcional
Tipo	String o referencia
Valores válidos	Cualquiera

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

Especifica el momento en que el token pasa a ser válido. El token no es válido hasta el momento especificado. Puedes especificar un valor de tiempo absoluto o una hora relativa al momento en que se genera el token.

Valor predeterminado	N/A
Presence	Opcional
Tipo	String
Valores válidos	Consulta a continuación.

Valores de tiempo válidos para el elemento NotBefore con valores de tiempo absolutos

Nombre	Formato	Ejemplo
sortable	yyyy-MM-dd'T'HH:mm:ss.SSSZ	2017-08-14T11:00:21.269-0700
RFC 1123	EEE, dd MMM yyyy HH:mm:ss zzz	Lunes 14 de agosto de 2017 a las 11:00:21 PDT
RFC 850	EEEE, dd-MMM-yy HH:mm:ss zzz	Lunes, 14 de agosto a las 17 11:00:21 PDT
ANCI-C	EEE MMM d HH:mm:ss yyyy	Lun 14 de agosto de 2017 a las 11:00:21

Para valores de tiempo relativos, especifica un número entero y un período, por ejemplo:

• 10 s
• 60 min
• 12 h

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Especifica dónde se debe colocar el JWS que genera esta política. De forma predeterminada, se ubica en la variable de flujo jwt.POLICYNAME.generated_jwt.

Valor predeterminado	jwt.POLICYNAME.generated_jwt
Presence	Opcional
Tipo	String (un nombre de variable de flujo)

<PasswordKey>

<PasswordKey>
  <Id>abcdefg</Id>
  <Value ref="private.password"/>
  <SaltLength>8</SaltLength>
  <PBKDF2Iterations>10000</PBKDF2>
</PasswordKey>

Especifica una clave para encriptar un JWT cuando el algoritmo de encriptación es uno de los siguientes:

• PBES2-HS256+A128KW
• PBES2-HS384+A192KW
• PBES2-HS512+A256KW

Para cada uno de estos algoritmos de clave, debes proporcionar una contraseña a partir de la cual se deriva la clave de encriptación de claves, a través de la variable private.password en el elemento <Value ref="private.password"/>.

Elementos secundarios de <PasswordKey>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <PasswordKey>:

Elemento secundario	Presence	Descripción
ID	Opcional	Identificador de clave
Valor	Obligatorio	Especifica la contraseña usada para generar la clave de encriptación de claves. Usa un atributo ref y especifica una variable, como private.password.
SaltLength	Opcional	Longitud de Salt. Configuración predeterminado: 8 bytes.
PBKDF2Iterations	Opcional	Recuento de iteraciones de PBKDF2: Configuración predeterminada: 10,000.

<PrivateKey>

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

Especifica la clave privada que se usará cuando se genera un JWT firmado, y Algorithm es una variante de RSA o curva elíptica (EC): una de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Elementos secundarios de <PrivateKey>

En la siguiente tabla, se proporciona una descripción de los elementos secundarios de <PrivateKey>:

Elemento secundario	Presence	Descripción
ID	Opcional	El identificador de clave. El valor puede ser cualquier cadena. Puedes especificar el valor como un valor de texto literal o de forma indirecta a través de una referencia de variable con el atributo ref. La política incluirá este identificador de clave como la reclamación kid en el encabezado del JWT generado.
Valor	Obligatorio	Una clave privada con codificación PEM. Especifica la clave privada usada para firmar la carga útil. Usa un atributo ref y especifica una variable, como private.private-key. Si el elemento <Algorithm> contiene una variante de RSA, una de RS256/RS384/RS512 o PS256/PS384/PS512, debes proporcionar una clave privada RSA codificada. Si el elemento <Algorithm> contiene una variante de EC, una de ES256/ES384/ES512, debes proporcionar una clave privada de curva elíptica para la curva adecuada.
Contraseña	Opcional	La contraseña que debe usar la política para desencriptar la clave privada, si es necesario. Usa el atributo ref para pasar la contraseña a través en una variable de flujo. Nota: Debes especificar una variable de flujo. Apigee rechazará la configuración de la política como no válida en la que la contraseña se especifica en texto simple. La variable de flujo debe tener el prefijo “privado”. Por ejemplo, private.mypassword

<PublicKey>

<PublicKey>
  <!-- specify exactly one of the following -->
  <Value ref="variable-containing-encoded-publickey"/>
  <Value>PEM encoded public key</Value>
  <Certificate ref="variable-containing-encoded-x509-certificate"/>
  <Certificate>PEM encoded X509 certificate</Certificate>
  <JWKS>jwks-content</JWKS>
  <JWKS ref="variable-containing-jwks-content"/>
  <JWKS uri="variable-containing-jwks-content"/>
  <JWKS uriRef="variable-containing-uri"/>
</PublicKey>

Especifica la clave pública que se usará cuando se genera un JWT encriptado, y el algoritmo Key es una variante de RSA o curva elíptica (EC): RSA-OAEP-256, ECDH-ES, ECDH-ES+. A128KW, ECDH-ES+A192KW o ECDH-ES+A256KW.

Elementos secundarios de <PublicKey>

Proporciona exactamente uno de Value, Certificate o JWKS. Si especificas JWKS, también debes especificar Id. En la siguiente tabla, se proporciona una descripción de estos elementos secundarios de <PublicKey>:

Elemento secundario	Descripción
Valor	Una clave pública con codificación PEM. Especifica la clave pública que la política debe usar para encriptar la clave de encriptación de contenido. Puedes especificar la clave de forma literal o indirecta a través de una referencia de variable. <PublicKey> <Value ref="public.publickey"/> </PublicKey> o <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW 2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey> La clave pública codificada debe denotar una clave RSA si usas el algoritmo RSA-OAEP-256, o una clave de EC de la curva adecuada si usas un algoritmo de EC.
Certificado	Un certificado X.509 codificado con PEM que une una clave pública. Apigee extraerá la clave pública del certificado y, luego, la usará para encriptar la clave de encriptación de contenido. Puedes especificar el certificado de forma literal o indirecta a través de una referencia de variable. <PublicKey> <Certificate ref="public.pem-encoded-certificate"/> </PublicKey> o <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC 2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv ... YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8 rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw== -----END CERTIFICATE----- </Certificate> </PublicKey> La clave pública codificada debe denotar una clave RSA si usas el algoritmo RSA-OAEP-256, o una clave de EC de la curva adecuada si usas un algoritmo de EC. Nota: Apigee no valida las fechas de validez en el certificado que proporcionas ni valida la cadena de confianza en el certificado. Apigee trata todos los certificados que especificas con este elemento como válidos y de confianza.
JWKS	Una fuente JWKS de claves públicas. Esta será una lista de claves con el formato descrito en IETF RFC 7517 - JSON Web Key (JWK). Puedes especificar el JWKS de cuatro maneras: De forma literal, como un valor de texto: <PublicKey> <JWKS>jwks-content-here</JWKS> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> De forma indirecta, con el atributo ref, especifica una variable de flujo: <PublicKey> <JWKS ref="variable-containing-jwks-content"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> La variable a la que se hace referencia debe contener una cadena que represente un JWKS. De forma indirecta a través de un URI estático, con el atributo uri: <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> De forma indirecta a través de un URI determinado de forma dinámica, con el atributo uriRef: <PublicKey> <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> En todos los casos, cuando se especifica un elemento JWKS dentro de GenerateJWT para generar un JWT encriptado, también debes especificar el elemento PublicKey/Id. <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey>
ID	Una cadena que representa el identificador de clave. En el entorno de ejecución, Apigee recupera una clave de JWKS que tiene un campo kid que coincide con este valor. El elemento Id es obligatorio si usas el elemento JWKS dentro de GenerateJWT.

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.variable-here"/>
</SecretKey>

El elemento SecretKey es opcional. Especifica la clave secreta que se usará cuando se verifique un JWT firmado que usa un algoritmo simétrico (HS*) o cuando se genera un JWT encriptado que usa un algoritmo simétrico (AES) para la encriptación de claves.

Secundarios de <SecretKey>

En la siguiente tabla, se proporciona una descripción de los elementos secundarios y los atributos de <SecretKey>:

Hijo	Presence	Descripción
codificación (atributo)	Opcional	Especifica cómo se codifica la clave en la variable a la que se hace referencia. De forma predeterminada, cuando no hay un atributo encoding presente, la codificación de la clave se trata como UTF-8. Estos son los valores válidos para el atributo: hex, base16, base64 o base64url. Los valores de codificación hex y base16 son sinónimos. <SecretKey encoding="VALUE_HERE" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> En el ejemplo anterior, cuando el atributo de codificación es hex y el contenido de la variable private.secretkey es 494c6f766541504973, la clave se decodificará como un conjunto de 9 bytes, que en formato hexadecimal será 49 4c 6f 76 65 41 50 49 73. Por el contrario, cuando el atributo de codificación esbase64 y el contenido de la variable private.secretkey es VGhpcy1pcy1hLXNlY3JldA, la clave se decodificará como un conjunto de 16 bytes, en formato hexadecimal: 54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74. Nota: Apigee aplica una seguridad de clave mínima. Consulta la documentación del elemento Value para obtener más detalles.
ID (elemento)	Opcional	El identificador de clave. El valor puede ser cualquier cadena. Puedes especificar el valor como un valor de texto literal o, de forma indirecta, a través de una referencia de variable con el atributo ref. <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> La política incluirá este identificador de clave como la reclamación kid en el encabezado del JWT generado.
Valor (elemento)	Obligatorio	Una clave secreta codificada. Especifica la clave secreta usada para firmar la carga útil. Usa el atributo ref para proporcionar la clave de forma indirecta a través de una variable, como private.secret-key. <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Nota: El nombre de la variable debe incluir el prefijo private como se muestra en el ejemplo anterior. Apigee aplica una seguridad de clave mínima para los algoritmos HS256/HS384/HS512. La longitud mínima de la clave de HS256 es de 32 bytes, para HS384 es de 48 bytes, y para HS512 es de 64 bytes. El uso de una clave de baja intensidad provoca un error en el entorno de ejecución.

<Subject>

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

o

<Subject ref="flow_variable" />

Por ejemplo:

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

La política genera un JWT que contiene una reclamación sub, establecida en el valor especificado. Esta reclamación identifica o realiza una declaración sobre el tema del JWT. Este es uno de los conjuntos estándar de reclamaciones que se mencionan en IETF RFC 7519.

Valor predeterminado	N/A
Presence	Opcional
Tipo	String
Valores válidos	Cualquier valor que identifique de forma única un sujeto o una variable de flujo que haga referencia a un valor

<Type>

<Type>type-string-here</Type>

Describe si la política genera un JWT firmado o un JWT encriptado. El elemento <Type> es opcional. Puedes usarla para informar a los lectores sobre la configuración si la política genera un JWT firmado o encriptado.

• Si el elemento <Type> está presente:
  • Si el valor de <Type> es Signed, la política genera un JWT firmado y el elemento <Algorithm> debe estar presente.
  • Si el valor de <Type> es Encrypted, la política generará un JWT encriptado y el elemento <Algorithms> debe estar presente.
• Si el elemento <Type> está ausente:
  • Si el elemento <Algorithm> está presente, la política supone que <Type> es Signed.
  • Si el elemento <Algorithms> está presente, la política supone que <Type> es Encrypted.
• Si ni <Algorithm> ni <Algorithms> están presentes, la configuración no es válida.

Valor predeterminado	N/A
Presence	Opcional
Tipo	String
Valores válidos	Signed o Encrypted

Variables de flujo

La política Generar JWS no establece variables de flujo.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla	Estado de HTTP	Ocurre cuando
steps.jwt.AlgorithmInTokenNotPresentInConfiguration	401	Se produce cuando la política de verificación tiene varios algoritmos.
steps.jwt.AlgorithmMismatch	401	El algoritmo especificado en la política de generación no coincide con el esperado en la política de verificación. Los algoritmos especificados deben coincidir.
steps.jwt.EncryptionFailed	401	No se pudo crear un JWT encriptado por un motivo no específico
steps.jwt.FailedToDecode	401	La política no pudo decodificar el JWT. Es posible que el JWT esté dañado.
steps.jwt.GenerationFailed	401	La política no pudo generar el JWT.
steps.jwt.InsufficientKeyLength	401	En el caso de las claves inferiores a 32 bytes para el algoritmo HS256, menos de 48 bytes para el algoritmo HS386 y menos de 64 bytes para el algoritmo HS512.
steps.jwt.InvalidClaim	401	Para una reclamación faltante o una falta de coincidencia de una reclamación, o bien un encabezado faltante o una falta de coincidencia de un encabezado.
steps.jwt.InvalidConfiguration	401	Los elementos <Algorithm> y <Algorithms> están presentes.
steps.jwt.InvalidCurve	401	La curva especificada por la clave no es válida para el algoritmo de curva elíptica.
steps.jwt.InvalidJsonFormat	401	Se encontró un archivo JSON que no es válido en el encabezado o la carga útil.
steps.jwt.InvalidPasswordKey	401	La clave especificada no cumplió con los requisitos.
steps.jwt.InvalidPrivateKey	401	La clave especificada no cumplió con los requisitos.
steps.jwt.InvalidPublicKey	401	La clave especificada no cumplió con los requisitos.
steps.jwt.InvalidSecretKey	401	La clave especificada no cumplió con los requisitos.
steps.jwt.InvalidToken	401	Este error ocurre cuando falla la verificación de la firma del JWT.
steps.jwt.JwtAudienceMismatch	401	La reclamación del público falló en la verificación del token.
steps.jwt.JwtIssuerMismatch	401	La reclamación de la entidad emisora falló durante la verificación del token.
steps.jwt.JwtSubjectMismatch	401	La reclamación de la entidad falló durante la verificación del token.
steps.jwt.KeyIdMissing	401	La política de verificación usa un JWKS como fuente para las claves públicas, pero el JWT firmado no incluye una propiedad kid en el encabezado.
steps.jwt.KeyParsingFailed	401	No se pudo analizar la clave pública a partir de la información de claves determinada.
steps.jwt.NoAlgorithmFoundInHeader	401	Ocurre cuando el JWT no contiene un encabezado de algoritmo.
steps.jwt.NoMatchingPublicKey	401	La política de verificación usa un JWKS como fuente para claves públicas, pero la propiedad kid en el JWT firmado no aparece en el JWKS.
steps.jwt.SigningFailed	401	En GenerateJWT, ocurre en el caso de una clave que es menor que el tamaño mínimo para los algoritmos HS384 o HS512.
steps.jwt.TokenExpired	401	La política intenta verificar un token vencido.
steps.jwt.TokenNotYetValid	401	El token aún no es válido.
steps.jwt.UnhandledCriticalHeader	401	Un encabezado que encontró la política de verificación de JWT en el encabezado crit no aparece en KnownHeaders.
steps.jwt.UnknownException	401	Se produjo una excepción desconocida.
steps.jwt.WrongKeyType	401	El tipo de clave especificado es incorrecto. Por ejemplo, si especificas una clave RSA para un algoritmo de curva elíptica o una clave de curva para un algoritmo de RSA.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Nombre del error	Causa	Corregir
InvalidNameForAdditionalClaim	La implementación fallará si la reclamación que se usa en el elemento secundario <Claim> del elemento <AdditionalClaims> es uno de los siguientes nombres registrados: kid, iss, sub, aud, iat, exp, nbf o jti.
InvalidTypeForAdditionalClaim	Si la reclamación usada en el elemento secundario <Claim> del elemento <AdditionalClaims> no es del tipo string, number, boolean ni map, la implementación fallará.
MissingNameForAdditionalClaim	Si no se especifica el nombre de la reclamación en el elemento secundario <Claim> del elemento <AdditionalClaims>, fallará la implementación.
InvalidNameForAdditionalHeader	Este error ocurre cuando el nombre de la reclamación que se usó en el elemento secundario <Claim> del elemento <AdditionalClaims> es alg o typ.
InvalidTypeForAdditionalHeader	Si el tipo de reclamación usado en el elemento secundario <Claim> del elemento <AdditionalClaims> no es del tipo string, number, boolean ni map, la implementación fallará.
InvalidValueOfArrayAttribute	Este error ocurre cuando el valor del atributo de arreglo en el elemento secundario <Claim> del elemento <AdditionalClaims> no está configurado como true ni false.
InvalidConfigurationForActionAndAlgorithm	Si el elemento <PrivateKey> se usa con algoritmos de la familia HS o el elemento <SecretKey> se usa con algoritmos de la familia RSA, la implementación fallará.
InvalidValueForElement	Si el valor especificado en el elemento <Algorithm> no es un valor admitido, la implementación fallará.
MissingConfigurationElement	Este error se producirá si el elemento <PrivateKey> no se usa con algoritmos de la familia RSA o si el elemento <SecretKey> no se usa con algoritmos de la familia HS.
InvalidKeyConfiguration	Si el elemento secundario <Value> no está definido en los elementos <PrivateKey> ni <SecretKey>, la implementación fallará.
EmptyElementForKeyConfiguration	Si el atributo de referencia del elemento secundario <Value> de los elementos <PrivateKey> o <SecretKey> está vacío o no se especifica, la implementación fallará.
InvalidVariableNameForSecret	Este error se produce si el nombre de la variable del flujo especificado en el atributo de referencia del elemento secundario <Value> de los elementos <PrivateKey> o <SecretKey> no contiene el prefijo privado (private.).
InvalidSecretInConfig	Este error se produce si el elemento secundario <Value> de los elementos <PrivateKey> o <SecretKey> no contiene el prefijo privado (private.).
InvalidTimeFormat	Si el valor especificado en el elemento <NotBefore> no usa un formato admitido, la implementación fallará.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
fault.name="fault_name"	fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	fault.name Matches "InvalidToken"
JWT.failed	Todas las políticas de JWT establecen la misma variable en caso de falla.	JWT.failed = true

Ejemplo de respuesta de error

Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

Ejemplo de regla de falla

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