Haruno Knowledge base

Security

Add a second step to your own operator sign-in with an authenticator app, keep your recovery codes, and see when a super admin has to have one.

  • Operator consoleAvailable

Your operator key is the first step of signing in. Security lets you add a second step: a 6-digit code from an authenticator app. With it, a stolen key alone does not open the console.

An authenticator is an app on your phone that shows a new 6-digit code every half minute. Any app that supports time-based codes works.

The page is the last entry in the sidebar. Every operator, super admin or viewer, can set up a second step for their own account. The release publisher account cannot. It only runs the release process.

Set it up

  1. Open Security and press Set up an authenticator

    The page says "Second factor: off" until you do.

  2. Add the key to your authenticator app

    Add an account by typing in the key on the screen. The key is shown only now, so keep the page open until you are done. A folded line, "Link for apps that open it directly", holds the same thing as a link.

  3. Type the code and press Turn on

    Type the 6-digit code your app shows. If it is wrong, the page says "That code is not right. Check the clock on the device and try again." A phone with the wrong time gives wrong codes.

  4. Save your recovery codes

    The page shows ten recovery codes. Copy them somewhere safe, apart from your operator key, then press I have saved them.

Before: the second step is off.
The Security page before a second step is set up: the line Second factor: off and a Set up an authenticator button
The key is shown once. The code is the one your app shows.
The Security page showing a made-up setup key with a copy button, a folded line for apps that open it directly, a box with a 6-digit code typed in and a Turn on button
The recovery codes, made up here.
The Security page listing ten made-up recovery codes with a copy button and an I have saved them button
Recovery codes are shown once

Each recovery code works once, in place of an authenticator code. They are not shown again. When you type one, capital letters, small letters, spaces and dashes make no difference.

Signing in with it

Type your key and press Sign In as before. The box then asks for a code: "Enter the 6-digit code from your authenticator, or one of your recovery codes." The key field is locked while you do. Type the code and press Sign In again.

The sign-in box after the key was accepted.
The sign-in box with the key field filled and locked, the line asking for the 6-digit code from your authenticator or a recovery code, a Code field with a code typed in and a Sign In button
  • A code works once. A recovery code is used up when you type it.
  • A wrong code gives "Invalid operator key or code". The key stays in the box, so you only type the code again.
  • Several wrong codes in a row lock the codes for your account for a while. Even a right code is refused until the time has passed.

New recovery codes, or turn it off

Once it is on, the page says "Second factor: on". To change anything, type a current code (from your app, or a recovery code) and press one of two buttons.

  • New recovery codes shows ten new ones. The old ones stop working.
  • Turn off removes the second step and signs you out of the console everywhere. You sign in again with your key alone.
After: the second step is on.
The Security page with the second step on: the line Second factor: on, a Code field and the buttons New recovery codes and Turn off

When a super admin must have one

Whether super admins have to have a second step is a setting of the service. It is off unless the team that runs the service turns it on. Test environments turn it on.

When it is on, a super admin who has none can still sign in with the key. The console then shows only the Security page, with the line "Super admins must use a second factor. Set one up to continue; nothing else in the panel is available until you do." After the recovery codes are saved, the console opens as usual.

What a super admin sees when a second step is required and they have none.
The Security page shown alone, with the line: Super admins must use a second factor. Set one up to continue; nothing else in the panel is available until you do. Below it, Second factor: off and a Set up an authenticator button

While it is required, a super admin cannot turn it off. The page says "A super admin cannot turn the second factor off while it is required." Viewers are not required to have one.

If you lose your phone

Sign in with a recovery code. Then, unless super admins are required to have a second step, use another recovery code to turn it off and set it up again on the new phone.

If you have no recovery code left, another super admin has to clear your second step. The console has no button for it, so they do it with the service's admin tools, and they must type a current code of their own. You are then signed out everywhere and can set up a new one. While a second step is required, this is also how a super admin moves to a new phone.

Every change is recorded: setting it up, turning it on or off, new recovery codes and a clearing by another super admin.

What a person in support can ask an operator

  • "My code is refused." Check the time on the phone first. After several wrong codes, wait a while and try again.
  • "I lost my phone." An operator with a recovery code can still sign in. Without one, ask a super admin to clear the second step.

Last updated · PR #2944 · View this version on GitHub

History (1 version)
  1. Internal knowledge base for staff: site, reader keys, assistant, 197 pages and the PR rule (#2944)
    PR #2944Commit a2a7836The page at this version
    What changed
    @@ -0,0 +1,86 @@
+---
+title: Security
+summary: Add a second step to your own operator sign-in with an authenticator app, keep your recovery codes, and see when a super admin has to have one.
+feature: ops-security
+covers:
+  - web/monitoring/components/SecurityPage.tsx
+  - web/monitoring/components/AuthGate.tsx
+  - web/monitoring/components/AuthPage.tsx
+  - server-dotnet/src/Haruno.Server/Auth/AdminSecondFactorService.cs
+  - server-dotnet/src/Haruno.Server/Controllers/AdminAuthController.cs
+---
+
+Your operator key is the first step of signing in. **Security** lets you add a second step: a 6-digit code from an authenticator app. With it, a stolen key alone does not open the console.
+
+An authenticator is an app on your phone that shows a new 6-digit code every half minute. Any app that supports time-based codes works.
+
+The page is the last entry in the sidebar. Every operator, super admin or viewer, can set up a second step for their own account. The release publisher account cannot. It only runs the release process.
+
+## Set it up
+
+<Steps>
+<Step title="Open Security and press Set up an authenticator">
+The page says "Second factor: off" until you do.
+</Step>
+<Step title="Add the key to your authenticator app">
+Add an account by typing in the key on the screen. The key is shown only now, so keep the page open until you are done. A folded line, "Link for apps that open it directly", holds the same thing as a link.
+</Step>
+<Step title="Type the code and press Turn on">
+Type the 6-digit code your app shows. If it is wrong, the page says "That code is not right. Check the clock on the device and try again." A phone with the wrong time gives wrong codes.
+</Step>
+<Step title="Save your recovery codes">
+The page shows ten recovery codes. Copy them somewhere safe, apart from your operator key, then press **I have saved them**.
+</Step>
+</Steps>
+
+<Shot src="/m/86cec8521c53-ops-security-dark.png" alt="The Security page before a second step is set up: the line Second factor: off and a Set up an authenticator button" caption="Before: the second step is off." />
+
+<Shot src="/m/e7b038bac027-ops-security-setup-dark.png" alt="The Security page showing a made-up setup key with a copy button, a folded line for apps that open it directly, a box with a 6-digit code typed in and a Turn on button" caption="The key is shown once. The code is the one your app shows." />
+
+<Shot src="/m/a7aa7250a446-ops-security-codes-dark.png" alt="The Security page listing ten made-up recovery codes with a copy button and an I have saved them button" caption="The recovery codes, made up here." />
+
+<Callout variant="warning" title="Recovery codes are shown once">
+Each recovery code works once, in place of an authenticator code. They are not shown again. When you type one, capital letters, small letters, spaces and dashes make no difference.
+</Callout>
+
+## Signing in with it
+
+Type your key and press **Sign In** as before. The box then asks for a code: "Enter the 6-digit code from your authenticator, or one of your recovery codes." The key field is locked while you do. Type the code and press **Sign In** again.
+
+<Shot src="/m/e6b92e7b929f-ops-sign-in-code-dark.png" alt="The sign-in box with the key field filled and locked, the line asking for the 6-digit code from your authenticator or a recovery code, a Code field with a code typed in and a Sign In button" caption="The sign-in box after the key was accepted." />
+
+- A code works once. A recovery code is used up when you type it.
+- A wrong code gives "Invalid operator key or code". The key stays in the box, so you only type the code again.
+- Several wrong codes in a row lock the codes for your account for a while. Even a right code is refused until the time has passed.
+
+## New recovery codes, or turn it off
+
+Once it is on, the page says "Second factor: on". To change anything, type a current code (from your app, or a recovery code) and press one of two buttons.
+
+- **New recovery codes** shows ten new ones. The old ones stop working.
+- **Turn off** removes the second step and signs you out of the console everywhere. You sign in again with your key alone.
+
+<Shot src="/m/b9c6d812a7db-ops-security-on-dark.png" alt="The Security page with the second step on: the line Second factor: on, a Code field and the buttons New recovery codes and Turn off" caption="After: the second step is on." />
+
+## When a super admin must have one
+
+Whether super admins have to have a second step is a setting of the service. It is off unless the team that runs the service turns it on. Test environments turn it on.
+
+When it is on, a super admin who has none can still sign in with the key. The console then shows only the Security page, with the line "Super admins must use a second factor. Set one up to continue; nothing else in the panel is available until you do." After the recovery codes are saved, the console opens as usual.
+
+<Shot src="/m/e7f1dd261853-ops-security-required-dark.png" alt="The Security page shown alone, with the line: Super admins must use a second factor. Set one up to continue; nothing else in the panel is available until you do. Below it, Second factor: off and a Set up an authenticator button" caption="What a super admin sees when a second step is required and they have none." />
+
+While it is required, a super admin cannot turn it off. The page says "A super admin cannot turn the second factor off while it is required." Viewers are not required to have one.
+
+## If you lose your phone
+
+Sign in with a recovery code. Then, unless super admins are required to have a second step, use another recovery code to turn it off and set it up again on the new phone.
+
+If you have no recovery code left, another super admin has to clear your second step. The console has no button for it, so they do it with the service's admin tools, and they must type a current code of their own. You are then signed out everywhere and can set up a new one. While a second step is required, this is also how a super admin moves to a new phone.
+
+Every change is recorded: setting it up, turning it on or off, new recovery codes and a clearing by another super admin.
+
+## What a person in support can ask an operator
+
+- "My code is refused." Check the time on the phone first. After several wrong codes, wait a while and try again.
+- "I lost my phone." An operator with a recovery code can still sign in. Without one, ask a super admin to clear the second step.