SSO de fidelización
GuestMaker es un proveedor de identidad OpenID Connect estándar para huéspedes de fidelización. Tu sitio web se integra como Relying Party con el flujo Authorization Code y PKCE. Si tu plataforma ya admite «Iniciar sesión con Google / Apple / cualquier proveedor OIDC», es la misma integración con nuestros endpoints.
¿Prefieres empezar por el código? Guía completa del flujo para copiar y pegar, independiente del framework.
Sin cliente OIDC y con una URL de retorno que puede incluir el contexto de búsqueda del huésped.
El flujo
Authorization Code + PKCE (S256), cliente confidencial. El huésped se autentica una vez en nuestro inicio de sesión con la marca del hotel; intercambias el código en el servidor y lees datos del socio con el token de acceso.
Los tokens de acceso duran poco (~5 minutos). Repite el flujo al caducar: como la sesión persiste entre todos los establecimientos del grupo, el nuevo inicio de sesión suele ser silencioso (SSO real).
Te proporcionamos un client_id y un client_secret (se muestra una vez) por entorno. Los huéspedes se autentican en el inicio de sesión con la marca del hotel que alojamos. Recibes un código de autorización, lo intercambias por tokens en el servidor y lees los datos del socio con el token de acceso.
Todo se descubre en la URL well-known: carga siempre endpoints y claves de firma desde el descubrimiento, en lugar de fijarlos en el código, porque rotamos las claves.
id_token; el saldo e historial actuales provienen de los endpoints de recursos.| Alcance | Devuelve | Donde |
|---|---|---|
| openid | sub: the member's stable identifier. Required on every request. | id_token |
| profile | name, given_name, family_name, locale, country, updated_at | id_token |
| email (email_verified solo se emite cuando tenemos prueba de titularidad: nunca lo presupongas para socios existentes) | id_token | |
| loyalty:read | loyalty_tier, loyalty_tier_name, points_balance, member_number | id_token + GET /api/loyalty/me/balance |
| transactions:read | historial de obtención de puntos / canjes | GET /api/loyalty/me/transactions |
El saldo de crédito monetario está no disponible en v1.
/api/oidc: resuélvelas desde el descubrimiento, no desde esta lista.GET /api/oidc/.well-known/openid-configurationDiscovery: every endpoint, scope, and the JWKS URI. Load from here; don't hard-code.GET /api/oidc/authEndpoint de autorización (redirección del navegador).POST /api/oidc/tokenEndpoint de tokens (de servidor a servidor, client_secret_basic).GET /api/oidc/jwksClaves públicas de firma (RS256). Usa caché, pero actualízala ante un kid desconocido.GET /api/loyalty/me/balanceNivel del socio + saldo de puntos + valor del crédito (token de acceso Bearer).GET /api/loyalty/me/transactionsHistorial de puntos / canjes del socio (token de acceso Bearer).No hay endpoint UserInfo por diseño: el perfil y el correo electrónico llegan como declaraciones de id_token y los datos actuales del socio se sirven mediante /api/loyalty/me/*. El token de acceso es un JWT RS256 cuyo aud es nuestro indicador de recurso. Estos endpoints lo verifican y aíslan los datos por socio y cuenta.
- PKCE con S256 (nunca
plain); un nuevocode_verifierpor intento. - Envía y verifica
state(CSRF) ynonce(protección frente a reutilización); comprueba que el parámetro de respuestaisscoincide con nuestro emisor. - Verifica la firma de id_token frente a nuestras JWKS con RS256: comprueba
iss,aud = your client_id,noncey la caducidad. Nunca aceptes un token sin verificar; rechazaalg: none/ HS256. - redirect_uri debe coincidir exactamente: solo HTTPS, byte a byte, sin comodines ni variantes de barra final o mayúsculas. Registra cada valor que vayas a usar.
- Mantén
client_secreten el servidor; intercambia tokens solo desde tu backend. Usa TLS en todas las conexiones. - Guarda las JWKS en caché, pero actualízalas ante un
kiddesconocido: rotamos las claves.
Tanto access_token como id_token son JWT asimétricos RS256 que verificas frente a las JWKS publicadas. Los tokens de acceso duran unos 5 minutos.
La introspección está desactivada por diseño. Verifica la firma JWT y llama a /api/loyalty/me/*. Estos endpoints aplican una época de revocación en el servidor: cerrar sesión, bloquear, borrar datos o retirar el consentimiento invalida inmediatamente los tokens de acceso pendientes, incluso antes de que caduquen.
client_id/redirect_uri o cuando el SSO no está activado para la cuenta.| error | Significado |
|---|---|
| invalid_request | Parámetro ausente o mal formado (p. ej., sin desafío PKCE, sintaxis de permisos incorrecta). |
| invalid_client | client_id desconocido o client_secret incorrecto. Misma respuesta genérica para ambos. |
| invalid_grant | Código caducado o reutilizado, redirect_uri no coincide o code_verifier no ha superado PKCE. |
| invalid_scope | Se ha solicitado un permiso no concedido a tu cliente. |
| access_denied | El huésped ha abandonado o rechazado el inicio de sesión. |