2.2.2. Hints For the Adaptive Risk Authentication Module

The Adaptive Risk module is designed to assess risk during authentication so that OpenAM can determine whether to require the user to complete further authentication steps. After configuring the Adaptive Risk module, insert it in your authentication chain with criteria set to sufficient as shown in the following example.

Including the Adaptive Risk module in an authentication chain

[D]

In the example authentication chain shown, OpenAM has users authenticate first using the LDAP module providing a user ID and password combination. Upon success, OpenAM calls the Adaptive Risk module. The Adaptive Risk module assesses the risk based on your configured parameters. If the Adaptive Risk module calculates a total score below the threshold you set, the module returns success, and OpenAM finishes authentication processing without requiring further credentials. Otherwise the Adaptive Risk module evaluates the score to be above the risk threshold, and returns failure. OpenAM then calls the HOTP module, requiring the user to authenticate with a one-time password delivered to her by email or by SMS to her mobile phone.

When you configure the Adaptive Risk module to save cookies and profile attributes after successful authentication, OpenAM performs the save as post-authentication processing, only after the entire authentication chain returns success. You must set up OpenAM to save the data as part of post-authentication processing by editing the authentication chain to add org.forgerock.openam.authentication.modules.adaptive.Adaptive to the list of post authentication plugins.

ssoadm service name: sunAMAuthAdaptiveService

General

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: openam-auth-adaptive-auth-level

Risk Threshold

Risk threshold score. If the sum of the Scores is greater than the threshold, the Adaptive Risk module returns failure. Default: 1

ssoadm attribute: openam-auth-adaptive-auth-threshold

Failed Authentications

Failed Authentication Check

When enabled, check the user profile for authentication failures since the last successful login. This check therefore requires OpenAM to have access to the user profile, and Account Lockout to be enabled (otherwise OpenAM does not record authentication failures).

ssoadm attribute: openam-auth-adaptive-failure-check

Score

Value to add to the total score if the user fails the Failed Authentication Check. Default: 1

ssoadm attribute: openam-auth-adaptive-failure-score

Invert Result

When selected, add the Score to the total score if the user passes the Failed Authentication Check.

ssoadm attribute: openam-auth-adaptive-failure-invert

IP Address Range

IP Range Check

When enabled, check whether the client IP address is within one of the specified IP Ranges.

ssoadm attribute: openam-auth-adaptive-ip-range-check

IP Range

For IPv4, specifies a list of IP ranges either in CIDR-style notation (x.x.x.x/YY) or as a range from one address to another (x.x.x.x-y.y.y.y, meaning from x.x.x.x to y.y.y.y).

For IPv6, specifies a list of IP ranges either in CIDR-style notation (X:X:X:X:X:X:X:X/YY) or as a range from one address to another (X:X:X:X:X:X:X:X-Y:Y:Y:Y:Y:Y:Y:Y, meaning from X:X:X:X:X:X:X:X to Y:Y:Y:Y:Y:Y:Y:Y).

ssoadm attribute: openam-auth-adaptive-ip-range-range

Score

Value to add to the total score if the user fails the IP Range Check. Default: 1

ssoadm attribute: openam-auth-adaptive-ip-range-score

Invert Result

When selected, add the Score to the total score if the user passes the IP Range Check.

ssoadm attribute: openam-auth-adaptive-ip-range-invert

IP Address History

IP History Check

When enabled, check whether the client IP address matches one of the known values stored on the profile attribute you specify. This check therefore requires that OpenAM have access to the user profile.

ssoadm attribute: openam-auth-adaptive-ip-history-check

History Size

Specifies how many IP address values to retain on the profile attribute you specify. Default: 5

ssoadm attribute: openam-auth-ip-adaptive-history-count

Profile Attribute Name

Name of the user profile attribute on which to store known IP addresses. Default: iphistory

ssoadm attribute: openam-auth-adaptive-ip-history-attribute

Save Successful IP Address

When enabled, save new client IP addresses to the known IP address list following successful authentication.

ssoadm attribute: openam-auth-adaptive-ip-history-save

Score

Value to add to the total score if the user fails the IP History Check. Default: 1

ssoadm attribute: openam-auth-adaptive-ip-history-score

Invert Result

When selected, add the Score to the total score if the user passes the IP History Check.

ssoadm attribute: openam-auth-adaptive-ip-history-invert

Known Cookie

Cookie Value Check

When enabled, check whether the client browser request has the specified cookie and optional cookie value.

ssoadm attribute: openam-auth-adaptive-known-cookie-check

Cookie Name

Specifies the name of the cookie for which OpenAM checks when you enable the Cookie Value Check.

ssoadm attribute: openam-auth-adaptive-known-cookie-name

Cookie Value

Specifies the value of the cookie for which OpenAM checks. If no value is specified, OpenAM does not check the cookie value.

ssoadm attribute: openam-auth-adaptive-known-cookie-value

Save Cookie Value on Successful Login

When enabled, save the cookie as specified in the client's browser following successful authentication. If no Cookie Value is specified, the value is set to 1.

ssoadm attribute: openam-auth-adaptive-known-cookie-save

Score

Value to add to the total score if user passes the Cookie Value Check. Default: 1

ssoadm attribute: openam-auth-adaptive-known-cookie-score

Invert Result

When selected, add the Score to the total score if the user passes the Cookie Value Check.

ssoadm attribute: openam-auth-adaptive-known-cookie-invert

Device Cookie

Device Registration Cookie Check

When enabled, check whether the client browser request has the specified cookie with the correct device registration identifier as the value.

ssoadm attribute: openam-auth-adaptive-device-cookie-check

Cookie Name

Specifies the name of the cookie for the Device Registration Cookie Check. Default: Device

ssoadm attribute: openam-auth-adaptive-device-cookie-name

Save Device Registration on Successful Login

When enabled, save the specified cookie with a hashed device identifier value in the client's browser following successful authentication.

ssoadm attribute: openam-auth-adaptive-device-cookie-save

Score

Value to add to the total score if the user fails the Device Registration Cookie Check. Default: 1

ssoadm attribute: openam-auth-adaptive-device-cookie-score

Invert Result

When selected, add the Score to the total score if the user passes the Device Registration Cookie Check.

ssoadm attribute: openam-auth-adaptive-device-cookie-invert

Time Since Last Login

Time Since Last Login Check

When enabled, check whether the client browser request has the specified cookie that holds the encrypted last login time, and check that the last login time is more recent than a maximum number of days you specify.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-check

Cookie Name

Specifies the name of the cookie holding the encrypted last login time value.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-cookie-name

Max Time since Last Login

Specifies a threshold age of the last login time in days. If the client's last login time is more recent than the number of days specified, then the client successfully passes the check.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-value

Save time of Successful Login

When enabled, save the specified cookie with the current time encrypted as the last login value in the client's browser following successful authentication.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-save

Score

Value to add to the total score if the user fails the Time Since Last Login Check. Default: 1

ssoadm attribute: openam-auth-adaptive-time-since-last-login-score

Invert Result

When selected, add the Score to the total score if the user passes the Time Since Last Login Check.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-invert

Profile Attribute

Profile Risk Attribute check

When enabled, check whether the user profile contains the specified attribute and value.

ssoadm attribute: openam-auth-adaptive-risk-attribute-check

Attribute Name

Specifies the attribute to check on the user profile for the specified value.

ssoadm attribute: openam-auth-adaptive-risk-attribute-name

Attribute Value

Specifies the value to match on the profile attribute. If the attribute is multi-valued, a single match is sufficient to pass the check.

ssoadm attribute: openam-auth-adaptive-risk-attribute-value

Score

Value to add to the total score if the user fails the Profile Risk Attribute Check. Default: 1

ssoadm attribute: openam-auth-adaptive-risk-attribute-score

Invert Result

When selected, add the Score to the total score if the user passes the Profile Risk Attribute Check.

ssoadm attribute: openam-auth-adaptive-risk-attribute-invert

Geo Location

Geolocation Country Code Check

When enabled, check whether the client IP address location matches a country specified in the Valid Country Codes list. The

ssoadm attribute: forgerock-am-auth-adaptive-geo-location-check

Geolocation Database location

Path to GeoIP data file used to convert IP addresses to country locations. The geolocation database is not packaged with OpenAM. You can downloaded the GeoIP Country database from MaxMind. Use the binary .dat file format, rather than .csv. You can use the GeoLite Country database for testing.

ssoadm attribute: openam-auth-adaptive-geo-location-database

Valid Country Codes

Specifies the list of country codes to match. Use | to separate multiple values.

ssoadm attribute: openam-auth-adaptive-geo-location-values.

Score

Value to add to the total score if the user fails the Geolocation Country Code Check. Default: 1

ssoadm attribute: openam-auth-adaptive-geo-location-score

Invert Result

When selected, add the Score to the total score if the user passes the Geolocation Country Code Check.

ssoadm attribute: openam-auth-adaptive-geo-location-invert

Request Header

Request Header Check

When enabled, check whether the client browser request has the specified header with the correct value.

ssoadm attribute: openam-auth-adaptive-req-header-check

Request Header Name

Specifies the name of the request header for the Request Header Check.

ssoadm attribute: openam-auth-adaptive-req-header-name

Request Header Value

Specifies the value of the request header for the Request Header Check.

ssoadm attribute: openam-auth-adaptive-req-header-value

Score

Value to add to the total score if the user fails the Request Header Check. Default: 1

ssoadm attribute: openam-auth-adaptive-req-header-score

Invert Result

When selected, add the Score to the total score if the user passes the Request Header Check.

ssoadm attribute: openam-auth-adaptive-req-header-invert