{"id":36699231,"url":"https://github.com/iovation/risk-based-authentication-forgerock-plugin","last_synced_at":"2026-01-12T11:36:37.789Z","repository":{"id":71289606,"uuid":"241446922","full_name":"iovation/risk-based-authentication-forgerock-plugin","owner":"iovation","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-16T13:40:04.000Z","size":68084,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-16T14:53:24.422Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iovation.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-02-18T19:19:23.000Z","updated_at":"2024-05-16T13:40:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"ef29decc-9311-43b3-a7c2-191bc0a6512b","html_url":"https://github.com/iovation/risk-based-authentication-forgerock-plugin","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/iovation/risk-based-authentication-forgerock-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovation%2Frisk-based-authentication-forgerock-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovation%2Frisk-based-authentication-forgerock-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovation%2Frisk-based-authentication-forgerock-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovation%2Frisk-based-authentication-forgerock-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iovation","download_url":"https://codeload.github.com/iovation/risk-based-authentication-forgerock-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iovation%2Frisk-based-authentication-forgerock-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:58:46.209Z","status":"ssl_error","status_checked_at":"2026-01-12T10:58:42.742Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T11:36:37.732Z","updated_at":"2026-01-12T11:36:37.779Z","avatar_url":"https://github.com/iovation.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# IDVision with iovation Risk-Based Authentication Plugin for ForgeRock\u003cbr/\u003eQuick Start\n\n## Overview\n\nThe IDVision with iovation Risk-Based Authentication Plugin for ForgeRock \nenables you to integrate transparent device-based authentication directly into \nyour login flows. The Plugin adds the following to your ForgeRock authentication\nworkflows:\n\n  - Create a blackbox, an encrypted string that contains device attributes and is the basis of\n    iovation device recognition and a unique device ID\n  - Check whether a device is registered to a customer's account using\n    IDVision device-based authentication. \n  - Perform a full risk check against the device using IDVision with iovation\n    device-based reputation. If you are unfamiliar with a device and want greater\n    reassurance that you can trust it, IDVision can check for fraud\n    history in our global device network, and determine whether the\n    device has behaved suspiciously at any sites where it is already\n    known.\n  - Register trusted devices with customers' accounts using IDVision with iovation\n    device-based authentication. The next time your customer visits, accelerate their login\n    by verifying that they are using known, trusted devices.\n\n## What You Need to Get Started\n\n### Components\n\nTo implement the Plugin for ForgeRock, you need:\n\n  - A website that uses ForgeRock Access Management to provide user\n    access management and authentication.\n  - Established iovation implementations that include the following:\n      - Device-based authentication, in order to register your customers' devices\n        with their accounts and use them as authentication factors.\n      - Optionally, device-based reputation, in order to check a transaction\n        for risk signals. You must set up an integration point and\n        business rules for the transaction.\n  - The plugin, which is available from GitHub:\n    \u003chttps://github.com/iovation/risk-based-authentication-forgerock-plugin/releases\u003e\n\n### New to IDVision with iovation?\n\nLearn more about IDVision with iovation device-based authentication and reputation\nhere:\n[https://www.iovation.com](https://www.iovation.com \"https://www.iovation.com\")\n\nReady to schedule a demo? Reach out to us here:\n\u003chttps://www.iovation.com/demo?\u003e\n\n## How the Plugin Works\n\nLet's look at how the plugin integrates into ForgeRock, and the data\nflows when a customer logs in. This workflow describes a scenario that\nincludes both device-based authentication and reputation; depending on your \nlicense, you can implement either or both of these.\n\n1.  First confirm that the user has an established account, for example\n    by verifying a password.\n2.  Then, use device-based authentication to determine whether the device is\n    registered to a customer's account:\n    1.  When a customer logs in to a site that provides user access\n        management and authentication with ForgeRock, ForgeRock sends an\n        API request to IDVision to check whether the current device is\n        known for the customer. This calls a dedicated registration\n        check API.\n    2.  Via the API, IDVision returns an assessment to ForgeRock of how\n        closely the device matches any that are already known for the\n        customer. If the device is known, you may continue to log the\n        customer in by mapping the iovation results to the next steps in\n        the workflow.\n3.  If the device is unknown, you may opt to implement a full risk-aware\n    authentication step by performing a transaction risk check with\n    iovation FraudForce. You can then use the result to help decide next\n    steps:\n    1.  Perform a full device risk assessment with IDVision device-based \n        reputation. ForgeRock sends an API request to iovation to evaluate \n        device and transaction attributes for risk signals based on business\n        rules that you have set up for the integration point.  \n        **NOTE**\n        All device details and business rule results are stored with IDVIsion\n        with iovation; as with any other integration point, you can review \n        transaction details in the iovation Intelligence Center.\n    2.  IDVision returns the transaction outcome to ForgeRock. Within\n        your ForgeRock workflow, you may choose to allow users in with\n        **Allow** results, block users with **Deny** results, or require additional \n        authentication steps for users with **Review** results. For example, \n        you might use IDVIsion with iovation Multifactor Authentication \n        to implement mobile multifactor authentication.\n\n## Installing the Plugin\n\nThe plugin runs on your ForgeRock Access Management server. You must\ninstall it before you can implement it.\n\n1.  Go to the ForgeRock MarketPlace:\n    \u003chttps://backstage.forgerock.com/marketplace/catalogDisplay\u003e\n2.  Search for iovation. From here you can download the plugin, which\n    resides on Github:\n    [https://github.com/iovation](https://github.com/iovation \"https://github.com/iovation\")\n3.  Unzip the download.\n4.  Copy **iovation-rba-forgerock-plugin-1.0.2.jar** to the following location \n    on your ForgeRock AM server: \n    `\u003croot\u003e/webapps/openam/WEB-INF/lib`\n\n\n## Preparing to Set Up the Plugin\n\n### What's Included?\n\nOnce you've added it to an authentication tree, IDVision with iovation\nRisk-Based Authentication provides the following nodes:\n\n  - **Device ID BlackBox Collector:** This node resides on your page and\n    will collect a device print, or blackbox, that includes all of the\n    device details that IDVision with iovation needs to assess whether the \n    device is known and if it suggests potential for risky behavior.\n  - **Device Pairing Check:** This nodeVerifies whether the device is\n    already known and associated with the customer's account, and which\n    enables you to map followup actions based on the result.\n  - **Device Pairing:** Once you are confident that a new device\n    is legitimate and belongs to a good customer, this node registers \n    the device to a customer's account.\n  - **Device Pairing Reset:** Resets all device registrations for\n    a user's account.\n  - **Device Risk Check:** Assesses fraud risk for a device,\n    providing additional awareness and assurance of a device before you\n    allow it to log in and register with an account.\n\n### What Information Will You Need?\n\nYou'll need the following information about your iovation\nimplementation:\n\n  - Your iovation subscriber ID\n  - Your iovation subscriber account name and password\n  - If you will use the Risk Check node, the name of the rule set\n    that you will send transactions to\n  - URLs to the iovation services. Set this to one of the following:\n      - Customer Integration (CI) environment as you are testing integration: `https://mtls-ci-api.iovation.com/`\n      - Production, when you are ready to take your integration live: `https://mtls.api.iovation.com`\n\n## Adding the Risk-Based Authentication Plugin to Your ForgeRock Realm\n\nIn order to add IDVision with iovation to your ForgeRock Authentication tree,\nyou must add a service configuration to your realm.\n\nTo add the IDVision with iovation service to your realm:\n\n1. From the Forgerock Admin homepage, select your realm.\n\n2.  Select **Services** from the left-hand navigation bar. \n    ![Scheme](./services_menu.png)\n3.  Click **Add a Service**.\n4.  When prompted to choose a service type, select **IDVision with iovation Service\n    Configuration** and then select **Create**.\n    ![Scheme](./IDV_iovation_mtls_services.png)\n5.  In the **SERVICE** screen that appears, enter the following:\n    1. Your iovation subscriber ID\n    2. Your iovation account name and password\n    3. The root iovation API URL. Set this to one of the following:\n         - Customer Integration (CI) environment as you are testing integration: `https://mtls-ci-api.iovation.com/`\n         - Production, when you are ready to take your integration live: `https://mtls.api.iovation.com`\n      4. Your private key and certificate. These two fields are mandatory if you give mtls service URL.\n      5. Click **Save Changes**.\n\n## Setting Up Your Authentication Tree\n\n### Adding Device-Based Authentication Nodes\n\n#### Example Authentication Tree Configuration\n\nLet's look at an example authentication tree with integrated IDVision with iovation Device-Based Authentication nodes. Follow this sequence to add ClearKey to your own login page.\n\n![Scheme](./forgerock_dba_decision_tree_small_new.png)\n\n\n| Step | Description |\n|------|-------------|\n|***1***| Include a _Username Collector_ to gather the username from the customer; IDVision with iovation will then use this to locate the corresponding account ID. |\n|***2***|Add the _Device ID BlackBox Collector_ node to your page in order to collect information on the user's device. The *Device ID BlackBox Collector* automatically integrates with iovation web device print services, creating a blackbox that you can then send to iovation device registration. No configuration is required. This is required before using device pairing features.\u003cbr /\u003e\u003cbr /\u003eThis example includes a choice to enable users to forget previous device registrations. This calls the *Device Pairing Reset* node and returns the user to the login page. For your own flows, you can choose whether to expose this to end-users. You can also reset pairings from the Intelligence Center and a standalone API which is fully documented in the iovation Help Center.|\n|***3***|Include _Scripted Decision_ node that calls server-side JavaScript to set the outcome for the node programmatically and determine the path the authentication journey takes. The script can perform actions before setting the outcome.|\n|***4***|Confirm that the user has an established account, for example by verifying password.  Once you've verified the account, use the _Device Pairing Check_ node to determine whether the customer's device is already registered to the user's account. This sends the blackbox to iovation, which returns a **True** or **False** result.|\n|***5***|If the device is known, allow the user to log in.|\n|***6***|If not, we send the device through a step-up flow for additional verification. In this example, we use a one-time-password (OTP) sent through email, however you can customize the process as needed. For example, use IDVision with iovation Device-Based Reputation to perform a risk check on the device, or route through other flows that trigger multifactor solutions such as iovation Multifactor Authentication.|\n|***7***|In this example, if the user passes the OTP step, the device is registered with iovation via the *Device Pairing* node before completing the login flow.|\n\n#### 1. Configuring the Device ID Blackbox Collector Node\n\nThe *Device ID Blackbox Collector* node creates a profile of the user's device \nand stores it as an encrypted string called a blackbox. It is required.\n\n1.  Include the *Username Collector node* on your login page. This will\n    populate the customer's username, which will be passed to IDVision with \n    iovation as the account ID. By always basing the account ID on this username,\n    it will always be consistent when checking registered devices, registering new \n    devices, resetting registrations, and when running risk checks.\n2.  Add the *Device ID BlackBox Collector* node to your page. It\n    creates the blackbox, which populates the context for the \n    *Device Pairing Check* node. Optionally update the node name. \n3.  In the **WDP Third Party Host** field, verify that the URL to the iovation device print \n    server is correct. By default, this is: ` https://mpsnare.iesnare.com/`  \n4.  Optionally modify your subscriber key, which your iovation Integration Engineer \n    can provide to you.\n\n#### 2. Configuring the Scipted Decision Node\nNeed to add a JavaScript through Scripted Decision node. Here we will see how to add it.\n\n**Steps to add Scripted Decision Node**\n1.  Go to Scripts page and click New Script button.\n2. \tGive name of the script and select the script type as “Decision node script for authentication trees” and click Create button.\n3.  Copy the JavaScript from ![Javascript](./scripted_decision_javascript.txt) and paste it into script box and click save changes.\n4.  Add scripted decision node in your journey inside the Page node. Click the Scripted Decision node and select your newly created script and save your changes.\n\n#### 3. Configuring the Device Pairing Check Node\n\nThe *Device Pairing Check* node determines whether the device is\nregistered. It is required.\n\n**IMPORTANT!** The *Device Pairing Check* node uses the iovation Registration Check API \nwhich is only supported as part of the ForgeRock plugin. To check pairing status via \ndirect integrations on your web pages or in your apps, use the transaction risk \ncheck API together with the *Registered / Account Device Pair* business rule.\n\nAdd the *Device Pairing Check* node to your authentication tree. Optionally set a custom \nnode name.\n\n#### 4. Configuring the Device Pairing Node\n\nThe *Device Pairing* node registers the device with the customer's iovation account ID. It is required. \nTo set it up, add it to your authentication tree. Optionally set a custom node name.\n\n#### 5. Using the Device Pairing Reset Node\n\nThe optional *Device Pairing Reset* node resets any existing registrations with a given \naccount, effectively forgetting all known devices. To use it, add it wherever necessary \nnode to your authentication tree. Optionally set a custom node name.\n\n### Adding the Device Risk Check Node\n\n#### Overview\n\nThe *Device Risk Check* node sends the device details and basic transaction data to \nIDVision with iovation for a transaction risk check. It returns\none of the following:\n\n  - **Allow**: An **Allow** result provides risk assurance; you can proceed to \n    allow the user to log in knowing that the device appears trustworthy. \n  - **Review**: A **Review** result suggests that the device appears potentially risky and\n    requires more assurance such as multi-factor authentication. \n  - **Deny**: A **Deny** result signifies a high potential for fraud or abuse; you may opt to\n    deny entry entirely in this case.\n\n#### Example Authentication Tree Workflow with Integrated Risk Check\n\nOptionally follow this sequence to set up a basic risk check flow.\n\n![Scheme](./forgerock_rba_decision_tree_small.png)\n\n\n|Step|Description|\n|----|-----------|\n|***1***| Include a _Username Collector_ to gather the username from the customer; iovation will then use this to locate the corresponding iovation account ID. |\n|***2***| Add the _Device ID BlackBox Collector_ node to your page node in order to collect information on the user's device. This node automatically integrates with iovation web device print services, creating a blackbox that you can then send to IDVision with iovation for fraud checks and device registration. No configuration is needed. |\n|***3***| **IMPORTANT!** Before running a risk check, confirm that the user has an established account, for example by verifying password. \u003cbr\u003eUse the _Device Risk Check_ node to determine if the device is risky based on fraud history, evidence of evasion, and many other factors. This sends the blackbox to iovation, which returns an **Allow**, **Review**, or **Deny** result. |\n|***4***| An **Allow** result means that the device appears trustworthy according to your business rules. Complete the login flow and allow the user to enter.|\n|***5***| If the result is **Review**, meaning that your rule set identified significant enough risk to warrant manual assessment of the the device and account, send the device through a step-up flow for additional verification. In this example, we use a one-time-password (OTP) sent through email, however you can customize the process as needed. For example, route through other flows that trigger multifactor solutions such as iovation multifactor authentication. |\n|***6***| If the *Fraud Check* result is **Deny**, or if the user fails the OTP step, access fails. |\n|***7***| In this example, if the user passes the OTP step, the device is registered with iovation via the *Device Pairing* node before completing the login flow. |\n\n#### Configuring the Device Risk Check Node\n\n1.  Include the *Username Collector* node on your login page. This will\n    populate the customer's username, which will be passed to iovation\n    as the account ID. When you register a device, if the customer's\n    account doesn't already exist, iovation will create it using the\n    value from the *Username Collector* node. By always basing the\n    account ID on this username, it will always be consistent when\n    checking registered devices, registering new devices, and when\n    running device risk checks.\n2.  Include the *Device ID BlackBox Collector* node on your page. It\n    creates the blackbox, which captures the device data that iovation\n    uses to assess transaction risk.\n3.  Add the *Device Risk Check* node to your authentication tree and\n    configure the following:\n    1.  Optionally set a custom node name.\n    2.  Enter the name of the rule set that you have configured for this\n        integration point.\n\n# Managing Errors\n\nIf errors occur during processing, they will result in error outcomes.\n\n\n\n© Copyright 2022 iovation, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiovation%2Frisk-based-authentication-forgerock-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiovation%2Frisk-based-authentication-forgerock-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiovation%2Frisk-based-authentication-forgerock-plugin/lists"}