OneiD accounts and MFA

Learn how OneiD accounts are created, how passwords, lockout, recovery and MFA work, and what users and administrators can do.

View as Markdown

With OneiD accounts, OneiD keeps the users itself and checks their passwords. Administrators create the accounts, and users can protect them with an authenticator app. This page describes what users experience and what administrators can do.

How accounts are created

An administrator creates each account in the admin console, or through the Admin API. There is no self-service sign-up: users cannot register themselves.

When the administrator sets the first password, they can require the user to change it at the first sign-in. See Mandatory password change.

Passwords

A password must:

  • be at least 8 characters long,
  • contain an upper-case letter, a lower-case letter, a digit and a symbol,
  • differ from the user name and the email address.

Administrators can also ban patterns, for example the organisation’s name.

Lockout

After 5 wrong passwords, OneiD locks the account for 5 minutes. A locked account and an unknown user name get the same message, so the sign-in page does not reveal which accounts exist. An administrator can unlock an account sooner.

Forgotten password

  1. On the sign-in page, the user chooses to reset the password.
  2. OneiD sends a 6-digit code to the user’s email address. The code is valid for 10 minutes.
  3. The user enters the code and a new password.

After 6 wrong codes, OneiD blocks password resets for that address for 15 minutes.

Forgotten user name

Users who forget their user name can ask for it on the sign-in page. OneiD sends it to their email address.

Mandatory password change

An administrator can require a user to change the password. At the next sign-in, OneiD sends the user to change it before they can continue to any application.

Until the password is changed:

  • a sign-in request with prompt=none returns interaction_required to the application,
  • refresh requests for that user fail with invalid_grant.

Multi-factor authentication

OneiD offers MFA with an authenticator app (TOTP): the app shows a 6-digit code that changes every 30 seconds. Use any authenticator app that supports these time-based codes.

Not supported OneiD does not offer SMS codes, email codes, push notifications, passkeys or WebAuthn, or recovery codes.

MFA policy

An administrator chooses how MFA applies:

  • Optional. Users can turn MFA on from their profile page.
  • Mandatory for everyone. Every user must enrol.
  • Mandatory per user. The administrator requires MFA for chosen users.

A user who must use MFA but has not enrolled is sent to enrol at the next sign-in, before they reach any application. Until then, prompt=none requests return interaction_required and refresh requests fail with invalid_grant.

Enrol an authenticator app

  1. Sign in to OneiD. If MFA is mandatory, OneiD shows the enrolment page straight away. Otherwise open your profile page and choose to turn on MFA.
  2. OneiD shows a QR code. Scan it with your authenticator app.
  3. Enter the 6-digit code the app shows, to confirm that the app is set up.

Checkpoint OneiD confirms that MFA is on. From now on, sign-in asks for a code after your password.

Sign in with MFA

  1. Enter your user name and password.
  2. Enter the current 6-digit code from your authenticator app.

After 5 wrong codes, OneiD locks MFA for the account for 15 minutes.

After an MFA sign-in, the ID token contains amr ["pwd","mfa"] and acr urn:oltin:ac:mfa. Applications can check these before sensitive actions.

Lost device

There are no recovery codes. If a user loses the device with the authenticator app, an administrator resets the user’s MFA. The user then enrols again.

Turn off MFA

A user can turn off MFA on the profile page. OneiD asks for the current password or a code from the authenticator app, and sends an email to tell the user that MFA was turned off. If MFA is mandatory for the user, OneiD sends them to enrol again at the next sign-in.

The profile page

Signed-in users have a profile page in OneiD where they can:

  • change their display name,
  • change their password,
  • turn MFA on or off.

The consent page

When an application asks for consent, OneiD shows the application’s name and the scopes it requests. The user can:

  • untick optional scopes,
  • tick “remember” so OneiD does not ask again for the same scopes,
  • refuse, in which case the application receives access_denied.

Sign-in, consent and profile pages are in English and use the OneiD design. Your own logo and colours cannot be configured.

What administrators can do

In the admin console, an administrator with the right role can:

Action Effect
Create a user Creates the account.
Assign roles The roles appear in the role claim when an application requests the roles scope.
Unlock Ends a password lockout early.
Reset MFA Removes the user’s authenticator app. The user enrols again.
Reset the password by email Sends the user a reset code.
Set a temporary password Sets a new password that the administrator passes to the user.
Require a password change Sends the user to change the password at the next sign-in.
Require MFA Sends the user to enrol at the next sign-in.

When an administrator removes a role, locks the user, resets MFA or sets a temporary password, OneiD revokes the user’s tokens. A password change by the user does the same.

Learn more