Inicio rápido para motores de reservas
Guía para copiar y pegar que añade «Iniciar sesión en Recompensas» a un motor de reservas con el flujo Authorization Code + PKCE. Los fragmentos usan TypeScript de servidor (Node), fetch y Web Crypto; adáptalos a cualquier tecnología. Es la versión práctica de la referencia de SSO de fidelización.
- Te proporcionamos un
client_idy unclient_secret(se muestra una vez) y registramos los valores exactos deredirect_urique vayas a usar. - El emisor es
https://www.guestmaker.ai/api/oidc. Lee siempre los endpoints y las JWKS desde el descubrimiento, en lugar de fijarlos en el código: rotamos las claves. - El intercambio de tokens y la verificación de id_token se ejecutan solo en tu backend. El
client_secretnunca llega al navegador.
// Load discovery once at startup and cache it.
const ISSUER = "https://www.guestmaker.ai/api/oidc";
const disco = await fetch(`${ISSUER}/.well-known/openid-configuration`).then((r) => r.json());
// disco.authorization_endpoint, disco.token_endpoint, disco.jwks_uri, ...1 · Genera PKCE, state y nonce
Crea un nuevo code_verifier por intento y su code_challenge S256. Genera valores aleatorios de state (CSRF) y nonce (protección frente a reutilización). Guarda los tres en la sesión del huésped usando como clave state.
import { randomBytes, createHash } from "node:crypto";
const base64url = (b: Buffer) =>
b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const codeVerifier = base64url(randomBytes(32));
const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
const state = base64url(randomBytes(16));
const nonce = base64url(randomBytes(16));
// session.save({ state, nonce, codeVerifier }) // server-side, keyed by state2 · Redirige al endpoint de autorización
Solicita solo los permisos que necesitas. openid es obligatorio; añade profile email para la identidad y loyalty:read transactions:read para los datos del socio.
const authUrl = new URL(disco.authorization_endpoint);
authUrl.search = new URLSearchParams({
response_type: "code",
client_id: CLIENT_ID,
redirect_uri: REDIRECT_URI, // must byte-match a registered value
scope: "openid profile email loyalty:read transactions:read",
state,
nonce,
code_challenge: codeChallenge,
code_challenge_method: "S256",
}).toString();
// res.redirect(authUrl.toString()) // send the guest to our branded login3 · Gestiona el callback e intercambia el código
El huésped vuelve a tu redirect_uri con code, state y iss. Confirma que state coincide con la sesión y que iss coincide con nuestro emisor; después intercambia el código de un solo uso (unos 60 s) con client_secret_basic.
// In your /callback handler: q = request query
if (q.state !== session.state) throw new Error("state mismatch");
if (q.iss && q.iss !== ISSUER) throw new Error("issuer mismatch");
const basic = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
const tokens = await fetch(disco.token_endpoint, {
method: "POST",
headers: {
"Content-Type": "application/x-www-form-urlencoded",
Authorization: `Basic ${basic}`,
},
body: new URLSearchParams({
grant_type: "authorization_code",
code: q.code,
redirect_uri: REDIRECT_URI,
code_verifier: session.codeVerifier,
}),
}).then((r) => r.json());
// tokens.access_token (RS256 JWT, ~5 min), tokens.id_token4 · Verifica el id_token
Nunca confíes en un token sin verificar. Comprueba la firma frente a nuestras JWKS vinculadas a RS256, y comprueba iss, aud = your client_id, nonce y la caducidad. Usa cualquier biblioteca JOSE compatible; aquí, jose.
import { jwtVerify, createRemoteJWKSet } from "jose";
const jwks = createRemoteJWKSet(new URL(disco.jwks_uri)); // caches + refreshes on new kid
const { payload: claims } = await jwtVerify(tokens.id_token, jwks, {
algorithms: ["RS256"],
issuer: ISSUER,
audience: CLIENT_ID,
});
if (claims.nonce !== session.nonce) throw new Error("nonce mismatch");
// Identity + tier/points ride in the claims (per granted scope):
// claims.sub, claims.name, claims.email,
// claims.loyalty_tier_name, claims.points_balance, claims.member_number
// session.login({ memberId: claims.sub, accessToken: tokens.access_token })5 · Consulta datos actuales del socio
El id_token es una instantánea al iniciar sesión. Para obtener el saldo y el historial actuales, llama a los endpoints de recursos del socio con el access_token como token Bearer. Son específicos del socio: el token ya identifica al huésped, por lo que nunca pasas un correo electrónico ni un ID de socio.
const auth = { Authorization: `Bearer ${tokens.access_token}` };
const balance = await fetch(`${origin}/api/loyalty/me/balance`, { headers: auth })
.then((r) => r.json());
// { points_balance, tier, pending_balance, credit, member_number, ... }
const history = await fetch(`${origin}/api/loyalty/me/transactions?limit=20`, { headers: auth })
.then((r) => r.json());
// { transactions: [...], total, limit, offset }No hay endpoint UserInfo: profile/email/tier llegan como declaraciones de id_token; los datos actuales provienen de /api/loyalty/me/*. Access tokens last ~5 minutes; re-run the flow when one expires (the guest stays signed in with us, so it’s a silent redirect: see below).
Mantener la sesión del huésped
A guest who has signed in once stays signed in with us for 30 days, until they log out. The session is shared by every booking engine of the hotel group, OIDC or club login, and by the member portal. Send the guest to the authorize endpoint whenever you need to know who they are: if they are signed in they come straight back with a code and never see the form. Two standard parameters and a logout cover the rest.
// Silent check on page load: never shows a page.
authUrl.searchParams.set("prompt", "none");
// → back with ?code= when signed in (exchange it as in step 3)
// → back with ?error=login_required when not
// Always show the form (switch account, shared computer):
authUrl.searchParams.set("prompt", "login");
// Ask again if the sign-in is older than you accept (seconds):
authUrl.searchParams.set("max_age", "3600");
// Sign the guest out of GuestMaker too, from your own logout:
const logout = new URL(disco.end_session_endpoint);
logout.search = new URLSearchParams({
id_token_hint: tokens.id_token,
post_logout_redirect_uri: "https://book.hotel.com/", // must be registered
state,
}).toString();
// res.redirect(logout.toString())The logout signs the guest out of GuestMaker on every device and ends their access tokens. A logout from another engine or from the portal does the same, so your next silent check answers login_required. Without your logout, your own sign-out lasts until the next time you send the guest to us. When the id_token carries auth_time (it does whenever you send max_age), it is when the guest really signed in, which may be days before this request.
- Un nuevo
code_verifierpor intento; PKCE solo conS256(nuncaplain). - Verifica
state,noncey el parámetro de respuestaiss. - Verifica la firma de id_token frente a las JWKS vinculadas a
RS256; rechazaalg: none/ HS256. redirect_uridebe coincidir exactamente, con HTTPS y sin comodines ni variantes de barra final.- Mantén
client_secreten el servidor; intercambia tokens solo desde tu backend.
Los detalles completos, el modelo de tokens y el comportamiento de revocación están en la referencia de SSO de fidelización.