WHMCS integration mTLS

GameCloud integration requests use HMAC signatures always. In production you can additionally require a client TLS certificate.

Enable on GameCloud

INTEGRATION_MTLS_ENABLED=true

When enabled, every /api/v1/integrations/whmcs/* request must:

Pass HMAC validation (unchanged)
Present a client certificate whose SHA-256 fingerprint matches the installation record

Register client fingerprint

PUT /api/v1/integrations/whmcs/mtls/fingerprint
X-HGC-Client-Cert-Fingerprint: <optional when registering via proxy>

{
  "fingerprint": "ab12…",
  "subject": "whmcs-integration-client"
}

Or use the WHMCS addon page mTLS → Register fingerprint.

Generate fingerprint:

openssl x509 -in client.crt -outform DER | openssl dgst -sha256

Reverse proxy (recommended)

Terminate mTLS at nginx and forward the fingerprint:

ssl_verify_client optional;
proxy_set_header X-HGC-Client-Cert-Fingerprint $ssl_client_fingerprint;
proxy_set_header X-HGC-Client-Cert-Subject $ssl_client_s_dn;

See deploy/nginx/integration-mtls.conf.example.

WHMCS PHP client

In the addon module enable Use mTLS client certificate and set paths to:

Client certificate PEM
Client private key PEM
CA bundle (GameCloud or internal CA)

The PHP client sends X-HGC-Client-Cert-Fingerprint when configured.

Development

Leave INTEGRATION_MTLS_ENABLED=false (default). HMAC-only auth matches local dev workflow.

1.5 KiB Raw Blame History