Política GenerateJWT

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

Consulta la documentación de Apigee Edge.

La política GenerateJWT genera un JWT firmado o un JWT cifrado con un conjunto configurable de reclamaciones. A continuación, el JWT se puede devolver a los clientes, transmitir a los destinos de backend o usar de otras formas. Consulta la información general sobre las políticas de JWS y JWT para obtener una introducción detallada.

Si la política genera un JWT firmado o cifrado, depende del elemento que uses 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 cifrado.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Generar un JWT firmado

En esta sección se explica cómo generar un JWT firmado. En el caso de los JWT firmados, usa el elemento <Algorithm> para especificar el algoritmo de firma de la clave.

Ejemplos de un JWT firmado

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

Algoritmo HS256

Esta política de ejemplo genera un nuevo JWT 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 y la carga útil del JWT y, a continuación, firma digitalmente el JWT. En el vídeo de arriba puedes ver un ejemplo completo, incluido cómo enviar una solicitud para aplicar la política.

La configuración de la política creará un JWT con un conjunto de reclamaciones estándar tal como se define en la especificación de JWT, incluida una caducidad de 1 hora, así como una reclamación adicional. Puedes incluir todas las reclamaciones adicionales que quieras. Consulta la referencia de elementos para obtener información sobre los requisitos y las opciones de cada elemento de esta política de ejemplo.

<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 un contenido similar a este:

{
  "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."
}

El valor de las reclamaciones iat, exp y jti variará.

Algoritmo RS256

Nota: Usa este mismo ejemplo para generar un JWT para el algoritmo PS256 o ES256. Solo tienes que cambiar el valor de <Algorithm>RS256</Algorithm> a PS256 o ES256. En el caso de ES256, también debes especificar una clave compatible con el algoritmo. Para obtener más información sobre los requisitos de las claves, consulta Acerca de los algoritmos de cifrado de firma.

Esta política de ejemplo genera un nuevo JWT y lo firma con el algoritmo RS256. Para generar una firma RS256, se necesita una clave privada RSA, que debe proporcionarse en formato codificado con PEM y que puede estar cifrada con contraseña. En el vídeo de arriba puedes ver un ejemplo completo, incluido cómo enviar una solicitud para aplicar la política.

Cuando se activa esta acción de 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 cifran y firman, consulta el estándar 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 se genera un JWT firmado. El elemento <PrivateKey> especifica la clave criptográfica utilizada para firmar el JWT. También hay otros elementos clave. El que uses dependerá del algoritmo especificado por el valor de <Algorithm>, tal como se describe en la siguiente sección.

Definir los elementos clave de 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 dependerá del algoritmo elegido, tal 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 los 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 Acerca de los algoritmos de cifrado de firma.

Generar un JWT cifrado

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

Ejemplo de un JWT cifrado

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

RSA-OAEP-256

En el ejemplo siguiente:

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

El elemento <PublicKey> especifica la clave que se usa para el cifrado 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 siguiente:

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

El elemento <SecretKey> especifica la clave que se usa para el cifrado 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>

Definir los elementos clave de un JWT cifrado

Usa exactamente uno de los siguientes elementos para especificar la clave de cifrado de GenerateJWT cuando quieras generar un JWT cifrado:

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

El elemento que uses dependerá del algoritmo de cifrado de claves elegido, tal como se muestra en la siguiente tabla:

Algoritmo de cifrado de claves	Elementos clave
RSA-OAEP-256	<PublicKey> <Value ref="rsa_publickey"/> </PublicKey> Nota: La clave debe resolverse en una clave pública 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 Acerca de los algoritmos de cifrado de firma.

Referencia de elemento de Generar JWT

En la referencia de la política se describen los elementos y atributos de la política Generar JWT.

Nota: La configuración variará ligeramente en función del algoritmo de cifrado que utilices. Consulta los ejemplos de JWT firmado o el ejemplo de JWT cifrado para ver configuraciones de casos prácticos 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 principales de la política.

Atributo	Descripción	Predeterminado	Presencia
name	El nombre interno de la política. Solo puedes usar los siguientes caracteres en el nombre: A-Z0-9._\-$ %. Sin embargo, la interfaz de usuario de Apigee aplica restricciones adicionales, como la eliminación automática de caracteres que no son alfanuméricos. También puede usar el elemento <displayname></displayname> para etiquetar la política en el editor de proxy de la interfaz de usuario de Apigee con un nombre diferente en lenguaje natural.	N/A	Obligatorio
continueOnError	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado en la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política.	falso	Opcional
habilitada	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará, aunque siga adjunta a un flujo.	true	Opcional
asíncrono	Este atributo está obsoleto.	falso	Obsoleto

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxies de la interfaz de usuario de Apigee con un nombre diferente en lenguaje natural.

Predeterminado	Si omite este elemento, se usará el valor del atributo name de la política.
Presencia	Opcional
Tipo	Cadena

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

Predeterminado	N/A
Presencia	Opcional. Es obligatorio usar <Algorithm> o <Algorithms>.
Tipo	Cadena
Valores válidos	HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 y PS512

<Algorithms>

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

Especifica los algoritmos criptográficos para el cifrado de la clave y del contenido. Usa el elemento <Algorithms> para generar un JWT cifrado.

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

Predeterminado	N/A
Opcional. Es obligatorio usar <Algorithm> o <Algorithms>.	Obligatorio
Tipo	Cadena

Elementos secundarios de <Algorithms>

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <Algorithms>:

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

Algoritmos de cifrado de claves

En la siguiente tabla se enumeran los algoritmos disponibles para el cifrado de claves.

Valor de <Key> (algoritmo de cifrado de claves)	Es obligatorio indicar el elemento Key
dir	<DirectKey>
RSA-OAEP-256	<PublicKey> (que debe resolverse en una clave pública 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 debe resolverse en una clave pública de curva elíptica)

Consulta Generar un JWT cifrado para ver un ejemplo en el que el algoritmo de cifrado de claves es RSA-OAEP-256, por lo que se usa el elemento <PublicKey> con el valor que se resuelve en una clave pública RSA.

Algoritmos de cifrado de contenido

Para cifrar contenido, se pueden usar los siguientes algoritmos (simétricos y basados en AES):

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

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

Predeterminado	N/A
Presencia	Opcional
Tipo	Matriz (una lista de valores separados por comas)
Valores válidos	Cualquier elemento que identifique a la audiencia.

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

Permite especificar pares clave-valor de reclamaciones adicionales en la carga útil del JWT. Puedes especificar la reclamación explícitamente como cadena, número, valor booleano, mapa o matriz. Un mapa es simplemente un conjunto de pares nombre/valor.

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

Predeterminado	N/A
Presencia	Opcional
Valores válidos	Cualquier valor que quieras usar para una reclamación adicional. Puedes especificar la reclamación explícitamente como cadena, número, valor booleano, mapa o matriz.

El elemento <Claim> acepta estos atributos:

• name: (obligatorio) nombre de la reclamación.
  Nota: No uses ninguno de los nombres de reclamación registrados en este elemento. Las reclamaciones registradas se especifican en RFC7519. Entre ellos, se incluyen "iss", "sub", "aud", "iat", "exp", "nbf" y "jti".
• ref: (opcional) Nombre de una variable de flujo. Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican tanto un atributo ref como un valor de reclamación explícito, el valor explícito será el predeterminado y se usará si la variable de flujo a la que se hace referencia no se resuelve.
• type: (opcional) uno de los siguientes valores: string (valor predeterminado), number, boolean o map.
• array: (opcional) asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false.

Si incluye el elemento <Claim>, los nombres de las reclamaciones se definen de forma estática cuando configura la política. También puedes enviar un objeto JSON para especificar los nombres de las reclamaciones. Como el objeto JSON se transfiere como una variable, los nombres de las reclamaciones del JWT generado se determinan en el tiempo de ejecución.

Por ejemplo:

<AdditionalClaims ref='json_claims'/>

La variable json_claims contiene un objeto JSON con 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 del objeto JSON.

Es importante tener en cuenta lo siguiente con respecto al uso de una referencia de variable y un valor de reclamación explícito en el elemento Claim:

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

• Si hay una referencia de variable, pero no se resuelve, y
• Si no especifica un valor explícito (un valor predeterminado)
• Si el atributo de política IgnoreUnresolvedVariables 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, 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>

Incluye los pares nombre-valor de la reclamación adicional en el encabezado del JWT.

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

Predeterminado	N/A
Presencia	Opcional
Valores válidos	Cualquier valor que quieras usar para una reclamación adicional. Puedes especificar la reclamación explícitamente como cadena, número, valor booleano, mapa o matriz.

El elemento <Claim> acepta estos atributos:

• name: (obligatorio) nombre de la reclamación.
  Nota: No uses ninguno de los nombres de reclamación registrados en este elemento. Las reclamaciones registradas se especifican en RFC7519. Entre ellos, se incluyen "iss", "sub", "aud", "iat", "exp", "nbf" y "jti".
• ref: (opcional) Nombre de una variable de flujo. Si está presente, la política usará el valor de esta variable como la reclamación. Si se especifican tanto un atributo ref como un valor de reclamación explícito, el valor explícito será el predeterminado y se usará si la variable de flujo a la que se hace referencia no se resuelve.
• type: (opcional) uno de los siguientes valores: string (valor predeterminado), number, boolean o map.
• array: (opcional) asigna el valor true para indicar si el valor es una matriz de tipos. Valor predeterminado: false.

<Compress>

<Compress>true</Compress>

Especifica si el texto se comprime antes de cifrarse. Este elemento solo es válido cuando se genera un JWT cifrado.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Añade la cabecera crítica, crit, a la cabecera del JWT. La cabecera crit es una matriz de nombres de cabeceras que debe conocer y reconocer el receptor del JWT. Por ejemplo:

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

Según la especificación, las partes verificadoras deben examinar la cabecera crit y verificar que se entiende cada una de esas cabeceras. Por ejemplo, la política VerifyJWT examina el encabezado crit. Por cada elemento que se indica en la cabecera crit, se comprueba que el elemento <KnownHeaders> de la política VerifyJWT también incluya esa cabecera. Si la política VerifyJWT encuentra en crit una cabecera que no esté incluida en <KnownHeaders>, la política VerifyJWT fallará.

Nota: <CriticalHeaders> no añade los encabezados al JWT. Solo define el contenido del encabezado crit. Puedes usar <AdditionalHeader/Claims> para añadir los encabezados.

Predeterminado	N/A
Presencia	Opcional
Tipo	Matriz de cadenas separadas por comas
Valores válidos	Una matriz o el nombre de una variable que contenga la matriz.

<CustomClaims>

Nota: Actualmente, se inserta un elemento CustomClaims cuando añade una nueva política GenerateJWT a través de la interfaz de usuario. Este elemento no funciona y se ignora. El elemento correcto que debe usar es <AdditionalClaims>. La interfaz de usuario 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 cifrar un JWT cuando el algoritmo de cifrado es dir ("cifrado directo").

Elementos secundarios de <DirectKey>

En la siguiente tabla se ofrece una descripción general 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 cadena codificada de una matriz de bytes, codificada mediante hexadecimal (base16), base64 o base64url.

Con el cifrado directo con clave, puedes proporcionar directamente una serie de bytes que actuará como clave de cifrado de contenido (CEK). Debes especificar la matriz de bytes como una cadena codificada. La longitud necesaria de la matriz de bytes depende de la solidez del algoritmo de cifrado de contenido seleccionado. Por ejemplo, en el caso de A256CBC-HS512, debe proporcionar una clave de exactamente 512 bits (64 bytes).

El contenido de la variable private.directkey debe ser una cadena codificada, ya sea mediante hexadecimal (base16), base64 o base64url. Por ejemplo, aquí tienes 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

En la codificación hexadecimal, se aceptan los espacios en blanco, pero no son obligatorios. Además, se aceptan tanto las mayúsculas como las minúsculas (B7 es lo mismo que b7).

El equivalente codificado en base64url de lo anterior es:

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

En las variantes base64*, no se aceptan espacios en blanco y se distingue entre mayúsculas y minúsculas. Si no especificas ninguna codificación, la política asume que la codificación es base64.

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

Algoritmo de cifrado 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 longitud de la clave de cifrado de contenido proporcionada a través del elemento <DirectKey> debe ser exactamente la correcta para el algoritmo de cifrado de contenido especificado. En el caso de cualquier algoritmo de cifrado de claves que no sea dir, la política genera una CEK aleatoria con la longitud adecuada, pero en el caso de dir, la configuración debe proporcionar una clave con el tamaño adecuado de forma explícita.

<ExpiresIn>

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

or:

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

Especifica el tiempo de vida del JWT en milisegundos, segundos, minutos, horas o días. Especifique la fecha de vencimiento mediante el elemento XML o el atributo ref, pero no ambos.

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

Predeterminado	N/A
Presencia	Opcional
Tipo	Entero
Valores válidos	Un valor o una referencia a una variable de flujo que contenga el valor. Las unidades de tiempo se pueden especificar de la siguiente manera: ms = milisegundos (valor predeterminado) s = segundos m = minutos h = horas d = días Por ejemplo, ExpiresIn=10d equivale a ExpiresIn 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. Si el valor de texto y el atributo ref están vacíos, la política generará un jti que contenga un UUID aleatorio. La reclamación de ID de JWT (jti) es un identificador único del JWT. Para obtener más información sobre jti, consulta RFC7519.

Predeterminado	N/A
Presencia	Opcional
Tipo	Cadena o referencia.
Valores válidos	Una cadena o el nombre de una variable de flujo que contenga el ID.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Asigna el valor false si quieres que la política genere un error cuando no se pueda resolver ninguna variable de referencia especificada en la política. Se define como true para tratar cualquier variable que no se pueda resolver como una cadena vacía (nula).

Predeterminado	Falso
Presencia	Opcional
Tipo	Booleano
Valores válidos	verdadero o falso

<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 y un valor definido como el valor especificado. Una reclamación que identifica a la entidad emisora del JWT. Es uno de los conjuntos de reclamaciones registrados que se mencionan en RFC7519.

Predeterminado	N/A
Presencia	Opcional
Tipo	Cadena 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 la hora en la que el token pasa a ser válido. El token no es válido hasta la hora especificada. Puede especificar un valor de tiempo absoluto o un tiempo relativo al momento en que se genera el token.

Predeterminado	N/A
Presencia	Opcional
Tipo	Cadena
Valores válidos	Consulta la información que aparece a continuación.

Valores de tiempo válidos para el elemento NotBefore en el caso de los valores de tiempo absolutos

Nombre	Formato	Ejemplo
Se puede ordenar	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	Lun, 14 ago 2017 11:00:21 PDT
RFC 850	EEEE, dd-MMM-yy HH:mm:ss zzz	Lunes, 14 de agosto del 2017, 11:00:21 (PDT)
ANCI-C	EEE MMM d HH:mm:ss yyyy	Lun, 14 de agosto del 2017, 11:00:21

En el caso de los valores de tiempo relativos, especifica un número entero y un periodo, por ejemplo:

• 10s
• 60 m
• 12 h

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Especifica dónde colocar el JWT generado por esta política. De forma predeterminada, se coloca en la variable de flujo jwt.POLICYNAME.generated_jwt.

Predeterminado	jwt.POLICYNAME.generated_jwt
Presencia	Opcional
Tipo	Cadena (nombre de una variable de flujo)

<PasswordKey>

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

Especifica una clave para cifrar un JWT cuando el algoritmo de cifrado es uno de los siguientes:

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

Para cada uno de estos algoritmos de clave, debe proporcionar una contraseña a partir de la cual se deriva la clave de cifrado de la clave mediante la variable private.password del elemento <Value ref="private.password"/>.

Elementos secundarios de <PasswordKey>

En la siguiente tabla se ofrece una descripción general de los elementos secundarios de <PasswordKey>:

Elemento secundario	Presencia	Descripción
ID	Opcional	Identificador de clave
Valor	Obligatorio	Especifica la contraseña que se usa para generar la clave de cifrado de claves. Usa un atributo ref y especifica una variable, como private.password .
SaltLength	Opcional	Longitud de la sal. Valor predeterminado: 8 bytes.
PBKDF2Iterations	Opcional	Número de iteraciones de PBKDF2: valor predeterminado 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 va a usar al generar un JWT firmado. Algorithm es una variante de RSA o de curva elíptica (EC), como RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 o ES512.

Elementos secundarios de <PrivateKey>

En la siguiente tabla se describen los elementos secundarios de <PrivateKey>:

Elemento secundario	Presencia	Descripción
ID	Opcional	Identificador de la clave. El valor puede ser cualquier cadena. Puede especificar el valor como un valor de texto literal o de forma indirecta, mediante 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 codificada en PEM. Especifica la clave privada que se usa 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 (RS256, RS384, RS512, PS256, PS384 o PS512), debes proporcionar una clave privada RSA codificada. Si el elemento <Algorithm> contiene una variante EC (ES256, ES384 o ES512), debes proporcionar una clave privada de curva elíptica para la curva correspondiente.
Contraseña	Opcional	La contraseña que debe usar la política para descifrar la clave privada, si es necesario. Usa el atributo ref para transferir la contraseña mediante una variable de flujo. Nota: Debes especificar una variable de flujo. Apigee rechazará como no válida una configuración de política en la que la contraseña se especifique en texto sin cifrar. La variable de flujo debe tener el prefijo "private". 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 va a usar al generar un JWT cifrado. El algoritmo Key es una variante de RSA o de 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 los valores Value, Certificate o JWKS. Si especifica JWKS, también debe especificar Id. En la siguiente tabla se describe cada uno de los elementos secundarios de <PublicKey>:

Elemento secundario	Descripción
Valor	Clave pública codificada en PEM. Especifica la clave pública que debe usar la política para cifrar la clave de cifrado de contenido. Puedes especificar la clave literalmente o de forma indirecta mediante 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 EC de la curva adecuada si usas un algoritmo EC.
Certificado	Un certificado X.509 codificado en PEM que envuelve una clave pública. Apigee extraerá la clave pública del certificado y, a continuación, la usará para cifrar la clave de cifrado de contenido. Puedes especificar el certificado literalmente o de forma indirecta mediante 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 EC de la curva adecuada si usas un algoritmo EC. Nota: Apigee no valida las fechas de validez del certificado que proporciones ni la cadena de confianza del certificado. Apigee trata todos los certificados que especifique con este elemento como válidos y de confianza.
JWKS	Una fuente JWKS de claves públicas. Se trata de una lista de claves con el formato descrito en IETF RFC 7517 - JSON Web Key (JWK). Puede especificar el JWKS de cuatro formas: literalmente, como un valor de texto: <PublicKey> <JWKS>jwks-content-here</JWKS> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> Indirectamente, con el atributo ref, especificando 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. indirectamente 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> Indirectamente, mediante 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 especifiques un elemento JWKS en GenerateJWT para generar un JWT cifrado, 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	Cadena que representa el identificador de la clave. En el tiempo de ejecución, Apigee recupera una clave del JWKS que tiene un campo kid que coincide con este valor. El elemento Id es obligatorio si usas el elemento JWKS en 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 debe usar al generar un JWT firmado que utilice un algoritmo simétrico (HS*) o al generar un JWT cifrado que utilice un algoritmo simétrico (AES) para el cifrado de claves.

Hijos de <SecretKey>

En la siguiente tabla se describen los elementos secundarios y los atributos de <SecretKey>:

Hijo/a	Presencia	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, si no se incluye el atributo encoding, la codificación de la clave se trata como UTF-8. Los valores válidos del atributo son: 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 hexadecimal será 49 4c 6f 76 65 41 50 49 73. Por el contrario, si el atributo de codificación es base64 y el contenido de la variable private.secretkey es VGhpcy1pcy1hLXNlY3JldA, la clave se decodificará como un conjunto de 16 bytes en hexadecimal: 54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74. Nota: Apigee aplica una longitud mínima de la clave. Para obtener más información, consulta la documentación del elemento Value.
Id (elemento)	Opcional	Identificador de la clave. El valor puede ser cualquier cadena. Puede especificar el valor como un valor de texto literal o de forma indirecta mediante 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 que se usa para firmar la carga útil. Utilice el atributo ref para proporcionar la clave indirectamente 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 longitud mínima de clave para los algoritmos HS256, HS384 y HS512. La longitud mínima de la clave de HS256 es de 32 bytes, la de HS384 es de 48 bytes y la de HS512 es de 64 bytes. Si se usa una clave con una seguridad inferior, se produce un error de tiempo 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, definida con el valor especificado.Esta reclamación identifica o hace una declaración sobre el asunto del JWT. Este es uno de los conjuntos estándar de reclamaciones que se mencionan en IETF RFC 7519.

Predeterminado	N/A
Presencia	Opcional
Tipo	Cadena
Valores válidos	Cualquier valor que identifique de forma única a un asunto o a 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 cifrado. El elemento <Type> es opcional. Puedes usarlo para informar a los lectores de la configuración sobre si la política genera un JWT firmado o cifrado.

• 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 cifrado y el elemento <Algorithms> debe estar presente.
• Si falta el elemento <Type>:
  • Si el elemento <Algorithm> está presente, la política asume que <Type> es Signed.
  • Si el elemento <Algorithms> está presente, la política asume que <Type> es Encrypted.
• Si no se incluye <Algorithm> ni <Algorithms>, la configuración no es válida.

Predeterminado	N/A
Presencia	Opcional
Tipo	Cadena
Valores válidos	Signed o Encrypted

Variables de flujo

La política Generate JWT no define variables de flujo.

Referencia de errores

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code	HTTP status	Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration	401	Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch	401	The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.EncryptionFailed	401	Creation of an encrypted JWT failed for a non-specific reason
steps.jwt.FailedToDecode	401	The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed	401	The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength	401	For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim	401	For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration	401	Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve	401	The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidJsonFormat	401	Invalid JSON found in the header or payload.
steps.jwt.InvalidPasswordKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey	401	The specified key specified did not meet the requirements.
steps.jwt.InvalidToken	401	This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch	401	The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch	401	The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch	401	The subject claim failed on token verification.
steps.jwt.KeyIdMissing	401	The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed	401	The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader	401	Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey	401	The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed	401	In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired	401	The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid	401	The token is not yet valid.
steps.jwt.UnhandledCriticalHeader	401	A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException	401	An unknown exception occurred.
steps.jwt.WrongKeyType	401	Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

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

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidNameForAdditionalClaim	The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim	If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim	If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader	This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader	If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute	This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidConfigurationForActionAndAlgorithm	If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.
InvalidValueForElement	If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement	This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration	If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration	If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidVariableNameForSecret	This error occurs if the flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidSecretInConfig	This error occurs if the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidTimeFormat	If the value specified in the<NotBefore> element does not use a supported format, the deployment will fail.

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta el artículo Información sobre los errores de las políticas.

Variables	Dónde	Ejemplo
fault.name="fault_name"	fault_name es el nombre del error, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	fault.name Matches "InvalidToken"
JWT.failed	Todas las políticas de JWT definen la misma variable en caso de error.	JWT.failed = true

Ejemplo de respuesta de error

Para gestionar los errores, la práctica recomendada es interceptar la parte errorcode de la respuesta de error. No te fíes del texto de faultstring, ya que podría cambiar.

Regla de error de ejemplo

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