Skip to content

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
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.

Create one client per environment, each with its own origin. In the Google Cloud console, in a project for the installation:

  1. Google Auth Platform → Branding: the app name, a support address, and the authorized domain of <app-origin>.

  2. 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.

  3. 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.

  4. 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 example https://app.example.com/api/auth/callback/google. For local development with wrangler dev, a separate client with http://localhost:8787/api/auth/callback/google.
  5. 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.com
    npx 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:

  1. Set BOOTSTRAP_TOKEN as a secret and deploy.
  2. 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 carry Origin: <app-origin>, as a same-origin fetch does.
  3. A 200 sets the session cookie. Every refusal, including a second attempt once any user exists, answers 404.
  4. Remove BOOTSTRAP_TOKEN (npx wrangler secret delete BOOTSTRAP_TOKEN --name <worker-name>).

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.