Multi-factor authentication#

This provides persons with the ability to protect their Skalio ID local accounts with multi-factor authentication.

Persons authenticating via a trusted external identity provider are excluded. The external identity provider is required to provide such functionality.

Details#

Enabling multi-factor authentication is an option for persons. A person is able to register multiple factors. The first authentication step is always based on email address & password. Should the person have registered and verified at least one "second factor", multi-factor authentication is required. During authentication, they are presented with their list of "second factors", and must choose one of them to complete authentication. The second factor must be provided within a short period of time after initiating the authentication (currently: 5 minutes).

Users can manage their authentication factors. Additional factors can be registered, existing factors can be removed. An existing factor cannot be edited; it must be removed and registered again. Removing all factors leads to the account dropping multi-factor-authentication protection.

Registration#

Registering a second factor requires that the user demonstrates control over it. Depending on the type of factor this may involve entering a one-time-key. Only after the verification was successful is the authentication factor available.

A second factor greatly protects against phishing attacks. Therefore, it is necessary for the registration process to be protected against misuse: the person must prove they are the legitimate owner of the user-account, before they can secure it further. The registration of a second factor requires that the person has a "young" session and has recently demonstrated having access to their primary email address. If either of these criteria fail, the registration process is interrupted and the person must solve the issue.

• Renew authentication: If the session was established too long ago, the person must simply authenticate again. With the new session, the person can retry the registration.
• Confirm email verification: If the verification of the primary email address occurred too long ago, the registration is aborted. A confirmation-key is sent to the primary email address, and the person must enter the confirmation-key in order to continue with the registration.

Flow#

After initial auth-login, Skalio ID checks if the person has MFA enabled. If so, the response contains an intermediate mfa-token that explains which authenticator types are available to the person. He has to obtain the second factor and provide it together with the mfa-token. If verification is successful, the Skalio ID token is returned as usual. The auth-level claim of the token is set to 2.

Note:

• The mfa-token has a short validity period of several minutes only. If expired, first-factor authentication has to be repeated.
• While the mfa-token can be used multiple times (while valid), each second-factor can only be used once!

Types of authentication factors#

Password#

This authenticator stores a Bcrypt hash of a user-provided password. To authenticate, the person provides a plain-text password. The plain-text is hashed, using the salt contained in the hash, and the result is compared against the hash. If they match, the authentication is considered successful.

This authenticator is only available as the first factor.

Time-based one-time password#

This authenticator follows the TOTP concept: a shared secret is used to generate a short numeric key that is valid for a very short time (30 seconds, with intervals starting on the full and half minute). To authenticate, the person uses a OTP-generator seeded with the shared secret. The generated key is sent to Skalio ID, where the same process is performed. If both generate the same key, the authentication is considered successful. A cache-check ensures that a successful OTP can be used only once.

During registration, the backend generates the shared secret and provides it to the person for provisioning of his OTP-generator. The shared secret is shown only once. To complete registration, the person must provide a matching generated OTP in time. The secret is also offered as a QrCode image, following the Key Uri Format.

Useful links:

• https://github.com/samdjstevens/java-totp: Java library used by the backend to manage TOTP. Can also be used as a client library.
• https://totp.app/: In-browser TOTP generator.

Recovery code#

During registration, this authenticator provides a small number of one-time passcodes with unlimited expiration. The person is encouraged to store these codes offline in a secure location, for example as a printout.

The passcodes can be used as a second factor. After successful authentication, a passcode is "burned" and can no longer be used. Once all available recovery codes have been spent, the person has to recreate new passcodes.

Passcodes are (re-)created by registering the authenticator. The registration can be repeated at any time. Any existing, not yet used, recovery code will be removed. After successful registration, only the newly created passcodes are valid. Recovery codes do not require verification.

Passcode details:

• number of passcodes generated: 3
• length of a passcode: 12 characters
• validity: unlimited, until used, de-registered or replaced with new set of passcodes
• alphabet: ACDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz2345679

SMS one-time password#

This authenticator is similar to the TOTP concept, except that the one-time key is always created server-side. It is cached for a short period of time (typically 60 seconds) and sent as a short message (SMS) to the mobile phone of the person. Upon receipt the person sends the code to Skalio ID. If the key matches the cache, the authentication is considered successful. Immediate removal of the cache entry ensures the key can be used only once.

To register, the person must provide a mobile phone number (MSISDN) to Skalio ID, where it is persisted as part of the authenticator. An OTP is generated and sent to the phone number. To complete registration, the person must provide the generated OTP in time.

Each person can only register one SMS authenticator.

The registered phone number should be shown to the person during the authentication process, with parts of the number masked. Example:

A one-time password has been sent to the mobile phone with number +49 151 xxxx5566.

This implementation requires a third party integration to send SMS. Ratelimiting and careful selection of supported country codes shall be employed to limit the potential for cost runaway. The person may need to request re-delivery, in which case a new OTP shall be generated and sent. Again, this should be rate-limited.

In-App authentication approval#

The idea of this authenticator is that a person may have an authenticated session on a separate device already, from where the authentication can be approved. During the authentication process, an event is sent to all authenticated sessions of the person. The event triggers the appropriate screen, example:

You are attempting to login from another device. Ok? (Possibly display information such as device type, geo-location of IP address, etc.)

Clicking OK will approve the authentication request on the additional device.

This method does not require registration, but may not be available unless the person currently has established sessions. As such, it may be that this method is only available after at least one other second factor has been registered.

Implementation may require use of push notification services, unless the event is sent only to live apps (those with an active websocket event feed subscription), limiting the useability.

Out of scope#

OIDC users are excluded#

As stated above, inbound authentications via OIDC are excluded from multi-factor authentication. It is the responsibility of the remote identity provider to use multi-factor authentication.

Hardware factors: Yubikey, Smartcard#

While providing exceptional security, hardware-based authenticators are out of scope for the moment.

NFC-based solutions following the U2F standard might be the most likely candidate for attempting an integration.