10.7.1 Configuring Risk-based Authentication

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.

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 a Risk Policy

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 MySQL, Microsoft SQL Server, or Oracle 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.

    NOTE: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:

    Risk Policy Name: Specify a name for the policy.

    Policy Description: Describe 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.

    NOTE:If you select an existing class, settings of the selected class are overwritten with values of this policy.

    For creating a new class, perform the following steps:

    Configuring a Risk-based Authentication Class

    1. Select one of the following options:

      Create Risk-based Auth Class:

      Calculates the risk score after authentication. For more information, see Risk Assessment and Risk Mitigation after Authenticating a Login Attempt.

      Create Risk-based Pre-Auth Class

      Calculates the risk score before authentication. For more information, see Risk Assessment and Risk Mitigation before Authenticating a Login Attempt.

      NOTE:To modify an existing class, go to Identity Server > cluster > Edit > Local > Classes.

    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. For more information, 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. For more information, see Cumulative Scoring:.

    5. To send the 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. Whenever 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 by 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 (Linux: catalina.out; Windows: stdout.log). 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 select an existing rule or create a new rule. You can assign multiple rules to a policy. 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.

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

    1. Click Actions > Create Rule.

    2. Specify a rule name.

    3. Select a rule definition. For details, see Step 2 in Configuring Rules.

    4. Click OK.

    5. 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 or create a risk level and then assign it to the rule. For information about creating a new risk level, see Configuring Risk Levels. No other rules in this policy are executed. The action specified for that risk level is executed.

      If rule condition is not met, add risk score

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

    NOTE:You can also create a rule here Policies > Risk-based Policies > Rules > New. See Configuring Rules.

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

    NOTE:To validate the rule configuration and view the result when a condition is met, click Actions > Toggle Validate. See Understanding 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.

    You can use an existing authentication contract or create a new one. 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.

  3. Click Next to configure a card for the contract. For more information, see Section 4.1.4, Configuring Authentication Contracts.

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

Configuring Rules

  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 required rules as follows:

    Rule Type

    Procedure

    Cookie

    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 4-5.

    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.

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

    Rule Type

    Procedure

    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.

    Rule Type

    Procedure

    Device Fingerprint

    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 store the fingerprint in risk-database, 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 only 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 if you want to send a mail to a user when the user logs in using an unknown device.

      You must configure the email server for this option to work. For more information, see Section 3.8, Email Server Configuration.

    7. Click Parameter Settings to modify the default settings. For information about parameters, see Understanding Device Fingerprint Parameters.

    Rule Type

    Procedure

    External Parameters

    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. In Access Manager 4.5 Service Pack 2 and earlier, you must create a custom class to retrieve details from an external provider. Access Manager 4.5 Service Pack 3 onwards, 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 more information, see User Information Methods and Creating an Authentication Class in the NetIQ Access Manager 4.5 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 4-5.

      For an example, see Using External Parameters in Risk Assessment:.

    Rule Type

    Procedure

    Geolocation

    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.

    Rule Type

    Procedure

    Geo-Velocity Tracker

    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 to record the user history, configure a history database, and configure a geolocation provider for this rule to work. See Configuring User History and Configuring Geolocation Profiling.

    Rule Type

    Procedure

    HTTP Header

    1. Specify the HTTP header Name.

    2. Specify the value that you want an HTTP header to include. For example, to search for an HTTP header that includes the value NetIQ, use Equals. To query for an HTTP header that does not include the value NetIQ, use Does Not Contain.

    Rule Type

    Procedure

    IP Address

    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 the 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. In Connection Timeout, specify the time in second. After this time, an unresponsive connection is closed. For example, 5 seconds.

      3. In Refresh Interval, specify the time in second. The connection will be refreshed at the specified interval. For example once in 86400 seconds.

      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 4-5.

    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.

    Rule Type

    Procedure

    User Profile

    1. Select an LDAP attribute from the list. Click New to define a custom LDAP attribute.

    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 the condition. For information about virtual attributes, see User Attribute Retrieval and Transformation.

    Rule Type

    Procedure

    User Last Login

    1. Specify a name for 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, select 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:This cookie is set only when a user is authenticated by using second-factor authentication. The cookie is not created if the risk is low and the user authenticates by using the primary authentication method.

    Rule Type

    Procedure

    User Time of Login

    1. Select a condition to determine how 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:Access Manager 4.5 Service Pack 3 onwards, this rule considers Coordinated Universal Time (UTC) in calculations. Access Manager versions earlier to 4.5 Service Pack 3, used the local time. If you want to use the local time instead of UTC, perform the following steps:

    1. Open /opt/novell/nam/idp/conf/tomcat.conf.

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

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

    3. Restart Identity Server.

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