Skip to main content
Version: 7.2405.x.x LTS

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 Appendix H 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 scheduledScript nameCrontab template name
Download and overwrite IP blacklistdownload-ip-blacklist.shcrontab-ip-blacklist_template
Download and overwrite IP-to-location mappingdownload-ip-location.shcrontab-ip-location_template

Results

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

NameDescriptionRecommended next steps
noDataFoundNo login ID or user ID were found.Retry authentication
okThe authentication had no issues according to nevisAdapt.Authentication is successful
notifySuspicious activity was detected.Send a notification to the user
stepUpHighly suspicious activity was detected.Second factor authentication along with a notification
errorAn 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:

NameType / unitDefaultDescription
validateResponsebooleanfalseConfigures whether the response from nevisAdapt must be validated after sending the data.
read.timeoutnumber/millisecondsThe 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:

NameType / unitDescription
urlstringThe URL for the nevisAdapt service
httpclient.*stringConfigure 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.

NameType / RangeDefaultDescription
riskScore.weight.geolocationnumber / [0-1]0.4The weight of the Geolocation risk scores in the calculation of the aggregated score.
riskScore.weight.ipnumber / [0-1]0.4The weight of the IP Address risk scores in the calculation of the aggregated score.
riskScore.weight.ip.reputationnumber / [0-1]0.6The weight of the IP Reputation risk scores in the calculation of the aggregated score.
riskScore.weight.ip.velocitynumber / [0-1]0.6The weight of the IP Velocity risk scores in the calculation of the aggregated score.
riskScore.weight.suspicious.countrynumber / [0-1]0.7The weight of the Suspicious Country risk scores in the calculation of the aggregated score.
riskScore.weight.device.cookienumber / [0-1]0.7The weight of the Device Cookie risk scores in the calculation of the aggregated score.
riskScore.weight.device.sharingnumber / [0-1]0.7The weight of the Device Sharing risk scores in the calculation of the aggregated score.
riskScore.weight.fingerprintnumber / [0-1]0.35The weight of the Fingerprint risk scores in the calculation of the aggregated score.
riskScore.weight.fingerprint.sharingnumber / [0-1]0.35The weight of the Fingerprint Sharing risk scores in the calculation of the aggregated score.
riskScore.threshold.mediumnumber / [0-1]0.6The threshold above which user notification is recommended.
riskScore.threshold.highnumber / [0-1]0.89The 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.

NameType / RangeDefaultDescription
feedbackActionOptionsdeviceThere 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.
feedbackKeyBase64 (32 bytes hashed -> 44 chars total)NoneJWE token encryption key for generating the notification links.
feedbackUriURLNoneThe frontend address of the application as defined by the associated nevisProxy instance, extended with '/feedback'.
tokenLifetimeinteger12Defines 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>