Genera GenerateJWT

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Información

Qué

Genera un JWS firmado con un conjunto de reclamaciones configurables. 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.

Video

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

Ejemplos

• Genera un JWT firmado con el algoritmo HSD256
• Generar un JWT firmado con el algoritmo RS256

Genera un JWT firmado con el algoritmo HSD256

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, Edge codifica el encabezado y la carga útil del JWT y, luego, firma el JWT de manera 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>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

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-edge-JWT-policy-test",
  "aud" : "show",
  "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.

Generar un JWT firmado con el algoritmo RS256

Esta política de ejemplo generará un JWT nuevo y lo firmará con el algoritmo RS256. Generar de una firma RS256 se basa en una clave privada RSA, que se debe proporcionar en formato de codificación PEM. 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 política, Edge codifica y firma digitalmente el JWT, incluidos los reclamos. Para obtener información sobre las partes de un JWT y cómo se encriptan y firman, consulta RFC7519.

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

Configura los elementos clave

Los elementos que usas para especificar la clave usada para generar el JWT dependen del algoritmo elegido, como se muestra en la siguiente tabla:

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

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

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 ver ejemplos que demuestran configuraciones específicas 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.

<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 administración con un nombre diferente y con lenguaje natural.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica el algoritmo de encriptación para firmar el token.

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

<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> incluye los siguientes atributos:

• name: El nombre del reclamo (obligatorio).
• 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" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

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

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

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

El elemento <Claim> incluye los siguientes atributos:

• name: El nombre del reclamo (obligatorio).
• 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

<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” ],
}

En el entorno de ejecución, la política VerifyJWS 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.

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

<ExpiresIn>

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

Especifica la duración del JWT en milisegundos, segundos, minutos, horas o días.

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

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

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

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

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

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

• 10s
• 60m
• 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.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Especifica el ID de clave (kid) que se incluirá en el encabezado JWS. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<PrivateKey/Password>

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

Especifica la contraseña que debe usar la política para desencriptar la clave privada, si es necesario. Usa el atributo ref para pasar la clave en una variable de flujo. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<PrivateKey/Value>

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

Especifica una clave privada con codificación PEM que se usa para firmar el JWS. Usa el atributo ref para pasar la clave en una variable de flujo. Usa solo cuando el algoritmo es uno de RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Especifica el ID de clave (kid) que se debe incluir en el encabezado JWT de un JWT firmado con un algoritmo HMAC. Úsalo solo cuando el algoritmo sea uno de HS256/HS384/HS512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Proporciona la clave secreta usada para verificar o firmar tokens con un algoritmo HMAC. Úsalo solo cuando el algoritmo sea uno de HS256/HS384/HS512. Usa el atributo ref para pasar la clave en una variable de flujo.

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

<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 de reclamaciones estándar que se mencionan en RFC7519.

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 y mensajes de error que se muestran y las variables de fallas que establece Edge 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.

Errores en la implementación

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

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.

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 "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>