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.
-
In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts, click + New Script, and select Policy Condition.
-
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; }
-
Adapt the sample script for the deployment as necessary.
BioCatch policy
-
Create a policy set for BioCatch policies.
For details, refer to Policy sets.
-
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:
For details, refer to Policies in the UI.
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:
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:
In both cases, the policy configured as a prerequisite determines access based on the score from BioCatch.