Enable social login and the captcha

Both social login and the captcha are off by default. Each is enabled purely by configuration — there is no database table, no migration and no license to apply (both are available in the Community edition, see ADR 0064).

Note

Every secret below is resolved env-first, then from the supacloud/app OpenBao map (see ADR 0036 — consolidated secret provisioning). Prefer the vault in production; the value never enters a config struct or a log line.

Enable social login

SupaCloud ships Google and GitHub. A provider appears on the sign-in page only once both its client id and client secret resolve — otherwise the button is simply absent, so you can never present a button that cannot work.

1. Register an OAuth application with the provider

Create an OAuth app at the provider and set its authorized redirect URI to:

<your public URL>/api/auth/social/google/callback
<your public URL>/api/auth/social/github/callback

<your public URL> is exactly the SUPACLOUD_PUBLIC_URL your instance serves on (no trailing slash). Requested scopes are openid email profile (Google) and the user + email scopes (GitHub) — enough to read a verified email address, nothing more.

Caution

SupaCloud requires a verified address: Google must assert email_verified, and GitHub’s address must be the account’s primary and verified email. A provider that cannot prove the address is rejected.

2. Configure the credentials

Variable	Purpose
SUPACLOUD_SOCIAL_GOOGLE_CLIENT_ID	Google OAuth client id
SUPACLOUD_SOCIAL_GOOGLE_CLIENT_SECRET	Google OAuth client secret (vault-able)
SUPACLOUD_SOCIAL_GITHUB_CLIENT_ID	GitHub OAuth client id
SUPACLOUD_SOCIAL_GITHUB_CLIENT_SECRET	GitHub OAuth client secret (vault-able)

Restart the server. The sign-in page now shows a button per configured provider, and GET /config advertises the enabled methods.

3. What your users will experience

• A new email address creates an account, exactly like a normal signup (pending workspace invitations for that address are claimed).
• An email that already belongs to an account is never auto-merged. The user is told an account exists and must sign in with their existing method, then link the provider from Settings → Connected accounts.
• A user with an authenticator app still completes their second factor after the provider redirect. Their 2FA belongs to SupaCloud, not to the provider.
• A user can never disconnect their last remaining sign-in method.

Enable the captcha

SupaCloud uses ALTCHA, a self-hosted proof-of-work challenge. The browser solves it with WebCrypto; the server verifies it statelessly against an HMAC-signed challenge. There is no third-party script and no third-party network call — no visitor data leaves your instance.

Setting the HMAC secret turns the feature on; everything else is optional.

Variable	Default	Purpose
SUPACLOUD_CAPTCHA_HMAC_SECRET	(unset — captcha off)	Signs and verifies challenges. Set this to enable.
SUPACLOUD_CAPTCHA_MAXNUMBER	built-in	Proof-of-work difficulty (search space). Raise to slow bots; it also slows real browsers.
SUPACLOUD_CAPTCHA_TTL_SECS	built-in	How long a challenge stays valid.
SUPACLOUD_CAPTCHA_LOGIN_FAILURE_THRESHOLD	built-in	Failed sign-ins from one source before the sign-in form arms a captcha.

Where it arms. register, magic-link request, password-reset request and email-verification request always require a solution. Sign-in arms it only after LOGIN_FAILURE_THRESHOLD failed attempts from the same source, so a normal sign-in never shows one.

Fail-closed and single-use

With the secret set the gate is fail-closed — a missing or invalid solution is rejected. Each solved challenge is single-use; a consumed solution cannot be replayed, not even in the final second of its lifetime.

The check needs a secure (HTTPS) context. On a plain http:// origin the browser exposes no crypto.subtle, and the UI says so explicitly instead of offering a retry that can never succeed. Serve over HTTPS.

Tune the rate limits

Two independent limits protect the authentication endpoints:

• The existing per-IP transport limit (tower_governor).
• A per-identity fixed window (5 / 60 s) on login, register, magic, reset and verify — because a per-IP limit cannot stop a distributed credential-stuffing campaign against a single account.

The sign-in limit is additionally scoped by source, so someone who merely knows a victim’s email address cannot exhaust the shared window and lock the legitimate owner out. The mail-sending endpoints stay keyed purely by email, where the throttle meters outbound mail.

Running behind a reverse proxy

Danger

The security counters ignore CF-Connecting-IP and X-Real-IP unless you declare the deployment proxy-fronted. Set SUPACLOUD_TRUSTED_FORWARDING only when a proxy you control overwrites the forwarding headers on every inbound request. Otherwise an attacker can rotate a header value per request and hold the captcha permanently disarmed.

With SUPACLOUD_TRUSTED_FORWARDING set, the client IP is derived from X-Forwarded-For by the same right-to-left, skip-trusted-hops walk used elsewhere; if no trustworthy address can be derived, the raw socket peer is used.

Verify

1. Open the sign-in page in a private window. Each configured provider shows a button.

2. Sign in with the provider using an address that is new to the instance — an account is created and you land signed in.

3. Sign out, then try the same provider with an address that already has a password account: you are told an account exists, and are not signed in.

4. If you enabled the captcha, submit the sign-in form with a wrong password LOGIN_FAILURE_THRESHOLD times — the verification step appears.

Related

• Sign in with Google or GitHub — the end-user view
• Configure OIDC SSO — enterprise single sign-on (a different mechanism)