Integrate Kount Control ForgeRock nodes into your ForgeRock authentication tree to utilize the Kount Control system. Integrating allows you to use Kount Control to determine if a login through ForgeRock should be allowed, blocked, or challenged, enabling a response from Kount Control to trigger a multi-factor authentication, remove authentication, or alter the login behavior in other ways.
To successfully integrate the ForgeRock node, you must have an existing ForgeRock environment. If you have not set this up yet, click here to view the ForgeRock setup documentation. You must also have the Kount Custom nodes jar - found here (https://github.com/Kount/forgerock/releases).
Table of contents:
Adding Kount custom nodes to your ForgeRock environment
Set up the ForgeRock environment by adding the Kount custom nodes, and then creating a new Realm and Tree.
- Add the Kount Control Nodes JAR file to the class path, commonly found nested in the folder for your host manager app (e.g. - {Tomcat Installation Directory}\webapps\openam\WEB-INF\lib).
- Restart the ForgeRock AM webserver to activate the Kount Control Nodes and make them available to your Authentication Trees.
- To create an Authentication Tree, on the Realm Overview page, click Authentication Tree.
- From the Trees page, click Create Tree.
- Enter a unique name for the tree, and then click Create.
- Build a tree structure for your business that incorporates the Kount Control Nodes. For additional details on tree structure, see the Tree Structure section below.
Kount Nodes
This section provides an overview of the available Kount nodes - and details the necessary configuration properties for each. The available Kount nodes are:
Kount Data Collector
The Kount Data Collector node injects the Kount Data Collector JavaScript SDK into the login page. The Kount Data Collector SDK creates a unique session ID for each session, and then sends all collected data to the Kount Control service. This node has a single outcome path.
Configuration Properties:
- Client ID: This is your company’s unique client ID that was provided by your Kount Solutions Engineer. (e.g. - 900900)
- Kount Data Collector URL: This is the Kount DDC URL. (e.g. – kaxsdc.com or portal-prod06.kount.com)
Kount Login
The Kount Login node makes the call to the Kount Control Login API, which makes the risk decision based on Kount's collected data. The response is Allow, Block, or Challenge, and a separate node (likely the Kount Decision node) is used to determine how to handle the response.
Configuration Properties:
- API Key: The API key Kount provided to authenticate your API requests. (e.g. – 1a2B3c4d5E6f7G8h9i0J1k2L)
- Kount Login API: The URL to the Kount Control REST API. (e.g. – api-qa06.KOUNT.com/login)
- Unique Identifier: Specify the property present in the ForgeRock data store attribute which uniquely identifies the user. This value can be the user’s ID in your user system, their username, their email address, or anything else that uniquely identifies the user, and will be used as userId in the login request. For more details on Unique Identifiers, click here to review the ForgeRock documentation on the topic. (e.g. – mail)
Kount Decision
The Kount Decisions node takes input from the Kount Login node and allows you to configure the tree based on the three possible outcomes: Allow, Block, or Challenge. The output is mapped as follows:
- If the login response is Allow, the outcome is Success.
- If the login response is Block, the outcome is Failure.
- If the login response is Challenge, the outcome is Challenge.
This node has no configuration properties.
Kount Trusted Device
The Kount Trusted Device node is a single-outcome node which should be used when the user has validated their identity (typically after a successful multi-factor authentication), so the device can automatically be trusted in the future..
The node checks the given device against the trusted device list and adds devices not listed.
Configuration Properties:
- Kount Trusted Device API: The URL to the Kount Trusted Device REST API. (e.g. - api-qa06.kount.com/trusted-device)
Kount Events
The Kount Events node is a single-outcome node which should be used to record a failed login or a failed or successful MFA check, which feeds into Kount’s service to help inform future risk inquiries. Since it requires a different configuration for success, failure, login, and challenge, multiple instances of the Kount Events node might be needed to capture each state.
Configuration Properties:
- API Key: The API key Kount provided to authenticate your API requests. (e.g. – 1a2B3c4d5E6f7G8h9i0J1k2L)
- Kount Events API: The URL to the Kount Events REST API. (e.g. - api-qa06.KOUNT.com/events)Outcome: Whether the authentication was a success or failure.
- Success – Secondary authentication succeeded (Authentication Type - Login should never be needed for a successful outcome).
- Failure – The primary or secondary validation failed.
- Authentication Type: Indicates what kind of authentication occurred
- Login – The user attempted the primary login (typically username/password).
- Challenge - The user attempted a secondary validation (2FA/MFA) challenge (e.g. - email link, push notification, secret question, etc.)
- Challenge Type: The type of secondary step-up authentication that the user was challenged with. The available options are:
- N/A – If the Authentication Type was Login, Challenge Type is not applicable and this option should be chosen.
- Captcha – The user is asked to answer a question that only a human should be able to answer in an effort to keep bots from authenticating.
- Captcha2 – reCAPTCHA from Google.
- Email Link – The user is emailed a link to visit.
- Email PIN – The user is emailed a one-time passcode to enter into the login form.
- MFA App - Google Auth – The user must enter a time-based code.
- MFA App - Duo – The user must validate using the Duo app.
- MFA App – iOS – The user must validate using an Apple device.
- MFA App – Authy – The user must validate using the Authy app.
- MFA App – Microsoft – The user must validate using a Microsoft service.
- MFA App – LastPass – The user must validate using the LastPass app.
- MFA App – Other – The user must validate with some other authentication app.
- Puzzle – The user is asked to solve a problem that only a human should readily understand.
- Secret Question – The user is asked to answer a question for which they previous provided the answer or are asked questions available from public records.
- Text PIN – The user is texted a one-time passcode to enter into the login form.
- Text Link – The user is texted a link to visit.
Tree Structure
The image below shows a simple authentication tree structure using Kount Authentication Nodes.
- The Page Node that contains your authentication must include the Kount Data Collector node. The Kount Data Collector injects the JavaScript SDK to collect the device data and sends it to Kount Control.
- Drag the Kount Data Collector node into the Page Node that includes your user’s authentication method.
- Set the configuration properties for the Kount Data Collector.
- Client ID: The Client ID that Kount provided to you. (e.g. - 900900)
- Kount Data Collector URL: The URL to the Kount Data Collector SDK. (e.g. - kaxsdc.com or portal-prod06.kount.com)
- Once the Kount Data Collector generates the unique session ID, the session ID and Client ID will be added to the shared state, so they are available to the other nodes.
- Add the ForgeRock-provided Data Store Decision node as the output to the authentication Page Node, which authenticates the user using the data store as you’ve configured it.
- An identity entity will be generated and be added to the shared state so that other nodes can use the identity.
- An identity entity will be generated and be added to the shared state so that other nodes can use the identity.
- Add the Kount Login node as the true output of the Data Store Decision node. This node sends the Kount Login API Call to Kount Control and store the result (Allow, Block, or Challenge) in shared storage.
- Set the configuration properties for the Kount Login node:
- API Key: The API key Kount provided to authenticate your API requests. (e.g. – 1a2B3c4d5E6f7G8h9i0J1k2L)
- Kount Login API: The URL to the Kount Login REST API. (e.g. - api-qa06.KOUNT.com/login)
- Unique Identifier: For support on the Unique Identifier, click here to review the ForgeRock documentation on the topic.
- Add the Kount Decision node as the output of the Kount Login node. This node has three outcomes: Success (Allow), Failure (Block), and Challenge. Only one outcome gets enabled at one time based on the response provided by the Kount Login Node. It has no configuration properties.
NOTE: In this example Challenge leads to the Success node, but as a best practice, link Challenge to a form of step-up authentication.
- If you are using the Kount Trusted Device node, set its configuration properties:
- Kount Trusted Device API: The URL to the Kount Trusted Device REST API. (e.g. - api-qa06.KOUNT.com/trusted-device)
- Kount Trusted Device API: The URL to the Kount Trusted Device REST API. (e.g. - api-qa06.KOUNT.com/trusted-device)
- Add the Kount Events node (configured with Authentication Type as Login and the Outcome as Failure) as the output of the False outcome of the Data Store Decision node. This node records failed authentications to help feed the Kount Control machine learning data.
- Set the configuration properties for the Kount Events node:
- API Key: The API key Kount provided to authenticate your API requests. (e.g. – 1a2B3c4d5E6f7G8h9i0J1k2L)
- Kount Events API: The URL to the Kount Events REST API. (e.g. - api-qa06.KOUNT.com/events)
-
Authentication Outcome: The Outcome is set as Failure.
-
Authentication Type: The Authentication type is set as Login
-
Challenge Type: As this is Login Failure so Challenge Type will be N/A
-
Login URL: This is the URL of the login page where the user performed their primary authentication (the URL of the Page Node page in this ForgeRock authentication tree). (e.g. – https://login.example.com/login)
Example tree structure with Challenge step-up
The workflow below uses the Kount nodes in conjunction with multi-factor authentication (MFA) nodes to handle Kount’s Challenge response.
When the outcome of the Kount Decision node is Challenge, we call an MFA node (which can be any ForgeRock MFA node, but we’re using the HOTP Generator in this example).
Kount’s machine-learning systems use MFA timing data to detect fraudulent signal, so route the MFA node that presents the MFA to a Timer Start node, which will record the time. Set the Start Time Property for this node to KountTimerNodeStartTimestamp.
The Timer Start node routes to the MFA node that collects the user’s validation (the OTP Collector Decision node in our example). Based on the outcome of this node, you are redirected to different nodes:
If the outcome of the OTP Collector Decision node is true, this implies that the one-time passcode (OTP) entered is valid and we proceed to another Timer Start node so we can send the time when the Challenge authentication was completed. Set the Start Time Property for this node to KountTimerNodeCompletedTimestamp.
The Timer Start Node is deployed before the OTP Collector Decision node to get the GMT timestamp for when the challenge was completed by the end-user.
Configuration property for Timer Start node placed before OTP Collector Decision node should be set as KountTimerNodeStartTimestamp.
ForgeRock Documentation for OTP Email Sender Node: https://backstage.forgerock.com/docs/am/7/authentication-guide/auth-node-configuration-hints.html#auth-node-otp-email-sender
ForgeRock Documentation for HOTP Generator Node:
https://backstage.forgerock.com/docs/am/7/authentication-guide/auth-node-configuration-hints.html#auth-node-hotp-generator
ForgeRock Documentation for Timer Start Node: