Step 5. Create adaptive rulesets

Once you have configured any non-FIDO authentication methods you plan to use and created your supporting data lists and FIDO policies, you are ready to create your Adaptive Rulesets.

1. In the Admin Console, login to the correct tenant. Navigate to Authentication > Adaptive Rulesets.

2. On the Adaptive Rulesets page, click Add Adaptive Ruleset or edit an Adaptive Ruleset.

3. On the Adaptive Ruleset page, enter a ruleset name and description.

4. Click Add Rule in either the Registration Decision Rules or Authentication Rules section to add rules.

5. On the Registration Decision Rule or Authentication Rule page enter the rule name and description.
   A rule name can contain letters, digits, and the following characters: hyphen (-), forward slash (/), underscore (_) and space ( ).
   A rule's description should describe what it's testing for and its intention.

The sections below walk you through the process of creating an Adaptive Rule. After you finish defining your rules, examine their order. You can reorder a rule by dragging and dropping it in a new location. To test and use a ruleset, activate it.

Step 5A: Add the condition

The built-in Condition Builder enables you to quickly construct an Adaptive Rule's condition.

Since there are many types of data you can use in a rule, they are organized by category as seen below. Click Add Condition to see this drop-down list.

For a complete list of the conditions you can use in an adaptive rule, see Data used by Adaptive rules and FIDO policies. If you select Network, the data dropdown displays IP Address. But the network category contains one other related data item. You see both IP Address and WiFi Network when you click on the dropdown, as shown below. Only the location, network, and device categories contain multiple data items.

Next, specify the operator and value or list to compare against. The operators and values listed in the menus change dynamically depending on the data type. You can quickly select from a drop-down list by typing the first letter of your selection. Retyping that letter advances to the next matching list item.

If the operator can be "is in" or "is not in", then you can create a new list of values by clicking New. Click the trash can icon to delete the clause.

When you add the second condition, specify the logical operator to use to join all your conditional clauses, either AND or OR. You can reorder clauses by dragging and dropping them. Below is an example condition with 3 clauses.

If you use Location with the operator is within provided location, you must specify the provided location using context data in your client app. See Sending Signals and Passing in Context Data in the iOS, Android, and Web Developer Guides.

Using context data

Context data is handled differently from signals and user history. This section walks through an example showing how to add payment amount. Select Context Data from the Add Condition drop-down menu.

The Admin Console adds a new clause, shown below.

Since the Admin Console has no knowledge of context data, you need to provide a name and select its datatype. The name is case-sensitive. For our payment amount example, enter the text PaymentAmount in the Context Data textbox, select Double as the data type, select the desired operator, and enter a value.

If your value is a string that contains spaces, use single quotes to delimit your string. Otherwise, do not quote the string. If your value is a list, use a comma-separated list of values. Parentheses are not needed.

The names you use for context data must match the names your mobile and web apps send to the Auth Server when they initiate authentication. See section Sending Signals and Passing in Context Data in the iOS, Android, and Web Developer Guides for how to send context data.

Using a custom condition

Use a custom condition for greater control over the execution order of your conditional clauses or to create a rule that tests for True in its condition. Once you change a condition to be a custom condition you cannot change it back.

To create a custom condition, click Custom Condition in the Conditions section.

For a rule with True as its condition, enter Boolean TRUE.

If you have an existing condition that you created with the Condition Builder, clicking Custom Condition converts it into a Java expression. Use the logical Java operators and parentheses to control the execution order of your expression. Below are 2 examples of a rule condition and their corresponding custom condition expression.

Corresponding Java expression:

(AdaptiveNetworkRulesHelper.isWifiNetworkAvailableInList($contextData,$tenant,"Work")) && 
(!AdaptiveDeviceRulesHelper.isDeviceModelAvailableInList($device,$tenant,"S10-Devices")) &&
(!AdaptiveLocationRulesHelper.isLocationInList($contextData, $tenant, "High Risk Countries" ))

Sample condition containing context data:

Corresponding Java expression:

($contextData.isDoubleLessThanEqualTo("PaymentAmount", 30)) && 
($contextData.isStringEqualTo("TransactionType", "PAYMENT")) && 
($contextData.isStringEqualTo("PaymentVenue", "ContactlessPOS")) && 
($contextData.isDoubleGreaterThanEqualTo("SumContactlessPayments", 150))

You can edit the expression to group clauses and intermix the use of logical operators. The expression can call boolean Java functions.

Step 5B. Select the Action

Click the Action drop-down. For a Registration Decision Rule, select one of:

• Suggest Registration: The user can register one or more methods listed in the sequence. They can defer registration or cancel out of it.

• Enforce Registration: The user must register all the methods listed in the sequence so they can successfully authenticate in the future.

• Ignore Registration: The user is unable to register.

• Deny: The user cannot register.

For an Authentication Rule, select one of:

• Trigger Authentication: The user is authenticated only if they successfully complete one or more methods specified in the authentication sequences.

• Deny: The user's authentication attempt is rejected.

• Allow: The user is authenticated and doesn't need to do anything else.

Step 5C. Modify the maximum time allowed

You can specify how long the user has to execute the most time-consuming sequence defined for your rule using the Maximum Time Allowed (seconds) textbox. The default is 180 seconds which is 3 minutes. If the user exceeds this time limit, then authentication fails.

User authentication with non-FIDO methods, such as Photo ID and email OTP, takes longer than with FIDO methods. If your rule contains non-FIDO methods in its sequences, then you can customize this time to allow 5 minutes for OTP Using Email/SMS, or 10 minutes for Photo ID. If your rule requires more than one authentication method, for example one FIDO and one FIDO OOB, then you can set the maximum time to 6 minutes to allow 3 minutes for each authentication method.

Step 5D. Enter sequences

To add a sequence, click Add Registration Sequence on the Registration Decision Rule page, or click Add Authentication Sequence on the Authentication Rule page. Override the default name of your new sequence to make it more meaningful and take a note of it if you need to use that sequence name in a dynamic claim. Select the authentication method. For FIDO Auth and FIDO OOB Auth, you must select an active FIDO policy. That policy specifies a list of UAF authenticators and/or the desired characteristics of FIDO2 authenticators approved for use by your organization.

Any updates made to a FIDO policy are used by the Auth Server and App SDK when they process the authentication method.

You can optionally provide a reason code for an authentication method. This is used by the mobile or web app to explain to the user why they are being prompted for this authentication method. The Digipass S3 App SDK uses the reason code to retrieve and display the corresponding text to the user. Providing a reason code for the second authentication method in a sequence allows your app to tell the user why they are being asked to authenticate with a second method. To define the reason code's text explanation, see the Digipass S3 App UI Customization Guide.

To add another method to the sequence, click Add Method. Non-FIDO authentication methods are not as secure so it's a good idea to list 2 or 3 together in one sequence.

If you have FIDO Auth in an authentication sequence followed by another authentication method, then you can create a Post Operation Check for that FIDO Auth. You can also define a Post Operation Check if you use FIDO OOB Auth or a non-FIDO authentication method. However, a Post Operation Check for a non-FIDO method can only use device ID.

To add a Post Operation Check to an authentication sequence, click Add Post Operation Check. A Post Operation Check also has a built-in condition builder.

Add a clause by selecting the authenticator or device characteristic, operator, and value(s) from the dropdowns. See Risk signals for a description of the characteristics. To add more clauses, click Add Post Operation Check.

To complete the PostOperation Check in an Authentication Rule, select the desired action which is triggered when the condition evaluates to true. One of:

• Allow Authentication: Authentication is complete because the condition detects a strong authenticator and secure device.

• Deny Authentication: Authentication fails because the condition detects a weak authenticator or unsecure device.

• Drop Sequence: Authentication with the current authentication sequence fails because the condition detects a substandard authenticator. The Authentication Server switches authentication to use methods from an alternate sequence, if one is available from the succeeding Authentication Rule.

For an Authentication sequence you can enter an optional risk score for the Authentication sequence, which is returned if the user is successfully authenticated with this sequence. Note that the Auth sequence risk score is a different risk score than the FIDO auth policy risk score. A FIDO auth policy risk score is used by the FIDO policy’s logic to determine if the FIDO policy’s action is allow or deny. It is up to you to implement the logic on how to interpret the Authentication rules’s risk score. See Data used by Adaptive rules and FIDO policies for more information about risk scores.

You can continue to add more authentication sequences.

Add a Supplemental Check to a Registration Decision Rule to evaluate the end user's existing authenticator registrations and determine whether additional authenticator registrations are needed. These supplemental checks help ensure that the registered authenticators meet enterprise-grade security and compliance standards. A Supplemental Check in a Registration Decision Rule can only be used to complete registration and skip the remaining methods in the registration sequence. In this situation, the condition of the Supplemental Check must test for a strong authenticator.

The order of sequences within a ruleset doesn't matter. See Sequences under How Adaptive Rulesets Work.

Step 5E. (Optional) Add a claim

To send custom data to your backend server after a user successfully authenticates, create a claim. Claims are returned in the session token. For more information, see Claims under How Adaptive Rulesets Work. Your claim can be static or dynamic. A static claim has a hardcoded value that you provide while creating the rule. A dynamic claim has a value that is determined at runtime.  

Add a static claim

To add a static claim, click Add Static Claim. Enter the name and value of the data item. The example below shows how to create a claim called SylvanianIndex with a value of 95.

Add a dynamic claim

To add a dynamic claim, click Add Dynamic Claims From List and enter the data item’s name and select a value from the list. The example below shows how to create a claim called CountryCode.

For information about Risk Scores, see Data used by Adaptive rules and FIDO policies.

Toggle on Include EMV 3DS Data to have that data sent. EMV 3DS is a protocol developed by EMVCo that enables consumers to authenticate themselves when making credit card-not-present purchases. The App SDK includes the EMV 3DS information inside the SessionData object only when the API Server's EMV 3DS plugin is active. By default this plugin is active. If you have deactivated this plugin, see EMV 3DS Generator Plugin for instructions to reactivate it.