# OpenAM Administration Guide
2.2. Configuring Authentication Modules

Sidebar | Prev | Up | Next

### 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.

[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`