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
hdclaim in the ID token decides, never the email address. WithAUTH_DOMAIN_JOIN=memberthey join as members on their first login; withinvite(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_JOINother thaninviteormember, andgooglewithout bothGOOGLE_CLIENT_IDandAUTH_DOMAINS. Flags are trimmed, and provider names, the join mode andEMAIL_CODE_DOMAINlowercased. A value already on the Worker is carried exactly as it is; one the server would read differently (padded like"member ", wrong case likeGoogle, an empty list item, an emptyAUTH_PROVIDERS, or the var held as a secret or JSON binding) is refused instead: fix it with its flag. A missingGOOGLE_CLIENT_SECRET(orTURNSTILE_SECRETwith a site key) is only a warning on thedeployline; 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 withaction_required. Rerun once they are readable (the token needs Workers Scripts Read). A first install, with no Worker yet, is not affected. --checkreports the values it would deploy asdata.signinon thedeployline.
SESSION_SECRET
Direct login keys everything it signs fromSESSION_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./healthznever 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
- 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.
- Add the redirect URI
https://<your app host>/auth/callback/google. - Use only the
openid,emailandprofilescopes. - 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
hdexactly inAUTH_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_KEYandTURNSTILE_SECRETif 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, usesync_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_frozentoFEATURES. - 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 recordsuser.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.