Advanced Identity Cloud

BioCatch Session node

Manages the interaction with the BioCatch scoring API.

This node initializes a session with the BioCatch scoring API, associates the session with the user who authenticates, and links the session ID in the user-agent with the BioCatch server.

Prerequisites

Before you start, create at least one scripted policy to determine access based on BioCatch scores.

BioCatch script

The policy relies on a policy condition script to grant or deny access depending on the BioCatch score.

  1. In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts, click + New Script, and select Policy Condition.

  2. Name your script, replace the default JavaScript with the following sample, update the default variables at the top of the script with values that suit your deployment, and save your work:

    try {
    //==================== Update these variables for the deployment ======================
      var biocatchEndpoint = "https://api-customer-id.eu.v2.customers.biocatch.com/api/v6/score";
      var customerId = "customer-id";
      var minScore = 0;
      var maxScore = 500;
      var advices = ["Fraud Alert"]; // Advices to return for a fraudulent request
    //=====================================================================================
    
      var customerSessionID = null;
    
      /**
       * Sends a request to Biocatch to get the score of a customer session.
       *
       * @returns {*} The score of a customer session.
       */
      function getScore() {
    
        var loginDoRequest = new org.forgerock.http.protocol.Request();
    
        //Set the method type.
        loginDoRequest.setMethod("POST");
    
        //set the POST URL
        loginDoRequest.setUri(biocatchEndpoint);
    
        //set some header values
        loginDoRequest.getHeaders().add('Content-Type', 'application/json; charset=UTF-8');
    
        var user = String(session.getProperty("UserToken"));
    
        //set some body values
        var theBody = JSON.stringify({
          "action": "getScore",
          "customerSessionID": customerSessionID,
          "uuid": user,
          "solution": "ATO",
          "activityType": "LOGIN",
          "customerID": customerId
        });
    
        loginDoRequest.getEntity().setString(theBody);
        var response = httpClient.send(loginDoRequest).get();
    
        var resultJSON = JSON.parse(response.getEntity().getString());
        return parseInt(resultJSON.score);
      }
    
      /**
       * Retrieve and validate the variables required to make the external HTTP calls.
       *
       * @returns {boolean} Will be true if validation was successful.
       */
      function validateAndInitializeParameters() {
    
        if (username == null || biocatchEndpoint == null || maxScore == null || customerId == null || advice == null || minScore == null)
          return false;
    
        if (!environment) {
          logger.warning("No environment parameters specified in the evaluation request.");
          return false;
        }
    
        if (environment.get("customerSessionID") != null && environment.get("customerSessionID").iterator().hasNext()) {
          customerSessionID = environment.get("customerSessionID").iterator().next();
        } else {
          logger.warning("No customerSessionId specified in the evaluation request environment parameters.");
          return false;
        }
    
        return true;
      }
    
    
      if (validateAndInitializeParameters()) {
    
        var scoreFromBiocatch = getScore();
    
        if (scoreFromBiocatch >= minScore && scoreFromBiocatch <= maxScore) {
          logger.message("Authorization Succeeded");
          authorized = true;
        } else {
          logger.message("Authorization Failed");
          advice.put("advice", advices);
          authorized = false;
        }
    
      } else {
        logger.message("Required parameters not found. Authorization Failed.");
        advice.put("advice", ["Required parameters not found"]);
        authorized = false;
      }
    } catch (error) {
      logger.error(error);
      advice.put("advice", ["Error occurred"]);
      authorized = false;
    }
  3. Adapt the sample script for the deployment as necessary.

BioCatch policy

  1. Create a policy set for BioCatch policies.

    For details, refer to Policy sets.

  2. Create a policy with the BioCatch policy decision script as an environment condition.

    The following policy grants authenticated users with an appropriate score HTTP GET and POST access to URLs:

    Grant access to GET and POST given an appropriate score

    For details, refer to Policies in the UI.

Outcomes

True

Initialization succeeded.

False

Initialization failed.

Error

An error occurred.

Properties

Property Usage

BioCatch End Point

URL for the BioCatch initialization API

Customer Id

The customer or project identifier from BioCatch

Examples

The following example injects a unique session identifier (customerSessionID) in the page for collecting credentials with the BioCatch Session Profiler node and initiates scoring:

Inject a BioCatch session identifier and initiate scoring.

The following example relies on the customer web application having the JavaScript to inject the user’s unique session identifier (customerSessionID). It collects the identifier with the BioCatch Session Collector node and initiates scoring:

Collect a BioCatch session identifier and initiate scoring.

In both cases, the policy configured as a prerequisite determines access based on the score from BioCatch.