Set up or reset the second factor

The second factor is a six-digit code from an authenticator app (such as Microsoft Authenticator) that changes every 30 seconds. A key alone is then no longer enough: whoever intercepts it can't reach the data without the person's phone. The sign-in policy decides when the code is required; a new service requires it for administration.

In most cases, people set up the second factor themselves: the first time someone signs in with a new key, the administration app shows the Zweiten Faktor einrichten (Set up second factor) card with a QR code instead of asking for a code. This works for 24 hours after the key was issued (setting totp_enrol_hours). People who sign in only with a Windows account or SQL login have no key and therefore no such period.

For those people, and for anyone whose period has expired, you set up the second factor in the app: you get a one-time link, and the person opens it and adds the QR code to their authenticator app. If someone loses their phone, you remove the second factor or set it up again.

Set up the second factor

1. Open Personen und Schlüssel (People and keys) and select the person.
2. In the command bar, choose Zweiten Faktor (neu) einrichten … (Set up second factor (again) …), or in the row's shortcut menu (right-click) choose Zweiter Faktor und Sitzung (Second factor and session) > Zweiten Faktor (neu) einrichten ….
3. The Zweiter Faktor eingerichtet (Second factor set up) message shows a one-time link. Give it to the person.

4. The person opens the link, selects the button, and scans the QR code with their authenticator app. If they can't scan it, they can type in the key shown below the code. The app lists the entry under the installation name and the person's name, for example “Data Service (Production): Jane Doe”.

   

5. The next time the person signs in, they enter their first code.

Result: The Zweiter Faktor (Second factor) column shows “eingerichtet (unbestätigt)” (set up, not confirmed) and, after the first accepted code, “aktiv” (active). Bestätigt (Confirmed) shows when that happened.

In the screenshot: (1) state of the second factor.

Set up the second factor again (lost phone, new app)

1. Right-click the person and choose Zweiten Faktor (neu) einrichten ….
2. Confirm the prompt. The service replaces the second factor and ends all of the person's sessions; the message shows the one-time link for the new one.

If the person shouldn't have a second factor for now, choose Zweiten Faktor entfernen (Remove second factor).

<a id=“name-der-installation”></a>Change the installation name

The installer suggests the name. To change it, open Anmelderichtlinie (Sign-in policy), go to the Einstellungen (Settings) tab, enter it in the Name der Installation (Installation name) field (up to 64 characters, with no colons or quotation marks), and choose Speichern (Save). The service picks up the change without a restart. The new name applies to every second factor set up from then on; an entry that's already in someone's app keeps its name until that person sets up the second factor again. The field takes precedence over the name from the installation; if you clear it, that name applies again.

• Method: TOTP as defined in RFC 6238 (“TOTP: Time-Based One-Time Password Algorithm,” https://www.rfc-editor.org/rfc/rfc6238), using the parameters every common app supports out of the box: HMAC-SHA-1, 6 digits, and a 30-second time step. The app and the service share a secret, and the code proves that the person has the device holding that secret.
• Setting it up again replaces it. If the person already has a second factor, Zweiten Faktor (neu) einrichten … asks for confirmation, replaces it, and ends their sessions. The old entry in their app produces only wrong codes after that.
• The second factor belongs to a person. When someone signs in with a Windows account, the service finds the person through their Windows-Konto (Windows account) field. A group isn't a person: anyone who signs in with Windows and isn't linked to a person can't provide a code, so they're rejected whenever one is required.
• Sessions: An accepted code starts a session that lasts 10 hours by default (setting totp_session_hours, 1 to 168). To see and end active sessions, go to Read the log and sessions.
• Too many wrong codes: After five wrong codes for one person, or twenty from the same origin, within 15 minutes, the service accepts no codes for up to 15 minutes (429), not even correct ones. The second limit slows down anyone trying codes for many people from one computer.
• Clock drift: Besides the code for the current time step, the service also accepts the codes for the step before and the step after (HTTP: sign-in (reference), section “Sign-in policy and second factor” (data service documentation)). RFC 6238, section 6, recommends allowing at most one extra time step to cover transmission delay. How much clock drift that tolerates depends on where in the 30-second step the sign-in falls: up to 30 seconds is always fine; beyond that, more and more codes are rejected. The fix is to set the phone to get its time automatically.
• Self-setup is a window of risk: Until the person has set up the second factor, their first factor is enough to set it up, and the service can't tell whether that's the person or someone who has their key. Anyone who intercepts the key and signs in first ties the second factor to their own device. That's why the window is limited (totp_enrol_hours, 24 hours after the key is issued by default), and during that time the first factor works only for setup, not for data or administration. Where that risk isn't acceptable, such as for administrators, set up the second factor yourself with a one-time link, and hand over the key and the link through separate channels. If someone reports that their app has no entry but the column shows “aktiv”, set up the second factor again right away.

• Define the sign-in policy
• Sign in to the administration app
• Reference: HTTP: sign-in (reference), section “Sign-in policy and second factor” (data service documentation)