docs: document backup codes for users who sign in with password + TOTP #167

Nytt ärende

Öppen

öppnade 2026-08-02 12:30:28 +00:00 av supernaut · 0 kommentarer

supernaut kommenterad

2026-08-02 12:30:28 +00:00

Ägare

Why

"I lost my authenticator app" currently has no self-service answer for a password + TOTP user
beyond a full credential reset. The identity provider has supported backup codes for exactly
this case for a long time — the release notes describe "backup codes as MFA in case of lost
TOTP/Webauthn" — and they are generated inside the ordinary credential-update flow, so they are
available to our users today. No server change is needed.

They are undocumented on our side, and the upstream "Authentication and Credentials" page does not
mention them either, so in practice nobody knows they exist.

This is the cheap half of the lost-authenticator problem. It is also the pattern that already
rescued the second-factor lockout in gitborg/gitborg-infra#292 on the git-host side: recovery codes are stored hashed
rather than encrypted, so they survive events that destroy the enrolled secret.

Scope

Guide + FAQ: what backup codes are, when to generate them (at TOTP enrolment), how to store them,
and how to use one to sign in.
Fold a "generate your backup codes now" prompt into the credential-setup guidance for the
password path.
EN + SV, style guide applied.

Done when

A user who signs in with password + TOTP can find, in our own docs, how to get back in after losing
their phone — without contacting the operator.

Part of gitborg/gitborg-docs#69.

## Why "I lost my authenticator app" currently has no self-service answer for a password + TOTP user beyond a full credential reset. The identity provider has supported **backup codes** for exactly this case for a long time — the release notes describe "backup codes as MFA in case of lost TOTP/Webauthn" — and they are generated inside the ordinary credential-update flow, so they are **available to our users today**. No server change is needed. They are undocumented on our side, and the upstream "Authentication and Credentials" page does not mention them either, so in practice nobody knows they exist. This is the cheap half of the lost-authenticator problem. It is also the pattern that already rescued the second-factor lockout in gitborg/gitborg-infra#292 on the git-host side: recovery codes are stored hashed rather than encrypted, so they survive events that destroy the enrolled secret. ## Scope - Guide + FAQ: what backup codes are, when to generate them (at TOTP enrolment), how to store them, and how to use one to sign in. - Fold a "generate your backup codes now" prompt into the credential-setup guidance for the password path. - EN + SV, style guide applied. ## Done when A user who signs in with password + TOTP can find, in our own docs, how to get back in after losing their phone — without contacting the operator. Part of gitborg/gitborg-docs#69.

supernaut lade till etiketterna

2026-08-02 12:31:29 +00:00

~~supernaut refererade till detta ärende från bitborg/bitborg-docs 2026-08-02 12:32:47 +00:00~~

The path into the service: sign-up, the anti-spam check and sign-in wayfinding #69

supernaut lade till detta till projektet Bitborg Web

2026-08-02 12:34:32 +00:00

Logga in för att delta i denna konversation.