How to set up two factor with OS2faktor OTP

Introduction

From version 5.5, Safewhere Identify added support for OS2faktor service as an option to do second factor. This guideline will show you how to set it up.

Terminologies

• Connector: a connector is an application that wants to use OS2 factor as the 2nd factor in a login flow. In our case, Identify is a connector.

• Client: a client "app" that a user uses to perform 2nd factor login. That can be a Yubikey, Chrome extensions or a mobile app (Android, iOS). Note: Yubikey is currently support only in Chrome, Firefox and Opera which enable support for FIDO U2F. Other browsers are not supported yet. See more here.

Link to download client apps: https://www.os2faktor.dk/download.html

Admin settings

We support the new OS2faktor properties for OTP authentication connection for following products:

Identify Admin

• New option to "Order of factors". In most cases, you only need to enter "OS2faktor". Configuring multiple OTP methods is an advanced use case.

• New OS2faktor properties

Safewhere Admin

• New option appended to "Second factor method(s)": OS2faktor

• New OS2faktor properties

Which are represented in OTP authentication connection’s json format for REST API as follow:

"configurations": [
    {
      "os2faktorDeviceIdClaimType": "",
      "os2faktorPseudonymClaimType": "",
      "os2faktorPollingTimeout": 60,
      "os2faktorApiKey": "",
      "os2faktorBackendUrl": "https://backend.os2faktor.dk/",
      "os2faktorGetDeviceUrl": "https://www.os2faktor.dk/",
      "os2faktorConnectorVersion": "",
      "os2faktorAllowDeviceRegistration": false,
    }
]

• OS2faktorDeviceIdClaimType: a free claim type that holds OS2faktor’s device Ids (multiple device Ids are supported, separated by comma). This claim type may or may not exist as a claim definition in Identify. When the claim type is defined in Identify, Identify can use it to store user’s device Ids. When OS2faktorAllowDeviceRegistration is enable then OS2faktorDeviceIdClaimType is required.
• OS2faktorPseudonymClaimType: a free claim type that holds OS2faktor’s pseudonyms. This claim type may or may not exist as a claim definition in Identify.
• OS2faktorPollingTimeout: the number of seconds that Identify will poll OS2faktor before timeout. The value for OS2faktor Polling Timeout must be a number between 60 and 300.
• OS2faktorApiKey: the OS2faktor’s API Key that Identify needs to use to connect to OS2faktor service.
• OS2faktorBackendUrl: the backend URL of the OS2faktor service. Its default value is https://backend.os2faktor.dk/
• OS2faktorGetDeviceUrl: the URL to the OS2faktor homepage where users can read about OS2faktor and install some clients. This URL will be shown on the onboarding view. Its default value is https://www.os2faktor.dk/
• OS2faktorConnectorVersion: specifies the connector version. OS2faktor seems to reserve this value for future usage.
• OS2faktorAllowDeviceRegistration: when this setting is enabled and Identify cannot find any clients for a user, Identify can offer the user with an option to register his or her device Ids to Identify.

Setup two factor with OS2faktor OTP

Step 1: Create an OTP Authentication Connection

• Order of factors: set value to OS2faktor. You can also add more methods (SMS, Email or Authenticator – separated by comma) to provide your users with more options

• OS2faktor API key: the OS2faktor’s API Key that Identify needs to use to connect to OS2faktor service.
• OS2faktor Device Id claim type: set value to the claim type which contains user’s device Ids. For example:

• OS2faktor backend URL, OS2faktor get device URL: leave it to default values.
• OS2faktor polling timeout(seconds): set values base on your security requirement. Five minutes can be a good value.
• OS2faktor connector version, OS2faktor Pseudonym claim type: optional.

Step 2: Create a first factor authentication connection (Username & Password, SAML, WsFed, etc.)

Step 3: Select a second factor authentication connection for it

The main flow

There will be a lot of features that are built around the main flow:

Step 1: a user performs the 1st factor login using one of the authentication methods.

Step 2: Identify figures out that the 1st factor login is configured with OS2faktor 2nd factor. Identify uses user’s claims value information to build search parameters and makes a call to the OS2faktor service to get a list of OS2faktor clients for this user. We supported following search parameters to get the list of OS2faktor clients:

Use OS2faktor’s device Id

You can configure a claim type that contains OS2faktor’s deviceIds in a token returned from an upstream IdP or from Identify’s local user store. Claims in principal take precedence over claims in local account. If the claim type is configured and if it exists in either the token or local user, its values will be used to query OS2faktor. For local user, device Ids are stored as a comma-separated string in a chosen free claim type:

Use user’s SSN

Identify will use the standard CPR claim type (dk:gov:saml:attribute:CprNumberIdentifier) to check if a token returned from an upstream IdP or from Identify’s local user store has CPR. Claims in principal take precedence over claims in local account. The CPR will be used as OS2faktor’s SSN to query for clients.

Use NemID’s PID

Identify will use the standard PID claim type (dk:gov:saml:attribute:PidNumberIdentifier) to check if a token returned from an upstream IdP or from Identify’s local user store has PID. Claims in principal take precedence over claims in local account. The PID will be used as OS2faktor’s IDs to query for clients.

Use pseudonym

You can configure a claim type that contains OS2faktor’s pseudonyms in a token returned from an upstream IdP or from Identify’s local user store. Claims in principal take precedence over claims in local account. If the claim type is configured and if it exists in either the token or local user, its values will be used to query OS2faktor.

For local user, currently only a single value is supported.

Use combinations of search parameters

Identify will use all search parameters (device IDs, user’s SSN, NemID’s PID, pseudonyms) if they exist to search for all possible clients.

Step 3: if there are more than one OS2faktor clients responded, Identify will show a list of clients so that he/she can pick one to start 2nd factor login with OS2faktor. Each device Id has its own device, so you need to use the right device to do authentication which is shown as "Login via TYPE". (TYPE can be CHROME, ANDROID, IOS, WINDOWS, YUBIKEY).

Note: if you want to use Name instead of Type, you can modify the view "C:\Program Files\Safewhere\Identify\Tenants\dev\runtime\Views\OS2faktor\OS2faktorPickDevice.cshtml" (line 36)

<p><a id="@device.DeviceId" href="#">@Resources.OtpResources.OtpAuthenticationFailedView_OS2faktorPickDeviceLoginVia @device.Type</a></p>

Change device.Type to device.Name to show the client Name instead of Type. If you use Hosted form, change the same thing in form "OS2faktor Pick Device" (line 21).

<p><a id="{{device.DeviceId}}" href="setDeviceId('{{device.DeviceId}}')">{{Resources.OtpResources.OtpAuthenticationFailedView_OS2faktorPickDeviceLoginVia}} {{device.Type}}</a></p>

Step 4: Identify presents the user to a HTML page (or mobile app) where the control code is displayed. Identify will keep polling OS2faktor service every second in the background to retrieve the user action.

CHROME

ADNROID / IOS

YUBIKEY

Note: to approve Yubikey, you need to touch the "Y" icon on the Yubikey device

Step 5: when Identify detects that the user has completed the 2nd flow (either approve / reject / timeout), Identify will ask the server for outcome and proceed accordingly. There are 3 possible outcomes:

• If the user has approved the login request, login flow will continue.
• If the user has rejected the login request, Identify will redirect to a rejection page and offer user another OTP method to authenticate (if there is one configured).

• Timeout - Identify will redirect to a rejection page and offer user another OTP method to authenticate (if there is one configured).

User’s device Ids registration

When you configure Identify to use UserName & Password authentication, or when users logged in using an upstream IdP and are mapped to local user store, you can also allow your users to register device Ids if none exists in both upstream token as well as local account. Firstly, you need to check the setting "Allow device registration for OS2faktor" of the second factor OTP authentication connection.

For upstream IdP, you need to configure the first factor authentication connection’s (except Username & Password and Device-based) "Do not map logins to user store" and "Update unknown users from login" settings as follow:

Identify offers device registration when:

• When a user does not have any search parameters.
• Or when a user has one or more search parameters, e.g. SSN, but the following conditions match:
  • OS2faktor service does not return any clients
  • And user’s device Id claim value is empty
  • And no other OTP methods are configured for that OTP connection (aka OS2faktor is the sole method)

Identify will redirect the user to the device registration page.

The user can enter a list of device Ids separated by comma.

Click register and Identify will make a call to OS2faktor service to verify user's device Ids. You can see that only valid devices are listed:

Users can choose one of them to authenticate. In this case I chose "Login via CHROME"

After a login completes successfully, the device Id values will be saved in user’s device Id claim type.

When the "Allow device registration for OS2faktor" setting of the second factor OTP authentication connection is not checked (false) and a user does not have any search parameters, Identify will redirect to an error page.

Identify also offers user another OTP method to authenticate (if other methods are configured).

User’s Devices Id filter

Currently we support filtering user's devices by the option "Only allow users to use devices that have pin codes set up":

• False: all valid devices listed, no matter it pin code is set up or not. It is default value.
• True: only devices that have pin codes set up are allowed.

Logging

All error logs related to OS2faktor are logged with event id 4416