Guía de Integración SSO JWT
Se prefiere SSO con JWT por su menor complejidad. La empresa firma un JWT de un solo uso con el secreto compartido, redirige al usuario al endpoint de Nume, y Nume crea o reactiva la cuenta e inicia sesión.
Integración preferida
Flujo
Empresa
1. Portal
Usuario autenticado
Empresa
2. Firma JWT
Con el secreto compartido
Empresa
3. Redirect
/integrations/sso/…?token=…
Nume
4. Login en Nume
Valida, crea o reactiva e inicia sesión
- El usuario está autenticado en el portal de la empresa.
- La empresa firma un JWT con los datos del usuario, un
jtiúnico y el secreto compartido. - Redirige el browser a Nume con ese JWT en la query.
- Nume valida el JWT, rechaza un
jtiya utilizado, crea el usuario si no existe (o lo reactiva si estaba desactivado), inicia sesión y redirige a la app.
Requisitos previos
Antes de usar este flujo, Nume les entrega:
- API host — base URL de la API de Nume (prod o testing)
- Integration UUID — identifica la integración en la URL
- JWT secret — clave compartida para firmar el JWT (algoritmo HS256)
Endpoint
Método GET. La empresa debe redirigir el browser del usuario a esta URL (no es una llamada server-to-server).
Producción:
GET https://api.nuevometodo.com/integrations/sso/{integrationUuid}?token={jwt}Ruta:
GET /integrations/sso/{integrationUuid}?token={jwt}Claims del JWT
Algoritmo HS256. El secret es el valor entregado por Nume.
Campos requeridos
| Campo | Tipo | Descripción |
|---|---|---|
email o external_id | string | Al menos uno de los dos. Si se envían juntos, se reutiliza la cuenta de esta integración que ya coincida con el email o con el external_id; si esa cuenta se había creado solo con external_id, se le asigna el email. Si no existe ninguna, se crea la cuenta con el email y se guarda el external_id. El acceso se rechaza si cada uno pertenece a un usuario distinto, si la cuenta del email ya tiene otro external_id, si el external_id ya está en una cuenta con otro email o si el email pertenece a otra empresa. |
iat | number | Unix timestamp (segundos) de emisión. El token se rechaza si tiene más de 5 minutos de antigüedad. |
jti | string | Identificador único del token. Cada JWT es de un solo uso; un jti ya utilizado se rechaza. |
Campos opcionales
| Campo | Tipo | Descripción |
|---|---|---|
full_name | string | Nombre completo del usuario |
data.first_name | string | Nombre |
data.last_name | string | Apellido |
data.dni | string | Documento |
data.date_of_birth | string | Fecha ISO 8601 UTC, ej. "1995-07-21T00:00:00.000Z" |
data.country | string | País, ej. "Argentina" |
data.gender | string | "M" o "F" |
data.dial_code | string | Código de país, ej. "+54" |
data.phone_number | string | Teléfono sin código de país |
exp | number | Opcional. Si se envía, Nume lo ignora. |
Ejemplo de payload
Con email y datos de perfil:
{
"email": "usuario@ejemplo.com",
"full_name": "Juan Pérez",
"jti": "3f1c0a8e-2b9d-4c7a-9e11-5a6b7c8d9e00",
"iat": 1710000000,
"data": {
"first_name": "Juan",
"last_name": "Pérez",
"dni": "12345678",
"date_of_birth": "1995-07-21T00:00:00.000Z",
"country": "Argentina",
"gender": "M",
"dial_code": "+54",
"phone_number": "1123456789"
}
}Mínimo con external_id:
{
"external_id": "USR-12345-ABC",
"jti": "7b2e91c4-0d55-4a18-8f3c-1d9a2b4c6e70",
"iat": 1710000000
}Ejemplo de código (Node.js)
Importante
const { randomUUID } = require('crypto');
const express = require('express');
const jwt = require('jsonwebtoken');
const app = express();
const secret = process.env.NUME_SSO_JWT_SECRET; // secreto entregado por Nume
const integrationUuid = process.env.NUME_INTEGRATION_UUID; // integration UUID entregado por Nume
const apiBaseUrl = process.env.NUME_API_BASE_URL; // host de la API de Nume
app.get('/entrar-a-nume', (req, res) => {
const token = jwt.sign(
{
email: 'usuario@ejemplo.com',
full_name: 'Juan Pérez',
// iat lo agrega jsonwebtoken automáticamente
},
secret,
{ algorithm: 'HS256', jwtid: randomUUID() },
);
const url =
`${apiBaseUrl}/integrations/sso/${integrationUuid}` +
`?token=${encodeURIComponent(token)}`;
res.redirect(url);
});
app.listen(3000);Errores comunes
Si el acceso falla, Nume redirige al usuario a una pantalla de error genérica (código en la URL). Códigos posibles:
| Código | Causa típica |
|---|---|
invalid_request | El JWT no incluye email ni external_id, el UUID de la integración no es válido, o email y external_id no corresponden al mismo usuario |
invalid_token | JWT inválido, firma incorrecta, sin iat o con un jti ya utilizado |
missing_jti | JWT sin el claim jti |
token_expired | iat con más de 5 minutos de antigüedad |
forbidden | Integración inactiva, empresa inactiva, empresa eliminada o email que pertenece a otra empresa |
email_in_use | El email ya está en otra cuenta |
admin_account | El email ya está en una cuenta de administración |
not_found | Integration UUID inexistente |
unexpected | Error inesperado al procesar el acceso |
Notas
- Si el usuario no existe, Nume lo crea.
- Si existía pero estaba desactivado, Nume lo reactiva al entrar por SSO.
- Cada JWT es de un solo uso. El claim
jtino puede repetirse. - Si el JWT trae solo
external_id, Nume usa un email sintético interno basado en ese id. Si trae los dos, Nume entra a la cuenta que ya coincida con cualquiera de ellos y, si esa cuenta usaba el email sintético, le asigna el email real. El acceso se rechaza si los dos identificadores no corresponden al mismo usuario o si el email pertenece a otra empresa. - Cuando no es posible utilizar SSO, corresponde el flujo por API key:
POST /integrations/token.
Implementación con iframe (flujo embebido / nativo)
Si preferís no sacar al usuario de tu portal (o lo mostrás dentro de una app nativa con WebView), podés apuntar un iframe / WebView al mismo endpoint de tu backend que firma el JWT y hace el redirect (por ejemplo /entrar-a-nume).
Importante
Firmá el JWT siempre en tu backend. No expongas el secret en el frontend ni en la app.
Sin el atributo allow correcto no funcionan las llamadas con los médicos (cámara, micrófono y captura de pantalla).
El iframe carga tu endpoint; ese endpoint redirige a Nume
<iframe
title="Nume"
src="/entrar-a-nume"
style="width: 100%; height: 100%; border: 0;"
allow="camera *; microphone *; autoplay *; display-capture *; clipboard-read *; clipboard-write *"
allowfullscreen
></iframe>Los permisos de cámara y micrófono para mostrar Nume dentro de una app están en Apps móviles.