8.7.1 Configuring Risk-based Authentication

Adding a Risk Policy

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

   If there is no risk policy configured, clicking Risk Configuration opens the Overview page.

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 either 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 authentication 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, then 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 will 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 a rule from the existing list or create a new rule and then assign it to the risk policy. You can assign multiple rules to a policy. 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 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, you must perform the following steps:

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 execution sequence is executed. Allow Access and Exit Policy: No other rules of this policy is executed and the user will get access to the resource. Deny Access and Exit Policy: No other rules of this policy is executed and the user will be 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. 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. For more information, 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:

   • 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 one or 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 in this field. For more information, see Risk Score Reduction After a Successful Additional Authentication:.

   • Share Score: Select this option if you want 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.

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.

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 either 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:If you want to use this contact in federation, ensure that you assign this contract to a protected resource.

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 and specify the details.

   Rule Type	Procedure
   IP Address	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. To consider the list of IP addresses provided by an external provider or an internal web service, select Dynamically consume from the Datasource. Specify URL of the provider. In Connection Timeout, specify the time in second. After this specified time, an unresponsive connection is closed. For example, 5 seconds. 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"] 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-6, Risk-based Authentication Terms. 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.
   Cookie	Specify the name of the cookie. 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-6, Risk-based Authentication Terms. [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. Specify the validity of the cookie in days. 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.
   HTTP Header	Specify the HTTP header Name. Specify the HTTP header value that you want to search for an HTTP header that includes a specific value. 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	Select an LDAP attribute from the list. If you want to define a custom LDAP attribute, click New. Specify how the conditions for the rule must be matched. Specify the value of the attribute to be searched. For example, if you selected the LDAP attribute birthDate for rule creation, specify the birth date to be searched.
   User Last Login	Specify the name of the last login cookie. Specify the path for the cookie. Specify the validity of the cookie in days. If you want the cookie to be secured by HTTPS, enable Secure Cookie. 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. Specify the crypto key to encrypt the cookie. IMPORTANT:A User Last Login cookie is set only when the user is authenticated by using second-factor authentication. A User Last Login cookie is not created if the risk is assessed to be low and the user authenticates by using primary authentication method.
   User Time of Login	Select Is/Is not condition based on your requirements. This determines how the conditions for the rule must be matched. Specify the date and time of the user login. To validate the user history recorded in the database, select Check user history. To use this option, enable Record User History in the User History tab.
   Device Fingerprint	Specify the validity of the fingerprint in number of days. 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) NOTE:Storing a fingerprint in Built-in Data Store (Bundled eDirectory) is not supported. 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. Select Prompt User Consent if you want users to provide their consent before storing the device fingerprint. 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. 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 4.6, Email Server Configuration. Click Parameter Settings if you want to modify the default settings. For information about parameters, see Section 6.2, Understanding Device Fingerprint Parameters.
   Device ID (Deprecated)	In Access Manager 4.3, this rule has been replaced with the Device Fingerprint rule. If you have configured any Device ID rule in Access Manager 4.1 or 4.2, this rule will be listed as deprecated after upgrading to Access Manager 4.3.
   Geolocation	Specify the geolocation details. Select Is/Is not condition based on your requirements. This determines how the conditions for the rule are matched. To validate the user history recorded in the database, select Check user history. To use this option, select Record User History in the User History tab.
   Geo-Velocity Tracker	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 the user tries to log in again from another location in less than five hours, the user will need to perform additional authentication. 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 Section 8.7.2, Configuring User History and Section 8.7.3, Configuring Geolocation Profiling.
   External Parameter Configuration	Select Negate Result to reverse the result of the rule evaluation. For example, if you have defined this rule to get authentication details of a request using a specific IP address, you can use Negate Result to define the rule to not consider inputs originated from that IP address. Under External Parameter, add the following details for a parameter set: Name of the parameter. Specify the 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, you can specify a regular expression as follows: (?:(?: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. 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. The available operators include contains, does not contain, is equal to, is equal to ignore case, is greater than, is greater than or equal to, is less than, is less than or equal to, in between, is not equal to, is not equal to ignore case. Specify a parameter value for evaluation. Click Add Parameter to add more parameters in this parameter set. You can define multiple parameters in a parameter set. (Conditional) Click Add Parameter Set to define additional parameter set. You can define multiple parameter sets. If you have defined two or more parameter sets, specify how the conditions for the parameters must match. The available options are Or and And. For more information, see Combination Rule in Table 5-6, Risk-based Authentication Terms. For an example about configuring external parameter, see Using External Parameters in Risk Assessment:. NOTE:To use this rule, you must create a custom class to retrieve details from an external provider. For more information, see User Information Methods and Creating a Custom Rule Class in the NetIQ Access Manager 4.4 SDK Guide.
   Custom Rule	Specify a fully qualified name of the custom class for which you want to create a custom rule. For example: com.Company.test.MyCustomclass. Select Check user history to check the user history details if the rule execution fails. 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. Click Add Property to add custom properties and values.