Centro de Ayuda: Nivelat

Aprende como integrar una plataforma externa con Nivelat Single Sign-On utilizando el estándar JWT (JSON Web Token)

Resumen

Una de las funcionalidades de la plataforma Nivelat es incorporar distintas maneras de autenticar a los usuarios de plataformas externas en Nivelat de una manera simple y segura. Para ello se utiliza el estándar JSON Web Token (JWT), con el cual se enviará el identificador de usuario de la plataforma externa a Nivelat utilizando una clave secreta para firmar el token, la cual se creará para la plataforma y se compartirá para que Nivelat pueda confirmar que la información enviada proviene de la plataforma correcta.

El siguiente diagrama explica el funcionamiento de esta integración:

Estructura JWT NIVELAT

El token compartido a las plataformas externas estará compuesto de las tres secciones mencionadas de JWT y en cada una de ellas vendrán los siguientes datos.

• Header

Se utilizará el algoritmo de firma HMAC-SHA256 y será del tipo JWT.

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

• Payload

Se enviarán ciertos campos estándar de JWT para indicar el usuario en nombre del cual fue emitido el JWT (sub), el proveedor de identidad que emitió el JWT (iss) y la fecha en la cual fue emitido el JWT (iat), se utilizará un día de validez del token para prevenir el uso indebido del link generado. También se incorporará el nombre del usuario autenticado (name) y el correo electrónico en caso de ser necesario (email). Para todos los datos adicionales que se quieran enviar se utilizará el campo “extra”.  Los campos en cursiva son opcionales.

{
  "iss": "<SUBDOMINIO>",
  "iat": 1422779638,
  "sub": "uniqueid",
  "name": "Nombre Usuario",
  "email": "usuario@empresa.com",
  "company": "COMPANY_CODE",
  "business_unit": "BUSINESS_UNIT_CODE",
  "division": "DIVISION_CODE",
  "department": "DEPARTMENT_CODE",
  "group": "GROUP_CODE",
  "course": "COURSE_CODE",
  "redirect": "REDIRECT"
}

Sobre el campo redirect, es un campo opcional que permitirá indicar la pantalla a la cual se enviará al usuario luego un inicio de sesión exitoso, los valores permitidos son los siguientes:

• course_list: Enviará al usuario al listado de cursos

• curriculum_list: Enviará al usuario al listado de programas

• user_ranking: Enviará al usuario al ranking de usuarios

• team_ranking: Enviará al usuario al ranking de equipos

Signature

Todos los token deberán venir firmados utilizando la clave secreta entregada al habilitar la integración SSO JWT en Nivelat, esta clave se podrá modificar posteriormente e impedirá la autenticación del usuario si es que la firma es inválida.

LOGIN NIVELAT

Una vez construido el token correspondiente a los datos del usuario, será necesario enviar esta información por medio de una llamada GET al endpoint /api/v1/auth/jwt indicando el token y apuntando al dominio correspondiente.

Cabe mencionar que ambos ambientes tendrán claves secretas diferentes las cuales serán proporcionadas por medio de un correo electrónico por el equipo Nivelat una vez hecha la solicitud.

Dominio Pruebas

https://<SUBDOMINIO>.staging.nivelat.com/api/v1/auth/jwt?jwt=TOKEN

Dominio Producción

https://<SUBDOMINIO>.nivelat.com/api/v1/auth/jwt?jwt=TOKEN