PW Portal Prowinch Guía de integración
Ver checklist ↓

Documento técnico · Colombia

Integración React con Portal Prowinch

Guía para implementar un acceso seguro y transparente desde la intranet de Colombia, sin exponer el correo del empleado ni el secreto de firma en el navegador.

React Node / Express Ticket HMAC PHP central
01

Objetivo y flujo correcto

El empleado abre el Portal Prowinch desde la intranet React de Colombia sin iniciar sesión por segunda vez.

Regla principal React no envía el correo. El backend de Colombia lo obtiene de la sesión autenticada y entrega al navegador únicamente una URL temporal firmada.
Paso 1El usuario inicia sesión en Colombia.
Paso 2React llama al endpoint protegido.
Paso 3Node toma el correo de request.user.
Paso 4El backend genera un ticket firmado.
Paso 5El portal valida el ticket y abre la sesión.
02

Usuario autenticado

El middleware de autenticación debe dejar disponibles los datos del empleado en el servidor.

Objeto esperado
request.user = {
  id: 74,
  email: 'usuario@prowinch.com',
  name: 'Nombre del empleado'
};

email · obligatorio

Correo corporativo que identifica al empleado en el portal central.

id · obligatorio

ID numérico estable del empleado en la intranet de Colombia.

name · recomendado

Nombre visible del empleado para trazabilidad y presentación.

canViewReceivables · opcional

Permiso booleano para habilitar acceso al módulo de cuentas por cobrar.

Si Colombia usa nombres de campos diferentes

Mapeo de campos
function currentEmployee(request) {
  const source = request.user;

  return {
    email: source.UsuEmail,
    name: source.UsuNombre,
    legacyUserId: Number(source.UsuCod),
    showReceivables: source.canViewReceivables === true,
  };
}
03

Endpoint del backend Colombia

La ruta debe ejecutarse después de los middleware de sesión y autenticación existentes.

Node / Express
function currentEmployee(request) {
  const user = request.user;

  if (!user) {
    throw new Error('Usuario no autenticado');
  }

  const email = String(user.email || '').trim().toLowerCase();
  const legacyUserId = Number(user.id);

  if (!email) {
    throw new Error('El usuario autenticado no tiene correo');
  }

  if (!Number.isInteger(legacyUserId)) {
    throw new Error('El usuario no tiene un ID válido');
  }

  return {
    email,
    name: user.name || '',
    legacyUserId,
    showReceivables: user.canViewReceivables === true,
  };
}

app.get(
  '/api/employee-portal/embed-url',
  requireAuth,
  (request, response) => {
    try {
      const employee = currentEmployee(request);
      const url = createColombiaPortalEmbedUrl({
        employee,
        parentOrigin: process.env.PROWINCH_PORTAL_PARENT_ORIGIN,
      });

      response.json({ ok: true, url });
    } catch (error) {
      response.status(401).json({
        ok: false,
        message: error.message,
      });
    }
  }
);

Orden de montaje

Express
app.use(sessionMiddleware);
app.use(authenticationMiddleware);
app.use(employeePortalRouter);
04

Configuración del origen

Ambos servidores deben usar exactamente el mismo origen público de la aplicación React.

Backend Colombia

PROWINCH_PORTAL_PARENT_ORIGIN=https://web-intranet-co-dev.azurewebsites.net

Portal central

PORTAL_EMBED_COLOMBIA_ORIGINS=https://web-intranet-co-dev.azurewebsites.net

Formato correcto Usar solamente protocolo, dominio y puerto opcional. Aunque React use rutas con /#/, el hash no forma parte del origen.
No usar Barra final, rutas, /#/, parámetros o nombres de páginas dentro del valor del origen.
05

Frontend React

React solicita una URL nueva al montar el componente y la utiliza como dirección del iframe.

Solicitud autenticada
async function getPortalUrl() {
  const response = await fetch('/api/employee-portal/embed-url', {
    method: 'GET',
    credentials: 'include',
    headers: {
      Accept: 'application/json',
    },
  });

  const result = await response.json();

  if (!response.ok || !result.ok || !result.url) {
    throw new Error(
      result.message || 'No fue posible abrir el Portal Prowinch'
    );
  }

  return result.url;
}

Respuesta esperada

JSON
{
  "ok": true,
  "url": "https://prowinch.us/intranet/portal-embed.php?ticket=..."
}

El correo no aparece directamente en la respuesta: queda protegido dentro del ticket firmado y temporal. La URL no debe guardarse en localStorage, una base de datos ni estados persistentes.

06

Validación en el portal central

Después de validar la firma y consumir el ticket, el portal crea su propia sesión con el correo firmado.

PHP central
$_SESSION['glocodusu'] = strtolower(
    trim((string) $claims['sub'])
);
  • El correo debe existir como empleado activo en el Portal Prowinch.
  • También puede existir como alias autorizado del empleado.
  • El correo se normaliza en minúsculas y sin espacios exteriores.
07

Reglas de seguridad

La identidad siempre debe provenir de una sesión o token previamente validado por el backend.

Prohibido No enviar ?email=usuario@prowinch.com ni incluir un correo elegido por el navegador en el cuerpo de la solicitud. Esto permitiría intentos de suplantación.
  • Obtener el correo exclusivamente de request.user.
  • Proteger el endpoint con el middleware requireAuth.
  • Utilizar HTTPS en la intranet y en el portal.
  • Mantener el secreto de firma únicamente en los servidores.
  • No exponer el secreto en variables VITE_* o REACT_APP_*.
  • No imprimir el ticket completo ni los secretos en logs.
  • Crear tickets de corta duración y uso único.
08

Diagnóstico

Este log temporal comprueba la identidad sin revelar credenciales ni el ticket.

Log seguro
console.log('Portal integration user:', {
  authenticated: Boolean(request.user),
  emailPresent: Boolean(request.user?.email),
  userId: request.user?.id,
});

El endpoint responde 401

Revisar requireAuth, credentials: 'include', la existencia de request.user y que tenga correo e ID.

El portal no reconoce al empleado

Confirmar que el correo exista y esté activo en employees o employee_aliases.

El iframe es rechazado

Comparar los orígenes exactos y revisar CSP, especialmente la directiva frame-ancestors.

El endpoint responde correctamente

El backend ya recibió un correo e ID válidos. Continuar la revisión en la validación central del usuario.

09

Checklist de entrega

La integración está lista cuando todos estos puntos han sido verificados.

  • El middleware deja al usuario autenticado en request.user.
  • currentEmployee() devuelve correo, nombre e ID numérico correctos.
  • La ruta /api/employee-portal/embed-url está protegida.
  • El origen está configurado sin barra final, rutas ni /#/.
  • React utiliza credentials: 'include'.
  • React recibe solamente la URL firmada y temporal.
  • El correo identifica a un empleado activo o alias en el portal central.
  • No hay secretos ni tickets completos en el frontend o en los logs.
Resumen para el desarrollador El correo no se envía desde React. Node/Express lo obtiene de request.user, genera una URL firmada y React usa únicamente esa URL para cargar el portal.