Gigya Job Openings

Risk Based Authentication

Skip to end of metadata
Go to start of metadata

Overview

Risk Based Authentication (RBA) is an added layer of client-side account security that can prevent malicious attacks and hacking attempts on your site. It does this by calculating the level of risk associated with a given login attempt, and presenting users with authentication challenges according to that risk level. RBA includes two types of rules for determining the risk level and its outcomes: global rules, which apply to all login attempts in your site (or site groups), and account rule-sets, which apply to individual accounts (used to ensure a more secure authentication for accounts with stronger permissions, such as site admins and other employees). Gigya provides several rules of each type out of the box. 

Risk-Based Authentication can only be applied when using SAP Customer Data Cloud (Gigya) Screen-Sets and our Web SDK. It is not available for server-side implementations.



Unable to render {include} The included page could not be found.

Watch an Instructional Video

To watch a video about this subject, you can visit our Enablement portal with your approved SAP customer or partner ID (S user). Please visit the About page to find out how to get an S user.

Components

Risk Factors

Any of the following events can trigger a requirement for a higher level of authentication: 

  • Failure to login after a specified number of attempts, from a specific account or IP address.
  • Percentage of failed logins, triggered after a specified number of attempts
  • New device used for login.
  • First login from a different country.

Authentication Levels

Authentication levels are associated with each authentication method by their degree of security. A higher authentication level means a higher level of trust. When defining rules, assign a higher required authentication level for more suspicious behavior. For example, you can define that when a user tries to log in from a new country, they have to pass a two-factor authentication with a level of 20, (they must authenticate via an SMS sent to their mobile phones, or using an authenticator app) , whereas activity that is perceived as less suspicious, such as a device change, might only require an authentication level of 10, meaning users can verify with an OTP sent to their email. 

Authentication MethodAuthentication Level
Email10
Phone20
Time-based authentication (e.g. Google Authenticator), also known as "TOTP"20
Push TFA (Two-Factor Authentication via mobile device push notification). Note that this method is not used in a registration flow as it requires a user to have an existing session for their second factor authentication. Instead, it is triggered by a third-party app. For more information, see below.30

Notes:

  • A new registration automatically receives an authentication level of 10.
  • To be able to authenticate users via their mobile phones, you must set up an account with Twilio. When configuring an authentication level of 20, you should also provide your Twilio credentials. For more information, see below.
  • For a user to use Push TFA they must already have Phone TFA enabled. Phone TFA is a requirement for Push TFA.

Two-Factor Authentication Registration

The following diagram illustrates the registration flow when two-factor authentication (TFA) is enabled in your RBA policy. The authentication choices presented to the user depend on the methods you configured for your site: 

Example screen that registering users see if all 3 methods are enabled: 

Security Methods

The following security methods can be applied to a login attempt using RBA: 

  • CAPTCHA : Requires that the user successfully pass a CAPTCHA challenge, thereby preventing account hacks via automated login attempts
  • Two-Factor Authentication (TFA): Requires that the user pass two steps of authentication: the first is the password when initially logging in, and the second is an authentication code the user receives on their mobile device. 
  • Lockout: Locks out the user or IP address for a specified length of time. 

    The lockout event fires an accountLockedOut Webhook.

Rules

RBA includes two types of rules for determining the risk level and its outcomes:

  • Global Rules: Apply to all login attempts in a site (or site group). In the RBA Policy object these are defined in the commonRules array. 
  • Account Rule-Sets: Apply to individual accounts. Usually used to ensure a more secure authentication for accounts with stronger permissions, such as site admins and other employees. In the RBA Policy object these are defined in the ruleSets array. 

Multi-Sites and SSO

RBA can be used in a nuanced way in a multi-site scenario. Capabilities include: 

  • Rules are configured for the parent site, and apply throughout the site group. For example, if you set a risk factor of 3 failed logins for the parent site, and a user has failed two consecutive logins on child-site A, the risk factor will be triggered if the user immediately attempts and fails to login to child-site B. 
  • You can use the apiKey root factor to set up different rules per different API keys. 

    Using an apiKey root factor in conjunction with account lockout action is not supported due to account lockout being triggered at the partner level, and not the site level.

Network Protected Identity (NPI)

Network Protected Identity is a component of RBA that capitalizes on the data gleaned from the login activity of ~1.2 billion identities stored at Gigya, to benefit users of RBA and enhance overall security. An email or IP address which displays suspicious behavior (hack attempts) is automatically flagged, so that you can define a low threshold of failed login attempts from these sources, and automatically lock out the account, force it to pass a CAPTCHA challenge, etc. The relevant values are: 

  • global_IP
  • global_email

For more information, see Accounts RBA Policy Object.

  • NPI does not store any user data. The data it stores pertains only to suspicious account activity.
  • NPI does not in any way share user data.

 

Unable to render {include} The included page could not be found.

Configuration

For push notification configuration, see below.

Rules

To apply a new global rule: 

  1. Go to the RBA page in Gigya's Console.
  2. Under Global Rules, click Add Rule
  3. You can base the new rule on the existing templates, or create a custom rule. A template-based rule can be edited in the next step. 
  4. In the Add Global Rule window, the risk factor is defined under Root Factor, and the action taken if that factor is triggered, under Action. You can edit the following: 
    • Description
    • Status: can be switched on or off (this can be done from the RBA dashboard as well)
    • Root Factor: you can change the type, scope, threshold, ratioresetInterval and any other parameters that appear. For more information consult the Accounts RBA Policy Object, under the commonRules array. 
    • Action: you can change the type, scope,duration and authLevel, as relevant to the chosen root factor. For more information consult the Accounts RBA Policy Object, under the commonRules array.
  5. Click Save Settings

When setting custom Global Rules, only enter the actual value of the action/rootFactor property:

Correct Action field:

{
  "type": "TFA",
  "authLevel": 10
}

Correct Root Factor field:

{
  "type": "device",
  "authLevel": 10,
  "expirationPeriod": 300
}

Incorrect Action/Root Factor Fields:

"action": {
     "type": "TFA",
     "authLevel": 10
}
 
 
"rootFactor": {
     "type": "device",
     "authLevel": 10,
     "expirationPeriod": 2592000
}

 

Account Rule-Sets

Create Rule-Set 

  1. Go to the RBA page in Gigya's Console.
  2. Under Global Rules, click Add Rule-Set
  3. You can base the new rule on the existing templates, or create a custom rule. A template-based rule can be edited in the next step. 
  4. In the Add Rule-Set window, you can edit the following: 
    • ID: the unique ID of this rule. The ID must be unique and not start with an underscore _ . 
    • Status: can be switched on or off (this can be done from the RBA dashboard as well)
    • Rules: edit the JSON object according to the Accounts RBA Policy Object documentation. Note the Policy Examples
    • Click Apply

Configure How the Rule-Set Applies

Rule-sets are applied to user accounts by passing the details in the rba parameter of accounts.setAccountInfo together with the UID to which the rule applies.

Rule-sets can apply to designated users, or can be made the default rule-set to apply to all users. In addition, you can give permissions to the admin and the end-user to override the rule-set. 

  • To apply one rule-set to all logins, select the rule set from the Default Account Rule-Set dropdown. In this case, the selected rule will apply to all users together with the global rules
  • To allow an admin, or an admin and the end-user, to override the applied rule-sets, select the relevant option under Account Rule-Set Override

 

Saving the RBA configuration uses the accounts.rba.setPolicy REST API to set the RBA policy, passing your Gigya API key and the RBA policy object as parameters.

Verification Methods

Select all the verification methods that apply to your site: 

  • Email (auth level 10)
  • SMS (auth level 20)
  • Authentication app (auth level 20). If you select this method,  also enter a user-facing application name:



    For additional information on how TOTP functions, see https://tools.ietf.org/html/rfc6238.
  • Push TFA (auth level 30). For more information, see below

When more than one verification method is enabled, users will be presented with a drop-down from which to select their preferred method.

 

 

Twilio Credentials for Mobile Authentication

If you configured an authentication level of 20 (mobile), provide your Twilio credentials in the relevant section:

From Number is a Twilio definition of the number sending out the SMS. The Gigya configuration should match Twilio's. This must be a standard Twilio number (not a short code) and may only contain digits.

 

Push Notification

Push Notification, or Push TFA, allows you to step up your verification process using push notifications to any registered devices. 

Enabling push notifications requires setting up your app, and configuring the RBA settings in the SAP Customer Data Cloud Console. Push notifications require users to have an active session in your application. A push notification flow can be outlined as follows: 

  1. A user registers to your site or app and completes their registration as usual (this could require a TFA verification, up to level 20, but doesn't have to). 
  2. At some point, based on your business logic (e.g. after a user downloads your app and has an active session there, or after a specific app interaction), the user is asked to opt in to push notifications. This sends a push notification to the mobile application, that the user needs to approve. 
  3. After a user opts in, when later the user tries to login from another device (e.g. desktop), the user receives a push notification to their mobile phone, and can complete login only after approving the notification.. 
     


App Configuration

In order to add push TFA to your application you will need a working push notification/messaging account with Google Firebase. Instructions on how to add Firebase toyour Android application can be found here.

Once you have your Firebase up and running, you are able to register your application in the cloud messaging tab of your project settings page. This is used for configuring push notifications in the Customer Data Cloud Console, as explained below. 

To allow opting in using push TFA, you will need to add the option to opt-in after the user has successfully logged in.

Android

Step 1: Messaging Service

The Customer Data Cloud Android SDK provides a GigyaFirebaseMessagingService class for you. In order to integrate it, add the following to your AndroidManifest.xml:

<service
    android:name="com.gigya.android.sdk.tfa.push.firebase.GigyaFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

 

Our GigyaFirebaseMessaingService extends the provided FIrebaseMessaingService. If your application already uses the FirebaseMessagingService your will you will need to make your class extend the GigyaFirebaseMessaingService.

In order for all flows to remain intact make sure to call the relevant super methods:

@Override
public void onNewToken(String newToken) {
    // Calling the super method to enable the Gigya messaging flow.
    super.onNewToken(newToken);
}
  
@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    // Calling the super method to enable the Gigya messaging flow.
    super.onMessageReceived(remoteMessage);
}

 

Step 2: Adding the TFAPushReceiver

The push TFA notification contains a content pending intent (setContentIntent) which will trigger an Activity to open in order to handle the notification content. You will have to declare that activity in your AndroidManifest.xml.

The Android SDK provides a template, PushTFAActivity class, which handles the content intent for you and will display the relevant action UI and handle the selection.

In order to use the provided PushTFAActivity class, add the following to your AndroidManifest.xml file:

 

<activity
    android:name="com.gigya.android.sdk.tfa.ui.PushTFAActivity"
    android:excludeFromRecents="true"
    android:launchMode="singleTask"
    android:taskAffinity=""
    android:theme="@style/Theme.AppCompat.Translucent" />

Additionally, all action-based push notifications will add the relevant buttons to the notification body.

In order to allow the SDK to handle these actions, register the following Broadcast Receiver:

 

<receiver
    android:name="com.gigya.android.sdk.tfa.push.TFAPushReceiver"
    android:exported="false">
    <intent-filter>
        <action android:name="com.gigya.android.sdk.tfa.push_approve" />
        <action android:name="com.gigya.android.sdk.tfa.push_deny" />
    </intent-filter>
</receiver>

Available Customization Options

The Android SDK provides some customization options to add a your personal touch to the notifications or the content activity.

In order to apply customization, extend the GigyaFirebaseMessaingService class with your own custom service. If you do. Make sure to register your own service in the AndroidManifest.xml file instead of the GigyaFirebaseMessagingService class. Available customization overrides: 

public class CustomMessagingService extends GigyaFirebaseMessagingService {
 
    @Override
    public void onNewToken(String newToken) {
        super.onNewToken(newToken);
    }
 
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        super.onMessageReceived(remoteMessage);
    }
 
    @Override
    protected int getSmallIcon() {
        // Return your customized notification small icon. This cannot be null!!
    }
 
    @Override
    public Class getCustomActionActivity() {
        // Return your own content activity class. Note that you will have to handle all logic
        // and don't forget to register the activity in the AndroidManifest.xml file.
    }
 
    @Override
    protected int getApproveActionIcon() {
        // Return your customized approve action icon.
    }
 
    @Override
    protected int getDenyActionIcon() {
        // Return your customized deny action icon.
    }
}

Android Push TFA Flow

For users to opt in using a push notification, add the option for user opt-in after they log in to the app: 

GigyaTFA.getInstance().optInForPushTFA(new GigyaCallback<GigyaApiResponse>() {
    @Override
    public void onSuccess(GigyaApiResponse obj) {
        // Step one of the opt-in process has been completed.
        // Wait for approval push notification and to complete flow.
    }
 
    @Override
    public void onError(GigyaError error) {
        // Handle error.
    }
});

 

 

Console Configuration

To configure push notifications in the Customer Data Cloud Console

  1. Create an account rule-set, and select a rule that requires "level 30 or higher". Edit the rule as described above. 
  2. Under Verification Methods, select Auth Level 30: 
  3. To enter your Firebase Server Key:
    1. Open the Firebase console. select your project and open Project settings as shown: 
       
    2. Select the Cloud Messaging tab and copy your Server key.


    3. Enter the server key in the Customer Data Cloud console.
  4. Select a default rule-set (one of the rules configured with an auth level of 30). Push notifications must have a default rule-set configured. 
  5. Save your settings. 

 

 

Examples

Say you have configured the following policy, which is defined globally (as common rules and not rule sets): 

  • Trigger a phone TFA when logging in from a new device

    A device is determined by a cookie set in the user's browser, multiple browsers on the same platform/OS are considered as separate 'devices'. Deleting cookies will also cause logging in from the same browser to be treated as a new 'device'.

  • Trigger a lockout after 5 failed logins from a user account
  • Trigger a CAPTCHA after changing a country

 

Enable TFA Example

If you wanted to trigger TFA for every user on every login, you would accomplish this by creating a Common Rule for triggering TFA, you would set this rule to trigger on Device Change, and you would set the Device expirationPeriod to a very low integer, e.g., 10 seconds.

Example:

{
// Permanent TFA
    "enabled": true,
    "description": "TFA for all users always",
    "action": {
        "type": "TFA",
        "authLevel": 20
    },
    "rootFactor": {
        "type": "device",
        "authLevel": 20, 
        "expirationPeriod": 300                 
    }
}

For additional information on how TFA works, see Console Two-Factor Authentication.

 

Enforce Push TFA Example

{
 "rules": [
   {
     "description": "On device change, force verification of auth level 30 or higher",
     "action": {
       "type": "TFA",
       "authLevel": 30
     },
     "rootFactor": {
       "type": "device",
       "authLevel": 30,
       "expirationPeriod": 2592000
     },
     "enabled": true
   },
   {
     "enabled": true,
     "description": "On country change, force verification of auth level 30 or higher",
     "action": {
       "type": "TFA",
       "authLevel": 30
     },
     "rootFactor": {
       "type": "country",
       "authLevel": 30,
       "trustedCountries": [
         "US","CA","GB"
       ],
       "expirationPeriod": 2592000
     }
   }
 ]
}

 

 

Complete Policy Object Example

Using the aforementioned scenario, your full policy object will look like this: 

{
    "commonRules": [
        {
        // rule #1 - Lockout after 5 failed logins
            "enabled": true,
            "description": "Lockout",
            "action": {                
                "type": "lockout",
                "scope": [
                    "account"
                ],
                "duration": 43200
            },
            "rootFactor": {                
                "type": "failedLogins",
                "scope": [
                    "account","ip" //locks out both this account and the IP from which the attempts were made
                ],
                "threshold": 5,
                "resetInterval": 86400
            }
        }, 
		{
		// rule #2 - CAPTCHA after country change
            "enabled": true,
            "description": "CAPTCHA after country change",
            "action": {
                "type": "captcha",
                "scope": [
					"account"
				]
            },
            "rootFactor": {
                "type": "country",
                "scope":  [
					"account"
				],                
                "resetInterval": 3600
             }
        },
		{
		// rule #3 - Phone TFA from a new device
            "enabled": true,
            "description": "Phone TFA from new device",
            "action": {
                "type": "TFA",
                "scope":  [
					"account"
				]
            },
		  "rootFactor": {
                        "type": "device",
                        "authLevel": 20, 
						"expirationPeriod": 86400,                       
                    }
		}
    ],
}

 

As a result,

  • A user will see a lockout screen on their sixth login attempt
  • A user will be challenged by CAPTCHA after changing a country: 
  • A user will be required to enter a code from their phone when logging in via a new device:

For more examples, see RBA Policy object example.

 

Administration

Admin Actions

Site admins can use Identity Access to perform the following actions related to risk-based authentication: 

  • Reset TFA Devices: Reset the methods of identification used as the second factor for authenticating the user (e.g., phone number, authentication app). In their next login, they will need to register a device.
  • Force TFA Expiration: Force the user to provide second-factor authentication the next time they log in.
  • Unlock Account: Unlocks a user account that is locked out due to a triggered RBA policy (for example, 3 unsuccessful login attempts). 

User Actions

Once a user has selected a second authentication factor, they can only change it if an admin resets their TFA devices.

Users can edit the information relating to that factor in the Update Profile screen: 

  • If the user has authenticated with a phone number, they may edit that number. 
  • If the user has authenticated with a time-based authenticator, they may change their device (re-scan the authenticator barcode), and print backup codes to use when their device is inaccessible.

Auditing

To review Risk-Based Authentication errors using the Audit Log, go to the Audit Log located inside the Gigya Console. In the Date Range change the From field to a couple of days previously, and the To date to the next or current day. Next, uncheck the Configuration updates only checkbox so that you retrieve results for all events. Finally, select Custom Where Clause and enter errCode !=0. This will display all log entries for failures such as login failure, account locked out, etc.

 

To search for all errors for a particular user you can use their UID and a custom query similar to the following:

errCode != 0 AND uid = '<UID of the user>'

 

Additional Information

RBA is only supported when using client-side (Web SDK) calls to Gigya's servers and is not supported when using REST API login/registration flows.