Aplicación vLanzadera y login social
Documentación y guía de instalación
Qué es vLanzadera
Es una aplicación de Velneo que permite configurar una lanzadera de aplicaciones para un navegador web. La lanzadera permite utilizar un formulario web para identificar usuarios a través de nombre de usuario y contraseña usados tradicionalmente en Velneo, pero también añade la posibilidad de hacer login mediante oauth con diferentes proveedores, lo que se conoce como Login Social.
Contacta con Velneo para informarte sobre cómo puedes conseguirla.
Requisitos necesarios
vLanzadera solo funciona en Velneo Cloud, en versiones 32 o superior, y es necesario tener contratado el servicio Velneo Cloud vModApache.
En el caso de querer habilitar el login social, es necesario configurar las credenciales de oauth con el proveedor de identidades que se desee utilizar (Google, facebook, etc.).
Configuración
vLanzadera
vLanzadera es una aplicación de Velneo. Para disponer de la lanzadera de aplicaciones hay que instalar el vin de la aplicación y crear una instancia durante la instalación.
Apache
La configuración se establece en el fichero /apache2/001-default-ssl.conf del servidor Velneo cloud.
Podremos editarlo conectándonos con el servidor cloud vía sftp.
Lo primero que tenemos que asegurarnos es que la línea:
Include /etc/apache2/conf-available/vlanzadera.conf
esté presente al final de nuestro fichero de configuración de Apache. Si no lo está, añadirlo antes de la etiqueta </VIRTUALHOST>.
Debe quedar algo como sigue:
Ahora tenemos que crear el location para la aplicación que hemos instalado en el punto anterior. Dentro de la sección VirtualHost, debemos tener algo similar a esto:
El location tiene que llamarse obligatoriamente /auth.
El nombre de la aplicación debe ser el alias de la instancia del proyecto de aplicación de vLanzadera:
El puerto a usar puede ser el indicado u otro, en función de los servicios contratados. Si tienes dudas puedes consultarlo con el personal de soporte de Velneo.
La línea VelneoMode está comentada intencionadamente, porque esta aplicación NO FUNCIONA en ese modo.
El usuario debe ser un usuario declarado en ese servidor y que tenga privilegios de supervisor.
Si queremos que el raíz de nuestro sitio responda a las llamadas que se realicen a la vLanzadera, tendremos que añadir dentro de la directiva Directory del VirtualHost la redirección oportuna. Debería quedar algo similar a esto:
Una vez realizados dichos cambios, reiniciar el servicio de Apache desde tu panel de Velneo Cloud.
vServer
La lanzadera utiliza JWT para intercambiar información con el servidor. Para garantizar y securizar el intercambio de información entre la lanzadera y Velneo vServer, es necesario especificar una clave JWT en el registro de Velneo vServer.
Para ello, en Velneo Cloud es tan sencillo como conectarse por sftp y editar el fichero .config/Velneo/vServer.conf.
Si no la tenemos ya, añadir una línea que contenga la propiedad:
jwtKey=TU_CLAVE_JWT_DE_32
La clave JWT debe tener una longitud mínima de 32 caracteres.
De forma opcional, se puede configurar un parámetro de tiempo de validez del token.
jwtExpiredSeconds=NUMERICO_SEGUNDOS
Por seguridad el servidor solo aceptará el token generado por la lanzadera durante los siguientes jwtExpiredSeconds segundos más 60 segundos de cortesía por sí hay desviación de la hora entre el cliente y el servidor.
Si no se configura el parámetro tendrá un valor por defecto de 60 segundos.
IMPORTANTE: Por temas de seguridad, la clave JWT solo debe ser conocida por el administrador. Es única responsabilidad del desarrollador mantener la clave JWT a buen recaudo y no compartir ni publicar en web o repositorios.
Aplicación vLanzadera y personalización
Cuenta con las siguientes pantallas:
Principal
En esta pantalla se pueden ver mensajes de información y alerta.
Tipos de errores
A continuación listamos los mensajes de errores que pueden generarse y las acciones que recomendamos llevar a cabo.
| Mensaje de error | Acción |
|---|---|
Error de descarga de fichero | Contactar con soporte de Velneo (incluir la salida del log de errores). |
Error de creación de fichero | Contactar con soporte de Velneo (incluir la salida del log de errores). |
Para usar Login Social con la aplicación vLanzadera es necesario que esté definida una clave. Consulta la documentación. | Configurar la clave jwt como se indica en el apartado de configuración de vServer. |
Parámetros
Datos
Aquí se modifican los textos que aparecen en la lanzadera.
Hay un booleano para activar el modo depuración, que activa diversos logs en el panel de desarrollador (F12) del navegador web cuando se carga la lanzadera.
Iconos
Aquí se pueden cambiar los iconos que se utilizan en la lanzadera.
Instancias
Aquí se define una lista de las instancias que van a aparecer en la lanzadera. Para que una instancia le aparezca al usuario que se identifica en la lanzadera, tiene que cumplir dos requisitos:
Que la instancia esté dada de alta en la vLanzadera en este menú.
Que en Velneo vAdmin el usuario que va a hacer login tenga permisos para ejecutar la instancia.
Para añadir una instancia en vLanzadera, hay que crear un registro desde el menú de instancias. Hay que rellenar el campo código de instancia en el combobox.
En el combobox aparecen las instancias a las que el usuario que está ejecutando la aplicación vLanzadera tiene acceso, que no tienen porqué coincidir con las mismas que el usuario que va a hacer login en la web.
Proveedores
Para que funcione el Login Social, el email asociado al usuario debe estar definido en el campo Email de dicho usuario en Velneo vAdmin. Si la validación oAuth se hace contra Google y se usa Google Workspace (Google Apps) con varios dominios, el dominio a indicar es el principal de ese Google Workspace.
Aquí se pueden configurar métodos de autenticación adicionales. En vLanzadera el proveedor de login social Google viene deshabilitado por defecto.
Al crear un proveedor aparece un botón nuevo en la lanzadera. En vLanzadera se puede configurar el texto del botón, el icono, los colores y definir un javascript onClick a ejecutar tras pulsar el botón.
En la pestaña de variables de proveedor se pueden declarar variables. Al hacer click en el botón del proveedor, se sustituyen las variables por su valor en el javascript onClick. El proveedor de Google ya está preparado para rellenar el ID de cliente, el secreto de cliente y el Redirect URI que hayamos indicado en el provedor oAuth (ver siguiente punto para aclaración sobre estos valores)
Google (opcional)
La aplicación ya viene con la programación para utilizar el login con Google, pero hace falta realizar unos pasos en Google cloud console y añadir varios parámetros en vLanzadera.
Los pasos a realizar en la consola de Google son:
Crear un proyecto (Si no lo has hecho antes, tendrás que configurar la pantalla de consentimiento de OAuth).
En API y servicios → credenciales → crear credenciales → ID de cliente de OAuth.
Seleccionar tipo de aplicación web.
En la sección de URI de redireccionamiento autorizados, agregar una URI. Poner la URI donde se sirve tu Apache de Velneo Cloud (si has incluído la redirección a / que se indica en la sección de apache, será la URL que se informa en la sección Apache del panel de control cloud. En caso contrario será esa URL seguida de /auth (o el nombre del location utilizado)
En las credenciales se puede ver un ID de cliente y un secreto de cliente. En el apartado de personalización de la ficha del proveedor de Google en la lanzadera utilizaremos estos valores.
Por último, en la ficha del proveedor de Google en la lanzadera activar el proveedor (inactivar el check Desactivar).
Creación de nuevo proveedor
Esta parte es opcional. Solo será necesaria si queremos añadir algún nuevo proveedor oAuth o crear nuestro propio sistema de login.
La creación de un nuevo proveedor de autenticación requiere añadir programación javascript.
Un nuevo proveedor implica que aparezca un botón nuevo para autenticarse en vLanzadera.
Desde el registro de proveedor nuevo, puedes añadir código JavaScript para el "onClick" del botón y código para gestionar el comportamiento de Velneo vServer en el "script backend".
Script on click
En este campo se escribe código JavaScript que se va a ejecutar en el navegador. La librería de jquery ya está cargada, por lo que se puede usar en este script.
Antes de ejecutar el script, se busca texto que coincida con los nombres de las variables de proveedor y se sustituye por el valor. Se recomienda utilizar la nomenclatura %%NOMBRE_VARIABLE%%.
Es importante que, tras hacer todo lo que se desee, el flujo termine en una redirección al host de la vLanzadera con el parámetro state={"prov": “nombreDeProveedor”}
En el caso de un proveedor de tipo Oauth, la redirección se debe hacer a la pantalla de login del proveedor. Es importante pasarle el parámetro state con el nombre del proveedor y otro parámetro redirect_uri que sea el host de vLanzadera. El proveedor de Oauth, tras el login con éxito del usuario, hará una redirección a la redirect_uri conservando el state que le pasamos al principio.
Script backend
En este campo se escribe código JavaScript que se va a ejecutar en Velneo vServer, por lo que no hay acceso al DOM ni a Jquery, pero se tiene acceso a la API de Velneo para JavaScript.
Cualquier petición get con el parámetro state={“prov”, “nombreDeProveedor”}, buscará un proveedor con el nombre "nombreDeProveedor" y ejecutará el script definido en ese registro.
Si se han declarado variables %%NOMBRE_VARIABLE%%, en el ámbito de este JavaScript están ya declaradas las variables NOMBRE_VARIABLE (Quitando los %).
Tras la ejecución del script, vLanzadera espera que se haya declarado una variable resultado de tipo objeto. Este objeto debe tener las siguientes claves:
Obligatorios:
exitoLogin: booleano. Si vale true, permite el acceso a la lanzadera.
email: cadena. En caso de que haya habido éxito en el login, la lanzadera buscará al usuario con este email para loguearle.
Opcionales:
access_token: cadena. Si el proveedor es de tipo Oauth, se guardará para la sesión del usuario este valor.
refresh_token: cadena. Si el proveedor es de tipo Oauth, se guardará para la sesión del usuario este valor.
state: aquí se puede guardar toda la información adicional que se desee para la sesión del usuario.
Error message: cadena. Mensaje que aparecerá en la vLanzadera para darle información al usuario.
Error code: Numérico. Código de error que aparecerá en el mensaje. Se recomienda usar un código superior a -1000.
Estáticos
Aquí están definidos el html y css de la lanzadera de modo que se pueden editar y personalizar.
Conectarse a la lanzadera vía web
Para acceder vía web a la lanzadera usaremos la url que se indica en la sección Apache en el panel de control cloud del servidor (si hemos establecido la redirección a / en la sección apache).
Última actualización
