Skip to main content

Direct login (without Cloudflare Access)

Open Artifacts logs people in through Cloudflare Access by default. Direct login is the alternative: Sign in with Google, locked to your Google Workspace domain, and emailed one-time codes for people you share artifacts with. Every Access login uses a Zero Trust seat, so direct login avoids that cost.

What you get

  • Google: anyone whose Google account belongs to your verified Workspace domain can log in. The hd claim in the ID token decides, never the email address. With AUTH_DOMAIN_JOIN=member they join as members on their first login; with invite (the default) only people you invited can.
  • Emailed codes: only for people outside your domain who were invited or have a share. They log in as guests and are read-only: they can view what is shared with them, never edit, share or write live data. Their sessions last 24 hours.
  • A trial without Google (optional): domain members can also use codes while Google is off. This needs Turnstile.

Configuration

Codes need email sending set up (EMAIL binding and EMAIL_FROM). Code requests are rate limited per IP by the RL_AUTH binding.

Setting it with setup

Pass the vars to setup as flags, and put the secrets on the Worker yourself (they never go through setup):
  • Upgrades keep them. Every setup run deploys the Worker, and a deploy replaces its vars with the rendered config. Without a flag, setup reads the value already on the deployed Worker and deploys it again, so a later --upgrade (stateless CI included) keeps your login settings. A flag replaces the value, with a note naming the old one. Values set in the Cloudflare dashboard are kept the same way.
  • Clearing one: pass it empty, e.g. --auth-domains "" or --auth-domain-join=. The var is removed and the server default applies.
  • Setup refuses before deploying an unknown provider, a malformed domain, an AUTH_DOMAIN_JOIN other than invite or member, and google without both GOOGLE_CLIENT_ID and AUTH_DOMAINS. Flags are trimmed, and provider names, the join mode and EMAIL_CODE_DOMAIN lowercased. A value already on the Worker is carried exactly as it is; one the server would read differently (padded like "member ", wrong case like Google, an empty list item, an empty AUTH_PROVIDERS, or the var held as a secret or JSON binding) is refused instead: fix it with its flag. A missing GOOGLE_CLIENT_SECRET (or TURNSTILE_SECRET with a site key) is only a warning on the deploy line; that login method stays off until you set it.
  • If setup can’t read the Worker’s settings (or they come back with no bindings), it never deploys an existing Worker, with or without --upgrade: the deploy step stops with action_required. Rerun once they are readable (the token needs Workers Scripts Read). A first install, with no Worker yet, is not affected.
  • --check reports the values it would deploy as data.signin on the deploy line.

SESSION_SECRET

Direct login keys everything it signs from SESSION_SECRET: one key per purpose (session cookies, login state, code hashes, pending-code cookies), each derived with HKDF.
  • Use at least 32 characters. Setup generates a random one. To make your own: openssl rand -base64 32.
  • Emailed codes need it. With a shorter secret, code requests answer 503 code_unavailable.
  • Shorter, older secrets (legacy). Session and login cookies keep working, signed with the raw secret as before, so nobody is logged out. Emailed codes stay off (503 code_unavailable) until you rotate it, so rotate it soon. /healthz never reports this: it is public, and naming a weak secret there would help an attacker.
  • Cookies from before the per-purpose keys (signed with the raw secret) are still accepted until 1 December 2026. After that date they are refused, and anyone still holding one logs in again once.
  • Rotating it signs everyone out and invalidates every pending code.

Setting up Google

  1. In Google Cloud, create an OAuth client of type Web application. If your users are all in one Workspace, set the consent screen’s user type to Internal: then no other Google account can use it at all.
  2. Add the redirect URI https://<your app host>/auth/callback/google.
  3. Use only the openid, email and profile scopes.
  4. Put the client id and secret in the variables above.

Switching an existing install

Existing members keep their accounts and artifacts. On their first Google login, the account with the same email address is linked to their Google account. Existing sessions keep working. To switch back, run setup with --auth-providers access (or set AUTH_PROVIDERS to access and keep it there: setup carries it forward); nothing else changes.

Security notes

  • Each install verifies Google’s ID token itself: signature, issuer, audience, expiry, its own nonce, a verified email, and hd exactly in AUTH_DOMAINS.
  • Codes are 8 digits and expire after 10 minutes. Each code request allows 5 tries, there is a per-IP failure cap, and codes are stored only as keyed hashes.
  • Asking for a code answers the same way whether or not the address can log in.
  • Code sends are capped per address and network (3 an hour, 5 a day), so someone on other networks can’t stop a person getting codes. Those caps can’t stop an attacker spread across many networks; Turnstile does. Without Turnstile, emailed codes are weaker: set TURNSTILE_SITE_KEY and TURNSTILE_SECRET if you turn codes on. Until you do, the owner sees “Login codes are on without a bot check. Add a Turnstile key so bots can’t use your email quota.” under login problems. Hosted installs refuse code login without Turnstile.
  • See the security model for the threat model.

Directory sync (Google Workspace)

On a self-hosted install, directory sync follows the connection: once an owner connects Google Workspace (Settings → Directory) and confirms it, members and groups sync from the directory. Nothing syncs before that. Code: directoryMode in apps/server/src/services/spaces.ts. The FEATURES Worker var can still name a mode, and it wins over the connection:
  • sync_frozen: keep the connection and what it synced, but stop reading groups. Synced memberships stay and admins can edit them by hand; user status is still checked.
  • sync_google: sync while connected (the same as leaving it out).

Stopping sync

To stop sync, use sync_frozen or Disconnect. Removing sync_google from FEATURES no longer stops it: with a live connection, sync resumes without asking, also on an install upgraded from a release where sync_google turned it on.
  • Freeze, keep the connection: add sync_frozen to FEATURES.
  • Stop for good: Settings → Directory → Disconnect (owner only). It revokes the Google grant, wipes the stored directory state and stops sync. Reconnecting starts over, with its own confirm.

A restored Workspace user who doesn’t come back

When you restore a deleted user in Google Workspace, the next sync brings them back with their address. If someone else now has that address on this install (for example, someone you invited after the user was deleted), sync can’t bring them back. The audit log records user.revive_blocked, with the id of the member who holds the address. To bring the Workspace user back, remove that member, then erase them (Settings → Members), and the next sync restores the Workspace user. Erasing needs the member’s personal artifacts transferred first.