How Adaptive Rulesets Work

The figures below are a high-level overview of the data sources for Adaptive Rules as well as the overall flow of how they work with registration and authentication. Context data and signals can also be generated by the Nok Nok servers but this has been omitted. You can find a full example of registration and authentication using Adaptive Rulesets in the Adaptive Rulesets section of Features.

Figure 5 Adaptive Registration Overview

Figure 6 Adaptive Authentication Overview

Although you may have defined several rulesets, the Auth Server uses one Adaptive Ruleset when it performs either Adaptive Registration or Authentication.

The Auth Server determines that ruleset for either registration or authentication using the following process:

1. If the client app is configured to use a specific Adaptive Ruleset then use it.

2. If there is an Adaptive Ruleset called default, then use it.

3. If all the previous steps fail, then registration or authentication fails.

Only Registration Decision Rules are used for registration while Authentication Rules are only used for authentication. For either registration or authentication, the Auth Server executes the associated rules in the Adaptive Ruleset in order until one rule's condition succeeds. At that point, the Auth Server stops and returns the decision along with any other information. Prior to returning any sequences, the Auth Server filters out any methods that are not applicable to the user or device. For example, the device doesn't support a method or the user didn't register the method.

Sometimes you won't know a FIDO authenticator's actual characteristics until after the user has registered it or used it to authenticate. This is especially the case with FIDO2 authenticators. Likewise, you can make decisions based on the device that was used for the FIDO operation. You can still enforce your organization's criteria at this point in the process by using a PostOperation Check in an authentication rule, or by using a Supplemental Check in a registration decision rule.

A PostOperation Check or a Supplemental Check validates that an authenticator and/or device conforms to your organization's specification and then performs an action. A PostOperation Check or a Supplemental Check can test any of the characteristics contained in the authenticator's metadata statement as well as properties of the device that the end user utilized. It can determine if the authenticator is a platform authenticator. With respect to authenticator characteristics, the Attestation Type characteristic is critical because it represents the degree of certainty in the authenticator model. Consequently, it should always be present when the PostOperation Check or a Supplemental Check contains other authenticator properties. You can only reliably test other authenticator characteristics if Attestation Type is full or attca.

Although you can define a PostOperation check or a Supplemental Check for a non-FIDO authentication method, that check can only contain the device ID characteristic. See Authenticator and Device Characteristics for the characteristics you can use in a PostOperation Check or a Supplemental Check.

A PostOperation Check's primary function is to perform an action that can bypass the remaining methods in a sequence. As a result, you can only create one if an authentication method is followed by at least one other authentication method in the sequence.

In order to create the rules that make up a ruleset, you need to know the data you can potentially use. Data from your app falls into 2 categories: signals and context data. Signals refer to information that the mobile device tracks such as the device model, IP address, user location, and WiFi network. Signals can also be information that the Auth Server can access, such as IP address. In addition, signals are information that the Server can derive about the user, such as velocity.

Context data is custom information that your business uses to make intelligent registration or authentication decisions, such as the transaction amount, transaction type, and timestamp of the last secure sign-in. Context data can be supplied by you or generated by Nok Nok. Additionally, you can access user history from the Auth Server about a user's last known login date and time, location, IP address, and the WiFi network.

Your organization's authentication criteria are implemented in Adaptive Rulesets. Each ruleset contains an ordered set of one or more Registration Decision Rules and an ordered set of one or more Authentication Rules. A rule is similar to an if-then statement since it has a condition and an action. Adaptive Rules have three additional, unique features: sequences, Authentication Checks, and claims. Rule components are described below.

• Condition: Compares signals, context data, and user history against values and lists of values. See Data Used in an Adaptive Rule's Condition for the complete list of data you can use in a condition. If the condition evaluates to true (succeeds), the rule's action is processed.

• Action: Valid outcomes, depending on the type of Adaptive Rule.

  • For Registration Decision Rules: Specifies the decision affecting registration. One of suggest registration, enforce registration, deny, or ignore registration.

  • For Authentication Rules: Specifies the authentication decision. One of allow, deny, or trigger authentication.

• Claims: If the action is to allow authentication or to trigger authentication, you can optionally include one or more claims. A claim is a name-value pair of data, like Department: security, or Prompt-for-Password: true. It allows your app or backend server to receive custom information after a user successfully authenticates.  Claims are of two types - static and 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.  

  
  When an Adaptive Rule returns one or more claims, the API Server inserts those claims into its session token, a JWT. The API Server sends the authentication response, which includes the JWT, to the App SDK. Your client app is responsible for sending this JWT to your backend server. Your backend server extracts the claims and processes them.
  
  A special type of claim is a FIDO 3DS (Three Domain Secure) blob. This object encapsulates data that confirms that users have authenticated with FIDO and is used by the payments industry. A FIDO 3DS blob can be retrieved by the client app from the authentication results.

• Sequences: An ordered set of authentication methods. The use of a sequence is dictated by whether it is contained in a Registration Decision Rule or Authentication Rule. If a sequence contains FIDO authentication (defined by a FIDO policy) and other authentication methods, always make FIDO authentication the first in the sequence.
  
  For a Registration DecisionRule: If the action is either suggest registration or enforce registration, you must define at least one sequence containing one or more authentication methods for the user to register. Registering the methods from one sequence guarantees that the user has the necessary methods to authenticate in the future.
  
  For an Authentication Rule: If the action is trigger authentication, you must define at least one sequence containing one or more authentication methods.

  • All methods listed in one sequence must be satisfied before a user is successfully authenticated, unless there is a PostOperation Check that succeeds and exits the sequence. You can think of these methods as being joined by AND.

  • Multiple sequences represent alternative ways that the user can be authenticated. As long as the user successfully verifies their identity with the methods listed in any one of those sequences, they are authenticated. You can think of these sequences as being joined by OR.
    
    Each sequence is intended to target a specific user segment. For example, smartphones that have biometric authentication, desktop and laptop computers that rely on a remote authenticator that connects to them using CTAP (for example, USB, NFC or Bluetooth), mobile devices without biometric authentication, and smart watches. As a result, order is irrelevant for multiple authentication sequences.

• PostOperation Checks and Supplemental Checks: Like Adaptive Rules, a PostOperation Check or a Supplemental Checkhas a condition and action. It compares authenticator and/or device characteristics to a value or a set of values. If the comparison succeeds, the PostOperation Check functions similarly to a break statement and enables the Authentication Server to perform a different action instead of processing the remaining methods in a sequence. See Authenticator and Device Characteristics for the complete list of characteristics that you can use in a PostOperation Check or a Supplemental Check.
  
  The action performed differs for a Registration Decision Rule versus an Authentication Rule.

  • For a Registration Decision Rule, the only action is Done.

  • For an Authentication Rule,the action can be one of Allow, Deny, or Drop Sequence.

Data Used in an Adaptive Rule's Condition

You can use the following types of data in a rule condition.

• App SDK Version: The Nok Nok App SDK version used by your mobile or web app. A signal. You can create rules that use the version number of the App SDK since that may affect the type of data you can use in a rule's condition or approved FIDO authenticators that a user can register.

• Context Data: Context data is information outside of Nok Nok's signals and user history that you want to factor into an authentication decision. For example, by using transaction amount and type as context data, you can create rules that can enforce PSD2 compliance for low-risk, medium-risk, and high-risk transactions. Your client app is responsible for passing in the context data to the App SDK authentication method. See Sending Signals and Passing in Context Data in the iOS, Android, and Web Developer Guides.
  
  The S3 Suite also defines or generates context data, see Nok Nok Context Data.

The following names are reserved for SPC. Do not use them for your context data names: payment.isSPC, payment.rpId, payment.payeeName, payment.payeeOrigin, payment.total.currency, payment.total.value, payment.instrument.displayName, payment.instrument.icon.

• Device Health: The device's health based on the available jailbreak signal. A signal.

• Device ID: Either "is known" or "is not known". A signal. For more information, see the table in Authenticator and Device Characteristics.

• Device is Shared By: The number of registered users who share the device. More users indicates more risk. A signal.

• Device Manufacturer: The manufacturer of the user's device. A signal.

• Device Model: The model of the user's device. A signal. Some device models have known security vulnerabilities and you can create a rule that denies authentication or requires that the user authenticate with other methods. For example, if the fingerprint sensor on a device is known to authenticate a fingerprint that doesn't belong to a registered user, a rule could trigger password authentication.

• Device Operating System Version: The operating system version of the user's device. A signal.

• Device Operating System: The operating system of the user's device. A signal.

• Device Supports Platform Authenticator: Whether or not the device supports platform authenticators. A signal.

• Device Type: The type of the user's device. A signal. One of "android", "ios", or "browser". A signal.

• IP Address: The IP address of the user's device. A signal.

• Last Login (time): Applies only to Authentication Rules. The user's last login time. User history.

• Last Login Location: Applies only to Authentication Rules. The user's geographical location when they last logged in. User history. In a rule condition, last login location can be compared to a list of countries, compared to a list of geofences, or be within a certain distance of the current location.

• Location: The user's current geographic location. A signal. In a rule condition, location can be compared to a list of countries, compared to a list of geofences, or within a certain distance of a specified location.
  
  If you are implementing a web app and want to use rules based on lists of countries, you must perform additional configuration. See Configure the Google Geocoding Service.

• Transaction: Applies only to Authentication Rules. Specifies whether or not the user is performing a transaction confirmation. Either "true" or "false". A signal.

• Velocity: Applies only to Authentication Rules. Calculated from the user's current location, current time, their previous location, and their previous time. A signal.
  
  Determines whether the user could have reasonably traveled to their current location from their last-logged location. This is useful for detecting fraudulent activity. For example, it's unlikely that someone who last logged in to their phone 10 minutes ago in London would be in Paris. Use a maximum feasible travel speed for velocity.

• WiFi Network: The WiFi network the user is connected to. A signal. You can restrict the use of your app to specific WiFi networks if your app requires a secure setting.

If you use device health, location, or WiFi network in your rules, the client app developer must configure these signals so the App SDK sends them to the Authentication Server.

• See Configuring Signal Generation in the Android or iOS Developer Guide.

• Web apps send location, not device health or WiFi network. See Sending the User Location Signal in the Nok Web Developer Guide.

The following table shows the data that Adaptive Rules can use, organized by protocol, App SDK, and OOB. The Notes can be found after the table.

Table: Availability of Signals Used in Adaptive Rules by Protocol, App SDK, and OOB

1. You must configure the App SDK to send this signal. See Configuring Signal Generation in the Android or iOS Developer Guide.

2. To get this signal, you must enable the IP Address Extractor plugin on the API Server.

3. Location is sent subject to the end user's consent. You must also configure the App SDK to send the signal. See section Sending the User Location Signal in the Nok Web Developer Guide. or Configuring Signal Generation in the Android or iOS Developer Guide.

4. Velocity is calculated by the Auth Server based on the current location and the previous location, if available. Velocity is subject to the same requirements as location.

5. WiFi SSD is sent subject to the end user's consent. You must also configure the App SDK to send this signal. See Configuring Signal Generation in the Android or iOS Developer Guide..

6. The web app sends the device model if the UA Parser plugin is enabled on the API Server and the user agent string contains the device model. You are more likely to get this information if the web app is running in a mobile browser.

7. The device type is always browser.

8. The web app sends the device manufacturer if the User Agent Parser plugin is enabled on the API Server and the user agent string contains the device manufacturer. You are more likely to get this information if the web app is running in a mobile browser.

9. The web app sends the device operating system and version if the User Agent Parser plugin is enabled on the API Server and the user agent string contains the device operating system and version. You are more likely to get this information if the web app is running in a mobile browser.

10. In OOB, Adaptive Rules are executed using signals from a web app running on a primary device, not the mobile app performing auth that is running on the second device. In version 5.0.0, the Android and iOS App SDKs were enhanced to support OOB in apps on the primary device, although this feature is rarely used.

11. Refer to footnotes listed in data columns for FIDO2 JavaScript.

12. In App-less OOB, Adaptive Rules are executed using signals from a web app running on a primary device, not the browser performing auth that is running on the second device.

Nok Nok Context Data

The S3 Suite provides additional information of its own as context data.

• providedLocation: Specifies a second location, like the user's home, that is compared to the user's current location. The current location has to be within a certain radius of providedLocation. When a rule's condition contains Location and the operator is within provided location, it is implied that the comparison is with providedLocation.
  
  You do not have to specify this as context data in the Adaptive Rule editor. Your client apps are responsible for supplying a value for providedLocation. See Sending Signals and Passing in Context Data in the iOS, Android, and Web Developer Guides.

• Session Information: Information available from Nok Nok's session token, a JWT. A JWT includes claims specified by Nok Nok's API Server and, optionally, custom claims provided by your backend server. The API Server extracts these claims from a validated JWT. It creates a context data item for each claim by prepending "session_" to the claim name. For Nok Nok's claim names, see API Server JWT Claim Set.
  

  The string session_* is reserved. Do not use this string pattern for your context data names.

  Additional references for the API Server's session token:

• Understanding the Session Token

• JWT Format

Authenticator and Device Characteristics

You can use the authenticator and device characteristics to make registration and authentication decisions. The Nok Nok S3 Suite intelligently detects critical data including whether a credential has been synced to the current device, which specific passkey credential provider is in use, and the user identifier linked to the credential provider. Also, authenticator characteristics are present in an authenticator's metadata statement. To get the latest metadata, see Update Authenticator Metadata. Refer to the authenticator and device characteristics listed in the table below when you create the condition in a PostOperation Check or in a Supplemental Check.

Authenticator characteristics depend on knowing the authenticator model. PostOperation Checks or Supplemental Checks that depend on authenticator characteristics listed below must include Attestation Type is full or attca in the condition to ensure the characteristic is valid. The only exception to this is platform authenticator which does not depend on Attestation Type.