Security

Guardhouse provides identity and authorization building blocks. Your organization remains responsible for choosing safe policies, validating tokens in every API, protecting credentials, and operating its applications securely.

Protect administrative access

• Grant System Access only to named administrators.
• Require MFA for privileged users and issue recovery codes through an approved process.
• Keep at least two recoverable administrator accounts.
• Review administrator and high-privilege role membership regularly.
• Block accounts promptly when access must stop.
• Review user activity after email changes, MFA resets, recovery events, and unexpected logins.

Application roles do not replace System Access controls, and System Access must not be used as an application permission.

Use the correct OAuth client

• Use an SPA client with Authorization Code and PKCE for browser applications.
• Use a Native client with Authorization Code and PKCE for installed applications.
• Use a Service client with Client Credentials for service-to-service access.
• Create separate clients for separate applications and environments.
• Never give a browser or mobile application a confidential client secret.

Do not select a weaker client model to avoid configuring redirects or PKCE.

Protect and rotate secrets

Client, resource-introspection, webhook, and provider secrets are confidential.

• Copy one-time secrets directly into an approved secret store.
• Never commit them to source control or include them in a container image.
• Do not place them in browser code, mobile packages, analytics, URLs, or logs.
• Restrict access to the runtime and operators that need the secret.
• Record an owner and rotation procedure.
• Rotate immediately after suspected disclosure.

Test rotation before an incident. A rotation is incomplete until every authorized caller uses the replacement and the old credential no longer works.

Constrain redirects and browser origins

• Register exact HTTPS redirect and post-logout URIs for production.
• Keep localhost entries in development clients.
• Permit only the exact browser origins that need access.
• Remove obsolete callback URLs after a migration.

CORS controls whether a browser may read a response. It does not authenticate the caller or authorize an API operation.

Validate every access token

An API accepting a JWT must validate:

• the cryptographic signature and allowed algorithm;
• issuer;
• audience;
• expiry and not-before time;
• the scopes and user authorization required by the endpoint.

Load the issuer and JWKS values shown for the Guardhouse resource. Do not decode a token and trust its claims without validation.

When using introspection, keep the resource credentials on the API backend, protect the connection to Guardhouse, and deny access when a token is inactive or the validation result cannot be trusted.

Limit token exposure

• Keep access-token lifetimes no longer than the application needs.
• Enable refresh tokens only for clients with a defined storage and revocation strategy.
• Never log complete access, ID, or refresh tokens.
• Revoke affected access where the supported flow permits it.
• Rotate the underlying client credential if a service credential is exposed.

Treat every access token as a bearer credential: possession can be enough to call an API until the token expires or is rejected.

Harden user authentication

• Choose invite-only signup when public registration is not required.
• Verify email-delivery and account-recovery paths.
• Require MFA for privileged or sensitive access.
• Test backup-code and administrator-reset procedures.
• Use HTTPS and a stable domain for passkeys.
• Preserve at least one tested login method while changing authentication policy.

An administrator MFA reset is a sensitive recovery event. Verify the user through an approved channel and review the event afterward.

Protect providers, webhooks, and customization

• Give storage and email providers dedicated least-privilege credentials.
• Verify webhook signatures using the received request body and the documented algorithm.
• Reject malformed or unverifiable webhook deliveries.
• Make event processing idempotent because a delivery can be retried.
• Add only trusted HTML and CSS to hosted pages.
• Do not place secrets or personal data in branding content.

See Providers and webhooks for the supported configuration workflow.

Harden a self-hosted deployment

Self-hosted operators must also:

• terminate TLS at a trusted reverse proxy or ingress;
• trust forwarded headers only from known proxies and networks;
• protect data stores and caches from public access;
• back up persistent application state and cryptographic key material;
• load sensitive configuration from an approved secret store;
• run the application with a least-privilege identity;
• monitor application, proxy, data-service, and certificate health;
• keep sensitive request content and personal data out of telemetry;
• test upgrades and schema changes before production rollout.

An application health response does not prove that every data service, storage provider, email provider, or webhook destination is healthy. Monitor critical dependencies and authentication flows separately.

Respond to an incident

1. Identify the affected user, client, resource, provider, or webhook.
2. Block the affected user or rotate the affected secret.
3. Revoke sessions or tokens through the supported controls where applicable.
4. Inspect user activity and webhook/provider logs.
5. Confirm issuer, audience, redirect, and authorization settings have not changed unexpectedly.
6. Restore service with replacement credentials.
7. Document scope, timeline, recovery actions, and follow-up controls.

For deployment ownership, see Guardhouse Cloud and self-hosted deployments.