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:
① 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
-
Go to Realm > Scripts > Custom Endpoints, then click + New Script.
-
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>')
-
-
(Optional) Enter a Description for your new endpoint; for example "Get the current date".
-
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. -
To test your script, click Save, then either:
-
When your testing is complete, click Save and Close.
Generate a cURL request for a custom endpoint
In the script editor:
-
Click the angled brackets icon (
<>
) to open the cURL Request tab. -
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. -
(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 torequest.content.param1
andrequest.content.param2
. -
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.
-
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:
-
Click the triangle icon (
) to open the Test tab.
-
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 scriptrequest.method
variable parameter values, see this mapping table. -
(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 torequest.content.param1
andrequest.content.param2
. -
Click Run to run the cURL request. The result will appear below the editor.