5.7.3 Configuring Risk-based Authentication

Important:You must consider the following points while configuring the risk-based authentication:

  • A rule must be included in a risk policy. A rule can exist in multiple risk policies.

  • A risk-based authentication class maps to only one risk policy and vice versa.

  • If a rule condition is not met, the score associated with that rule is added to the risk score. If the rule condition is met, the specified action is executed.

  • The risk level is determined based on the total risk score, that is the sum of the scores of all rule conditions that are not met.

  • If a rule is configured to allow or deny access and exit the policy when a condition is met, the risk score is zero as other rules in the group are not evaluated.

Configuring risk-based authentication involves the following steps:

  1. Create a risk policy. See Configuring a Risk Policy.

  2. Create a method for the risk-based authentication class. See Configuring a Method for an Authentication Class.

  3. Create a contract for the risk-based authentication class. See Configuring a Contract for an Authentication Class.

Configuring a Risk Policy

Prerequisites: Before creating a risk-based policy, determine the following criteria for defining a rule:

  • The application or resource you want to protect.

  • The parameters you want to assess during a login attempt.

  • The risk score for each parameter.

  • The risk levels for risk scores.

  • The action for the risk levels.

  • If you want to record the details of risk assessment.

  • If you want to store history details from the risk assessment in an external database.

  • If you want to perform profiling on user login events based on the geolocation of the user.

  • If you want to assess the risk before a user attempts to login.

Configuring a risk policy includes the following three parts:

1. Adding a Risk Policy > 2. Configuring Policy Rules > 3. Configuring Risk Levels

Adding a Risk Policy

  1. Click Policies > Risk-based Policies > Risk Policy.

  2. Click the Create Risk Policy icon.

    To create an identical copy of any existing risk policy:

    1. Click Policies > Risk-based Policies > Risk Policy.

    2. Locate the policy you want to clone and click the Clone Risk Policy icon. All rules and risk levels configured for the existing policy are copied to the new policy.

    3. Specify a name for the new policy and assign a cluster and an authentication class.

  3. Under Add Risk Policy, specify the following details:

    Field

    Description

    Risk Policy Name

    Specify a name for the policy.

    Policy Description

    Specify the purpose of this policy.

    Assign Policy To

    Select Identity Server cluster and then select an authentication class. You can select the class from the list of existing classes or you can create a new class.

    If you select an existing class, this policy overwrite settings of the selected class. To modify an existing class, go to Identity Server > cluster > Edit > Local > Classes.

    To create a new class, see Creating a Risk-based Authentication Class:.

    Creating a Risk-based Authentication Class: Perform the following steps:

    1. Select one of the following options:

      Create Risk-based Auth Class: Calculates the risk score after authentication. See Risk Assessment and Risk Mitigation after Authenticating a Login Attempt.

      Create Risk-based Pre-Auth Class: Calculates the risk score before authentication. See Risk Assessment and Risk Mitigation before Authenticating a Login Attempt.

    2. Specify a name for the class.

    3. Select Record User History to record the user’s login details.

      Before enabling this option, ensure that you have enabled recording user history in Policies > Risk Configuration > User History and configured a database. See History.

      NOTE:The Record User History option is available only for Risk-based Auth Class.

    4. Select Use Cumulative Risk Score to add current risk score of the session to this evaluation.

      If you select this option, ensure that you have defined appropriate risk levels in this class to accommodate the cumulative value. See Cumulative scoring.

    5. To send user name, risk score, and risk level of a specific login attempt to an external REST interface, click Score Sharing URLs and specify the URL of the interface. The external REST interface uses this score information to perform additional actions on the user’s identity.

      (Optional) Specify the REST endpoint authentication credential. When the risk score is sent to the REST endpoint, the endpoint sends these credentials as a basic authentication header. If the REST endpoint is protected using basic authentication, this credential is used.

      If Reduce Score is enabled, the reduced risk score is sent to the REST endpoint for a successful additional authentication.

      After enabling Score Sharing URLs, you must enable the identified risk scores for sharing.

      You can enable two Score Sharing URLs. If the REST endpoint is down, a warning message is logged in the log file, catalina.out. If the REST endpoint is down during risk score sharing, the risk is not cached and is not be shared later.

      NOTE:The Score Sharing URLs option is available only for Risk-based Auth Class.

  4. Continue with Configuring Policy Rules.

Configuring Policy Rules

You can assign multiple rules to a policy. Select a rule from existing rules or create a new rule. You can also create a rule here: Policies > Risk-based Policies > Rules > New. See Configuring Rules.

The rules are executed in the top to bottom sequence. You can drag and drop to change the priority and sequence of rules. Rules for which the action is defined as Allow Access, Deny Access, or Exit with Risk Level as specified risk level are executed as specified in the rule irrespective of the risk score accumulated for other rules that previously failed.

For each rule you want to add to a policy, perform the following steps:

  1. To create a new rule, perform the following actions:

    1. Click Actions > Create Rule.

    2. Specify a rule name and select a rule definition. For details, see Configuring Rules.

    3. Click OK.

    4. Define actions for the rule.

      Condition

      Action

      If rule condition is met

      Select any of the following options:

      Proceed to Next Rule: The next rule in the sequence is executed.

      Allow Access and Exit Policy: No other rules of this policy are executed and the user gets access to the resource.

      Deny Access and Exit Policy: No other rules of this policy are executed and the user is denied access.

      Exit with Risk Level as: Select a risk level. You can also create a risk level and then assign it to the rule. No other rules in this policy are executed. The action specified for that risk level is executed.

      To create a risk level, see See Configuring Risk Levels.

      If rule condition is not met, add risk score

      Specify the risk score that will be stored when the rule evaluation fails.

  2. To select a rule from the existing list, perform the following actions:

    1. Under Policy Rules, click Actions > Add Existing Rule.

    2. In Risk Rule, select the rule you want to add from the list.

    3. Define actions for the rule. For details, see Step 1.d.

      NOTE:To validate the rule configuration and view the result, click Actions > Toggle Validate. See How to Use the Validate Tool to Emulate Total Risk Score and Risk Levels.

  3. Continue with Configuring Risk Levels.

Configuring Risk Levels

  1. Under Risk Levels, click Actions > Add Risk Level.

  2. Specify the following details:

    Field

    Description

    Risk Level

    Select a risk level to associate with the risk score. If you select Other, specify a name to identify the custom risk level.

    Risk Score

    Specify a risk score to be associated with the risk level. The risk score indicates a value that is stored in the database after rule evaluation fails.

    Action

    Select an action for this risk score.

    If you select Additional Authentication under Action, you can select multiple classes and methods to configure additional authentication. Use a method for additional authentication when branding, overwriting of users, or a change of userstore is required. If the userstore of the additional authentication is same as the risk-based authentication class and no additional branding is needed, then use a class.

    The following are examples when you can configure multiple classes and methods:

    • When you are configuring a risk-policy for assessing the risk before authenticating a login attempt. You want to achieve the following actions:

      • Enforce X.509 authentication if the user is internal

      • Enforce form-based authentication and OTP if the user is external

      You can configure two methods or classes X.509 and OTP combination.

    • When you are configuring a risk-policy for assessing the risk after authenticating a login attempt. You can configure the combination of OTP and biometric as additional authentication methods or classes.

    Reduce Score

    After a successful additional authentication, you can configure to reduce the associated risk score. Specify the value that you want to reduce from the risk score. See Risk score reduction after a successful additional authentication.

    Share Score

    Select this option to send the risk score of this risk level to the URL specified in Score Sharing URLs in the associated authentication class. You can share risk scores only for the risk levels configured for Risk-based Auth Class.

    This option is available only if at least one Share Score URLs is configured for the authentication class.

  3. Continue with Configuring a Method for an Authentication Class.

Configuring a Method for an Authentication Class

  1. Click Local > Method > New to create a new method for the risk based authentication class.

  2. Specify a name to identify the method.

  3. Select the risk-based authentication class from Class.

  4. Deselect Identifies User.

    NOTE:If the policy is using Risk-Based Pre-Auth Class, this options must be selected at least in one method of the contract.

  5. Select a user store from the list of Available User Stores.

    IMPORTANT:In a risk-based authentication class, properties configured for the risk-based authentication method are ignored. So, if you want to configure additional properties, add the property to the risk-based authentication class.

  6. Continue with Configuring a Contract for an Authentication Class.

Configuring a Contract for an Authentication Class

  1. Click Local > Contract > New to create a new contract for the risk based authentication class.

  2. Specify a name to identify the contract.

  3. You can use an existing authentication contract or create a new authentication contract. For example, for Risk-based Auth Class, you can add the default Name/Password – Form method as the first method and risk-based authentication method as the second method. For Risk-based Pre-Auth Class, the risk-based authentication method must be configured as the first method.

  4. Click Next to configure a card for the contract. For more information about configuring contracts, see Section 5.1.4, Configuring Authentication Contracts.

    NOTE:To use this contact in federation, ensure to assign this to a protected resource.

Configuring Rules

Access Manager provides the following risk rules:

Rule

Description

IP Address

Use this rule to define a condition to track login attempts from an IP address, range of IP addresses, an IP subnet range, or a list of IP addresses from an external provider.

For example, If you are aware that login attempts from a specific range of IP addresses are riskier, you can define a rule to watch for such login attempts. When a request originates from the specified IP address range, you can prompt for additional authentication.

IMPORTANT:You cannot create a rule using the IP subnet condition. Instead you can use the IP address range condition to select a range of IP addresses in the rule.

NOTE:The IP address might not be the clients IP address, but that of an intermediate device. In such a case, use X-Forwarded-For to determine the IP address of the workstation

Cookie

Use this rule if you want to track login attempts from a browser-based application that has a specific cookie value or name.

For example: You have a financial application and a user accessing this application has cookies stored on the browser. If the cookie has a specific value or name, the user is granted access without additional authentication. If the user accessing the application has no cookies stored, then you can request additional authentication to validate the user.

HTTP Header

Use this rule to track the HTTP header of requests based on the name or the value contained in the HTTP header.

For example, if you want to track HTTP requests containing custom HTTP header information, you can define the action to be performed on evaluation of this rule.

User Last Login

This rule creates a cookie in the browser after a successful step up authentication. Subsequent login verifies this cookie. Use this rule to define the validity duration for the cookie. After the specified time, the user is prompted for additional authentication.

For example, you can use this rule to evaluate if a user logs in by using a device that was used earlier for login. You can define the risk level and also request additional authentication, as necessary.

User Profile

Use this rule to define a condition based on the LDAP attribute of the user.

For example, you can define a rule to deny access if the employee ID of the user matches a specific string.

User Time of Login

Use this rule to define a condition based on the user’s attempts to login at a specific time.

For example, if the usual login pattern for an employee is between 9 a.m. to 5 p.m., you can define a rule that takes an action if the login pattern differs from the observed pattern.

Device Fingerprint

Use this rule to uniquely identify and control the type of device from which a user could log in to the applications secured by Access Manager.

When a user log in the first time from a device and device fingerprint is not available for that device, a risk is added and Access Manager can be configured to prompt for an additional authentication. After the first successful authentication, a device fingerprint is calculated based on the parameters configured in the Device Fingerprint rule.

In subsequent login attempts, Access Manager verifies device fingerprint parameters configured in the Device Fingerprint rule.

You cannot add more than one Device Fingerprint rule per Access Manager setup.

For more information about device fingerprinting, see Device Fingerprinting.

External Parameters

Use this rule to consider inputs from external providers to evaluate the risk associated with a login attempt.

For example, if a user is already authenticated with an external authentication provider, Access Manager receives authentication details from that provider such as the method used for the authentication. Access Manager can use this information for evaluating the risk.

Geolocation

Use this rule to track login attempts based on a user’s geographical location. You can track details ranging from a wide area such as a country or to a smaller area such as a region.

For example, you can use this rule to introduce additional authentication attempts in the following scenarios:

  • when a user logs in from a specific geolocation

  • when a user accessing from a specific geolocation to be considered as a valid user and be granted access without further checks

Geo-Velocity Tracker

Use this rule to check a user’s current time and location compared to the time and location of the last login. Access Manager supports only country as the location for this rule.

The last login details are picked from the history database. If the time between the last successful login and the current login attempt is less than the shortest possible travel time, you can configure the following actions:

  • Prompt for an additional authentication

  • Deny access

For example, a user logged in at 2 p.m. IST in Bangalore and tries to re-login at 5 p.m. IST from Hong Kong. Reaching Hong Kong in three hours from Bangalore is not possible. To mitigate such malicious login attempts, you can configure a policy using this rule to ask for an additional authentication or deny the access. For more information, see Scenario: Determining an Improbable Travel Event.

Custom Rule

Use this rule to define your own custom rules by using a custom Java authentication class. This is useful in deployments where the existing rules do not meet the requirements.

For example, an HTTP header contains the company name in an encoded format. You can create a custom rule to decode this HTTP header and retrieve the name of the company. You can compare this value with an LDAP attribute and decide an action based on results.

For information about creating a custom class, see the NetIQ Access Manager SDK Guide.

To create a rule, perform the following steps:

  1. Click Policies > Risk-based Policies > Rules > New.

  2. Specify a name for the rule and select a rule type in Rule Definition based on your requirement.

  3. Configure the following rules as required:

    IP Address Rule

    Cookie Rule

    HTTP Header Rule

    User Profile Rule

    User Last Login Rule

    User Time of Login

    Device Fingerprint Rule

    Geolocation Rule

    Geo-Velocity Tracker Rule

    External Parameters Rule

    Custom Rule

     

    IP Address Rule

    1. To manually add IP addresses, select Manually enter the Datasource. You can specify a single IP address, IP address range, IP address subnet, or upload a text file containing IP addresses. To specify IPv4 subnets, use the Classless Inter-Domain Routing (CIDR) notation.

      Click Add to List.

      Sample text format 

      # Example IP List
10.0.0.0
172.16.0.0
192.168.0.0

      Each entry in the text files must be on a separate line.

    2. To consider the list of IP addresses provided by an external provider or an internal web service, select Dynamically consume from the Datasource.

      1. Specify URL of the provider.

      2. Specify Connection Timeout. After this time, an unresponsive connection is closed.

      3. Specify Refresh Interval. The connection will be refreshed at the specified interval.

      The external provider provides the list of IP addresses in text or JSON formats.

      • Sample text format
      • # Example IP List
      • 10.0.0.0
      • 172.16.0.0
      • 192.168.0.0
      • Sample JSON format
      • ["10.0.0.0","172.16.0.0","192.168.0.0"]

    3. Specify how the conditions for the rule must match. The available options are Is and Is Not. For more information about Is and Is Not conditions, see Table 5-1.

    4. To validate the user history recorded in the database, select Check user history. You can use this option only when Record user history is enabled in the User History tab.

    IMPORTANT:You cannot specify the IP subnet in the IPv6 format. Instead, you can use the IP range condition and define it in the IPv6 format.

    A cookie is set when a user authenticates using second-factor authentication. The cookie is not created if the risk is low and the user authenticates using primary authentication method.

    1. Specify the name of the cookie.

    2. Specify the value of the cookie. The different search criteria that you can use are Is and Is Not. For more information about Is and Is Not condition, see Table 5-1.

    3. [Optional] If the cookie is not found, but you want to create a cookie after the user authenticates, select Create cookie if the user authenticates successfully.

      1. Specify the validity of the cookie in hours.

      2. Specify the path for the cookie.

    HTTP Header Rule

    1. Specify the HTTP header Name.

    2. Specify the value that you want an HTTP header to include.

      For example, if you want to search for an HTTP header that includes the value NetIQ, you can use the search criterion Equals. Whereas, if you want to query for an HTTP header that does not include the value NetIQ, use Does Not Contain.

    User Profile Rule

    1. Select an LDAP attribute from the list. To define a custom LDAP attribute, click New.

    2. Specify how the conditions for the rule must be matched.

    3. Select one of the following options:

      • LDAP Attribute: Specify the value of the attribute to be searched.

        For example, if you selected the attribute birthDate for rule creation, specify the birth date.

      • Virtual Attribute: Select the type of the virtual attribute and specify a condition.

        For information about virtual attributes, see User Attribute Retrieval and Transformation.

    User Last Login Rule

    1. Specify the name of the last login cookie.

    2. Specify the path for the cookie.

    3. Specify the validity of the cookie in days.

    4. If you want the cookie to be secured by HTTPS, enable Secure Cookie.

    5. Specify the number of days the cookie can be accessed from the same device or system. This value must be less than the value in Max Age.

    6. Specify the crypto key to encrypt the cookie.

    IMPORTANT:The User Last Login cookie is set only when a user is authenticated by using second-factor authentication. This cookie is not created if the risk is assessed to be low and the user authenticates by using the primary authentication method.

    User Time of Login

    1. Select Is/Is not condition based on your requirements.

      This determines how the conditions for the rule must be matched.

    2. Specify the date and time of the user login.

    3. To validate the user history recorded in the database, select Check user history.

      To use this option, select Record User History.

    NOTE:: In Access Manager 4.5 Service Pack 3 and 5.0, the User Time of Login rule considers Coordinated Universal Time (UTC) in calculations. To use the local time instead of UTC, perform the following steps:

    1. Edit Identity Server’s tomcat.conf file. For information about how to edit a file, see Modifying Configurations.

    2. Comment out the following java option by adding #:

      JAVA_OPTS="${JAVA_OPTS} -Duser.timezone=UTC"

    However, these steps will change the time standard for OAuth logs from UTC to local time.

    In other versions of Access Manager (5.0 Service Pack 1 and later, and earlier to 4.5 Service Pack 3), the rule uses the local time.

    Device Fingerprint Rule

    1. Specify the validity of the fingerprint in number of days.

    2. Select any one of the following options under Store Fingerprint in:

      • Browser: To store the fingerprint in the browser cache on the device.

      • Server: To store the fingerprint in the configured risk-database.

        You can use this option only in risk-based post-authentication scenarios. To use this option, you must enable storing the user history in the User History tab. (Policies > Risk-based Policies > User History)

    3. Specify the number of fingerprints you want to store per user.

      This option is applicable when you select Server to store fingerprints. The permissible value is 1 to 5.

    4. Select Prompt User Consent if you want users to provide their consent before storing the device fingerprint.

    5. Select Refresh Fingerprint Validity if you want to make the fingerprint valid again for the time specified in Valid for if the user logs in from that device within the specified time.

    6. Select Send Email Notification to send an email to a user when the user logs in using an unknown device. You must configure the email server for this option to work. See Email Server Configuration.

    7. Click Parameter Settings to modify the default settings. See Understanding Device Fingerprint Parameters.

    Geolocation Rule

    1. Specify the geolocation details.

    2. Select Is/Is not condition based on your requirements.

      This determines how the conditions for the rule are matched.

    3. To validate the user history recorded in the database, select Check user history.

      To use this option, select Record User History in User History.

    Geo-Velocity Tracker Rule

    1. Specify the time in hours. If a user tries to re-login from a different location within this time, the user is prompted for an additional authentication or the access is denied.

      Access Manager verifies the location whenever the user attempts to log in.

      For example, specify 5 here. When a user tries to log in again from another location in less than five hours, the user will need to perform additional authentication.

    2. Select Negate Result to reverse the output of the rule condition.

    IMPORTANT:You must enable recording user history, configure a database, and configure a geolocation provider for this rule to work. See Configuring User History and Configuring Geolocation Profiling.

    External Parameters Rule

    1. Select Negate Result to reverse the result of the rule evaluation.

      For example, if this rule fetches authentication details of a request using a specific IP address, use Negate Result to make the rule to not consider inputs from that IP address.

    2. You can specify the URL of the external source to retrieve GET requests that return simple JSON responses.

      To perform advanced operations, such as GET that returns nested data and POST, you must create a custom class to retrieve details from an external provider. For information, see User Information Methods and Creating an Authentication Class in the NetIQ Access Manager SDK Guide.

      Perform the following steps to configure the external resource details:

      1. Select Get parameters from an external source and specify Source URL.

      2. Select Authentication Type for authenticating the external source URL.

      3. (Conditional) If you selected Basic Authentication in Authentication Type, specify Username and Password to access the specified External Source URL.

      4. Specify the Request Timeout value. After the specified time, the request is expired.

      5. Select a Request Method that is accepted by the specified external source.

      6. Select request parameters.

    3. Add the following details for a parameter set:

      1. Name of the parameter.

      2. Specify a regular expression if required. For example, suppose an external source sends the following value for the Virtual IPv4 parameter:

        The Virtual IP address is 127.0.0.1

        To extract the IP address from this string, specify the following value:

        (?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)

        This regular expression extracts the IP address 127.0.0.1 from the string and uses it for evaluating the configured condition. For more information about regular expression syntax, see the Javadoc for java.util.regex.Pattern.

      3. Select a relational or string operator to define a relationship between the parameter and parameter value. For example, whether a parameter must contain the specified parameter value or it must not be equal to the specified value.

      4. Specify a parameter value for evaluation.

      5. Click Add Parameter to add more parameters in this parameter set. You can define multiple parameters in a parameter set.

    4. (Conditional) Click Add Parameter Set to define additional parameter set.

    5. For two or more parameter sets, specify how the conditions for parameters must match. The available options are Or and And. See Combination Rule in Table 5-1.

      For an example, see Using external parameters in risk assessment.

    Custom Rule

    1. Specify a fully qualified name of the custom class for which you want to create a custom rule. For example, com.Company.test.MyCustomclass.

    2. Select Check user history to check the user history details if the rule execution fails.

    3. Select Negate Result if you want to reverse the results of rule execution. For example: if you have defined a rule to track authentication attempts from a specific geolocation, you can use Negate Result to define a rule to allow authentication if the user logging in is not from that geolocation.

    4. Click Add Property to add custom properties and values.