Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

Two-step sign-in for owners and managers

Set up the authenticator app for an owner or manager account and sign in with the 6 digit code.

For
OwnerAdministrator
Hosting
Any hosting
Devices
All devices
Business
All businesses

Checked against Pop Street Dispatch 0.1.0

Owners and managers sign in with a password and a 6 digit code from an authenticator app. You will be able to set the app up once and use the code at every sign-in. Dispatchers, advisors, technicians and drivers sign in with a password.

Before you start #

  • An authenticator app on your phone that reads time-based codes (the standard 6 digit, 30 second kind).
  • Your email address and password.

Steps #

  1. Open Settings, Security and choose to set up the authenticator app. The app sends your email address and password to /auth/totp/enrol.
  2. The server answers with a secret, a setup link (otpauth_uri) and the app name "Pop Street Dispatch". Add the account to your authenticator app by scanning the code the screen draws from the link, or by typing the secret.
  3. Save the secret in a password manager, so you can add it to a new phone later.
  4. Type the 6 digit code the app now shows. The app sends it to /auth/totp/verify. The server answers ok, and two-step sign-in is on.
  5. From now on, sign in with your email address, password and the current code.

Good to know #

  • Each code works once. A code the server has already accepted is refused, even inside its 30 second window.
  • The server accepts the code for the current 30 seconds and one step either side, so a phone clock that runs a little fast or slow still works.
  • A wrong code counts as a failed sign-in for the lockout. See "Signing in, tokens and lockout".
  • If a dispatcher, advisor, technician or driver has set up the authenticator app, the server asks for the code at their sign-ins too.
  • Set-up runs once for each account: once confirmed, a second set-up answers with a conflict.
  • Choosing a new password asks for the current 6 digit code too, once the app is on. A password alone never changes the password of an account that has the app set up.
  • A lost phone has a fix: whoever runs the server removes the app with dispatch-server reset-totp --tenant <account> --user <email>, and you set it up again from step 1.
  • After a backup is restored, every owner and manager sets up the authenticator app again. See "Backups and restore".
Technical details
  • RFC 6238 time-based codes, SHA-1, 6 digits, 30 second steps, a 20 byte secret.
  • The secret is stored on the server. Backups never contain it.
  • reset-totp deletes the stored secret, ends every earlier sign-in and integration key of that person, clears their lockout and writes an entry to the audit log. It prints no secret.
  • A code is accepted once. The server records the used 30 second step in the same transaction that checks it, so two sign-ins that arrive together with one code give one success.
  • Both set-up calls are public routes that check the email address and password themselves.

If something goes wrong #

  • totp_enrolment_required (401): set-up is still open. Start at step 1.
  • totp_required (401): the sign-in has no code. Add the totp field.
  • invalid_credentials (401): the code was wrong or already used. Wait for the next code.
  • conflict (409) at set-up: the app is already set up for this account. If you still have the secret from set-up, add it to the new phone. If the phone is lost, ask whoever runs the server to run dispatch-server reset-totp --tenant <account> --user <email>, then start again at step 1. See "Lost or stolen device".