NevisAdaptAuthState

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

Overview

The purpose of this AuthState is to enable nevisAuth to access the standalone nevisAdapt service. Based on the returned risk score information, nevisAuth then decides which authentication step to invoke next (if any).

The technical name of the AuthState is ch.nevis.detect.authstate.NevisAdaptAuthState. Integrate it in your login workflow in such a way, that it is invoked when all necessary information for the analysis tasks has been collected. This involves all login information, including the IP address.

caution

The analysis tasks can rely on external databases. This is especially valid for the Geolocation, IP velocity, and IP reputation tasks of the Geolocation module.

The quality of these external databases has a huge impact on the module's effectiveness. IP addresses are assigned dynamically. To keep the service up-to-date, a periodic update schedule is recommended. To set this up, the following templates can be customized:

Function to be scheduled	Script name	Crontab template name
Download and overwrite IP blacklist	download-ip-blacklist.sh	crontab-ip-blacklist_template
Download and overwrite IP-to-location mapping	download-ip-location.sh	crontab-ip-location_template

Results

The table below lists the various results that the NevisAdaptAuthState can set as a return value.

Name	Description	Recommended next steps
noDataFound	No login ID or user ID were found.	Retry authentication
ok	The authentication had no issues according to nevisAdapt.	Authentication is successful
notify	Suspicious activity was detected.	Send a notification to the user
stepUp	Highly suspicious activity was detected.	Second factor authentication along with a notification
error	An error occurred during processing or the response was invalid.	Retry authentication

Configuration

The configuration of the NevisAdaptAuthState consists of three sets of configurations: the configuration of the nevisAdapt Service, the nevisAdapt REST Client, and the risk scores/weights.

nevisAdapt Service configuration

The table below lists all properties needed to configure the connection behavior to nevisAdapt:

Name	Type / unit	Default	Description
validateResponse	boolean	false	Configures whether the response from nevisAdapt must be validated after sending the data.
read.timeout	number/milliseconds		The maximum processing time that nevisAuth will wait for the risk scores.

nevisAdapt REST Client configuration

The table below lists all properties needed to configure the nevisAdapt REST client on nevisAuth:

Name	Type / unit	Description
url	string	The URL for the nevisAdapt service
httpclient.*	string	Configure the outgoing HTTP communication to the nevisAdapt service. For a list of valid HTTP properties, see HTTP Client.

Session variables

If the calculated risk is higher than the medium threshold, nevisAdapt adds the following variables to the session in nevisAuth.

Possible Results

For all possible analyser results, see Appendix: Analyser results.

ch.nevis.nevisadapt.observation.date

Date of the login request (UTC time).

Example: January 14 2021 16:27:30

ch.nevis.nevisadapt.observation.city

City.

Example: Zurich

ch.nevis.nevisadapt.observation.countryCode

The two-letter ISO country code.

Example: CH

ch.nevis.nevisadapt.observation.country

Country name.

Example: Switzerland

ch.nevis.nevisadapt.observation.latitude

The calculated latitude.

Example: 47.349991

ch.nevis.nevisadapt.observation.longitude

The calculated longitude.

Example: 7.903290

ch.nevis.nevisadapt.observation.ipAddress

The source IP address (IPv4).

Example: 127.0.0.1

ch.nevis.nevisadapt.observation.os

Operating system.

Example: Mac OS X

ch.nevis.nevisadapt.observation.browser

Browser information.

Example: Safari

ch.nevis.nevisadapt.observation.device

Device information.

Example: Mac

ch.nevis.nevisadapt.observation.NevisAdaptGeolocation

Comma-separated list of the geolocation analyzer results.

Example: trusted-country,known-country,ip-reputation-ok,known-ip,unknown-ip-velocity

ch.nevis.nevisadapt.observation.NevisAdaptDeviceFingerprint

Comma-separated list of the fingerprint analyzer results.

Example: known-fingerprint,private-fingerprint

ch.nevis.nevisadapt.observation.NevisAdaptDeviceRecognition

Comma-separated list of the device analyzer results.

Example: unknown-device,private-device

Risk score weight configuration

The table below lists all properties needed to configure individual weights and the aggregate decision thresholds. The default weights configuration is the balanced weight configuration (see the sample code block further below).

Get in touch with your Nevis contact if different values need to be configured.

Name	Type / Range	Default	Description
riskScore.weight.geolocation	number / [0-1]	0.4	The weight of the Geolocation risk scores in the calculation of the aggregated score.
riskScore.weight.ip	number / [0-1]	0.4	The weight of the IP Address risk scores in the calculation of the aggregated score.
riskScore.weight.ip.reputation	number / [0-1]	0.6	The weight of the IP Reputation risk scores in the calculation of the aggregated score.
riskScore.weight.ip.velocity	number / [0-1]	0.6	The weight of the IP Velocity risk scores in the calculation of the aggregated score.
riskScore.weight.suspicious.country	number / [0-1]	0.7	The weight of the Suspicious Country risk scores in the calculation of the aggregated score.
riskScore.weight.device.cookie	number / [0-1]	0.7	The weight of the Device Cookie risk scores in the calculation of the aggregated score.
riskScore.weight.device.sharing	number / [0-1]	0.7	The weight of the Device Sharing risk scores in the calculation of the aggregated score.
riskScore.weight.fingerprint	number / [0-1]	0.35	The weight of the Fingerprint risk scores in the calculation of the aggregated score.
riskScore.weight.fingerprint.sharing	number / [0-1]	0.35	The weight of the Fingerprint Sharing risk scores in the calculation of the aggregated score.
riskScore.threshold.medium	number / [0-1]	0.6	The threshold above which user notification is recommended.
riskScore.threshold.high	number / [0-1]	0.89	The threshold above which a second factor authentication is recommended.

Notification feedback configurations

The table below lists all properties needed to configure feedback link generation and handling in case of suspicious behavior.

Name	Type / Range	Default	Description
feedbackAction	Options	device	There are four main actions possible, when the end user presses the provided link: disabled: Nothing happens. session: All observations associated with the login attempt's session are removed. device: All observations of the user are removed that can be connected to the device of the notified login attempt. all: All observations are removed for the user.
feedbackKey	Base64 (32 bytes hashed -> 44 chars total)	None	JWE token encryption key for generating the notification links.
feedbackUri	URL	None	The frontend address of the application as defined by the associated nevisProxy instance, extended with '/feedback'.
tokenLifetime	integer	12	Defines the validity duration of the generated feedback token in hours.

Example configuration with balanced weight configuration

<AuthState class="ch.nevis.detect.authstate.NevisAdaptAuthState" final="false" name="sso_authstate-adapt_NevisAdapt">
    <ResultCond name="error" next="sso_Authentication_Failed"/>
    <ResultCond name="noDataFound" next="sso_Check_Done"/>
    <ResultCond name="notify" next="{next auth step on notify}"/>
    <ResultCond name="ok" next="sso_Check_Done"/>
    <ResultCond name="stepUp" next="{next auth step on stepUp}"/>
    <ResultCond name="timeout" next="{next auth step on stepUp}"/>
    <property name="validateResponse" value="true"/>
    <property name="riskScore.threshold.medium" value="0.6"/>
    <property name="riskScore.threshold.high" value="0.89"/>
    <property name="read.timeout" value="10000"/>
    <property name="clientUri" value="https://localhost:8888/nevisadapt"/>
    <property name="httpclient.tls.keyObjectRef" value="auth-client-identity"/>
    <property name="httpclient.tls.trustStoreRef" value="auth-client-trust"/>
    <property name="riskScore.weight.geolocation" value="0.4"/>
    <property name="riskScore.weight.ip" value="0.4"/>
    <property name="riskScore.weight.ip.reputation" value="0.6"/>
    <property name="riskScore.weight.ip.velocity" value="0.6"/>
    <property name="riskScore.weight.suspicious.country" value="0.7"/>
    <property name="riskScore.weight.device.cookie" value="0.7"/>
    <property name="riskScore.weight.device.sharing" value="0.7"/>
    <property name="riskScore.weight.fingerprint" value="0.35"/>
    <property name="riskScore.weight.fingerprint.sharing" value="0.35"/>
    <property name="feedbackAction" value="session"/>
    <property name="feedbackKey" value="VGhpc0lzQW5FeGFtcGxlRm9yQmFzZTY0UGFzc3dvcmQ="/>
    <property name="feedbackUri" value="https://localhost/feedback"/>
    <property name="tokenLifetime" value="10"/>
</AuthState>

Event-based configuration

As an alternative to the risk weight profile, you can define combinations of events that directly influence the following authentication step.

nevisadapt.events.event_<index>

• Type / Range: string
• Description: Comma-separated list of events to match against. The position determines the priority of a given option: The lower the index, the higher the priority. Only a compatible match (at least as many are present from the options as defined) leads to a decision. The following events are supported:
  • unknown-device
  • unknown-country
  • ip-reputation-blacklisted
  • unknown-fingerprint
  • suspicious-country
  • high-ip-velocity.

If no set matches, the result from nevisAdapt is AUTH_OK.

Example configuration with risk event configuration

<AuthState class="ch.nevis.detect.authstate.NevisAdaptAuthState" final="false" name="sso_authstate-adapt_NevisAdapt">
    <ResultCond name="error" next="sso_Authentication_Failed"/>
    <ResultCond name="noDataFound" next="sso_Check_Done"/>
    <ResultCond name="ok" next="sso_Check_Done"/>
    <ResultCond name="event_0" next="{next auth step if this event set has valid match}"/>
    <ResultCond name="event_1" next="{next auth step if this event set has valid match}"/>
    <ResultCond name="event_2" next="{next auth step if this event set has valid match}"/>
    <ResultCond name="event_3" next="{next auth step if this event set has valid match}"/>
    <ResultCond name="timeout" next="{next auth step in case of timeout}"/> 
    <property name="validateResponse" value="true"/>
    <property name="read.timeout" value="10000"/>
    <property name="clientUri" value="https://localhost:8888/nevisadapt"/>
    <property name="httpclient.tls.keyObjectRef" value="auth-client-identity"/>
    <property name="httpclient.tls.trustStoreRef" value="auth-client-trust"/>
    <property name="feedbackAction" value="session"/>
    <property name="feedbackKey" value="VGhpc0lzQW5FeGFtcGxlRm9yQmFzZTY0UGFzc3dvcmQ="/>
    <property name="feedbackUri" value="https://localhost/feedback"/>
    <property name="tokenLifetime" value="10"/>
</AuthState>