Security, SSO & maintenance

The scoped Admin Proxy is the one management plane. Secrets are per-server and encrypted, SSH is off by default, and the auth engine upgrades in place with a pre-upgrade snapshot.

Tabs: Operations, Settings · Proxy: HTTPS on port 9098 (plain HTTP on 9099 for older connections)

1. Security posture

ImpulseAuth is least-privilege by default. The defining guarantees:

• Per-server secrets — every control plane gets its own Admin Proxy bearer secret, generated when it is provisioned. There is never a global one.
• Strict project scope — project-specific proxy calls must carry a service ID and project ID; strict-mode control planes reject a missing or mismatched scope with HTTP 403.
• Bootstrap-fetch — provider user-data holds only a one-time token; the full encrypted payload (bearer token, database admin credentials, SMTP credentials, DNS token, JWT secret pepper) is fetched once and the token burned.
• Encrypted storage — Admin Proxy secrets and customer BYO-SMTP, phone, and CAPTCHA credentials are stored encrypted.
• Controlled branding — hosted sign-in, consent, callback, and error pages accept controlled fields only, never arbitrary customer HTML or JavaScript.

Migrating legacy hosts

When moving older control planes onto bootstrap-fetch and strict scope, reapply them one at a time with Apply/Rebuild. Never paste full cloud-init user-data, and keep tenant identifiers out of any public issue report.

2. The Admin Proxy management plane

Every provisioning, configuration, lifecycle, security, and health action runs through each control plane’s Admin Proxy over HTTPS on port 9098 (plain HTTP on 9099 remains for older connections), bearer-authenticated with that server’s secret and firewall-restricted to your WHMCS host. WHMCS verifies the proxy’s certificate, or pins it when the box serves its own; after a deliberate certificate change, Re-pin TLS in the server’s menu trusts the new one. Project-scoped calls carry X-ImpulseAuth-Service-Id and X-ImpulseAuth-Project-Id. Operations are typed — there is no free-form shell endpoint.

Endpoint	Operation
GET /health	Liveness, database ping, and Admin Proxy capability flags.
POST /admin/v1/bootstrap/apply	Scoped config dry-run, apply, and rollback (self-updating bundle aware).
GET /admin/v1/services/status	Fixed service status.
POST /admin/v1/services/{service}/restart	Restart a fixed, named service.
GET /admin/v1/log/bootstrap	Tail the bootstrap log.
GET /admin/v1/security/status	Host patch posture for Core Security.
POST /admin/v1/security/apply-updates	Typed security update apply.
POST /admin/v1/system/reboot	Typed host reboot.
POST /admin/v1/tls/reissue	Reissue the wildcard certificate.
POST /admin/v1/gotrue/preupgrade-backup	Snapshot before an engine upgrade.

3. SSH is disabled by default

Break-glass SSH is gated behind the Enable HIGH RISK break-glass SSH toggle under Settings → General & Access → Break-Glass Access, which is off by default. When it is off, provider SSH-key injection, Proxmox snippet fallback, SSH console/rebuild fallbacks, and SSH-backed security collection/actuation are all refused — even if key material is stored.

HIGH RISK, bounded windows only

Enable SSH only for a bounded, audited rescue, then disable it again. Arbitrary shell over the Admin Proxy is forbidden; management is typed and scoped. Routine config changes go through bootstrap/apply, not an SSH rebuild.

4. Enterprise SSO & SCIM

On Pro-tier plans with an active IAUTH- license, each project can act as both an SSO consumer and an SCIM target:

• Enterprise SSO — SAML and OIDC identity providers with domain-matched sign-in, metadata and certificate health checks, and enforcement modes (mixed access, domain-required, or SSO-only). SSO health reports metadata expiry, certificate expiry, entity drift, sync state, and stale-check warnings; the sso_health_refresh cron (daily) keeps it current.
• SCIM 2.0 — Users and Groups provisioning from an upstream IdP, with a rotatable bearer token, filters, PATCH, membership changes, deprovision behaviour, and group-to-role mapping that propagates into token claims.

The project also exposes a first-party OAuth/OIDC issuer — hosted sign-in and consent, PKCE authorization-code exchange, refresh tokens, revocation, UserInfo, discovery, and JWKS — so a customer can turn a project into an identity provider for their own apps.

5. Roles, hooks & key rotation

Roles map from email domain, login provider, SSO domain, SCIM group, or a per-user override and are emitted as token claims such as app_role, app_roles, and app_permissions. Signed HTTPS auth hooks (before_user_created, custom_access_token, password_verification_attempt) carry timeout/retry settings, a generated signing secret, delivery health, and failure/recovery alerts.

Every project issues a public anon key and a privileged service-role key, both JWTs signed by the project’s own secret. JWT signing-key rotation is append-only — each rotation writes history rather than overwriting in place — and keys can be rotated by the customer from the dashboard or by the operator.

Protected projects

Mark a project protected (Customers → the project → Mark protected) when your own business depends on it — for example, the project behind your own client-area or staff sign-in. ImpulseAuth then refuses to suspend it from the Customers page, WHMCS can’t terminate it, and the day-7 purge skips it. Use Remove protection first when you really mean to retire it.

6. Security & Maintenance operations

The Operations tab has two sub-tabs, both rendered by ImpulseCore’s shared surfaces so Auth reports into the same Security & Maintenance pipeline as the rest of the stack:

• Security — host patch posture collected from each control plane via GET /admin/v1/security/status, with typed apply-updates and reboot actions. The tab distinguishes a stale proxy route from a stale on-host helper, so read-only status can recover inline.
• Maintenance — Core’s fleet-wide maintenance actions.

Mutating actions need a live path

Security updates and reboots require a current typed endpoint/helper or an explicitly enabled break-glass window. Read-only status can fall back to the provisioner’s inline probe when only an older helper is present.

7. In-place auth-engine upgrades

The authentication engine on each control plane is version-pinned and upgraded in place through the Admin Proxy — an operator-initiated lifecycle, never an automatic one. The default pin is Default GoTrue version under Settings → General & Access, with per-server overrides.

1. Set or bump the default GoTrue version in Settings.
2. On a server pinned to an older version, choose Upgrade to <version> from its menu, then Approve upgrade (or Run upgrade now). Cancel upgrade withdraws a request that hasn’t run.
3. The upstream_upgrade cron (every 5 minutes) runs approved upgrades one server at a time: the control plane first runs POST /admin/v1/gotrue/preupgrade-backup to snapshot state, the engine is redeployed and health-checked, and the previous binary is restored if the new one fails.
4. The effective version updates on the server row.

Watch the effective-version column and the activity log to confirm rollout. Upgrading the WHMCS module itself is separate: upload the new release over the existing directories and open Addons → ImpulseAuth so WHMCS runs the module’s upgrade routine. If a release needs a newer ImpulseCore than you have, update ImpulseCore first.

Blank version column?

The effective engine version is read from the security snapshot. If the column is empty, run a security status refresh from Operations.