Skip to content
bucker

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