52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
# 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
|