# Signing in, two-factor authentication and security keys

How a person gets into Bucker, and what the second factor is. Organization-wide rules —
"this org requires SSO", "this org requires MFA" — are per organization: SSO is described
in [sso-and-scim.md](sso-and-scim.md), and the MFA requirement at the end of this page.

## Signing in with GitHub or Google

Where the deployment offers it, the sign-in and sign-up pages show **Continue with
GitHub** and **Continue with Google**. A provider that is not configured shows no button
at all.

- **A new account** is created the first time you sign in with a provider, from the
  provider's **verified** email address. An address the provider has not verified is
  refused. Registration closure (`ALLOW_SELF_SERVE_REGISTRATION=false`) applies exactly as
  it does to the password form.
- **An existing account is never taken over by email.** If any of the provider's verified
  addresses already belongs to a Bucker account, the sign-in is refused with "sign in with
  your password, then connect the provider from account settings". Signing in with GitHub
  can only ever reach an account that GitHub was explicitly connected to.
- **Connecting** a provider to an account you already have is done from **Settings →
  General → Account security → Connected sign-in accounts**: you confirm your password,
  approve the connection at the provider, and it is attached only if one of that
  provider account's **verified** addresses is your Bucker account's address. One account
  per provider. **Disconnecting** takes your password too.
- **Your two-factor authentication still applies.** GitHub or Google replaces the
  password step; if your account has two-factor authentication on, you are asked for the
  code, recovery code or security key next, exactly as after a password. An account
  created through a provider has no password; to enrol two-factor authentication (every
  enrolment re-confirms a password) or to disconnect the provider, set one first with
  **Forgot password** on the sign-in page.
- **Single sign-on comes first.** An organization that requires single sign-on refuses a
  GitHub or Google session just as it refuses a password one — every other organization
  you belong to is reachable. An account with a provider connected cannot also sign in
  through an organization's identity provider; the owner of that organization can ask
  Bucker support to convert the account.

### For operators of the deployment: registering the providers

Social sign-in needs an app registered at each provider, by hand — nothing here can do it
for you. Each provider is offered only when **both** of its variables are set on the
service that runs the API (`bucker-api` on Fly); one without the other refuses to start in
production and is simply not offered elsewhere.

| Provider | Register at | Callback / redirect URI | Variables |
| --- | --- | --- | --- |
| GitHub | Settings → Developer settings → **OAuth Apps** → New OAuth App (an OAuth App, not the repository GitHub App) | `<API_URL>/auth/social/github/callback` | `GITHUB_OAUTH_CLIENT_ID`, `GITHUB_OAUTH_CLIENT_SECRET` |
| Google | Cloud console → APIs & Services → Credentials → OAuth client ID → **Web application** | `<API_URL>/auth/social/google/callback` | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET` |

Both use the authorization-code flow with PKCE; GitHub is asked for `read:user user:email`
(the verified-address list), Google for `openid email profile`.

## Two-factor authentication

Two-factor authentication starts with an **authenticator app** (TOTP, RFC 6238). Turn it
on from **Settings → General → Account security**: you confirm your password, add the
secret to your app, and enter the code it shows. Bucker then shows ten single-use
**recovery codes** once — save them. Each works once, for the day you lose the app.

Once it is on, signing in with a password asks for a second factor, which can be:

- a 6-digit code from the app;
- a recovery code;
- a **security key or passkey**, if you have registered one (below).

Turning two-factor authentication off takes your password and a current code.

## Security keys and passkeys

A security key (a YubiKey, a Titan key) or a passkey (Touch ID, Windows Hello, a phone)
can answer the sign-in check instead of a code. It is **phishing-resistant**: the browser
binds the key's answer to the real Bucker address, so a look-alike site cannot relay it.

- **Added beside the app, not instead of it.** Keys can be registered only once
  authenticator-app two-factor is on, and adding one asks for your password **and** a
  current code. From then on the key can stand in for that code, so adding one costs
  what turning the app off costs.
- **Up to ten per account.** Name each one so you can tell them apart.
- **Removing a key** takes your password. Turning two-factor authentication off removes
  every key with it.
- Every add and remove sends a security notice to your email address.

At sign-in, press **Use a security key** on the two-factor step and follow your browser's
prompt. If you close the prompt, nothing is spent: the step stays open for a code.

### What Bucker checks

Every check happens on the server. The browser's answer must be for this sign-in's
single-use challenge (five minutes), on the dashboard's exact address, for this
deployment, from a key registered to your account, with a valid signature. The key's
signature counter must move forward; a counter that goes backwards is the signal of a
cloned key, and the answer is refused. Bucker supports ES256 and RS256 keys and asks for
**no attestation** — it records nothing about which model of key you use, and makes no
claim about it.

A wrong answer counts against the sign-in exactly as a wrong code does: five and the step
has to start again from the password.

### For operators of the deployment

The relying party is the dashboard: its address (`APP_URL`) is the only origin accepted
and its host name is the relying-party ID. Keys registered on one host name work only on
that host name, so **moving the dashboard to a new address orphans every registered key**
— authenticator apps and recovery codes keep working, and people re-register their keys.
The ceremony needs a secure context, so the dashboard must be served over HTTPS
(`http://localhost` is the one exception browsers make).

## When an organization requires two-factor authentication

An owner turns this on under **Settings › Security › Organization security policy**
(`PATCH /orgs/:orgSlug/security-policy { "mfaRequired": true }`). Members without a second
factor keep their access for the grace period (14 days by default), then are refused in
that organization — and only there — until they enrol. An owner must have a second factor
of their own before turning it on.

**Phishing-resistant factors only** (`{ "mfaPhishingResistant": true }`) raises the bar:
an authenticator app no longer satisfies the requirement, and only a security key or
passkey registered to the account does. It needs two-factor authentication required, the
owner turning it on must hold a key of their own, and members get the same grace period
again, counted from when it was turned on, before an app-only account is refused with a
message asking for a key. The policy card counts how many enrolled people hold a key.
Turning two-factor authentication off for the organization turns this off too.

**The check is on the session, not only on the account.** Every session records how its
sign-in was completed — a password alone, the authenticator app, a recovery code, a
security key, a passkey, single sign-on, or a GitHub/Google sign-in — and that record
rides every refresh unchanged. Once the grace period ends, the organization accepts only
sessions signed in with a security key or passkey. A person who holds a key but signed in
with their app is refused with a message asking them to **verify this session**: under
**Settings › Account › Security keys**, press **Verify this session with a key** and answer
the browser's prompt. The session switches to the key in place — no sign-out — and a
dismissed prompt or a key that does not answer changes nothing. Signing out and back in
with the key does the same.

- **Sessions from before this was recorded** (and personal access tokens minted before it)
  count as *not* phishing-resistant. They keep working everywhere else, and in a strict
  organization during its grace period; after that, verify the session with a key as
  above, or mint the token again from a key-verified session.
- **Single sign-on does not count.** The identity provider may well have asked for a key,
  but Bucker cannot see which factor it used.
- **Personal access tokens** are exactly as phishing-resistant as the session that minted
  them. Tokens handed to an MCP client through the token exchange carry the session's
  record with them. Agent tokens and delegations are not gated by it: they are judged
  when they are created, by the session that creates them.
