Gigya Job Openings

Accounts RBA Policy Object

Skip to end of metadata
Go to start of metadata

Description

The RBA Policy Object defines the Risk Based Authentication policy for the site or site-group. The object contains the global rules, which apply to all login attempts, in the commonRules array, and the account rule-sets, which respond to login attempts from a specific user, in the rulesSets array. To set the RBA policy, see accounts.rba.setPolicy REST.

Unable to render {include} The included page could not be found.

Watch an Instructional Video

To watch a video about this subject, you can visit our Enablement portal with your approved SAP customer or partner ID (S user). Please visit the About page to find out how to get an S user.

Configuration

The license could not be verified: License Certificate has expired!

Policy Object

Depending upon which types of action and factor objects you set will determine which of these parameters will be required. See the individual sections below the table, which define each type of object with their respective code examples.

The license could not be verified: License Certificate has expired!

policy (object)

commonRules (array) -

Rules that apply to all login attempts

id (string)Must be unique and not start with an underscore (_).
description (string)A friendly description of the rule .
enabled (boolean)Defines if the rule is enabled.
action (object)type (string)lockoutLocks out (blocks) the LoginID or IP of the user from successfully logging in for the specified period of time. Requires defining a scope. Can not be used with rootFactor.type: apiKey in a site group.
  
TFAForces the user to pass Two-Factor Authentication.
captchaForces the user to pass a CAPTCHA. Requires defining a scope.
allow

No action required, login flow continues.

scope (array)

Required for captcha and lockout types

accountSpecify account if you wish the CAPTCHA or lockout to apply to a user account, if the rootFactor is met and the action triggered.
IPSpecify IP if you wish the CAPTCHA or lockout to apply to the IP address, if the rootFactor is met and the action triggered.
 

 

 

 

reservedreserved
duration (integer)(Only applies to  lockout  action) - The length of time the action will be in effect after triggering, in seconds.
authLevel (integer)(Only applies to  country  and  device  types) - The level of authentication this action satisfies.
rootFactor (object)type (string)deviceThe physical device (or unique browser) used to access the site.
countryThe country the login occurs from (based upon IP Address).
failedLoginsThe number of failed logins required to trigger the factor.
IPRatio

The action will be triggered above a certain percentage of failed login attempts. Configured using the following parameters:

  • ratio
  • threshold
  • resetInterval

The only allowed scope for the IPRatio is IP. Accordingly, the action scope should be set to IP as well.

IPAn IP address that will be included in the rule when its inclusive parameter is set to true, or will be excluded from it when inclusive is set to false. Requires ranges and inclusive.
apiKeyAn API key that will be included in the rule when its inclusive parameter is set to true, or will be excluded from it when inclusive is set to false. Requires apiKeys and inclusive. This factor is used in a multi-site scenario, to define rules that apply only to specific APIs within the site group.
allAll of the following factors: (requires an array of factor objects).
anyAny of the following factors: (requires an array of factor objects).

scope (array)

Only applies to  failedLogins  factor

accountThe unique user.
IPThe user's IP address. In the context of a rootFactor, the IP parameter is used to count the number of failed logins.
global_IPUses Network Effects global lockout by IP address. In the context of a rootFactor, the global_IP parameter is used to count the number of failed logins.
global_emailUses Network Effects global lockout by email address. In the context of a rootFactor, the global_email parameter is used to count the number of failed logins.
reserved reserved
threshold (integer)

Applies to failedLogins  and IPRatio

  • For failedLogins: Maximum number of login attempts.
  • For IPRatio: The number of failed login attempts after which the rule is triggered
ratio (integer)(Applies to IPRatio) - A number between 0 and 1 representing the percentage of failed login attempts of the total logins, above which the action will be triggered.
resetInterval (integer)

Applies to failedLogins and IPRatio:

  •  failedLogins  - The length of time before the triggered policy is reset, in seconds. Setting this to NULL will make the resetInterval infinite.
  • IPRatio - The length of time during which the IPRatio is calculated. This must be an integer between 1 to 172800 (48hrs). Setting this to NULL will cause an error.
authLevel (integer)(Only applies to country and device  types) - The level of authentication triggered by this factor.
trustedCountries (array)(Only applies to country  type) - A case-sensitive array of 2 character country codes in ISO 3166   format (e.g., ["GB", "US", "DE"]).
expirationPeriod (integer)(Only applies to country  and device  types) - The time between the triggered event and resetting the policy.
ranges (array)

(Only applies when defining IP as a type, and requires the inclusive parameter as well) - A ranges value can be a single IP or a range defined as:

["192.168.0.0/255.255.255.0",
"192.168.0.10 - 192.168.10.20",
"192.168.0.0/16"]

The license could not be verified: License Certificate has expired!

apiKeys (array)(Only applies when defining apiKey as a type, and requires the inclusive parameter as well) Defined as: ["apiKey1", "apiKey2", "apiKey3"]. This factor is used in a multi-site scenario, to define rules that apply only to specific APIs within the site group.
inclusive (Boolean)

Applies to IP and apiKey types. If set to true, the factor will be triggered for IP addresses and/or API keys that fall inside the given range. If set to false, the factor will be triggered for IP addresses and/or API keys that fall outside the given range.

For example, if you define a rule which locks out the user after 5 failed logins for a specific API key, and set the inclusive parameter to true, this rule will apply only to this API key. If you set the inclusive parameter to false, this rule will apply to any API key except the one specified in the rule.

rulesSets (array) -

Account-level rules

id (string)Must be unique and not start with an underscore (_).
description (string)A friendly description of the risk policy.
enabled (boolean)Defines if the risk policy is enabled.

rules (array)

(max 10 rule objects)

enabled (boolean)Defines if the rule is enabled.
description (string)A friendly description of the rule.
action (object)type (string)lockoutLocks out (blocks) the LoginID or IP of the user from successfully logging in for the specified period of time. Requires defining a scope. Can not be used with rootFactor.type: apiKey in a site group.
  
TFAForces the user to pass Two-Factor Authentication.
captchaForces the user to pass a CAPTCHA. Requires defining a scope.
allowNo action required, login flow continues.

scope (array)

Required for captcha and lockout

accountThe unique user.
IPThe user's IP address. In the context of an action, the IP parameter is used to challenge users after failed logins from an IP address (e.g. lock them out for a designated number of seconds).
  
  
reservedreserved
duration (integer)(Only applies to  lockout  action) - The length of time the action will be in effect after triggering, in seconds.
authLevel (integer)(Only applies to country and  device  types) - The level of authentication this action satisfies.
rootFactor (object)type (string)deviceThe physical device (or unique browser) used to access the site.
countryThe country the login occurs from (based upon IP Address).
failedLoginsThe number of failed logins required to trigger the factor.
allAll of the following factors: (array of factor objects).
anyAny of the following factors: (array of factor objects).

scope (array)

Only applies to  failedLogins  factor

accountThe unique user.
IPThe user's IP address. In the context of a rootFactor, the IP parameter is used to count the number of failed logins.
global_IPUses Network Effects global lockout by IP address. In the context of a rootFactor, the global_IP parameter is used to count the number of failed logins.
global_emailUses Network Effects global lockout by email address. In the context of a rootFactor, the global_email parameter is used to count the number of failed logins.
reservedreserved
threshold (integer)Only applies to failedLogins  factor) - Maximum number of login attempts.
resetInterval (integer)

Applies to failedLogins and IPRatio:

  • failedLogins  - The length of time before the triggered policy is reset, in seconds. Setting this to NULL will make the resetInterval infinite.
  • IPRatio - The length of time during which the IPRatio is calculated. This must be an integer between 1 to 172800 (48hrs). Setting this to NULL will cause an error.

authLevel (integer)

(Only applies to country  and device types) - The level of authentication triggered by this factor .

trustedCountries (array of strings)(Only applies to country  type) - A case-sensitive array of 2 character country codes in ISO 3166   format (e.g., ["GB", "US", "DE"]).
expirationPeriod (integer)(Only applies to country  and device types) - The time between the triggered event and resetting the policy.
defaultPolicy (string)

The default risk policy name. Can be set to any one of the defined rulesSets or any of the built-in risk policies. This property must be set in order for RBA to be enabled by default for all users. Built-in rulesSets include: 

  • _off - All users evaluated will pass login automatically.

To disable RBA for your site or site-group, set this value to null

allowOverrideMode (string)no( default ) - The defined defaultPolicy will always be used.
adminManagedOnly an admin can change a user's risk policy.
userManagedUsers can change their own risk policy.

Admins can always override a user's risk policy, regardless of this setting.

When using a factor type of either all or any, you can not have more than 3 nested Factor objects or you will receive an Invalid_parameter_value error.

To reset a site's RBA Policy to the default _off policy, you can call accounts.rba.setPolicy REST with either an empty Policy object or NULL.

The license could not be verified: License Certificate has expired!

 

 

 

 

 

Policy Object Example

{
    "commonRules": [
        {
        // rule #1
            "enabled": true,
            "description": "A friendly name for rule 1.",
            "action": {
                //actionObj
                "type": "lockout",
                "scope": [
                    "account", "ip"
                ],
                "duration": 43200
            },
            "rootFactor": {
                //factor.object
                "type": "failedLogins",
                "scope": [
                    "account","ip"
                ],
                "threshold": 5,
                "resetInterval": 86400
            }
        }
    ],
    "rulesSets": [
        {
            "id": "demo",
            "description": "A friendly description of the policy",
            "enabled": true,
            "rules": [
                {
                    rule #1
                },
                {
                    rule #2 //optional
                },
                {
                    rule #3 //optional
                }
            ]
        }
    ],
    "defaultPolicy": "demo",
    "allowOverride": "adminManaged"
}

 

Rule Object Base Structure

{
    "enabled": boolean,
    "description": "string",
    "action": { 
        actionObj
    },
    "rootFactor": {
        factorObj
	}
}

 

Available Action Objects

The action object must be one of the following:

Unless specified as optional below, all listed parameters are required for the specified type.

	{
        "type": "lockout",
        "scope": [
			"account",
			"IP"
		],
        "duration": 43200
    },
    {
        "type:": "TFA",
        "authLevel": 20
    },
    {
        "type": "captcha",
        "scope": [
			"account",
			"IP"
		],
    }

 

Available Factor Objects

The factor object must be one of the following:

Unless specified as optional below, all listed parameters are required for the specified type.

   {
       "type": "failedLogins",
       "scope": [
			"account",
			"IP"
		],
       "threshold": 5,
       "resetInterval": 86400
   },
   {
       "type": "IPRatio",
       "scope": [
			"IP" // only "IP" can be set as the scope for the IPRatio type
		],
       "ratio": 0.05,
       "threshold": 100,
       "resetInterval": 7200
   },
   {
       "type": "country",
       "authLevel": 20 //(optional),
	   "expirationPeriod": 86400,
       "trustedCountries": []
   },
   {
      "type": "IP",
      "ranges": ["192.168.0.0/255.255.255.0", "198.168.0.0/16"],
      "inclusive": true
   },
   {
      "type": "apiKey",
      "apiKeys": ["apiKey1", "apiKey2"],
      "inclusive": false
   },
   {
       "type": "device",
       "authLevel": 20 //(optional)
	   "expirationPeriod": 86400,
   },
   {
        "type": "all",
        "factors": [ 
			{
				factor1
			},
			{
				factor2
			}
		]
   },
   {
        "type": "any",
        "factors": [ 
			{
				factor1
			},
			{
				factor2
			}
		]
   }

 

RBA Associated Errors

errorCodeerrorMessage

Description

403120Account Temporarily Locked OutReturned when a user attempts to login while either their account (loginID) or ip is blocked by RBA policy.

 

Policy Examples

Captcha And Lockout

{
    "name": "captchaAndLockout",
    "rules": [
        {
            "enabled": true,
            "description": "Captcha after 3 failed logins",
            "action": {
                "type": "captcha",
                "scope": ["account"]
            },
            "rootFactor": {
                "type": "failedLogins",
                "scope": "account",
                "threshold": 3,
                "resetInterval": 3600
             }
        },
        {
            "enabled": true,
            "description": "Lockout after 10 failed logins",
            "action": {
                "type": "lockout",
                "scope": ["account"],
                "duration": 36000
            },
            "rootFactor": {
                "type": "failedLogins",
                "scope": ["account"],
                "threshold": 10,
                "resetInterval": 72000
            }
        }
    ]
}

 

TFA After Country Change

 {
    "name": "TFAAfterCountryChangeAndFailedLogin",
    "rules": [
        {
            "enabled": true,
            "description": "On country change and 1 failed login require TFA",
            "action": {
                "type": "TFA",
                "authLevel": 20
            },
            "rootFactor": {                        "type": "country",
                        "authLevel": 20,
                        "trustedCountries": ["EN", "US"]
                    }

        }
    ]
}

 

Fresh Default Policy Object Example

{
  "commonRules": [
    {
      "action": {
        "scope": [
          "account"
        ],
        "type": "captcha"
      },
      "rootFactor": {
        "type": "failedLogins",
        "scope": [
          "account"
        ],
        "threshold": 10,
        "resetInterval": null
      },
      "description": "_console_captcha",
      "enabled": true
    },
    {
      "action": {
        "duration": 800,
        "scope": [
          "IP"
        ],
        "type": "lockout"
      },
      "rootFactor": {
        "type": "failedLogins",
        "scope": [
          "IP"
        ],
        "threshold": 20,
        "resetInterval": 3600
      },
      "description": "_console_ipLockout",
      "enabled": true
    }
  ],
  "rulesSets": [
    {
      "id": "_off",
      "description": "This policy represents a policy without any validations",
      "enabled": true,
      "rules": []
    }
  ],
  "defaultPolicy": "_off",
  "allowOverrideMode": "no"
}

 

Using the apiKeys Parameter with TFA in an SSO Group example:

In the following example we are enabling TFA for all sites of a site group except the specified site; based upon the excluded site's API key.

For the Root Factor section enter:

{
  "factors": [
    {
      "type": "device",
      "expirationPeriod": 60,
      "authLevel": 20
    },
    {
      "type": "apiKey",
      "apiKeys": [
        "<apiKey1>"
      ],
      "inclusive": false
    }
  ],
  "type": "all"
}

 

For the Action section enter:

{
  "authLevel": 20,
  "type": "TFA"
}

 

 

Network Effects Global failedLogins example:

"factorTypes": [
   {
       "type": "failedLogins",
       "scope": ["account", "global_IP", "global_email"],
       "threshold": 5,
       "resetInterval": 86400
   },
   {
        "type": "captcha",
        "scope": ["account"],     
   }
]

 

 

Additional Information

accounts.rba.setPolicy REST

accounts.rba.getPolicy REST

accounts.rba.unlock REST

 

 

 

 

 

  • No labels