Cómo se conecta una aplicación a OpenPlatform: el lanzamiento y la verificación

Cuando un usuario abre una aplicación, OpenPlatform no le envía una contraseña ni una cookie. Le envía una dirección de lanzamiento de un solo uso, y la aplicación vuelve a llamar a OpenPlatform para saber quién es el usuario. Esta página sigue el código (schemas/account.js, acción Account/run, y controllers/verify.js).

1. El lanzamiento

Cuando el usuario hace clic en una aplicación, el portal llama a la API run/{appid}. OpenPlatform:

1. comprueba que la aplicación está en la lista del usuario (si no, App not found) y que no está deshabilitada;
2. crea una sesión de la aplicación (tabla tbl_app_session) que caduca según el ajuste app_session_expire (un día por defecto);
3. construye la dirección de verificación: la url de la plataforma + /verify/?token= + el identificador de la sesión unido al identificador de la instalación con X, seguido de X y una suma de comprobación (FUNC.checksum, que usa el secreto saltchecksum);
4. deriva los dos tokens de esa sesión a partir de los secretos compartidos de la aplicación:
   • reqtoken = el MD5 de la dirección de verificación con la sal del reqtoken de la aplicación, en minúsculas;
   • restoken = el MD5 de ese reqtoken con la sal del restoken de la aplicación;

abre la aplicación en su url con un parámetro de consulta adicional: openplatform=<verification address>~<reqtoken>.

Para una aplicación marcada como marcador no hay apretón de manos: la dirección recibe ssid=<session checksum> en su lugar.

2. La verificación

La aplicación toma el valor de openplatform, que es la dirección de verificación, un ~ y el reqtoken de la sesión, y:

1. calcula su propio restoken: el MD5 del reqtoken con la sal del restoken que comparte con OpenPlatform;
2. llama con GET al valor completo de openplatform (el ~ y el reqtoken se quedan en la query string) con la cabecera x-token puesta a ese restoken.

Entonces OpenPlatform (controllers/verify.js):

1. divide el token de la consulta en el último ~ (la parte posterior es el reqtoken que envió) y rechaza la llamada cuando falta la cabecera o el token;
2. comprueba la suma de comprobación del identificador de sesión, lee la sesión y compara ambos secretos (reqtoken y el restoken de la cabecera); cualquier diferencia es Invalid token;
3. si la aplicación tiene una lista de direcciones permitidas, comprueba la dirección del llamante (Not allowed IP address);
4. lee al usuario y rechaza a un usuario deshabilitado (User has been disabled) o inactivo (User is inactive);
5. se asegura de que el usuario tiene los enlaces de notificación de esta aplicación (tabla tbl_user_app);
6. construye la respuesta y la pasa por la transformación verify de la plataforma, de modo que un despliegue pueda añadir campos.

La respuesta es un objeto JSON. Los valores vacíos se descartan. Sus campos principales son:

Campo	Qué es
id, name, email, photo, gender, reference	quién es el usuario (photo es una dirección absoluta)
language, color, interface, darkmode, sounds	las preferencias (el idioma y el color de la plataforma cuando el usuario no tiene)
sa	el usuario es administrador de la plataforma
permissions	las cadenas value de los permisos del usuario en esta aplicación
groups	los ids de los grupos del usuario
appid, ssid	la aplicación y la suma de comprobación de su sesión
openplatformid, openplatform	el identificador y la dirección de la instalación
iframe	true salvo que la aplicación sea externa
notify	la dirección a la que enviar notificaciones, cuando el usuario las acepta (notificaciones)
platform	el name y el logo de la plataforma, sus groups y las aplicaciones del usuario

La respuesta se guarda en una caché en memoria con clave el token de la sesión (la parte anterior al ~) y la caché se vacía cada dos minutos. Una llamada con un token que está en esa caché se responde desde ella, antes de volver a comparar los secretos, de modo que una verificación repetida en ese tiempo es barata.

3. Preguntar de nuevo más tarde

GET /session/ recibe el ssid que recibió la aplicación (también acepta openplatformid, token y session como nombre del parámetro), comprueba su suma de comprobación y devuelve al usuario (id, language, name, color, sa, isonline) mientras la sesión del usuario no haya caducado.

Qué recordar al construir la aplicación

• Nunca envíes los secretos compartidos al navegador: solo los necesita el servidor de la aplicación.
• Verifica en el servidor y crea tu propia sesión a partir de la respuesta; el parámetro openplatform es para un solo lanzamiento.
• Usa los permissions de la respuesta, no un rol que envíe el navegador.
• Total.js 5 tiene un cliente nativo para esta familia de protocolos: consulta OPENCLIENT.