Gigya Job Openings

User Enabled TFA

Skip to end of metadata
Go to start of metadata

Description

It is possible to give users, on a case-by-case basis, the option to enable TFA (Two-Factor Authentication) for their account using Gigya's RBA (Risk-Based Authentication).

When TFA is enabled for a user's account, it will require them to enter a code received to their phone or email in order to login to the site. The frequency of TFA verification is globally configurable within the RBA policy settings.

To enable this ability for your users, there are several steps that need to be completed. This page will outline how to set up a simple TFA flow using RBA and RaaS Screen-Sets.

This document can be used as a reference to set any type of RBA rule on a user-specific basis, however, TFA is the option used herein.

 

Configure an RBA Policy

First, you must configure an RBA policy supporting TFA. 

Navigate to the RBA page of your Gigya Console.

 

Once there, select the Add Rule-Set button from the Accounts Rule-Sets section. This will open the Add Rule-Set dialog. Select Custom Rule-Set.

 

Now you will be in the Rule-Set editor. Enter a unique name for this new rule that describes what it does, i.e., 'TFA.phone.exp-2600000'.

 

By default, a new custom rule-set has an empty rules object. You must now configure the rule to enable TFA. You can do that by copying the following code and entering it into the window; you can then adjust the properties to fit your specific use-case.

{
  "rules": [
    {
      "action": {
        "authLevel": 20, // 20 specifies phone SMS verification (this must be equal to or greater than the authLevel of the rootFactor)
        "type": "TFA" // Specifies the type of action to perform, in this case we want TFA
      },
      "rootFactor": {
        "type": "device", // Designates the client that will trigger the rule-set. Device can be any client, i.e., a mobile device or any unique web browser.
        "expirationPeriod": 2600000, // The length of time, in seconds, between triggering the rule-set
        "authLevel": 20
      },
      "description": "", // a friendly description of the rule
      "enabled": true
    }
  ]
}

 

Once you have configured the rule-set, press Apply, and ensure that it's Status is set to Enabled.

Next, make sure that you define the Account Rule-Set Override to Admin and end user, and make sure you have activated Auth Level 20 - Mobile under Verification Methods.

Selecting Auth Level 10 - Email requires additional configuration for your account. For TFA it is recommended to only use SMS (Auth Level 20) verification which is supported out of the box.

 

 

Finally, scroll to the bottom of the page and press Save Settings.

 

Configure Screen-Sets

Navigate to the Screen-Sets page of your Gigya Console. We are going to create a new screen-set collection, however, you can also apply the following information to an existing screen-set collection.

 

Create a new Screen-Set collection by pressing the Add New Collection button and filling out the necessary information.

Open the ProfileUpdate screen-set of the new screen-set collection in the UI Builder.

Select the Update Profile screen from the Screens menu, and press Clone Screen.

 

Give the new screen a name and ID that describe it's function. We are using user-activated-tfa-screen.

On the new screen, delete all fields except the First name, Last name, Email, and the links on the bottom (Change password, Verification methods, and Change password - it is especially important not to delete the Verification methods link, as this will be used by TFA).

Add two new Link Controls and label them Add a TFA device and Configure TFA RBA Policy for your account, respectively.

 

Your screen should look similar to the following:

Fields that have a dashed yellow border are conditional and only display if certain conditions are met via the Visible When attribute.

 

For the First name, Last name, and Email fields, select them one at a time and in the Properties panel make them all Read only.

If your site does not require a user to have any of these fields, you can set a Visible When attribute so that they will only appear if the user has data for the fields. You can do that by entering the following code into the Visible When field (where profile.lastName is the name of the field as defined in the site's schema).

((typeof(profile.lastName) !== "undefined") && (profile.lastName !== ""))

 

Now we need to add additional Visible When attributes to the new Link Controls that were added, so that the appropriate link displays, according to the user's Registered Devices status.

For the Add a TFA device link, set Visible When to:

tfaProviders.activeProviders.length === 0

 

Next, for the Add A TFA device link, set it's behavior to Screen: From other screen-set: and select the RegistrationLogin screen of the current Screen-Set, and for the Screen, select TFA Registration.

 

For the Configure TFA RBA Policy for your account link, set Visible When to:

tfaProviders.activeProviders.length > 0

 

Save the Screen-Set.

Select the current user-activated-tfa-screen in the left-hand Screens menu and press Clone Screen.

Give the new screen a name and ID; we are using enable-user-activated-tfa.

On the new screen, delete the Add a TFA device and Configure TFA RBA Policy for your account links.

Add three new Link Controls labeled Enable TFA, Disable TFA and Cancel.

 

You can customize the look and feel of these links using the CSS Classes field of the Controls in the Properties panel and then adding a CSS style to the CSS Styles editor of the screen-set (being sure to use the !important modifier).

       

 

Configuring the Link Controls

Select the Cancel link, in the right-hand Properties panel select Screen: None (close screen).

 

Select the Enable TFA link, in the right-hand Properties panel select External URL: and add the following JavaScript to the field, being sure to change the name of the RBA Policy to reflect the name of the policy you set up at the beginning of this tutorial and the "screenSet" property reflects the name of the current Screen-Set, i.e., "Default-ProfileUpdate".

javascript:(function(){
	gigya.accounts.setAccountInfo({
 		"rba": {
 			"riskPolicy":"TFA.phone.exp-2600000" 
 		},
 		"callback":function(re){
 			console.log(re);
 			if (re.errorCode === 0) {
 				gigya.accounts.hideScreenSet({
 					"screenSet": ProfileUpdateScreen
 				});
				console.warn("RBA riskPolicy Updated!");
				alert("TFA RBA Policy was Enabled!");
 			}
		}
	});
}());

 

Select the Disable TFA link and in the right-hand Properties panel select External URL: and enter the following JavaScript in to the field (ensuring you update the "screenSet" value to reflect the name of the current Screen-Set):

javascript:(function(){
 	gigya.accounts.setAccountInfo({
 		"rba": {
 			"riskPolicy":null
	 	},
 		"callback":function(re){
 			console.log(re);
 			if (re.errorCode === 0) {
 				gigya.accounts.hideScreenSet({
 					"screenSet": ProfileUpdateScreen
 				});
				console.warn("RBA riskPolicy Updated!");
 				alert("TFA RBA Policy was Disabled!");
 			}
 		}
 	});
}());

 

Finally, return to the first cloned screen we created (user-activated-tfa-screen) by selecting it from the left-hand Screens panel and select the Configure TFA RBA Policy for your account link and in the right-hand Properties panel select Screen: and point it to the 2nd cloned screen that we created (enable-user-activated-tfa).

Save the screen-set.

The Console setup is now complete. To allow users to enable TFA for themselves, you should add a way for users to trigger the user-activated-tfa-screen on your website.

 

Additional Information

There is a working demo of the flow described here, located on our Demo site at: https://gigyademo.com/bin/simple-tfa/

Due to the internal logic of the Gigya TFA screens, you will need to re-open the screen after adding a TFA Device in order to enable RBA (by pressing the TFA Configuration button again).