Integration Guide

Frontend (React/Next/Vite)

• Use OIDC Authorization Code with PKCE against Keycloak realm client (public-app, admin-app, partner-console).
• Set redirect_uri per app domain.
• Store access token in memory. For refresh, call POST /auth/refresh on auth-service which stores/rotates secure HTTP-only cookie on auth(-env).portugalodyssey.pt.
• Configure CORS to allow cross-site cookies: SameSite=None; Secure.

API Gateway

• Add Express middleware (provided under services/auth-service/src/shared/express-jwt.ts) to validate JWT from Authorization header.
• On success, set proxy headers:
• x-user-id, x-email, x-tenant-id, x-roles
• Forward only to internal services; strip authorization from logs.

Backend Services (NestJS)

• Use shared Nest guards from services/auth-service/src/shared/nest/:
• JwtAuthGuard ensures authentication
• RolesGuard('admin'|'partner'|'customer')
• TenantGuard() enforces tenant claim present and (optionally) membership check via DB

Example controller:

@UseGuards(JwtAuthGuard, RolesGuard('admin')) @Get('/tenants/:id') findTenant() { ... }

Messaging (RabbitMQ)

• When emitting events, include user context metadata:
• user_id, tenant_id, roles, trace_id

WebSockets

• Validate JWT on connection (Authorization: Bearer ... in query/header).
• Create per-user rooms keyed by sub and optional tenant_id.

Keycloak

• Configure realm portugal-odyssey, clients, and protocol mappers:
• tenant_id (single string)
• tenant_ids (JSON array)
• Map realm roles to token via default mappers
• Enable Password Policies and 2FA (OTP/WebAuthn) in realm settings.
• Configure Social IdPs: Google, Facebook (client id/secret, redirect URI provided by Keycloak)