Te presentamos una guía práctica para generar y validar JWTs.

JWT (JSON Web Tokens) es un estándar abierto que define una forma compacta y autocontenida para compartir información entre dos componentes como objetos JSON. Esta información puede ser verificada ya que se encuentra firmada digitalmente. Los JWTs pueden ser firmados usando un secreto (con el algoritmo HMAC) o con un par de llaves privada y pública usando RSA o ECDSA.

Un JWT puede ser firmado o cifrado, para este escenario usamos JWTs firmados y en su forma compacta. Un JWT tiene tres elementos:

• Header: Es el que contiene la información de qué algoritmo se usa para firmar el mensaje.
• Payload: Es la información a compartir que se quiere firmar y verificar digitalmente.
• Signature: Es la firma resultado del procesamiento del header y el payload con el algoritmo definido en el header y la llave privada o secreto establecido.

La forma compacta del JWT se conforma de los 3 elementos anteriores separados por punto de la siguiente manera: base64URL(Header).base64URL(Payload).Signature.

Donde el Signature es la firma y se genera firmando el header y el payload.

Ejemplo: 

Signature = RSASHA256(base64UrlEncode(header) + "." +base64UrlEncode(payload), llavePrivada)

Y al final queda una cadena similar a esta:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.POstGetfAytaZS82wHcjoTyoqhMyxXiWdR7Nn7A29DNSl0EiXLdwJ6xC6AfgZWF1bOsS_TuYI3OG85AmiExREkrS6tDfTQ2B3WXlrr-wp5AokiRbz3_oB4OxG-W9KcEEbDRcZc0nH3L7LzYptiy1PtAylQGxHTWZXtGz4ht0bAecBgmpdgXMguEIcoqPJ1n3pIWk_dUZegpqx0Lka21H6XxUTxiy8OcaarA8zdnPUnV6AmNP3ecFawIFYdvJB_cm-GvpCSbr8G8y_Mllj8f4x9nBH8pQux89_6gUY618iYv7tuPWBFfEbLxtF2pZS6YC1aSfLQxeNe8djT9YjpvRZA

Instalación y configuración SSL

Para iniciar con la generación de un JWT es necesario tener instalado OpenSSL, aquí veremos el paso a paso de su instalación para el sistema operativo Windows.

• Descargaremos el instalador desde la página SHINING LIGTH PRODUCTIONS desde aquí escogeremos la versión para desarrolladores y el tipo de sistema operativo según sea el caso (win32 o win64).

• Ejecutar el archivo de instalación descargado y seguir las instrucciones como lo muestra las siguientes imágenes:

Al finalizar la instalación nos mostrara la siguiente ventana, desmarcamos las casillas y damos click en Finish.

Para comprobar la correcta instalación del OpesSSL y su versión instalada, procedemos a abrir una ventana de comandos (CMD) y escribimos la siguiente instrucción: openssL version y presionamos la tecla Enter.

     Luego de comprobar que la instalación fue correcta procedemos con la generación del JWT.

Generar el JWT

Para generar un JWT usando el algoritmo RS256 se debe contar con una llave privada para firmarlo y con un certificado para verificarlo. Este proceso implica generar una llave privada y certificado de prueba, generar un JWT de prueba y verificar si un JWT es válido con el certificado.

Llave privada y llave pública

Para pruebas

Para pruebas se puede usar un certificado auto firmado, para generarlo se puede usar openssl, el git bash tiene esta herramienta:

Comando: 

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

Información de EJEMPLO:

• Country Name: CO
• State or Province: ANTIOQUIA
• Locality Name: MEDELLIN
• Organization Name: Mi Organization S.A
• Organizational Unit Name: BANCOLOMBIA
• Common Name: nombreapp.apps.ambientesbc.com

El Common Name es el nombre de dominio de la app para la que se genera el certificado, este nombre es el que se le asigna a la app al momento de crearla en nuestro portal, para efectos de prueba en este caso se asignó el valor nombreapp.apps.ambientesbc.com.

Como resultado se generan dos archivos, la llave privada y el certificado, el primer archivo es el que se usa para firmar el JWT y el segundo es el que se puede usar como llave publica con la cual verificamos la firma del JWT. Al abrirlas con un editor de texto

Key.pem (llave privada).

Certificate.pem (Certificado que contiene llave pública).

Herramienta de prueba para generar y validar JWT

Para generar un JWT con la llave privada de prueba se puede usar la herramienta online https://jwt.io/.

Generar JWT

Para las pruebas se deben ingresan los datos:

Algorithm: RS256

Generar un nuevo Payload con los siguientes pasos.

Donde:

• iss: Es un el nombre de quien genera el JWT, para el caso del banco se debe asignar el AW de la aplicación que genera el JWT.
• sub: Identifica para quien se genera el token, debe ser el client_id de la APP en el portal.
• aud: Identifica el grupo o la audiencia para quien se genera el JWT, este dato puede ser un arreglo, para API Connect debe ser APIGateway_XXX (Donde el xxx son las letras del API GW donde está expuesta la API: LAN, DMZ, AWS).
• exp: Es la fecha en la cual el token expira. Es un número en formato NumericDate. Es un timestamp en segundos. Ejemplo: 1588628816.194 o 1588628816. El JWT deja de ser valido una vez se pase de esta fecha. Para el ambiente productivo este valor no puede ser mayor a 1 minuto después de la fecha de generación del token.
• iat: Es la fecha en la cual se genera el token. Es un número en formato NumericDate. Es un timestamp en segundos. Ejemplo: 1588628816.194 o 1588628816.

Nota: Ejemplo para generar estos valores en Javascript.

var iat = new Date()/1000; //1588630053.851

var exp = iat + 60*60; //1588633653.851

• nonce: Es un valor aleatorio de más de 10 caracteres hexadecimales o 20 numéricos.
• Ejemplo para generar estos valores en Javascript con nonce de 12 de longitud, el exp en el ejemplo es de 1 hora después de la fecha de generación del token para efectos de prueba:

let iat = new Date()/1000;
let exp = iat + 60*60;
let min = 17592186044416;//Hex 1000000000000
let max = 281474976710655;//Hex ffffffffffff
let nonce = Math.floor((Math.random() * (max - min + 1)) + min).toString(16);
let jwtPayload = {
    iss: "AW1234001",
    sub: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    aud: "APIGateway_DMZ",
    exp: exp,
    iat: iat,
    nonce: nonce
}
console.log(JSON.stringify(jwtPayload));

• Este código se pude ejecutar en cualquier navegador en la consola de inspeccionar (dando f12 o clic derecho->inspeccionar). En la consola ejecutas el Script y obtendrás un resultado similar al siguiente.

Se pega en la sección de payload lo que se imprime en consola.

Y en verify signature donde dice private Key se pega el texto de la llave privada.

Esto hace que en la sección que dice Encoded se genere un JWT válido que se puede enviar a la API.

El JWT generado:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJOb21icmVBUFAiLCJzdW0iOiJiY2Y3ODM1NC1jMDdhLTQyNzMtYTI2YS00OWIyMGFjZDhlNDUiLCJhdWQiOiJCYW5jb2xvbWJpYSIsImV4cCI6MTU4ODYzNDUxOC41NTMsImlhdCI6MTU4ODYzMDkxOC41NTN9.lFnJ0JdgLXYYjHxLVfsmi1crRnVTzpbpfBatQwQpSuGIuekSc9oGvRekVGQeL5so4qr2_7h1mlLN7JkT4s8YUzJiDwy7dIFfs_ebYj5oDqAVTVJN_6KgZUtAdaIaP5pcDX7WOstSZNXfeAcOiXBy4kG-DiRW8KHoNrNN9-pnPOKv4wrhpDTTgAzoILlMwgiakA3ayXXoUUIARnrj7emyJ6DDuT1DDFwPMj64tD4db_8xDKf7Pwb7VWUIXb4HxGUY4cuXIuIO4SW7J9T1JCeBQLTmo6_ttrZaFLfyzlJnGAd_Cp5-gE5K1A-iMp77f7VyaXZctjj8eEP6JYB5OlJoBg

Verificar JWT

Si se desea verificar un JWT se deben ingresar el JWT a verificar en el campo “Encoded” e ingresar en donde dice Public Key or Certificate el certificado con el que se va a verificar el JWT.

Ahora, debe enviarnos el certificado público para poder adjuntarlo a su aplicación, poder autenticarse y realizar el consumo de nuestras APIs. Puede hacerlo a través del chat o formulario contáctanos del Centro de Ayuda.

⚠️ Aquí te hemos brindado unos consejos generales sobre cómo crear y validar certificados y tokens JWT (JSON Web Tokens) en entornos de desarrollo. No es una guía definitiva ni asesoría legal o de seguridad. Es esencial entender que las prácticas recomendadas aquí son para pruebas y desarrollo, no se sugiere aplicarlas en entornos reales sin primero revisarlas con expertos en seguridad. Así mismo, generar tokens JWT involucra información delicada y claves privadas, compartirlas acá o en otro lado es un riesgo.

Cualquier acción que tomes basada en esta información es bajo tu responsabilidad.