NevisAdaptAuthState
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.
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 |
| http.client.keyStore | string | Path to the nevisAdapt client keystore |
| http.client.keyStorePassword | string | Reference to the keystore password |
| http.client.trustStore | string | Path to the nevisAdapt client truststore |
| http.client.trustStorePassword | string | Reference to the truststore password |
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 needs 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. |
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="{auth state to call on notify}"/>
<ResultCond name="ok" next="sso_Check_Done"/>
<ResultCond name="stepUp" next="{auth state to call 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="keyStoreRef" value="/var/opt/keys/own/auth-client-identity/keystore.jks"/>
<property name="keyStorePassword" value="pipe:///var/opt/keys/own/auth-client-identity/keypass"/>
<property name="trustStoreRef" value="/var/opt/keys/trust/auth-client-trust/truststore.jks"/>
<property name="trustStorePassword" value="pipe:///var/opt/keys/trust/auth-client-trust/keypass"/>
<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"/>
</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.
| Name | Type / Range | Default | Description |
|---|---|---|---|
nevisadapt.events.event_<index> | string | Comma-separated list of events to match against. The index determines the priority of a given option: The lower the index, the higher the priority. Only a full match 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 full match>">
<ResultCond name="event_1" next="<next auth step if this event set has full match>">
<ResultCond name="event_2" next="<next auth step if this event set has full match>">
<ResultCond name="event_3" next="<next auth step if this event set has full match>">
<property name="validateResponse" value="true"/>
<property name="read.timeout" value="10000"/>
<property name="clientUri" value="https://localhost:8888/nevisadapt"/>
<property name="keyStoreRef" value="/var/opt/keys/own/auth-client-identity/keystore.jks"/>
<property name="keyStorePassword" value="pipe:///var/opt/keys/own/auth-client-identity/keypass"/>
<property name="trustStoreRef" value="/var/opt/keys/trust/auth-client-trust/truststore.jks"/>
<property name="trustStorePassword" value="pipe:///var/opt/keys/trust/auth-client-trust/keypass"/>
</AuthState>