Identity Cloud

Custom endpoints

Overview

You can use custom endpoints to run arbitrary scripts through the REST API. These arbitrary scripts are extremely flexible and can extend Identity Cloud behavior in many ways:

  • Validate user input fields before storing them in a user profile.

  • Create utility functions, such as getting today’s date.

  • Mandate user input fields during registration to support delegated administration decisions.

  • Query identities with a particular relationship, such as being a member of an organization, and page the results.

You can consume custom endpoints within Identity Cloud, or integrate them into your external UIs or system applications.

Custom endpoints scripting introduction

For an introduction to custom endpoints scripting, read the following:

To understand how to create identity object query expressions to use in the request.queryExpression property, refer to Define and call data queries.

Use JavaScript for scripting custom endpoints in Identity Cloud. Groovy scripts are deprecated.

Manage custom endpoints

To manage your custom endpoints, go to Realm > Scripts > Custom Endpoints.

On the Custom Endpoints page, you can view a list of existing custom endpoints. To edit, duplicate, or delete a custom endpoint, click its More () menu.

The edit option in the More menu will open the custom endpoint script in a lightweight editor which features syntax highlighting and validation checking. You can maximize the editor to full screen to edit larger scripts:

idcloudui custom endpoints editor

① Endpoint name
② JavaScript editor
③ Fullscreen option
④ Syntax highlighting
⑤ Validation checking
⑥ cURL request tab, see Generate a cURL request for a custom endpoint
⑦ Test tab, see Run a test request for a custom endpoint

Create a custom endpoint

  1. Go to Realm > Scripts > Custom Endpoints, then click + New Script.

  2. Enter a Name for your new endpoint; for example, "getDate".

    • Your new custom endpoint will be accessible over HTTP at:
      https://<tenant-env-fqdn>/openidm/endpoint/<name>

    • Your new custom endpoint will be accessible via script using:
      openidm.read('endpoint/<name>')

  3. (Optional) Enter a Description for your new endpoint; for example "Get the current date".

  4. Next, use the editor to create your script. The editor is prepopulated with a default script, which is intended as a starting point for your custom script.

    See Custom endpoints scripting introduction for information on scripting basics.

  5. To test your script, click Save, then either:

    1. Generate a cURL request for a custom endpoint

    2. Run a test request for a custom endpoint

  6. When your testing is complete, click Save and Close.

Generate a cURL request for a custom endpoint

In the script editor:

  1. Click the angled brackets icon (<>) to open the cURL Request tab.

  2. In the Method field, choose an HTTP request method for the cURL request. To understand how HTTP request methods relate to the script request.method property values, see this mapping table.

  3. (Optional) In the Body field, enter a JSON-formatted body for the cURL request (except when using the GET HTTP request method). For example:

    {
    "param1": "foo",
    "param2": "bar"
}
    In the script, you can access the body using the request.content property. The example above would map to request.content.param1 and request.content.param2.

  4. Click Generate to output the cURL request, which will appear below your script. The cURL request is complete with an access bearer token, so it’s ready to run.

  5. Click the copy icon () to copy the cURL request from the editor, then paste it into your terminal, then press return to run it in you terminal.

Run a test request for a custom endpoint

In the script editor:

  1. Click the triangle icon () to open the Test tab.

  2. In the form field, enter a JSON-formatted configuration object for the cURL request. The form field is prepopulated with a default configuration object:

      {
    "request": {
      "method": "create"
    }
  }

    This default configuration object will create a request that uses the POST HTTP request method. To understand how HTTP request methods relate to the script request.method variable parameter values, see this mapping table.

  3. (Optional) To supply a body with the request, add a request.content property:

      {
    "request": {
      "method": "create",
      "content": {
        "param1": "foo",
        "param2": "bar"
      }
    }
  }
    In the script, you can access the body using the request.content property. The example above would map to request.content.param1 and request.content.param2.

  4. Click Run to run the cURL request. The result will appear below the editor.

HTTP request methods mapped to script request.method property values

HTTP request method Script request.method

GET

read

POST

create

PUT

update

PATCH

patch

DELETE

delete
Copyright © 2010-2023 ForgeRock, all rights reserved.