HexaHost-GameCloud/docs/integrations/whmcs/sso.md

WHMCS single sign-on (Phase D)

HexaHost GameCloud uses one-time SSO tickets to bridge WHMCS and the customer panel without long-lived tokens in URLs.

Flow

1. WHMCS calls ServiceSingleSignOn or AdminSingleSignOn in the server module.
2. The module requests POST /api/v1/integrations/whmcs/services/:externalServiceId/sso.
3. GameCloud stores a hashed ticket (60s TTL, single use) and returns redirectUrl.
4. WHMCS redirects the browser to {APP_URL}/auth/sso?ticket=....
5. The web app calls POST /api/v1/integrations/whmcs/auth/sso/consume — actually /auth/sso/consume.
6. GameCloud sets a normal HTTP-only session cookie and returns an allowlisted redirectPath.

Ticket properties

Stored server-side (hashed):

• GameCloud user and server IDs
• WHMCS installation, client, user, and service IDs
• Target path (allowlisted)
• Issuer (integrationId) and audience (APP_URL)
• Nonce (replay protection at ticket layer)

Admin SSO / impersonation

kind=admin creates an impersonation session:

• UserSession.isImpersonation = true
• Metadata includes WHMCS admin user reference
• Full audit events: whmcs.sso.admin_created, whmcs.sso.admin_consumed
• Panel shows an amber support banner

Allowlisted redirect paths

• /dashboard
• /servers
• /servers/{serverId}
• /servers/{serverId}/{console|files|properties|players|worlds|backups|addons}

Arbitrary external URLs are rejected.

WHMCS configuration

Server module hostname must match APP_URL origin used for ticket audience validation.

Security notes

• Tickets expire after 60 seconds
• Each ticket is single-use
• Only the WHMCS integration API (HMAC) can mint tickets
• Suspended or terminated services cannot obtain SSO tickets