Setting up sign-in
How to turn on dashboard sign-in for an installation on the Cloudflare target: email one-time codes and Google (ADR 0040). Sign-in is served under /api/auth/* by the api Worker. Until its settings are complete, every auth route answers 500 and logs the missing setting by name; the API is not affected.
Every value in angle brackets is a placeholder. Never commit real values: secrets, client IDs, and addresses stay in your Worker’s secrets.
| Placeholder | Meaning |
|---|---|
<app-origin> |
The Worker’s public origin (APP_ORIGIN), for example https://app.example.com |
<worker-name> |
The name of your deployed Worker |
Settings
Section titled “Settings”| Setting | Kind | Value |
|---|---|---|
BETTER_AUTH_SECRET |
secret, required | At least 32 random characters, for example openssl rand -base64 48. It signs the session cookies and keys the HMACs of sign-in codes, of their identifiers, and of the rate-limit keys. Rotating it signs every user out, voids codes in flight, and resets the rate limits. |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
secrets, both or neither | Google’s OAuth client (below). Without them, Google sign-in is not offered. |
ALLOWED_EMAILS |
variable or secret | Comma-separated addresses that may sign in. A self-hosted installation needs it or ADMIN_EMAILS; it is checked at every sign-in, and an address removed from it loses its sessions on its next request. A value with no address (such as ,) is a configuration error. |
SIGN_IN_OPEN |
secret, managed service only | true lets any address sign in. The managed service needs it or ALLOWED_EMAILS, not both; with neither, sign-in is closed. Set it with npx wrangler secret put SIGN_IN_OPEN --name <worker-name>: the managed service’s rendered configuration has no such variable, so one set in the dashboard is dropped by the next deploy. |
ADMIN_EMAILS |
variable | Self-hosted: addresses that may sign in and that approve sends (ADR 0033). Their users are installation admins: admin of every workspace, made so when a workspace is created and at each of their sign-ins, and no workspace admin can demote or remove them (ADR 0041’s amendment). A user already signed in when their address is added becomes admin at their next sign-in: sign out and in again. To take an address’s access away, remove it from both ADMIN_EMAILS and ALLOWED_EMAILS; its memberships stay as ordinary ones, which each workspace’s admins can then change or remove. If its user was a workspace’s only admin, list another address and sign in with it. A value with no address (such as ,) is a configuration error. |
BOOTSTRAP_TOKEN |
secret, temporary | Self-hosted: cl_boot_ and 32 to 128 letters, digits, _ or -. It creates the first user before system mail works (below). Remove it afterwards. |
SYSTEM_MAIL, SYSTEM_MAIL_FROM |
binding and variable | Where sign-in codes are mailed from (ADR 0029). Without them, a code request still answers success, mails nothing, and logs SYSTEM_MAIL_not_configured. |
The Worker also needs the nodejs_als compatibility flag and the daily cron trigger of apps/workers/wrangler.jsonc, which deletes expired sessions, codes, and rate-limit rows.
Apply the control-plane migrations, which include the sign-in tables of 0005_auth.sql, before deploying the Worker that serves sign-in: npx wrangler d1 migrations apply CONTROL_DB --remote from apps/workers (with --config for an environment’s configuration). Locally, pnpm dev:setup applies them.
Session cookies are named __Host-cl_session and are Secure, so APP_ORIGIN should be https:. On http://localhost, Chrome and Firefox treat the origin as secure and accept them; Safari may refuse them.
Google OAuth client
Section titled “Google OAuth client”Create one client per environment, each with its own origin. In the Google Cloud console, in a project for the installation:
-
Google Auth Platform → Branding: the app name, a support address, and the authorized domain of
<app-origin>. -
Audience: user type External. Publish the app (In production); while it is in testing, only listed test users can sign in. The scopes below are not sensitive, so publishing should need no scope verification, but Google may still ask to verify the branding (the app name, logo, and domain) before the consent screen shows it.
-
Data Access: the scopes
openid,.../auth/userinfo.email, and.../auth/userinfo.profile. No other scope: the installation calls no Google API and keeps none of Google’s tokens. -
Clients → Create client: application type Web application.
- Authorized JavaScript origins: none are needed (the browser never calls Google from script).
- Authorized redirect URIs: exactly
<app-origin>/api/auth/callback/google, for examplehttps://app.example.com/api/auth/callback/google. For local development withwrangler dev, a separate client withhttp://localhost:8787/api/auth/callback/google.
-
Copy the client ID and secret into the Worker’s secrets, prompted so they stay out of the shell history:
Terminal window npx wrangler secret put GOOGLE_CLIENT_ID --name <worker-name> # <client-id>.apps.googleusercontent.comnpx wrangler secret put GOOGLE_CLIENT_SECRET --name <worker-name>
A Google address that Google reports unverified creates no user. A verified Google address is linked to an existing user of the same address, whose address was verified by a code.
The first user of a self-hosted installation
Section titled “The first user of a self-hosted installation”With system mail configured, the first user signs in with a code like anyone listed in ALLOWED_EMAILS or ADMIN_EMAILS. Without it, use the bootstrap route once:
- Set
BOOTSTRAP_TOKENas a secret and deploy. - From the browser you will use, on a page of
<app-origin>, post{ "token": "<token>", "email": "<your address>" }as JSON to/api/auth/bootstrap. The address must be listed. The request must carryOrigin: <app-origin>, as a same-originfetchdoes. - A 200 sets the session cookie. Every refusal, including a second attempt once any user exists, answers 404.
- Remove
BOOTSTRAP_TOKEN(npx wrangler secret delete BOOTSTRAP_TOKEN --name <worker-name>).
Behind a proxy
Section titled “Behind a proxy”On Workers the client IP comes from cf-connecting-ip. Each auth request needs a usable client IP for its rate limits; a request without one is refused with a log line naming CLIENT_IP_HEADER, the setting with which a container installation names its proxy’s header.