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 Digipass S3 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 Post Operation Check or a Supplemental Check validates that an authenticator and/or device conforms to your organization's specification and then performs an action. A Post Operation 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 Post Operation 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 Post operation check or a Supplemental check for a non-FIDO authentication method, that check can only contain the device ID characteristic. See Risk signals for the characteristics you can use in a Post Operation Check or a Supplemental Check.

A Post Operation 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 Digipass S3. 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 by Adaptive rules and FIDO policies 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 Decision Rule: 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.

• Post Operation Checks and Supplemental Checks: Like Adaptive Rules, a Post Operation Check or a Supplemental Check has a condition and an action. It compares authenticator and/or device characteristics to a value or a set of values. If the comparison succeeds, the Post Operation 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 Risk signals for the complete list of characteristics that you can use in a Post Operation 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

See Data used by Adaptive rules and FIDO policies for a detailed list of conditions you can check for in an adaptive authentication rule or an adaptive registration rule.

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 Web Developer Guide.

Digipass S3 context data

Context data is information outside of the Digipass S3 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 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. The string session_* is reserved. Do not use this string pattern for your context data names.

Digipass S3 Authentication Software 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 the Digipass S3 session token, a JWT. A JWT includes claims specified by the Digipass S3 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 the Digipass S3 claim names, see API Server JWT Claim Set.
  For more information about the API Server's session token, see Understanding the session token and JSON web token format.

Authenticator and device characteristics

You can check risk signals when you define Post operation rules and Supplemental checks. Risk signals evaluate authenticator and device characteristics to make registration and authentication decisions. Digipass S3 Authentication Software detects risk signals 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 Risk signals for details when you create a Post operation check or a Supplemental check.