Example - Calculating the risk score for the Fingerprint module

This chapter describes some sample calculations of the risk score for the Fingerprint module. It also illustrates the terms used in nevisAdapt. The risk score calculation of the other modules is similar to the one of the Fingerprint module.

Preconditions

• The Fingerprint module is enabled. Also, the device fingerprint is present in the HTTP request. That is, the fingerprintjs2 technology is integrated in the application and/or in nevisLogRend.
• The thresholds are as follows: the "established" threshold is 3, the "known" threshold is 1 and the "trained" threshold is 1.
• The risk score mapping is as follows:
  • Fingerprint is "established" → risk score "0"
  • Fingerprint is "known" → risk score "0.3"
  • Fingerprint is "unknown" → risk score "0.7"
  • Fingerprint is "shared" → risk score "0.05"
  • Fingerprint is "private" → risk score "0"
• The time frame is set to 60 days.

Trained/untrained

A user is trained, if the number of user requests with stored context data is higher than the configured threshold. The numbers are considered per module. The default value is 1, which means that the first login for each user is ignored.

In our example, a user is trained if the Fingerprint module has stored one device fingerprint for this user (see the list of preconditions above). The stored fingerprints must not belong to the same device. It is possible that the user has used two different devices, and has thus generated two different device fingerprints.

As long as a user is untrained, the Fingerprint module will not calculate a risk score for this user's HTTP requests. In our use case, this means that the Fingerprint module will return "untrained" responses without risk scores for the first login of this user. As of the 2nd login, the Fingerprint module considers the user as "trained". As of this moment, the Fingerprint module will start calculating and returning risk scores for this user.

Fingerprint analyzer - unknown/known/established

The fingerprint analyzer checks how often a specific device is used by a specific user. The more often a device is used by a user, the more known is this device to the Fingerprint module for this specific user.

The first time a user sends an HTTP request with a new device, this device is unknown to the Fingerprint module: The device fingerprint has not been stored yet.

As soon as the user logs in again with the same device, the Fingerprint module considers the device as "known". To become established, the user must log in with the device at least as often as the defined "established" threshold, which is three times in our use case.

Time frame

nevisAdapt only considers context data observed within a configurable time frame, and "forgets" about all context data with an older history. For example, a user logs in with a device that he used more than 2 months ago for the last time. The set time frame is 60 days. In this case, nevisAdapt will consider the device as "unknown".

The following example illustrates the meaning of the time frame for the risk calculation of the Fingerprint module:

• Suppose a user used device "A" seven times, however only two times within the last 2 months. This means that the Fingerprint module will only consider the two last times for the risk score calculation.
• The same user used another device "B" fifteen times, all in the past 2 months.
• If this user logs in with device "B", his request will be considered as a low risk request:
  • The user used the device 15 times within the specified time frame of 60 days. This is more often than the "established" threshold of three times, which results in a risk score of "0" (see the list of preconditions).
• The next time, the user logs in with device "A". This will result in a higher risk score:
  • The user used device "A" only two times within the specified time frame of 60 days. This is lower than the "established" threshold of three times, however higher than the "known" threshold of one time. This results in a risk score of "0.3" (see the list of preconditions).

Fingerprint sharing analyzer - shared/private

The fingerprint sharing analyzer checks how many different users use the same device within the given time frame. Contrary to the fingerprint analyzer, the fingerprint sharing analyzer counts all sessions, not only the terminated ones.

There are two available options: "private" and "shared". Consider the following use cases:

• The user logs in with a device that no one has used before, also not the user himself. → the Fingerprint module considers the device as "private".
• Only one user has used a specific device within the last 60 days (no matter how often). → the Fingerprint module considers the device as "private".
• User "A", who uses an iPhone X, allows user "B" to log in with "his" iPhone. So both users share the same device at least once. → the Fingerprint module considers the device as "shared".
• In the next 365 days, only user "A" continues using the iPhone X. → The next time user "A" uses the iPhone after the 60 days, the Fingerprint module no longer considers the device as "shared", but as "private" (60 days = the specified time frame).

Calculating the risk score

In case of the Fingerprint module, the calculation of the risk score for a specific user request consists of the following steps:

1. The Fingerprint module determines whether the device used in the current request is "unknown", "known" or "established". The module also determines whether the device is "private" or "shared".
2. For each determined value (unknown/known/established and private/shared), the module fetches the corresponding risk score from the riskscore-mapping.properties file.
3. The module sums up the two risk scores, to get the final risk score for this module and this user request. Note that the total risk score may never be higher than "1.0".

The file riskscore-mapping.properties defines the mapping between observed context data and risk scores for all modules. For more information, see the chapter "Risk score mapping for nevisAdapt".

Here are some examples of possible risk scores calculated by the Fingerprint module for a specific user request:

The risk scores are based on the settings in the list of preconditions.

• The user uses a shared and known device. This results in a risk score of "0.05" (shared) + "0.3" (known) = "0.35".
• The user uses a private and an established device. This results in a risk score of "0" (private) + "0" (established) = "0".
• The user uses an unknown, but private device. This is the case when the user uses the device for the first time, and no one else has ever used this device before. This results in a risk score of "0" (private) + "0.7" (unknown) = "0.7".
• The user uses an unknown, but shared device. This is the case when this user uses the device for the first time. However, some other user has already used this device, and the Fingerprint module recognizes the device fingerprint. This results in a risk score of "0.05" (shared) + "0.7" (unknown) = "0.75".

Disabling Submodules of nevisAdapt

There is a possibility to disable submodules of nevisAdapt through the configuration file and nevisAdmin 4.

Disabling the submodules will result in lower risk score calculation and if all the modules have been disabled the user will always follow the "untrained user" authentication flow.

We discourage disabling submodules unless you have a specific use case for it.