RBA - Rule definition

In the context of RBA, a rule is a configuration item used within “risk policies”. Reminder: there are environment risk policies, user risk policies, and authentication risk policies.

A risk policy holds a set of rules. A rule consists of:

A matching criterion (condition), written as a Groovy script, returning either true or false. The syntax of Groovy scripts is detailed below
An action that the system applies if the rule criterion matches.

The possible actions applied when a rule matches are listed in the table below.

Types of Rule Actions

When a policy rule evaluates to true, the RBA engine executes an action. The type of action depends on the policy that contains the rule:

Environment and User Risk Policies adjust the risk score (increase or decrease) of the incoming connection request.
Authentication Risk Policies increase the minimum authentication level required to access the target application.

This table shows how each rule action works and how it affects the risk evaluation process.

Rule Action Type

Description

Computation Principle

Risk rule action
(used in Environment Risk Policies and User Risk Policies)

This rule defines a numeric correction value that modifies the current risk score.
When the Groovy script returns true (the rule matches), the RBA engine adds this value to the current risk score. A positive value increases the risk score and a negative value decreases the risk score.

New Risk Score = Current Risk Score + Rule Correction

Authentication rule action (used in Authentication Risk Policies)

This rule defines a new authentication level in a numeric value. When the Groovy script returns true (the rule matches), the RBA compares the new level with the current one.
If the new level is higher, the system removes the old level and updates the required authentication level to the new value.

New Requested Authentication Level = max(Current Authentication Level, Rule Authentication Level)

The RBA evaluates each rule dynamically using contextual data available in Groovy as “variables”, for example, the number of days since the last successful authentication. The rule uses the current risk evaluation context (user info, device info, authentication state, etc.) as input.

When the Groovy rule returns true, the rule immediately contributes to the risk evaluation:

A risk rule modifies the current risk score by adding or subtracting its configured correction value.
An authentication rule increases the required minimum authentication level if its configured value is higher than the current one.

The structure of a criteria

Context variables accepted in condition rules

RBA rules are based on “matching conditions”, meaning all condition rules written in Groovy scripts return either true or false.

These Groovy scripts have access to context variables, which are described in this section.

Request Groovy Context

The request groovy context (REQ) gives information about the user's HTTP request, such as HTTP headers.

You can use it everywhere. However, it’s especially useful for environment rules defined in the EnvironmentRiskPolicy.

Variable Name

Java Type

Description

Example Usage

REQ.userAgent

String

The user agent header.

Default value: "UNKNOWN"

CODE

return REQ.userAgent.contains('foo')

REQ.riskType

RiskType enum

How to evaluate the risk. Possible values:

RiskType.ENVIRONMENT:An environment risk is evaluated, the user is not known at this point.
RiskType.USER: A user risk is evaluated, it always includes the evaluation of the environment risk.

CODE

return REQ.riskType == RiskType.USER

REQ.ip

RequestIpAddressMatcher

Check whether the remote IP address of the client at the origin of the RBA request matches a specific IP address or a range specified using the IP/Netmask. For example, 192.168.1.45 or 192.168.1.0/24.

The variable supports both IPv4 and IPv6 addresses.

CODE

return REQ.ip.matches('81.2.69.0/24')

REQ.headers

Map

The request's HTTP headers (including REQ.userAgent).

Always write header names in lowercase.

To keep things simple, the system only keeps the first value of each header, so the header value is a single string.

CODE

return REQ.headers.some-header.contains('foo')

REQ.date

Instant

The request date.

Default value: now

CODE

return REQ.date.atZone(DYN.location.timeZone.toZoneId()).getDayOfWeek() == DayOfWeek.WEDNESDAY

REQ.accessType

AccessType enum

The type of access requested when evaluating the risk. Possible values are:

AccessType.AUTHENTICATION : The risk is evaluated during the user authentication phase, when a user with no SSO session attempts to access an application.
AccessType.AUTHORIZATION : The risk is evaluated during the user authorization phase, when an authenticated user attempts to access an application.

CODE

return REQ.accessType == AccessType.AUTHORIZATION

Device Groovy Context

The Device groovy context (DEVICE) gives information about a user device. It describes whether or not the user device has been recognized successfully, and provides various meta-information on the device.

This context is especially useful for rules defined in EnvironmentRiskPolicy and AuthenticationRiskPolicy.

Variable Name

Java Type

Description

Example Usage

DEVICE.status

DeviceStatus enum

The device status.

Accepted values:

DeviceStatus.UNKNOWN : No device information could be inferred, unknown, new device.
DeviceStatus.RECOGNIZED : The device has been successfully recognized and is valid.
DeviceStatus.INVALID : The device recognition has failed because of an invalid data. For example, the cookie signature could not be verified.
DeviceStatus.EXPIRED : The device was successfully recognized but with data that has expired.

Default value: DeviceStatus.UNKNOWN

CODE

return DEVICE.status == DeviceStatus.UNKNOWN

DEVICE.type

DeviceType enum

The device type.

Accepted values:

DeviceType.UNKNOWN : No device information could be inferred.
DeviceType.DESKTOP : Desktop device.
DeviceType.MOBILE : Mobile device.

Default value: DeviceType.UNKNOWN

CODE

return DEVICE.type == DeviceType.UNKNOWN

DEVICE.lastSeen

Instant

The last time the user used the device.

Null if the user is not identified yet (transparent authentication request).

Default value: Jan 1, 1970

CODE

return DEVICE.lastSeen.isBefore(REQ.date.minus(24, ChronoUnit.HOURS))

DEVICE.name

String

The name of the device set by the user.

Null if the user is not identified yet (transparent authentication request).

Default value: "UNKNOWN"

CODE

return DEVICE.name == "iPhone-12-Personal"

DEVICE.os

String

The device's operating system.

This information comes from the client, it may have been forged by a malicious user.

Default value: "UNKNOWN"

CODE

return DEVICE.os.contains('Windows')

DEVICE.osVersion

String

The device's operating system version.

This information comes from the client, it may have been forged by a malicious user.

Default value: "UNKNOWN"

CODE

return DEVICE.osVersion.startsWith("iOS 17")

DEVICE.browser

String

The device's browser.

This information comes from the client, it may have been forged by a malicious user.

Default value: "UNKNOWN"

CODE

return DEVICE.browser.contains('Edge')

DEVICE.browserVersion

The device's browser version.

This information comes from the client, it may have been forged by a malicious user.

Default value: "UNKNOWN"

CODE

return DEVICE.browserVersion.startsWith("Safari 17")

User Groovy context

The User groovy context (USER) gives information about the identified user.

This context should only be referenced in UserRiskPolicy rules. Indeed, those rules are not evaluated when the user is not identified, which happens for transparent authentication requests (Kerberos, X509 client certificate).

Variable Name

Java Type

Description

USER.id

String

The user's tenant Identity id.

Default value: null

Application Groovy context

The Application Groovy context (APP) gives information about the application for which the authentication is performed, with all attributes that may be used in order to compute a score.

This context is useful when you configure Authentication Risk Policies scopes.

Variable Name

Java Type

Description

Example Usage

APP.riskTolerance

Integer

The risk tolerance associated with the application.

This is a positive integer value where the lowest value (0) corresponds to a low tolerance (which should result in a low Maximum Acceptable Risk) and the highest value corresponds to a high tolerance (which should result in a high Maximum Acceptable Risk).

Usually, the values are 0, 1 or 2. However, there isn’t a formal upper limit.

Default value: 0

CODE

return APP.riskTolerance == 0

APP.name

String

The application's name, which is the Resource id.

Default value: null

CODE

return APP.name == 'PeopleDoc'

APP.authenticationLevel

Integer

The authentication level required to access the application. It may help categorize applications in authentication policy rules.

Default value: 0

CODE

return APP.authenticationLevel > 50

Risk Evaluation Groovy context

The Risk Evaluation groovy context (RISK) gives information about the ongoing risk evaluation.

This context is useful when you write authentication rules. Indeed, the RBA engine can define an authentication level to apply if some rules match.

Variable name

Java type

Description

Example

RISK.envRules

List<String>

The environment rules that matches to compute the environment risk.

CODE

return RISK.envRules.contains('Unknown device')

RISK.userRules

List<String>

The user rules that matches to compute the user risk.

CODE

return RISK.userRules.contains('New location')

RISK.unknownUser

boolean

true: The user is identified.

The system sets the value to true if there is no user information in the RBA request. For example, when the request corresponds to transparent authentication methods such as X509 or Kerberos.

false: The user isn’t identified.

Default value: false

CODE

return RISK.unknownUser

Location Dynamic Groovy context

The Location Dynamic (DYN.location) groovy context retrieves information about the input parameters of the geolocation from the remote IP address.

Variable name

Java type

Description

Example

DYN.location.continent

String

The name of the continent where the authentication takes place.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.location.continent == 'europe'

DYN.location.continentCode

String

Two-letter continent code:

"AF" (Africa)
"AN"(Antarctica)
"AS" (Asia)
"EU" (Europe)
"NA" (North America),
"OC" (Oceania),
"SA" (South America)

Default value: "UNKNOWN"

CODE

return DYN.location.continentCode == 'EU'

DYN.location.country

String

The country where the authentication takes place.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.location.country == 'france'

DYN.location.countryCode

String

The country code based on the ISO 3166-1 alpha-2 standards.

Example: enter "FR" for "France".

Default value: "UNKNOWN"

CODE

return DYN.location.countryCode == 'FR'

DYN.location.region

String

The region where the authentication takes place.

In English and lowercase.

Default value: “unknown"

CODE

return DYN.location.region == 'dongcheng'

DYN.location.city

String

The city where the authentication takes place.

In English and lowercase.

Default value: “unknown"

CODE

return DYN.location.city == 'beijing'

DYN.location.timeZone

TimeZone

The timezone where the authentication takes place.

Default value: UTC

CODE

return REQ.date.atZone(DYN.location.timeZone.toZoneId()).getDayOfWeek() == DayOfWeek.WEDNESDAY

DYN.location.localTime

LocalTime

Time when the authentication takes place in the location's timezone.

Default value: Midnight

CODE

return DYN.location.localTime.isAfter(LocalTime.of(22, 0))

Device Dynamic Groovy context

The Device Dynamic (DYN.device) groovy context retrieves information about the input parameters of the user’s device authentication history.

Variable name

Java type

Description

Example

DYN.device.newLocation

boolean

true: The location of the current authentication is new.

false: The location of the current authentication is found in previous access history.

Default value: true.

CODE

return DYN.device.newLocation

DYN.device.lastLocationVelocity

String

The speed in km/h from the last successful authentication and the current authentication.

Default value: Infinite

CODE

return DYN.device.lastLocationVelocity > 20

DYN.device.lastLocationRegion

String

The region where the last successful authentication occurred.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.device.lastLocationRegion == 'dongcheng'

DYN.device.lastLocationDistance

Integer

The distance in km from the last successful authentication and the current authentication.

Default value: Infinite

CODE

return DYN.device.lastLocationDistance > 200

DYN.device.lastLocationCountryCode

String

The country code of the last successful authentication.

Use a code from the ISO 3166-1 alpha-2 standard.

Default value: "UNKNOWN"

CODE

return DYN.device.lastLocationCountryCode == 'FR'

DYN.device.lastLocationCountry

String

The country of the last successful authentication.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.device.lastLocationCountry == 'france'

DYN.device.lastLocationCity

String

The city of the last successful authentication.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.device.lastLocationCity == 'beijing'

DYN.device.lastFailedAuthenticationDate

Instant

The date of the last authentication failure (passive or interactive).

Default value: Now

CODE

return DYN.device.lastFailedAuthenticationDate.isBefore(REQ.date.minus(24, ChronoUnit.HOURS))

DYN.device.lastAuthenticationWasInteractive

boolean

true: The last authentication was interactive.

false: The last authentication was passive.

Default value: false

CODE

return DYN.device.lastAuthenticationWasInteractive

DYN.device.lastAuthenticationInterval

Integer

Number of days since the last successful authentication.

Default value: Infinite

CODE

return DYN.device.lastAuthenticationInterval >= 180

DYN.device.lastAuthenticationDate

Instant

The last successful authentication date (passive or active).

Default value: Jan 1, 1970

CODE

return DYN.device.lastAuthenticationDate.isAfter(REQ.date.minus(24, ChronoUnit.HOURS))

User Dynamic Groovy Context

The User Dynamic (DYN.user) groovy context retrieves information about the input parameters of the user authentication history.

Only reference this context in UserRiskPolicy rules. Indeed, the system doesn’t evaluate UserRiskPolicy rules when the user is not identified, which happens for transparent authentication requests.

Variable name

Java type

Description

Example

DYN.user.lastAuthenticationDate

Instant

The date of the last successful authentication (passive or interactive).

Default value: Jan 1, 1970

CODE

return DYN.user.lastAuthenticationDate.isAfter(REQ.date.minus(24, ChronoUnit.HOURS))

DYN.user.lastInteractiveAuthenticationDate

Instant

The date of the last successful interactive authentication.

Default value: Jan 1, 1970

CODE

return DYN.user.lastInteractiveAuthenticationDate.isAfter(REQ.date.minus(24, ChronoUnit.HOURS))

DYN.user.lastAuthenticationWasInteractive

boolean

true: The last successful authentication was interactive.

false: The last successful authentication was passive.

Default value: false

CODE

return DYN.user.lastAuthenticationWasInteractive

DYN.user.lastAuthenticationInterval

Integer

Number of days since the last successful authentication.

Default value: Infinite

CODE

return DYN.user.lastAuthenticationInterval >= 180

DYN.user.lastInteractiveAuthenticationInterval

Integer

Number of days since the last successful interactive authentication.

Default value: Infinite

CODE

return DYN.user.lastActiveAuthenticationInterval >= 180

DYN.user.lastFailedAuthenticationDate

Instant

The date of the last authentication failure (passive or interactive).

Default value: Now

CODE

return DYN.user.lastFailedAuthenticationDate.isBefore(REQ.date.minus(24, ChronoUnit.HOURS))

DYN.user.lastConsecutiveAccessFailureCount

Integer

A number between 0 and 10 that indicates the last consecutive failed accesses.

Default value: 10

CODE

return DYN.user.lastConsecutiveAccessFailureCount >= 3

DYN.user.lastConsecutiveAccessSuccessCount

Integer

A number between 0 and 10 that indicates the last consecutive successful accessesd.

Default value: 0

CODE

return DYN.user.lastConsecutiveAccessSuccessCount < 3

DYN.user.lastAccessFailureCount

Integer

The number of failures in the last 10 access attempts.

Enter a number between 0 and 10.

Default value: 10

CODE

return DYN.user.lastAccessFailureCount >= 3

DYN.user.lastAccessSuccessCount

Integer

The number of successes in the last 10 access attempts.

Enter a number between 0 and 10.

Default value: 0

CODE

return DYN.user.lastAccessSuccessCount < 3

DYN.user.lastLocationCountry

String

The country of the last successful authentication.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.user.lastLocationCountry == 'france'

DYN.user.lastLocationCountryCode

String

The country code of the last successful authentication.

Use a code from the ISO 3166-1 alpha-2 standard.

Default value: "UNKNOWN"

CODE

return DYN.user.lastLocationCountryCode == 'FR'

DYN.user.lastLocationRegion

String

The region of the last successful authentication.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.user.lastLocationRegion == 'ile de france'

DYN.user.lastLocationCity

String

The city of the last successful authentication.

In English and lowercase.

Default value: "unknown"

CODE

return DYN.user.lastLocationCity == 'paris'

DYN.user.lastLocationDistance

Integer

The distance in km from the last successful authentication and the current authentication.

Default value: Infinite

CODE

return DYN.user.lastLocationDistance > 200

DYN.user.lastLocationVelocity

String

The speed in km/h from the last successful authentication and the current authentication.

Default value: Infinite

CODE

return DYN.user.lastLocationVelocity > 20

DYN.user.newLocation

boolean

true: The location of the current authentication is new.

false: The location of the current authentication is found in previous access history.

Default value: true.

CODE

return DYN.user.newLocation

Handle Groovy errors

Groovy errors can happen when the RBA evaluates rules. There are two types of errors:

Compilation errors:
Compilation errors occur if the Groovy script syntax is incorrect.
They are detected early, when the administrator writes or updates the rule.
Compilation errors don't affect end users. The administrator fixes the syntax and resubmits the rule.
Runtime errors:
Runtime errors happen during rule execution, when end users access applications.
For example, an error occurs if the script tries to access a list element that does not exist.

The RBA handles runtime errors carefully to avoid blocking all users. Instead, it tries to allow authentication, sometimes requiring stronger authentication than usual.

You can also use the standard Groovy logger inside your scripts to help with troubleshooting. For example:

CODE

LOG.debug("Something")

This lets you capture errors or debug messages in the usual log stream.