Customizing IDM

This book provides information on customizing the IDM UI.


How do I generate API documentation for custom endpoints in IDM 5.5.x, 6.x and 7?

The purpose of this article is to provide information on generating API documentation for IDM custom endpoints.

Overview

For IDM 7.1 and later, please refer to the documentation instead: Scripting Guide › Write an API Descriptor for a Custom Endpoint.

Pre-IDM 7.1

The IDM API Explorer provides API documentation for IDM’s default endpoints, for example: 

However, documentation is not automatically generated for custom endpoints. You can use the API Explorer to generate reference documentation for custom endpoints by including an apiDescription field in the endpoint’s configuration file.

Generating API documentation for custom endpoints example

The following example demonstrates how to do this for the sample custom endpoint (echo) and assumes you have already created the custom endpoint. See Samples Guide › Create a Custom Endpoint for further information.

Note

If you want to add "If-None-Match" and "If-Match" header parameters to Read requests and Delete/Patch requests, you should set the mvccSupported property to 'true'. You do not need to add “if-match” and “if-none-match” specifically to the request parameters.

You can generate API documentation for a custom endpoint as follows:

  1. Add the apiDescription field to the endpoint configuration file (/path/to/idm/conf/endpoint-echo.json in this example) to include all the actions and queries you want documented. See Forgerock Wiki - Defining API Descriptors for further assistance.

For example:{    "file" : "echo.groovy",     "type" : "groovy",     "_file" : "echo.js",     "_type" : "text/javascript",     "apiDescription" : {         "title" : "Echo",         "description" : "Service that echo's your HTTP requests.",         "mvccSupported" : true,         "create" : {             "description" : "Echo a CREATE request.",             "mode" : "ID_FROM_SERVER",             "singleton" : false         },         "read" : {         "description" : "Echo a READ request." },          "update" : { "description" : "Echo an UPDATE request." },         "delete" : { "description" : "Echo a DELETE request." },         "patch" : {             "description" : "Echo a PATCH request.",             "operations" : [ "ADD", "REMOVE", "REPLACE", "INCREMENT", "COPY", "MOVE", "TRANSFORM" ]         },         "actions" : [             {                 "description" : "Echo an ACTION request.",                 "name" : "echo",                 "request" : { "type" : "object" },                 "response" : {                     "title" : "Echo action response",                     "type" : "object",                     "properties" : {                         "method" : {                             "type" : "string",                             "enum" : [ "action" ]                         },                         "action" : { "type" : "string" },                         "content" : { "type" : "object" },                         "parameters" : { "type" : "object" },                         "context" : { "type" : "object" }                     }                 }             }         ],         "queries" : [             {                 "description" : "Echo a query-filter request.",                 "type" : "FILTER",                 "queryableFields" : [ "*" ]             },             {                 "description" : "Echo a query-all request.",                 "type" : "ID",                 "queryId" : "query-all"             },             {                 "description" : "Echo a query-all-ids request.",                 "type" : "ID",                 "queryId" : "query-all-ids"             }         ],         "resourceSchema" : {             "title" : "Echo resource",             "type" : "object",             "properties" : {                 "method" : {                     "title" : "CREST method",                     "type" : "string"                 },                 "resourceName" : { "type" : "string" },                 "parameters" : { "type" : "object" },                 "context" : { "type" : "object" }             }         }     } }

  1. Review the API Explorer to check that your custom endpoint is now included, for example:

See Also

REST API Reference › REST API Explorer

Scripting Guide › Create Custom Endpoints to Launch Scripts

Forgerock Wiki - Defining API Descriptors

Using the ForgeRock IDM API Explorer

Related Training

N/A

Related Issue Tracker IDs

OPENIDM-12996 (DOCS: API Descriptor for scripted custom endpoint)


How do I add drop-down list controls to the Admin UI in IDM (All versions)?

The purpose of this article is to provide information on adding drop-down list controls to the Admin UI in IDM. This information does not apply to the End User UI or the Self-Service UI. This allows you to customize the default forms for managed objects.

Adding drop-down list controls

The default forms for managed objects are driven by schema. You can add drop-down list controls to the managed objects schema by adding an enumerated type configuration to the managed.json file (located in the /path/to/idm/conf directory).

You should add the following properties to the field that requires a drop-down list:

  • enum - this should be the option codes (no spaces).
  • options: enum_titles - this should be the option names as you want them displayed in the drop-down list.

Example

This example snippet from the managed.json file shows an updated Country field, which has four selectable options:

"country" : {    "description" : "",     "title" : "Country",     "viewable" : true,     "userEditable" : true,     "policies" : [        {           "policyId" : "minimum-length",           "params" : {               "minLength" : 1            }        }     ],     "returnByDefault" : false,     "pattern" : "",     "type" : "string",     "enum" : [         "uk",         "germany",         "us",         "chile"     ],     "options" : {         "enum_titles" : [             "United Kingdom",             "Germany",             "US",             "Chile"         ]     } }
Note

Drop-down list controls work in the Admin UI but not the End User UI or the Self-Service UI. This is a known issue: OPENIDM-11996 (UI Self-service pages don't render enumerated fields).

See Also

How do I add a new custom UI page in IDM 5.x and 6?

How do I change the display properties for a User Profile field in the Self-Service UI in IDM 5.x and 6?

Setup Guide › Admin UI

Related Training

N/A

Related Issue Tracker IDs

OPENIDM-11996 (UI Self-service pages don't render enumerated fields)

OPENIDM-8549 (Expand usability of Admin UI to manage reference data)


How do I remove access to the browser-based UI in IDM (All versions)?

The purpose of this article is to provide information on removing access to the Admin and/or End User (previously Self-Service) UIs in IDM. You may want to do this for security reasons.

Removing access to the browser-based UI

You can remove access to the Admin and/or End User UIs using one of the following options:

  • Disable the UI
  • Remove the ui directory

Disable the UI

You can disable the UIs as follows:

  • Admin: edit the ui.context-admin.json file (located in the /path/to/idm/conf directory) and change enabled to false. For example: { "enabled" : false, "urlContextRoot" : "/admin",
  • End User
    • IDM 6.5 and later: edit the ui.context-enduser.json file (located in the /path/to/idm/conf directory) and change enabled to false. For example: { "enabled" : false, "urlContextRoot" : "/",
    • Pre-IDM 6.5: edit the ui.context-selfservice.json file (located in the /path/to/idm/conf directory) and change enabled to false. For example: { "enabled" : false, "urlContextRoot" : "/",

Remove the ui directory

The ui directory (located in the /path/to/idm directory) contains an admin directory and either an enduser (IDM 6.5 and later) or selfservice (pre-IDM 6.5) directory. You can simply remove one or both of these directories to remove access to the corresponding UI.

See Also

Customizing IDM

Setup Guide › Admin UI

Self-Service Reference › Self-Service End User UI

Security Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I prevent users viewing and editing their profile attributes in the End User UI for Identity Cloud or IDM 7.x?

The purpose of this article is to provide information on making individual user profile attributes not editable in Identity Cloud or IDM to prevent users from changing their profile attributes in the End User UI. A common profile attribute to make not editable is the username. For IDM, this article applies to the platform End User UI, which is not the same as the standalone IDM End User UI.

Making individual user profile attributes not editable

You can make selected user profile attribute(s) not viewable or editable if required. When you do this, the selected properties cannot be changed by the user via the End User UI or REST API calls.

To make a user profile attribute not editable:

  1. Select the attribute (property) that you want to make not editable:
    • Identity Cloud Admin UI: navigate to Native Consoles > Identity Management > Configure > Managed Objects > [User type Managed Object] and click the name of the required attribute.
    • IDM Admin UI: navigate to Configure > Managed Objects > [User type Managed Object] and click the name of the required attribute.
  2. Click Show advanced options on the Details tab.
  3. Deselect the User Editable option and click Save.

For example, if you don't want a user in the Alpha realm (Identity Cloud) to be able to change their username, the property details would look similar to this once you update them:

Note

In IDM, you can update a property in the managed.json file (located in the /path/to/idm/conf directory) as an alternative to using the Admin UI. Locate the required property and change userEditable to false. For example:

          "userName" : {                         "title" : "Username",                         "description" : "Username",                         "viewable" : true,                         "type" : "string",                         "searchable" : true,                         "userEditable" : false,

Verifying your change

You can check if your change has been successful as follows:

  1. Navigate to the End User UI in a browser using Incognito or Browsing mode. You can find the URL for a login journey in Identity Cloud as follows:
    1. In the Identity Cloud Admin UI, navigate to Journeys.
    2. Click the required login journey.
    3. Copy the Preview URL and paste into a browser using Incognito or Browsing mode.
  2. Log in as a valid end user.
  3. Click Edit Your Profile.
  4. Click Edit Personal Info. 

You will notice the field you changed (Username in this example) is no longer displayed and therefore cannot be changed.

See Also

FAQ: Identity Cloud hosted End User UI

UI Integration Options for Identity Cloud

Deploy the Platform UIs


How do I change the display properties for a User Profile field in the Self-Service UI in IDM 5.x and 6?

The purpose of this article is to provide information on changing the display properties for a User Profile field in the Self-Service UI in IDM. For example, you might want to make the First Name and Last Name fields read-only, or the Username field editable.

Changing the display properties for a field

Note

The information in this article does not apply to IDM 6.5 and later because the End User UI is now based on the Vue JavaScript framework instead of XUI. See ForgeRock/end-user-ui: Identity Management (End User) for further information on customizing this UI.

You can change the display properties for a User Profile field using the UserProfileTemplate.html file (located in the /path/to/idm/ui/selfservice/default/templates/user directory). You should copy this template to the /path/to/idm/ui/selfservice/extension/templates/user directory as detailed in Integrator's Guide › Customizing a UI Template and then update the readonly property as needed.

This article covers the following two common use cases:

Note

These changes should be dynamic and do not require you to restart the IDM instance; if you do not see your changes straight away, you should clear your browser cache.

Making the First Name and Last Name fields read-only

You can make the First Name and Last Name fields read-only as follows:

  1. Create a new /path/to/idm/ui/selfservice/extension/templates/user directory if it does not already exist.
  2. Copy the UserProfileTemplate.html file (located in the /path/to/idm/ui/selfservice/default/templates/user directory) to the /path/to/idm/ui/selfservice/extension/templates/user directory.
  3. Edit the new UserProfileTemplate.html file in the /path/to/idm/ui/selfservice/extension/templates/user directory and add the readonly=true property to the givenName and sn fields. The updated fields would look like this in the UserProfileTemplate.html file: {{#givenName}} {{> form/_basicInput property="givenName" label="common.user.givenName" readonly=true}} {{/givenName}} {{#sn}} {{> form/_basicInput property="sn" label="common.user.sn" readonly=true}} {{/sn}}

Making the Username field editable

You can make the Username field editable as follows:

  1. Create a new /path/to/idm/ui/selfservice/extension/templates/user directory if it does not already exist.
  2. Copy the UserProfileTemplate.html file (located in the /path/to/idm/ui/selfservice/default/templates/user directory) to the /path/to/idm/ui/selfservice/extension/templates/user directory.
  3. Edit the new UserProfileTemplate.html file in the /path/to/idm/ui/selfservice/extension/templates/user directory and change both the readonly=true properties to readonly=false for the userName field (this field is listed twice). The updated section would look like this in the UserProfileTemplate.html file: {{#userName}} {{> form/_basicInput property="userName" label="common.user.username" readonly=false}} {{/userName}} {{#username}} {{> form/_basicInput property="username" label="common.user.username" readonly=false}} {{/username}}

See Also

How do I add a new custom UI page in IDM 5.x and 6?

How do I add drop-down list controls to the Admin UI in IDM (All versions)?

Integrator's Guide › Customizing a UI Template

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)

Related Issue Tracker IDs

N/A


How do I add a new custom UI page in IDM 5.x and 6?

The purpose of this article is to provide information on adding a new custom UI page in IDM using the XUI. Custom UI pages can be used to extend the functionality in IDM.

Adding a new custom UI page

Note

The information in this article does not apply to IDM 6.5 and later because the End User UI is now based on the Vue JavaScript framework instead of XUI. See ForgeRock/end-user-ui: Identity Management (End User) for further information on customizing this UI.

The XUI in IDM uses require.js for modular JavaScript® loading, backbone.js for model/view binding and handlebars.js for templating.

The following steps demonstrate creating a page in the XUI that includes some sample text.

  1. Create a routes file to introduce a new route to your view, for example: /path/to/idm/ui/selfservice/default/config/routes/CustomIDMRoutesConfig.js And define a route in this file, for example: define("config/routes/CustomIDMRoutesConfig", [ ], function() {    var obj = {         "helloWorldView" : {             view: "org/forgerock/openidm/ui/custom/HelloWorldView",             role: "ui-admin",             url: "helloWorld/"         }     };     return obj; });
  2. Update the AppConfiguration.js file (located in the /path/to/idm/ui/selfservice/default/config/ directory) to add the new routes file to your Application Configuration; find the section that includes paths to the routes (~line 55) and add a new route: {"routes":"config/routes/CustomIDMRoutesConfig"}
  3. Create a view file, for example: /path/to/idm/ui/selfservice/default/org/forgerock/openidm/ui/custom/HelloWorldView.js And add your view code to this file, for example: define("org/forgerock/openidm/ui/custom/HelloWorldView", [    "org/forgerock/commons/ui/common/main/AbstractView",     "org/forgerock/commons/ui/common/main/Configuration",     "org/forgerock/commons/ui/common/util/UIUtils"  ], function(AbstractView) {     var HelloWorldView = AbstractView.extend({         template: "templates/custom/HelloWorld.html",         baseTemplate: "templates/common/MediumBaseTemplate.html",         events: {         }     });     return new HelloWorldView(); });
  4. Create a template file, for example: /path/to/idm/ui/selfservice/default/templates/custom/HelloWorld.html And add some sample text to this file: <h2>Hello World!</h2> <p> Some sample text. </p>

That's it. You should now be able to view the new view by navigating to #helloWorld/, for example:http://localhost:8080/#helloWorld/

See Also

How do I add drop-down list controls to the Admin UI in IDM (All versions)?

How do I change the display properties for a User Profile field in the Self-Service UI in IDM 5.x and 6?

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.

This content has been optimized for printing.