Use case: Configure a programmatic call out to a third-party service

Author:

Lucy Billington

Created at:

Mar 2023

Updated at:

Apr 2023

Use case overview

Calling out to a third-party service and taking actions based on the results returned is a common use case that is easily achieved in ForgeRock Identity Cloud.

This simple use case demonstrates how to create a journey that makes a call to a third party to deliver some data about the user and their context and receive a response. This might be in the format of a JSON payload or some other response that allows the journey to take the necessary steps according to the results of that external payload.

Steps to achieve this use case

In our example, we’ll use RunKit to create a very simple REST API that can be called from anywhere. We’ll then create a journey that will make a call to this REST API. The journey includes a debug node that allows the end user to view the response from the API.

Example REST API endpoint

Our example uses the following REST API, created in RunKit:

https://backstage-community-prod.storage.googleapis.com/original/2X/3/3c6faf953e12f6a69acd14b2a7cffff0676d0de0

Notice that a method has been created called /risk. If you make a call to this endpoint, the response reflects back the request headers, the query parameters, and a risk score with a hardcoded value of 99.99.

Create the user journey

Our example journey prompts the user for their username and makes a call to the third party API through a simple script. The end user can choose to display the API response via a scripted debug node.

The journey includes the following two scripts:

  • Call External API

  • FRDebug

Call external API script

Create the Call external API script, similar to this:

var userName = nodeState.get("username").asString()
var loginDoRequest = new org.forgerock.http.protocol.Request();

loginDoRequest.setMethod("GET");
loginDoRequest.setUri("https://forgerock-ig-e9ks8vbwdrab.runkit.sh/risk?username=" + userName);

var response = httpClient.send(loginDoRequest).get();

//Depending on the response, can take different actions - for now returning sent as default
//here is an example of using a response
sharedState.put("API RESPONSE", response.getEntity().getString());
outcome = "true";

Notice that the API request passes the username as a request parameter on the API call:

loginDoRequest.setUri("https://forgerock-ig-e9ks8vbwdrab.runkit.sh/risk?username=" + userName);

FRDebug script

The journey uses a debug scripted node to show the API response from the third party in the journey’s shared state. In our example, the debug script is called FRDebug:

/* debug
 *
 * Display shared state, transient state, and request headers.
 *
 * This script does not need to be parametrized. It will work properly as is.
 *
 * The Scripted Decision Node needs the following outcomes defined:
 * - true
 *
 * Author: volker.scheuber@forgerock.com
 */
(function () {
  try {
    outcome = 'true';
    var anchor = 'anchor-' + new Date().getTime();
    var message = '<p><b>Shared State</b>:<br/>' + sharedState.toString() + '</p>' +
                  '<p><b>Transient State</b>:<br/>' + transientState.toString() + '</p>' +
                  '<p><b>Request Headers</b>:<br/>' + requestHeaders.toString() + '</p>';
    var script =  "Array.prototype.slice.call(\n" +
                  "document.getElementsByClassName('callback-component')).forEach(\n" +
                  "function (e) {\n" +
                  "  var message = e.firstElementChild;\n" +
                  "  if (message.firstChild && message.firstChild.nodeName == '#text' && message.firstChild.nodeValue.trim() == '" + anchor + "') {\n" +
                  "    message.className = \"text-left\";\n" +
                  "    message.align = \"left\";\n" +
                  "    message.innerHTML = '" + message + "';\n" +
                  "  }\n" +
                  "})";
    var fr = JavaImporter(
      org.forgerock.openam.auth.node.api.Action,
      javax.security.auth.callback.TextOutputCallback,
      com.sun.identity.authentication.callbacks.ScriptTextOutputCallback
    )
    if (callbacks.isEmpty()) {
      action = fr.Action.send(
        new fr.TextOutputCallback(
          fr.TextOutputCallback.INFORMATION,
          anchor
        ),
        new fr.ScriptTextOutputCallback(script)
      ).build()
    }
    else {
      action = fr.Action.goTo(outcome).build();
    }
  } catch (error) {
    nodeState.putShared('error', error.message);
    logger.error('debug script error: {}', error.message);
  }
}());

Create the journey

  1. Sign in to the Identity Cloud admin UI using your admin tenant URL, in the format https://<tenant-name>/am/XUI/?realm=/#/.

  2. Go to Journeys > New Journey.

  3. Enter a unique name for the journey, select which identities will authenticate using this journey, (optionally) enter a journey description, and click Save.

  4. Create a journey similar to this:

    https://backstage-community-prod.storage.googleapis.com/original/2X/7/751572d9755172d15e9685250cee9b90ba128127

    Node descriptions: * Platform Username - Prompts the user to enter their username. See Platform Username node for further information. * Send Request with username - This Scripted Decision node makes a call to the third party. See Step 5 for information on configuring this node. * View Response? - This Message node asks the user if they want to view the response. See Step 6 for information on configuring this node. * Show Debug - This Scripted Decision node is a debug node that shows the response back from the API, if requested. See Step 7 for information on configuring this node.

  5. Click the Send Request with username node (Scripted Decision node), select the Call External API script you created previously, and set the outcomes to true.

    https://backstage-community-prod.storage.googleapis.com/original/2X/1/1134b1417cb6b8d9d82bb2c01d7f7c63422dd532

  6. Click the View Response? node (Message node) and enter the message you want to display to users, for example, “View the API response?”.

    https://backstage-community-prod.storage.googleapis.com/original/2X/8/81589945ac4a245f1be89adb5125b6ac2995795c

  7. Click the Show Debug node (Scripted Decision node), select the debug script you created previously, and set the outcomes to true.

    https://backstage-community-prod.storage.googleapis.com/original/2X/7/77f3d0e095273686f7f184453caefd805b3d5969

  8. Click Save to save the journey.

Test the end user journey

  1. In the Identity Cloud admin UI, go to Journeys.

  2. Click the journey you created previously and copy the Preview URL.

    uc_preview_url

  3. Paste the preview URL into a browser using Incognito or Browsing mode.

  4. Enter the username of your test user and click Next.

    https://backstage-community-prod.storage.googleapis.com/original/2X/2/22abec4d8046566a4a920c072cba91ffd91ea607

    The API call is made behind the scenes.

  5. Click Yes to view the API response.

    https://backstage-community-prod.storage.googleapis.com/original/2X/d/d7c978653f8ffd5073da34b8af94d53e7c540f2b

    The debug node shows the API response from the call to the third party in the journey’s shared state. Notice that the username, risk score and request headers are included in the response.

    uc_calloutpost_current_state

Additional resources