Risk-based Authentication

Risk-based Authentication, also known as RBA, offers a holistic approach to user authentication that provides a more frictionless experience for users while ensuring security and peace-of-mind from a site perspective.

RBA uses a risk calculation to develop a device profile, sometimes referred to as a fingerprint, so that future login attempts are compared against this fingerprint in order to determine the path to authentication, whether that means immediate authentication or perhaps a stepup may be required if it’s determined that the login attempt deviates too far from the device profile.

rba flow

Current features

Important concepts

The following should be considered when using RBA:

  • To get the RBA feature, you’ll need to request it directly with your Professional Services representative so they can enable it on your account.

  • Only users who have MFA activated can add trusted devices to their profile.

  • The feature does not work with the ROPC flow.

    See disabling the ROPC flow for a client for more details on how to do that.

  • Trusted devices are stored for 90 days.

  • Devices using the magic_link as a second factor can’t be added to the trust devices list.

RBA method and operation flow

When RBA is enabled with your account, it enhances your security by ensuring that only valid users are granted access. The flow here guides you through the methods and API operations needed to achieve that.

rba method flow abbr
RBA Flow table
Step Core JS SDK method API operation Notes

1

loginWithPassword

User logs in

User attempts to log into the site.

If successful, the step up token is delivered in the loginWithPassword response.

If you are integrating from the backend, you must provide the User-Agent header and true client IP to override the user agent and the user IP respectively.

If a user has already trusted his or her device, you must provide the __Host-trusted-device-id: <value> header.

2

Checks user has a second factor (MFA enabled).

If the user has a second factor, the flow continues. Otherwise, they are only notified via email and/or SMS.

3

Initiate stepup flow

Initiates the stepup flow.

4

startPasswordless

Start Passwordless MFA

Starts the passwordless flow for MFA using the step_up token received in the stepup flow initiation.

5

verifyMfaPasswordless

Verify Passwordless MFA

Verifies the passwordless flow for MFA with the user verification code and challenge_id.

If you are integrating from the backend, you must provide the User-Agent header and true client IP to override the user agent and the user IP respectively.

If a user has already trusted his or her device, you must provide the __Host-trusted-device-id: <value> header.

The trust_device field can also be passed depending on the user requirements. The default value for trust_device is false. If the user trusts their device, the following cookie is set __Host-trusted-device-id: VALUE. For API integration, the cookie must be stored on the user’s browser and provided the next time the user tries to login.

6

exchangeAuthorizationCodeWithPkce

Retrieve access token

Exchanges the authorization code for a new access token.

7

Decode the token

Confirms "mfa" is part of the user’s "amr" array.

{
    ...
    "amr": [
        "mfa",
        "sms"
    ]
}

8

User granted access.

RBA risk calculation

What is in a risk calculation?

Risk scores are calculated using anything from the device being trusted, the IP of the login attempt, the particular operating system, and so on and so forth.

Trusted devices are devices that have been trusted by the user, have the trusted device cookie, and are on the user’s trusted device list. If the device is trusted, the risk score is positively impacted.

Currently, any device that is over the configured risk_score threshold is forced to perform a stepup operation in order to authenticate via the device.

Any login attempt from an account without a second factor triggers a notification to the user via our RBA templates.

The risk threshold is configurable and the default is 30. It ranges from 0 (low) to 100 (highest).

In the Risk score example below, let’s imagine the device profile, or fingerprint, for Lula is the following:

  • Trusted devices (iPhone 13)

  • Typical IP 90.93.55.57 (Nantes, France)

  • Operating system typically iOS

  • Low risk

  • Medium risk

  • High risk

  • Very high risk

Category Value

Risk score

1

Trusted device

Listed device

IP address

90.93.55.57 (Nantes, France)

Operating system

iOS
Category Value

Risk score

35

Trusted device

Listed device

IP address

93.89.251.62 (Galway, Ireland)

Operating system

Android
Category Value

Risk score

50

Trusted device

Unlisted

IP address

67.183.58.7 Seattle, Washington USA

Operating system

iOS
Category Value

Risk score

99

Trusted device

Unlisted

IP address

219.93.183.103 Kuala Lumpur, Malaysia

Operating system

Android

Enable RBA

Enabling Risk-based Authentication through the ReachFive Console ensures that only the devices that your users have decided to trust will be allowed to login without a second step.

Prerequisites

  • You must have access to the ReachFive Console.

  • You must have a Developer, Manager, or Administrator role.

Instructions

  1. Log in to your ReachFive Console.

  2. Go to Settings  MFA  Settings.

  3. Enable Use risk based authentication.

  4. If desired, configure the Risk score threshold.

    What is that? 🤔

    This is the threshold at which a login attempt is considered risky.

    The default is 30 and it ranges from 0 (consider all login attempts risky) to 100 (consider no login attempts risky).

  5. Optional If needed, choose which of your clients you want to exclude from RBA protections.

  6. Don’t forget to Save your input.

mfa settings rba

RBA templates

You can send notifications to users about risky logins via our handy email and SMS templates. As part of those, you can even pass information about the particular user and device using the templating variables as shown here.

Template variables

Variable Description

{{link}}

This is the generated magic link (hosted by ReachFive that redirects to the specified URL).

{{user.email}}

The user’s email address.

{{user.lang}}

The default language for the user.

{{locale}}

The user’s locale (country).

{{user.given_name}}

The user’s given name (first name).

example

Nicole Dubois

{{user.family_name}}

The user’s family name (last name, surname).

example

Nicole Dubois

{{user.custom_fields.key}}

Custom user fields. Only the string, select, and tag custom field data types can be used in email templates.

example

{{user.custom_fields.favorite_movie}}

The tags custom field type is concatenated by default. If you want to separate the tags, use the join function:

Example

favorite_movie:["The Secret Life of Pets","Forrest Gump","Amélie"]

format
{{ user.custom_fields.favorite_movie | join: " , " }}
output
The Secret Life of Pets, Forrest Gump, Amélie

{{user.client_id}}

The client ID used to perform the API call. This can be either an Identity or Management client.

{{ip}}

The IP address of the user attempting to log in.

{{userAgent}}

The user agent content.

Typically, this includes browser and platform information.

{{operatingSystem}}

The user’s operating system such as Android.

{{deviceClass}}

The class of the user’s device such as Phone.

{{deviceName}}

The name of the user’s device such as Google Nexus 6.
Subsections

Email

Risky Login Notification

Sent to user when login attempt is deemed risky

This template should be used to notify users that a login attempt from their account is considered unusual or risky. For users that haven’t enrolled any identifiers for MFA, the email is sent every time a user attempts to log in.

You can use the {{link}} templating variable in the email template to redirect users to a password reset page. This is useful when the login attempt is not from the user and the user wants to quickly reset their password.

  1. Enable the template.

  2. Enter the sender’s email in the From field.

  3. Write your Subject.

    Unusual login attempt

  4. Enter the URL to redirect users in the Redirect to field.

  5. Specify the URL lifetime (in seconds).

  6. Write your Message for the template.

    <p>Hello {{user.given_name}},</p>

<p>We have detected a new connection from this user agent {{user_agent}} and this operating system {{operating_system}}.</p>

<p>If this is you, no action is required; otherwise we recommend you change your password by following <a href="{{link}}">this link</a>.</p>

  7. Don’t forget to Save your input.

Custom provider templates

If you have configured a custom provider, your templates will be different and only contain the following fields:

Field Description

Enabled

Checkbox to enable the template.

enabled

Template ID

The ID that you assign to the template.

template id

Redirect to

The URL to which you want to redirect the user.

redirect to

URL Lifetime (seconds)

The URL lifetime in seconds.

url lifetime

SMS

Risky Login Notification

Sent to user when login attempt is deemed risky

This template should be used to notify users that a login attempt from their account is considered unusual or risky. For users that haven’t activated Multi-factor Authentication with Risk-based Authentication, the SMS is sent every time a user attempts to log in.

  1. Go to Settings  SMS  Templates on your ReachFive Console.

  2. Toggle to the Risky Login Notification tab.

  3. Enable the template by ticking the Enabled checkbox.

  4. Enter the Verification Code Lifetime. This is in seconds.

  5. Use the Message section to write your customised template like the example below:

    Hi {{user.given_name}}. There has been an unusual login attempt on your account. Please contact your system administrator if this was not you trying to sign in. Otherwise, you can ignore this message.

  6. Don’t forget to Save your input.

Custom provider templates

If you have configured a custom provider, your templates will be different and only contain the following fields:

Field Description

Enabled

Checkbox to enable the template.

enabled

Template ID

The ID that you assign to the template.

template id

Code Lifetime (seconds)

The code lifetime in seconds.

code lifetime

RBA API endpoints

If a user has an MFA second factor device associated with their account, they can manage their trusted devices. The following endpoints allow you to perform the add and remove operations:

Identity API
Management API