Quickstart: put the second factor into service

The shortest way from “the plugin is installed” to “an enrolled account signs in in two steps”. Four steps, about fifteen minutes.

This page is for administrators. Somebody who only wants to secure their own account is better served by Setting up two-factor authentication, which walks the same procedure from the user's side in more detail.

• wkidentity is installed and enabled in the Extension Manager.
• You are signed in as superuser.
• An authenticator application on a phone or desktop.
• A second administrator account, or another way in. See the warning in step 4; do not skip it.
• Reasonably correct clocks on the server and on the device. Time-based codes depend on both.

Admin → Configuration, section wkidentity, setting issuer.

The name later appears beside the account in the authenticator app and decides whether somebody with three similar entries finds the right one. Empty means the wiki title is used.

Set it before anybody enrols: a later change does not update entries that already exist in the apps.

Open your own profile, /doku.php?do=profile, section Two-factor authentication (TOTP), and choose Set up two-factor authentication.

The procedure has two stages: starting it produces a secret but keeps it in the session only. Only a correct code stores it permanently. A wrong code leaves the pending secret untouched — the same QR code can be scanned again.

Before anything depends on it, open /doku.php?do=wkidentity_debug — the link Test TOTP codes (internal tool) sits in the profile while show_debug_link is on.

The page computes codes for a pasted secret entirely in the browser and sends nothing to the server. Compare with the app; the codes must match.

This is the most valuable step in the sequence: it separates “the secret is wrong” from “the clocks disagree” before a sign-in depends on the answer.

Admin → Configuration, section wkidentity:

enforce_login = 1

Then sign in from a second browser and keep your current session open until you have confirmed it works.

The setting overrides core sign-in behaviour and is therefore a plain switch in the ordinary configuration manager, not only in the plugin's own screen: it has to stay reachable even when that screen no longer opens.

• Your account signs in with a password, is given a code prompt instead of a finished session, and is signed in only after a correct code.
• An account without an enrolled factor signs in in one step, unchanged. That is what makes it safe to switch enforcement on while the wiki is still enrolling.
• Admin → Two-factor authentication (TOTP) shows the figures under Overview: Enrolled (app), Enrolled (email), Required but missing, Required namespaces.

• wkrequest — the structured way somebody locked out asks for a reset.
• Tutorial (German) — the full version including tolerance (window) and attempt limits.
• Authenticator lost or phone broken (German) — the page locked-out people rely on; it is deliberately readable without signing in.
• wkidentity (German) — the package page.