El complemento de Inicio de sesión con token tiene un interruptor en la esquina superior derecha que le permite activar o desactivar esta funcionalidad.

Para poder activar el complemento primero se deben llenar y guardar todos los campos del formulario.

Al activar este complemento, los usuarios podrán iniciar sesión validando un token que se recibe por URL en la vista de inicio de sesión contra un servicio Web externo, lo cual determinará si pueden ingresar a la plataforma o no.

En este complemento se definen todos los datos necesarios para realizar esta validación, como lo son: la ruta GET hacia el servicio Web externo (endpoint) y las cabeceras que contendrá la petición. Los campos a llenar de este complemento son:

Ruta: indica la ruta (endpoint) hacia la cual enviar el token para su verificación. Esta petición será de tipo GET.

Cabeceras:

Cabecera de envío de token: indica el nombre de la cabecera que se utilizará para enviar el token recibido. Por defecto, será la cabecera «Authorization» y puede ser editada, pero su valor no puede ser editado y será la palabra «Bearer» seguido del token.

Cabeceras adicionales a enviar:

• Nombre: indica el nombre de la cabecera que será incluida en la petición GET a enviar al servicio Web externo.

• Valor: indica el valor de la cabecera.

Nota: si no se especifica ninguna cabecera, se enviará la cabecera Content-Type con el valor de «application/json».

La ruta a la que el cliente debe redirigir a sus usuarios en Teachlr es la siguiente:

https://{dominio}/#signin?token={token}

Donde {dominio} es el dominio de la plataforma Teachlr y {token} es el token generado por el cliente para un usuario en específico.

Ejemplo para entrar la plataforma «demo» con un token «abc123»

https://demo.teachlr.com/#signin?token=abc1232

Adicionalmente, se puede incluir el parámetro «redirect» con el URL de alguna vista de la plataforma Teachlr a donde redirigir al usuario luego de iniciar sesión:

https://demo.teachlr.com/#signin?token=abc123&redirect=dashboard/student/curso-ej

La validación del usuario se logra realizando una petición GET hacia la ruta definida en el complemento y enviando en dicha petición las cabeceras con los valores que se hayan especificado, junto a la cabecera indicada en el campo «Cabecera de envío de token» con el valor de «Bearer {token}», donde {token} es el valor del token recibido por URL («abc123» en el ejemplo).

El servicio Web verifica el token enviado, devuelve una respuesta y, dependiendo de la respuesta, se le permite o se le impide al usuario el acceso a la plataforma.

Las respuestas se consideran exitosas o fallidas basándose principalmente en los códigos de estado HTTP.

Se considera una respuesta exitosa cuando se recibe un código de estado HTTP 2xx:

«Peticiones correctas» y cumple con las siguientes características:

Código de estado HTTP:	2xx
Formato de respuesta:	{   «message»: «OK»,   «user_data»: {     «external_id»: «EXID-123456»   } }

Nota: Si se recibe un código de estado HTTP 2xx pero el formato de respuesta no se cumple, se considerará fallida la respuesta.

La respuesta debe contener un objeto «user_data» que a su vez debe contener como mínimo la clave «external_id» cuyo valor debe ser un identificador único por usuario definido por el cliente.

Se admite recibir otros atributos en el objeto «user_data» que la aplicación podrá leer para completar la información del usuario.

Se puede incluir la clave booleana «update» dentro del objeto «user_data» que indicará si los atributos recibidos deben reemplazar o no a los que ya existen en la BD de Teachlr para ese usuario. Esta clave «update» tomará automáticamente el valor de «true» si el usuario no existía previamente y va a ser registrado por primera vez.

Los posibles atributos que se pueden enviar en la respuesta exitosa de inicio de sesión, y que se tomarán para completar la información del usuario en la aplicación, son los siguientes:

Atributo	Descripción
email	Dirección de correo electrónico
name	Nombre
last_name	Apellido
job	Cargo
department	Departamento
about	Bio (información acerca del usuario)
phone	Teléfono
identification_number	Número de identidad
employee_number	Número de empleado
organization_name	Nombre de la organización
external_id	ID externo
update	¿Actualizar información?

En la respuesta se pueden recibir todos o algunos de estos atributos, cuyos valores pueden ser modificados posteriormente por el usuario en el módulo de «Ajustes personales» de la aplicación, si están habilitados.

Otros atributos que puede recibir la respuesta son course_id y group_id, los cuales deben ser arreglos con los IDs de cursos/grupos a los cuales suscribir el usuario luego de iniciar sesión exitosamente.

A continuación, se muestra el objeto completo de respuesta exitosa que admite la aplicación.

Código de estado HTTP:	2xx
Cabecera:	Content-Type: application/json
Formato de respuesta:	{   «message»: «OK»,   «user_data»: {     «name»: «Pedro»,     «last_name»: «Pérez»,     «email»: «pedroperez@dominio.com»,     «job»: «Analista/programador»,     «about»: «Lorem ipsum dolor sit amet»,     «department»: «Informática»,     «identification_number»: «14425125»,     «employee_number»: «E14425125»,     «organization_name»: «Empresa»,     «phone»: «04169998877»,     «external_id»: «EXID-123456»,     «course_id»: [1,2,3],     «group_id»: [20,21,22],     «update»: true   } }

Nota: en caso de recibir los atributos «email» y/o «employee_number», la aplicación verificará que el email tenga un formato válido y que ambos no estén registrados ya en la aplicación para otro usuario. Si estas validaciones fallan, se le informará al usuario del error.

Se considerará una respuesta fallida cuando no se recibe un código de estado HTTP 2xx, como por ejemplo, un código 4xx: «Errores del cliente»:

Código de estado HTTP:	4xx
Cabecera:	Content-Type: application/json
Formato de respuesta:	{   «status»: «4xx»,   «message»: «Mensaje de error» }

Para los casos de respuesta fallida se le mostrará al usuario el mensaje recibido por el servicio Web externo en el parámetro «message», si lo hubiera.

Se admite recibir también en la respuesta un parámetro «lang» que la aplicación podrá leer para mostrar el mensaje de error en el idioma en el que se está visualizando la aplicación en ese momento.

Para especificar cada lenguaje se utiliza la nomenclatura estandarizada ISO 639-1 de dos letras. A continuación, se muestra el objeto completo de respuesta fallida que admite la aplicación.

Código de estado HTTP:	4xx
Cabecera:	Content-Type: application/json
Formato de respuesta:	{   «status»: «4xx»,   «message»: «Mensaje de error»,   «lang»: {     «es»: «Se ha producido un error»,     «en»: «An error occurred»,     «fr»: «Une erreur s’est produite»,     «pt»: «Ocorreu um erro»     «he»: » אירעה שגיאה»   } }

Cabe destacar que el parámetro «lang» es opcional y depende de que exista el parámetro «message». Si no se envía el parámetro «lang», la aplicación entonces mostrará el mensaje especificado en el parámetro «message».

Si el parámetro «message» no se envía o el objeto de respuesta no es un objeto JSON válido, la aplicación mostrará entonces (en el idioma actual de la aplicación) un mensaje por defecto, que en español sería:

«Tus credenciales no pudieron ser verificadas. Por favor, contacta al administrador.»