63 lines
1.5 KiB
Markdown
63 lines
1.5 KiB
Markdown
# WHMCS integration mTLS
|
|
|
|
GameCloud integration requests use **HMAC signatures** always. In production you can additionally require a **client TLS certificate**.
|
|
|
|
## Enable on GameCloud
|
|
|
|
```env
|
|
INTEGRATION_MTLS_ENABLED=true
|
|
```
|
|
|
|
When enabled, every `/api/v1/integrations/whmcs/*` request must:
|
|
|
|
1. Pass HMAC validation (unchanged)
|
|
2. Present a client certificate whose SHA-256 fingerprint matches the installation record
|
|
|
|
## Register client fingerprint
|
|
|
|
```http
|
|
PUT /api/v1/integrations/whmcs/mtls/fingerprint
|
|
X-HGC-Client-Cert-Fingerprint: <optional when registering via proxy>
|
|
```
|
|
|
|
```json
|
|
{
|
|
"fingerprint": "ab12…",
|
|
"subject": "whmcs-integration-client"
|
|
}
|
|
```
|
|
|
|
Or use the WHMCS addon page **mTLS → Register fingerprint**.
|
|
|
|
Generate fingerprint:
|
|
|
|
```bash
|
|
openssl x509 -in client.crt -outform DER | openssl dgst -sha256
|
|
```
|
|
|
|
## Reverse proxy (recommended)
|
|
|
|
Terminate mTLS at nginx and forward the fingerprint:
|
|
|
|
```nginx
|
|
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.
|