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 navegador. 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 funciona tanto en Velneo Cloud como en servidores propietarios y los servidores deben cumplir los siguientes requisitos:

  • Tener instalaodo el componente Velneo vModApache.

  • Servidor Web de Aapche 2.4 con SSL.

  • Licencia para ejecución web y login social (si se desea ejecutar las aplicaciones en un navegador Web).

  • Certificado ssl propio para Apache y para Velneo vServer.

  • Disponer de la aplicación vLanzadera.

En el caso de querer login social, es necesario configurar las credenciales de oauth con el proveedor de identidades que se desee utilizar (Google, facebook, etc.).

Instalación de vLanzadera

Instala vLanzadera en tu servidor con Velneo vAdmin, crea una instancia y ejecútala con Velneo vClient.

Si no tienes licencia de vLanzadera, el sistema no te dejará instanciarla.

En el caso de tener la licencia de vLanzadera y haberla cancelado, ya no podrá ser ejecutada.

vLanzadera solo se puede abrir con un usuario supervisor Al abrir la aplicación, se abre el formulario principal que muestra, en caso de que los haya, una lista de errores a solucionar.

Configuración

Una vez instalada, el siguiente paso será configurar Apache:

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 errorAcció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 y otros parámetros necesarios para su correcto funcionamiento. Son:

  • Título de la web: en este parámetro configuraremos el dato que aparecerá en el tag </TITLE> en la página de la lanzadera. Ejemplo: "Lanzadera de Velneo, S.A.".

  • Texto de bienvenida: nos permite configurar el texto que se mostrará en la página a modo de bienvenida. Ejemplo: "Hola".

  • Subtítulo: nos permite configurar otro texto a presentar debajo del de bienvenida. Ejemplo: "Por favor, introduce tus datos".

  • Etiqueta usuario: etiqueta que se presentará junto al campo donde el usuario deberá introducir su nombre/email. Ejemplo: "Usuario".

  • Etiqueta contraseña: etiqueta que se presentará junto al campo donde el usuario deberá introducir su contraseña. Ejemplo: "Contraseña".

  • Texto enviar formulario: texto que se presentará en el botón que enviará la información del formulario web. Ejemplo: "Iniciar sesión".

  • Nombre compañía: nombre de la empresa. Por ejemplo: "Velneo, S.A."

  • Versión personalizada: la lanzadera, por defecto, usará la misma versión de Velneo vClient Web que tenga el servidor al que nos hayamos conectado. Si por algún motivo queremos ejecutar las aplicaciones con una versión posterior (nunca anterior) de Velneo vClient Web, indicaremos el número de versión en este parámetro.

  • URL descarga personalizada: lo dejaremos en blanco. Solamente será necesario rellenarlo si en algún momento el personal de Velneo te lo indica.

  • Dominio: aquí especificaremos el dominio de nuestra lanzadera, que será el dominio para el cual se han generado los certificados SSL que hayamos configurado tanto en Apache como en Velneo vServer.

  • Puerto VATPS: puerto de escucha para vatps de nuestro servidor. Esta dato no debería modificarse ya que se calcula automáticamente la primera vez que se ejecuta. Si el campo tiene algún valor y posteriormente modificamos el puerto de escucha de nuestra licencia, tendremos que ejecutar la lanzadera y actualizarlo.

  • Puerto HTTPS: aquí configuraremos el puerto de escucha para https que hayamos configurado en Apache. En la configuración de Apache Haus, que es la que hemos tomado de ejemplo para generar esta documentación, el puerto por defecto es el 443.

  • Abrir instancias en nueva pestaña: si este parámetro está desactivado, cuando en la página de la lanzadera seleccionemos una instancia, se abrirá en la misma pestaña. Si lo activamos, se abrirá en una nueva pestaña.

  • Modo depuración: este parámetro activa diversos logs en el panel de desarrollador (F12 en Chrome) en la web de la lanzadera.

Iconos

Aquí se pueden cambiar los iconos que se utilizan en la lanzadera.

Instancias

Aquí se define una lista blanca de las aplicaciones (instancias) y/o enlaces externos (una web externa o la url de la lanzadera de otro servidor) que van a aparecer en la lanzadera.

Para añadir una instancia o un enlace externo en vLanzadera, hay que crear un registro desde el menú de instancias.

En el parámetro tipo de instancia, debemos indicar si se trata de una aplicación o de un enlace.

Si seleccionamos enlace, no tendremos más que indicar su URL. Por ejemplo: https://www.velneo.com/

Si seleccionamos instancia, debemos especificar cuál. Para que una instancia le aparezca al usuario que se identifica en la lanzadera, tiene que cumplir dos requisitos:

  1. Que la instancia esté dada de alta en la vLanzadera en este menú.

  2. Que en el vAdmin el usuario tenga permisos para ejecutar la instancia.

Hay que rellenar el campo código de instancia en el combobox.

Una instancia, por defecto, se ejecuta en el explorador Web. Si queremos que sea ejecutada por un Velneo vClient de escritorio, activaremos la propiedad Ejecutar en escritorio. Ver el punto lanzar vClient de escritorio para ver los requisitos previos.

La opción abrir en nueva pestaña, cuando ejecutamos en un explorador Web, hace que la aplicación se abra en una nueva pestaña del explorador, quedando en la anterior la página de la lanzadera. Si está desactivada, la aplicación se abrirá en la misma pestaña en la que estuviese cargada la lanzadera.

En el combobox aparecen las instancias a las que el usuario que está ejecutando vLanzadera tiene acceso.

Cuando ejecutemos una instancia en el explorador web, en el título de éste se mostrará el nombre que ésta tenga definida en Velneo vAdmin:

Ocultar barra de progreso: por defecto, mientras se carga una aplicación en un explorador web se muestra una barra de progreso. Si activamos esta opción podemos hacer que no se muestre barra de progreso alguna o que se muestre una personalizada.

JavaScript barra de progreso personalizada: esta opción solo estará disponible si hemos activado la opción anterior. Si lo dejamos vacío, no se mostrará la barra de progreso durante la carga de la aplicación en el explorador Web. Si tiene contenido, este script se ejecuta 2 veces. La primera vez para mostrar la barra de progreso y la segunda vez para ocultarla. Disponemos de la variable bShow que nos indica si se está ejecutando la pirmera vez (bShow = true) o si es la segunda (bShow = false).

En este JavaScript podemos hacer las operaciones en el DOM para insertar, mostrar u ocultar contenido html. Ejemplo:

let progressBar = document.querySelector("#pb");
if(!progressBar){
    // agregar un elemento al body forzando que se vea arriba del todo
    let body = document.querySelector("body");
    progressBar = document.createElement("div");
    progressBar.id = "pb";
    progressBar.style.position = "fixed";
    progressBar.style.top = "0";
    progressBar.style.left = "0";
    progressBar.style.width = "100%";
    progressBar.style.height = "100%";
    progressBar.style.background = "rgba(0,0,0,0.5)";
    progressBar.style.display = "block";
    progressBar.style.zIndex = "9999";
    body.appendChild(progressBar);
    // Insertamos un h1 con el texto cargando...
    let titulo = document.createElement("h1");
    titulo.innerText = "Cargando...";
    progressBar.appendChild(titulo);
    console.log(titulo);
}
if (bShow){
    console.log('mostrando')
    progressBar.style.display = "block";
} else {
    console.log('ocultando')
    progressBar.style.display = "none";
}

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. Con vLanzadera viene por defecto la opción de Google deshabilitada.

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 mencionados anteriormente en el apartado de configuración.

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:

  1. Crear un proyecto (Si no lo has hecho antes, tendrás que configurar la pantalla de consentimiento de OAuth).

  2. En API y servicios → credenciales → crear credenciales → ID de cliente de OAuth.

  3. Seleccionar tipo de aplicación web.

  4. En la sección de URI de redireccionamiento autorizados, agregar una URI. Poner la URI donde se sirve tu Apache de Velneo Cloud (la URL que se informa en la sección Apache del panel de control cloud.

  5. En las credenciales se puede ver un ID de cliente y un secreto de cliente. En el apartado "Variables de proveedor" de la ficha del proveedor de Google en la lanzadera utilizaremos estos valores.

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

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.

Restaurar configuración inicial

Estáticos

Aquí están definidos el html y css de la lanzadera de modo que se puedan editar y personalizar.

Restaurar configuración inicial

Modos de acceso

En esta pantalla se pueden configurar urls que cambian cómo el usuario accede a la aplicación, posibilitando acceder sin login o acceder a una aplicación directamente sin seleccionarla desde la lanzadera.

Cada registro, al configurarlo genera una url de modo. Los parámetros disponibles son:

  • Nombre: Para facilitar la identificación del modo al administrador de la vLanzadera

  • Modo de acceso:

    • Modo 1 - Usuario e instancia fijos: Acceso anónimo a una aplicación.

    • Modo 2 - Usuario fijo: Acceso anónimo a la lanzadera de aplicaciones.

    • Modo 3 - Instancia fija: Acceso con login a una aplicación.

  • Instancia: Configurable en los modos 1 y 3. Selecciona la aplicación que se ejecutará al abrir la url.

  • Nombre de usuario: Configurable en modos 1 y 2. Usuario que internamente la lanzadera utilizará para ejecutar la aplicación.

  • Contraseña de usuario: Configurable en modos 1 y 2. Contraseña del usuario.

  • Location/virtual host: puede ir en blanco en caso de que se haya configurado el rewriterule para servir la lanzadera en la raíz del host. En caso contrario estableceremos auth.

  • Url de modo: URL para ejecutar el modo en un navegador. Se genera automáticamente tras configurar el modo. La URL cambia si se hacen cambios en la configuración.

  • Url de retorno: Configurable en modos 1 y 3. Al no haber lanzadera de aplicaciones a la que redirigir, en esta opción se permite configurar una url a la que se desea redireccionar al usuario si este lanzara una acción "Archivo: Salir".

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.

Cuando desde la lanzadera lancemos una aplicación en Web o una URL externa, ésta será abierta en una nueva pestaña del navegador, de este modo dejaremos libre la lanzadera para seguir abriendo otras aplicaciones.

Lanzar vClient de escritorio desde vLanzadera

Windows

Requisitos previos:

Linux

Requisitos previos:

  • Decargar Velneo vClient.

  • Ejecutar vClient.sh descargado al menos una vez (con que salga la ventana de conexión es suficiente).

En Chrome escribir una ruta válida del tipo:

velneo-run://vatps://usuario:pass@host:puerto/instancia

Si escribimos la url y pulsamos la tecla intro, hará la búsqueda. Se debe hacer clic en la segunda opción del combo que aparece:

macOS

Requisitos previos:

  • Decargar Velneo vClient.

  • Ejecutarlo al menos una vez (con que salga la ventana de conexión es suficiente).

En Chrome escribir una ruta válida del tipo:

velneo-run://vatps://usuario:pass@host:puerto/instancia

Si escribimos la url y pulsamos la tecla intro, hará la búsqueda. Se debe hacer clic en la segunda opción del combo que aparece:

Nota importante

Pueden ocurrir problemas de cross-origin en procesos ejecutables en Web cuando tenemos la Lanzadera configurada.

Cuando se tiene una instalación de vModApache con la vLanzadera, otros location/virtualhost pueden dar error de cross-origin al intentar acceder a recursos de otros dominios. Esto se debe a que hay una cabecera (Cross-Origin-Embedder-Policy="require-corp") de Apache que es necesaria para el funcionamiento de vLanzadera que impide el uso de recursos externos.

Con la directiva Rewriterule se puede declarar un patrón de urls a las que le quieres cambiar la cabecera de Apache. Por ejemplo, si en el location apih, instancia verp_app_app, queremos ejecutar en Web el proceso mi_proceso.pro podemos poner lo siguiente:

RewriteEngine On
RewriteCond %{THE_REQUEST} \s/apih/verp_app_app/mi_proceso.pro?[\s?] [NC]
RewriteRule ^ - [E=MYENV1:1]
Header set Cross-Origin-Embedder-Policiy "unsafe-none" env=MYENV1

Última actualización