The health check service reports on the state of the server and outputs this state to the OSGi console and to the log files. The server can be in one of the following states:

To verify the current server state, use the following REST call:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/info/ping"
{
  "_id": "",
  "_rev": "",
  "shortDesc": "OpenIDM ready",
  "state": "ACTIVE_READY"
}

To obtain information about the current IDM session, beyond basic health checks, use the following REST call:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/info/login"
{
  "_id": "login",
  "authenticationId": "openidm-admin",
  "authorization": {
    "component": "internal/user",
    "authLogin": false,
    "roles": [
      "internal/role/openidm-admin",
      "internal/role/openidm-authorized"
    ],
    "ipAddress": "0:0:0:0:0:0:0:1",
    "id": "openidm-admin",
    "moduleId": "INTERNAL_USER"
  }
}

The openidm/health endpoint provides more detailed monitoring information on the following areas:

For information on controlling access to these endpoints, see "Understanding the Access Configuration Script (access.js)".

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/health/os"
{
    "_id" : "",
    "_rev" : "",
    "availableProcessors" : 1,
    "systemLoadAverage" : 0.06,
    "operatingSystemArchitecture" : "amd64",
    "operatingSystemName" : "Linux",
    "operatingSystemVersion" : "2.6.32-504.30.3.el6.x86_64"
}

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/health/memory"
{
    "_id" : "",
    "_rev" : "",
    "objectPendingFinalization" : 0,
    "heapMemoryUsage" : {
        "init" : 1073741824,
        "used" : 88538392,
        "committed" : 1037959168,
        "max" : 1037959168
    },
    "nonHeapMemoryUsage" : {
        "init" : 24313856,
        "used" : 69255024,
        "committed" : 69664768,
        "max" : 224395264
    }
}

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/health/recon"
{
    "_id" : "",
    "_rev" : "",
    "activeThreads" : 1,
    "corePoolSize" : 10,
    "largestPoolSize" : 1,
    "maximumPoolSize" : 10,
    "currentPoolSize" : 1
}

The configurable health check service verifies the status of the modules and services required for an operational system. During system startup, IDM checks that these modules and services are available and reports on any requirements that have not been met. If dynamic configuration changes are made, IDM rechecks that the required modules and services are functioning, to allow ongoing monitoring of system operation.

     "org.forgerock.openicf.framework.connector-framework"
     "org.forgerock.openicf.framework.connector-framework-internal"
     "org.forgerock.openicf.framework.connector-framework-osgi"
     "org.forgerock.openidm.audit"
     "org.forgerock.openidm.core"
     "org.forgerock.openidm.enhanced-config"
     "org.forgerock.openidm.external-email"
     ...
     "org.forgerock.openidm.system"
     "org.forgerock.openidm.ui"
     "org.forgerock.openidm.util"
     "org.forgerock.commons.org.forgerock.json.resource"
     "org.forgerock.commons.org.forgerock.util"
     "org.forgerock.openidm.security-jetty"
     "org.forgerock.openidm.jetty-fragment"
     "org.forgerock.openidm.quartz-fragment"
     "org.ops4j.pax.web.pax-web-extender-whiteboard"
     "org.forgerock.openidm.scheduler"
     "org.ops4j.pax.web.pax-web-jetty-bundle"
     "org.forgerock.openidm.repo-jdbc"
     "org.forgerock.openidm.repo-ds"
     "org.forgerock.openidm.config"
     "org.forgerock.openidm.crypto"

     "org.forgerock.openidm.config"
     "org.forgerock.openidm.provisioner"
     "org.forgerock.openidm.provisioner.openicf.connectorinfoprovider"
     "org.forgerock.openidm.external.rest"
     "org.forgerock.openidm.audit"
     "org.forgerock.openidm.policy"
     "org.forgerock.openidm.managed"
     "org.forgerock.openidm.script"
     "org.forgerock.openidm.crypto"
     "org.forgerock.openidm.recon"
     "org.forgerock.openidm.info"
     "org.forgerock.openidm.router"
     "org.forgerock.openidm.scheduler"
     "org.forgerock.openidm.scope"
     "org.forgerock.openidm.taskscanner"

By default, the server is given 15 seconds to start up all the required bundles and services before system readiness is assessed. Note that this is not the total start time, but the time required to complete the service startup after the framework has started. You can change this default by setting the value of the servicestartmax property (in milliseconds) in your resolver/boot.properties file. This example sets the startup time to five seconds:

openidm.healthservice.servicestartmax=5000

The Admin UI includes multiple default dashboards. You can create additional dashboards, or add and remove widgets from the existing dashboards. For more information, see "Managing Dashboards".

When you log into the Admin UI the Quick Start dashboard loads by default.

Quick Start Dashboard

The Admin UI includes a fixed top menu bar. As you navigate around the Admin UI, you should see the same menu bar throughout.

To display all configured dashboards, select Dashboards > Manage Dashboards. In addition to the Quick Start dashboard, three dashboards are provided by default: System Monitoring, Resource Report and Business Report. The default dashboards cover the following functionality:

You can set up additional dashboards for customized views of the Admin UI, and you can embed external dashboards such as Kibana or Grafana, or other monitoring boards.

To create a new dashboard, select Dashboards > New Dashboard. Enter a dashboard name and select whether this dashboard should be the default board that is displayed when you load the Admin UI.

To add a widget to a dashboard, click Add Widget and select the widget type. Widgets are grouped in logical categories, so scroll down to the category that fits the widget you want to add.

If you add a new Quick Start widget, select the vertical ellipsis () icon in the upper right corner of the widget, and click Settings.

IDM writes the changes you make to the ui-dashboard.json file for your project.

For example, if you add two widgets (Last Reconciliation and System Health) to a new dashboard named Test, you'll see the following excerpt in your ui-dashboard.json file:

{
    "name" : "test",
    "isDefault" : false,
    "widgets" : [
        {
            "type" : "lastRecon",
            "size" : "large",
            "barchart" : "false"
        },
        {
            "type" : "systemHealthFull",
            "size" : "large"
        }
    ],
    "embeddedDashboard" : false
}

For more information on each property, see the following table:

When complete, you can select the name of the new dashboard under the Dashboards menu or from the Manage Dashboards panel.

You can modify the options for each dashboard and widget. Select the vertical ellipsis in the upper right corner of the object, and make desired choices from the pop-up menu.

The following tables display an alphabetical list of the available widgets, by category:

In the Admin UI, you can manage most details associated with an account. Create a user if needed, and then select Manage > User > Username. In the screen that appears, you can configure the following elements of a user account:

With the following procedures, you can use the Admin UI to add, update, and delete accounts for managed objects such as users. To make these changes using REST, see "Working with Managed Users".

The managed object does not have to be a user. It can be a role, a group, or even a physical item such as an IoT device. The basic process for adding, modifying, deactivating, and deleting other objects is the same as it is with accounts. However, the details may vary; for example, many IoT devices do not have telephone numbers.

In a similar way, you can create accounts for other managed objects.

You can review new managed object settings in the managed.json file of your project-dir/conf directory.

In the following procedures, you learn how:

You may want to customize parts of the Admin UI. You've set up an openidm/ui/admin/extension directory as described in "Customizing the Admin UI". In that directory, you can find a series of subdirectories. The following table is intended to help you search for the right file(s) to customize:

To see an example of how this works, review "Customizing the End User UI". It includes examples of how you can customize parts of the End User UI. You can use the same technique to customize parts of the Admin UI.

$ cd /path/to/openidm/ui/admin/extension
$ tree

You can configure a few features of the UI in the ui-themeconfig.json file in your project's conf/ subdirectory. However, to change most theme-related features of the UI, you must copy target files to the appropriate extension subdirectory, and then modify them as discussed in "Customizing the Admin UI".

By default the UI reads the stylesheets and images from the respective openidm/ui/function/default directories. Do not modify the files in this directory. Your changes may be overwritten the next time you update or even patch your system.

The default Admin UI configuration files are located in openidm/ui/admin/default. To customize the UI, copy this directory to openidm/ui/admin/extension:

You may also need to update the "stylesheets" listing in the ui-themeconfig.json file for your project, in the project-dir/conf directory.

"stylesheets" : [
    "css/bootstrap-3.4.1-custom.css",
    "css/structure.css",
    "css/theme.css"
],

If you want to set up custom versions of these files, copy them to the extension/css subdirectories.

The default UI logo is in openidm/ui/admin/default/images. To change the logo, place your custom image in the openidm/ui/admin/extension/images directory. You should see the changes after refreshing your browser.

To specify a different file name, or to control the size, and other properties of the logo image file, adjust the logo property in the UI theme configuration file for your project (conf/ui-themeconfig.json).

The following change to the UI theme configuration file points to an image file named example-logo.png, in the openidm/ui/admin/extension/images directory:

...
"loginLogo" : {
     "src" : "images/example-logo.png",
     "title" : "Example.com",
     "alt" : "Example.com",
     "height" : "104px",
     "width" : "210px"
},
...

Refresh your browser window for the new logo to appear.

You can configure a few features of the UI in the ui-themeconfig.json file in your project's conf directory. However, to change most theme-related features of the UI, you must copy target files to the appropriate extension subdirectory, and then modify them as discussed in "Customizing the Admin UI".

By default the UI reads the stylesheets and images from the openidm/ui/admin/default directory. Do not modify the files in this directory. Your changes may be overwritten the next time you update or even patch your system.

To customize your UI, first set up matching subdirectories in (openidm/ui/admin/extension). For example, openidm/ui/admin/extension/libs and openidm/ui/admin/extension/css.

You might also need to update the "stylesheets" listing in the ui-themeconfig.json file for your project, in the project-dir/conf directory.

"stylesheets" : [
    "css/bootstrap-3.4.1-custom.css",
    "css/structure.css",
    "css/theme.css"
],

To set up custom versions of these files, copy them to the extension/css subdirectories.

You can specify custom response headers for your UI by using the responseHeaders property in UI context configuration files such as conf/ui.context-selfservice.json. For example, the X-Frame-Options header is a security measure used to prevent a web page from being embedded within the frame of another page. For more information about response headers, see the MDN page on HTTP Headers.

Since the responseHeaders property is specified in the configuration file for each UI context, you can set different custom headers depending on the needs of that part of IDM. For example, you may want different security headers included for the Admin and End User UIs.

From the Admin UI, you can change the passwords of accounts in the internal Managed User data store; to do so, take the following steps in the Admin UI:

By default, the Password Reset mechanism is handled within IDM. You can reroute Password Reset in the event that a user has forgotten their password, by specifying an external URL to which Password Reset requests are sent. Note that this URL applies to the Password Reset link on the login page only, not to the security data change facility that is available after a user has logged in.

To set an external URL to handle Password Reset, set the passwordResetLink parameter in the UI configuration file (conf/ui-configuration.json) file. The following example sets the passwordResetLink to https://accounts.example.com/account/reset-password:

passwordResetLink: "https://accounts.example.com/reset-password"

The passwordResetLink parameter takes either an empty string as a value (which indicates that no external link is used) or a full URL to the external system that handles Password Reset requests.

To set up basic user self-registration, you'll need at least the following configuration files:

To enable self-service registration in the UI, enable the following boolean in ui-configuration.json:

"selfRegistration" : true,

You can include several features with user self-registration, as shown in the following excerpts of the selfservice-registration.json file:

For audit activity data related to user self-registration, see "Querying the Activity Audit Log".

You can review the current user self-registration configuration over REST:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/config/selfservice/registration"

Unless you've disabled file writes per "Disabling Automatic Configuration Updates", the output will match the contents of your project's selfservice-registration.json file.

If needed, you can update this configuration by including the desired contents of the file:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request PUT \
--data '{ <Insert file contents here> }' \
"http://localhost:8080/openidm/config/selfservice/registration"

During user self-registration, IDM lists the attributes that users see in the user registration form, as defined in the selfservice-registration.json file. You can modify the properties shown to users in the registrationProperties code block:

"registrationProperties" : [
    "userName",
    "givenName",
    "sn",
    "mail"
],

If you add a managed user property to the registrationProperties code block, IDM includes it in the user self-registration screen.

Alternatively, you can add a managed user property in the Admin UI. Select Configure > User Registration, and add a property under the Registration Form tab. This action also adds a managed user property to the noted code block.

In either case, you can change the order of properties; IDM shows the order you configure in the user self-registration screen.

You can also set up user self-registration via configuration files, as described in the following table:

Before you can activate Social Registration under the User Registration, Social tab, you'll need to configure registration with social identity providers. To review the process, see "Configuring Social Identity Providers".

When you've configured one or more social identity providers, you can activate the Social Registration option. This action adds:

Under the Social tab, you'll see a list of property mappings as defined in the selfservice.propertymap.json file.

One or more source properties in this file takes information from a social identity provider. When a user registers with their social identity account, that information is reconciled to the matching target property for IDM. For example, the email property from a social identity provider is normally reconciled to the IDM managed user mail property.

You can also find property mappings in the sync.json for your project. For details of these synchronization mappings, see "Mapping Source Objects to Target Objects".

To configure user self-registration from the Admin UI, select Configure > User Registration and select Enable User Registration in the page that appears.

You can also add these settings to the following configuration file: selfservice-registration.json. When you modify these settings in the Admin UI, IDM creates the file for you.

After configuring user self-registration, test the result from the end user's point of view. Navigate to the End User UI at http://localhost:8080, and select Create an account. You'll see a single-page Sign Up screen with configured text boxes and required security questions. If included in your configuration files, you'll also see marketing preferences such as "Send me news and updates".

If you've configured Terms & Conditions, you'll see a link to those terms:

By clicking "Sign Up" you agree to our Terms & Conditions.

If you've activated the reCAPTCHA option as described in "Configuring Google reCAPTCHA", you'll need to satisfy the requirements before you can select the SAVE button to create your new user account.

If you've activated the Privacy & Consent option, you'll see a Privacy Notice pop-up. By default, users who try to register aren't allowed to select the Give Consent button, until they actually consent to sharing their information.

Once the new user is created, you should be able to verify the account in the following ways:

You can set up multiple self-registration flows, with features limited only by the capabilities listed in "User Self-Registration".

For example, you may want to set up different portals for regular employees and contractors. You'd configure each portal with different self-registration flows, managed by the same IDM backend. Each portal would use the appropriate registration API.

To prepare for this section, you'll need a selfservice-registration.json file. You can find a copy in the following directory: /path/to/openidm/samples/example-configurations/self-service.

User self-registration is normally coded in the selfservice-registration.json file. In preparation, copy this file to the selfservice-registration*.json to the names shown in the following list:

Once you've configured both portals, you can make REST calls to both URLs:

For more advice on how you can create custom registration flows, see the following public ForgeRock Git repository: Identity Management (End User) - UI.

To set up basic user password reset features, you'll need at least the following configuration files:

To set up self-service user password reset registration, enable the following boolean in ui-configuration.json:

"passwordReset" : true,

You can include several features with user password reset, as shown in the following excerpts of the selfservice-reset.json file:

You can review the current user password reset configuration over REST:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/config/selfservice/reset"

Unless you've disabled file writes per "Disabling Automatic Configuration Updates", the output should match the contents of your project's selfservice-reset.json file.

If needed, you can update this configuration by including the desired contents of the file:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request PUT \
--data '{ <Insert file contents here> }' \
"http://localhost:8080/openidm/config/selfservice/reset"

To configure Password Reset from the Admin UI, select Configure > Password Reset. When you select Enable Password Reset, you'll see a Configure Password Reset Form that allows you to specify the:

You can also add these settings to the following configuration file: selfservice-reset.json. When you modify these settings in the Admin UI, IDM creates the file for you.

After configuring password reset in "User Password Reset", you can test the result from the end user's point of view. Navigate to the End User UI at http://localhost:8080, select the Profile icon () > Account Security > Password > Reset your password.

You should see a Reset Your Password page with pre-configured queries. After providing an answer, IDM should send a password reset link to the email associated with the target user account.

To set up basic forgotten username configuration, you'll need at least the following configuration files:

To set up forgotten username retrieval, enable the following boolean in ui-configuration.json:

"forgotUsername" : true,

You can include several features with forgotten username retrieval, as shown in the following excerpts of the selfservice-reset.json file:

You can review the current forgotten username configuration over REST:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/config/selfservice/username"

Unless you've disabled file writes per "Disabling Automatic Configuration Updates", the output will match the contents of your project's selfservice-username.json file.

If needed, you can update this configuration by including the desired contents of the file:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request PUT \
--data '{ <Insert file contents here> }' \
"http://localhost:8080/openidm/config/selfservice/username"

To configure forgotten username retrieval from the Admin UI, select Configure > Forgotten Username. When you select Enable Forgotten Username Retrieval, you'll see a Configure Forgotten Username Form that allows you to specify the:

You can also add these settings to the following configuration file: selfservice-username.json. When you modify these settings in the Admin UI, IDM creates the file for you.

After configuring forgotten username retrieval, you can test the result from the end user's point of view. Navigate to the End User UI at http://localhost:8080, and select Forgot Username?.

You should see a Retrieve Your Username page with pre-configured queries. After providing an answer, IDM should either display your username in the local browser, or send that username to the associated email address.

Google reCAPTCHA helps prevent bots from registering users or resetting passwords on your system. For Google documentation on this feature, see Google reCAPTCHA. IDM works with Google reCAPTCHA v2.

To use Google reCAPTCHA, you will need a Google account and your domain name (RFC 2606-compliant URLs such as localhost and example.com are acceptable for test purposes). Google then provides a Site key and a Secret key that you can include in the self-service function configuration.

For example, you can set up reCAPTCHA by adding the following code block to the configuration file for user self-registration selfservice-registration.json, password reset, selfservice-reset.json and forgotten username selfservice-username.json functionality.

{
    "name" : "captcha",
    "recaptchaSiteKey" : "< Insert Site Key Here >",
    "recaptchaSecretKey" : "< Insert Secret Key Here >",
    "recaptchaUri" : "https://www.google.com/recaptcha/api/siteverify"
},

You may also add the reCAPTCHA keys through the UI for each of these self-service features.

When a user requests a new account, a password reset, or a reminder of their username, you can configure IDM to confirm the request by sending an email message to that user.

Before you can configure email validation, you must first configure an outgoing email service. To do so, select Configure > Email Settings. For more information, read "Configuring Outbound Email".

To activate Email Validation, you'll need to include an appropriate code block, depending on whether you're setting up self-registration, password reset, or forgotten username functionality, in the corresponding configuration file.

Alternatively, in the Admin UI, select Configure > User Registration or Password Reset or Forgotten Username. Enable the feature. Under the Options tab, enable the Email option.

To configure the email message that informs the user of the new account, see "Configuring Notification Emails".

The following sections include the code blocks that are added to each configuration file:

{
    "name" : "emailValidation",
    "identityEmailField" : "mail",
    "emailServiceUrl" : "external/email",
    "emailServiceParameters" : {
        "waitForCompletion" : false
    },
    "from" : "info@example.com",
    "subject" : "Register new account",
    "mimeType" : "text/html",
    "subjectTranslations" : {
        "en" : "Register new account",
        "fr" : "Créer un nouveau compte"
    },
    "messageTranslations" : {
        "en" : "<h3>This is your registration email.</h3><h4><a href=\"%link%\">Email verification link</a></h4>",
        "fr" : "<h3>Ceci est votre mail d'inscription.</h3><h4><a href=\"%link%\">Lien de vérification email</a></h4>"
    },
    "verificationLinkToken" : "%link%",
    "verificationLink" : "https://localhost:8443/#/registration/"
},

{
    "name" : "emailValidation",
    "identityEmailField" : "mail",
    "emailServiceUrl" : "external/email",
    "emailServiceParameters" : {
        "waitForCompletion" : false
    },
    "from" : "info@example.com",
    "subject" : "Reset password email",
    "mimeType" : "text/html",
    "subjectTranslations" : {
        "en" : "Reset your password",
        "fr" : "Réinitialisez votre mot de passe"
    },
    "messageTranslations" : {
        "en" : "<h3>Click to reset your password</h3><h4><a href=\"%link%\">Password reset link</a></h4>",
        "fr" : "<h3>Cliquez pour réinitialiser votre mot de passe</h3><h4><a href=\"%link%\">Mot de passe lien de réinitialisation</a></h4>"
    },
    "verificationLinkToken" : "%link%",
    "verificationLink" : "https://localhost:8443/#/passwordreset/"
},

{
    "name" : "emailUsername",
    "emailServiceUrl" : "external/email",
    "emailServiceParameters" : {
        "waitForCompletion" : false
    },
    "from" : "info@example.com",
    "mimeType" : "text/html",
    "subjectTranslations" : {
        "en" : "Account Information - username"
    },
    "messageTranslations" : {
        "en" : "<h3>Username is:</h3><br />%username%"
    },
    "usernameToken" : "%username%"
},

IDM uses security questions to enable users to verify their identities. Security questions are sometimes referred to as Knowledge-Based Authentication (KBA). When an administrator has configured security questions, self-service users can choose from the questions set in the selfservice.kba.json file, as described in "Security Questions and Self-Registration".

You can prompt users to update their security questions. As these questions may be subject to risks, you can set up IDM to prompt the user to update and/or add security questions, courtesy of the selfservice-kbaUpdate.json file. For more information, see "Prompting to Update Security Questions".

{
      "kbaPropertyName" : "kbaInfo",
      "minimumAnswersToDefine": 2,
      "minimumAnswersToVerify": 1,
      "questions" : {
          "1" : {
              "en" : "What's your favorite color?",
              "en_GB" : "What is your favourite colour?",
              "fr" : "Quelle est votre couleur préférée?"
          },
          "2" : {
              "en" : "Who was your first employer?"
          }
      }
}

"numberOfAttemptsAllowed" : 2,
"kbaAttemptsPropertyName" : "lockoutproperty"

"explicitMapping" : {
     "managed/user": {
     "table" : "managed_user",
     "objectToColumn": {
         ...
         "lockoutproperty" : "lockoutproperty",
         ...
}   

mysql> show columns from managed_user;

+----------------------+--------------+------+-----+---------+-------+
| Field                | Type         | Null | Key | Default | Extra |
+----------------------+--------------+------+-----+---------+-------+
| objectid             | varchar(38)  | NO   | PRI | NULL    |       |
| rev                  | varchar(38)  | NO   |     | NULL    |       |
| username             | varchar(255) | YES  | UNI | NULL    |       |
| password             | varchar(511) | YES  |     | NULL    |       |
| accountstatus        | varchar(255) | YES  | MUL | NULL    |       |
| postalcode           | varchar(255) | YES  |     | NULL    |       |
| lockoutproperty      | varchar(255) | YES  |     | NULL    |       |
...

IDM has specific policies for usernames and passwords, in the policy.js file in the openidm/bin/defaults/script directory. To enforce these policies for user self-registration and password reset, add the following objects to your conf/policy.json file, under resources:

{
    "resource" : "selfservice/registration",
    "calculatedProperties" : {
        "type" : "text/javascript",
        "source" : "require('selfServicePolicies').getRegistrationProperties()"
    }
},
{
    "resource" : "selfservice/reset",
    "calculatedProperties" : {
        "type" : "text/javascript",
        "source" : "require('selfServicePolicies').getResetProperties()"
    }
},

For more information on IDM policies, see "Using Policies to Validate Data".

When a new user registers through the IDM self-registration interface, and if you've configured email per "Configuring Outbound Email", that user will get a welcome email as configured in the emailTemplate-welcome.json file:

{
    "enabled" : true,
    "from" : "",
    "subject" : {
        "en" : "Your account has been created"
    },
    "message" : {
        "en" : "<html><body><p>Welcome to OpenIDM. Your username is '{{object.userName}}'.</p></body></html>"
    },
    "defaultLocale" : "en"
}

The Admin UI includes tools that can help you customize email messages related to two administrative tasks: creating users and resetting passwords.

To configure these messages from the Admin UI, select Configure > Email Settings > Templates, where you'll see the following option:

When you register with a social identity provider, IDM checks the email address of that account against the managed user data store.

If that email address doesn't exist for any IDM managed user, IDM takes available identifying information, and pre-populates the self-registration screen. If all required information is included, IDM proceeds to other screens, depending on what you've activated in this section: "Common Steps: User Self-Registration, Password Reset, Forgotten Username".

When you register with a social identity provider, IDM checks the email address of that account against the managed user data store.

If that email address exists for one IDM managed user, IDM gives you a chance to link to that account, with the following message:

We found an existing account with the same email address
<substitute email address>. To continue, please enter your password to
link accounts.

In the text box, users are expected to enter their IDM account password.

When you register with a social identity provider, IDM checks the email address of that account against the managed user data store.

If that email address exists for multiple IDM managed users, IDM denies the login attempt, with the following error message:

Unable to authenticate using login provider

IDM denies further attempts to login with that account with the following message:

Forbidden request error

When your users register with a social identity provider, as defined in "Configuring Social Identity Providers", they create an account in the IDM managed user data store. As an end user, you can link additional social identity providers to that data store, from the End User UI, using the following steps:

You can review social identity accounts linked to an IDM account, from the Admin UI and from the command line. You can disable or delete social identity provider information for a specific user from the command line, as described in "Reviewing Linked Accounts Over REST".

When you activate a social identity provider, IDM creates a new managed object for that provider. You can review that managed object in the managed.json file, as well as in the Admin UI, by selecting Configure > Managed Objects.

The information shown is reflected in the schema in the identityProvider-providername.json file for the selected provider.

$ curl \
--header "X-OpenIDM-Username:openidm-admin" \
--header "X-OpenIDM-Password:openidm-admin" \
--request GET \
"http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+'bjensen'&_fields=idps"
{
  "result": [
    {
      "_id": "bjensen",
      "_rev": "000000003062291c",
      "idps": [
        {
          "_ref": "managed/google/108246554379618660085",
          "_refResourceCollection": "managed/google",
          "_refResourceId": "108246554379618660085",
          "_refProperties": {
            "_id": "ba01a4c3-8a7f-468b-8b09-95f5d34f05ea",
            "_rev": "0000000098619792"
          }
        }
      ]
    }
  ],
...
}

$ curl \
--header "X-OpenIDM-Username:openidm-admin" \
--header "X-OpenIDM-Password:openidm-admin" \
--request GET \
"http://localhost:8080/openidm/managed/google/108246554379618660085"
    {
  "_id": "108246554379618660085",
  "_rev": "00000000e5cace4d",
  "sub": "108246554379618660085",
  "name": "Barbara Jensen",
  "given_name": "Barbara",
  "family_name": "Jensen",
  "picture": "https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg",
  "email": "babs.jensen@gmail.com",
  "email_verified": true,
  "locale": "en",
  "_meta": {
    "subject": "108246554379618660085",
    "scope": [
      "openid",
      "profile",
      "email"
    ],
    "dateCollected": "2018-03-08T02:07:27.882"
  }
}

$ curl  \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-type: application/json" \
--request POST \
"http://localhost:8080/openidm/managed/user/9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb?_action=unbind&provider=google"

When you integrate IDM with ForgeRock Access Management (AM) you can take advantage of AM's abilities to work with User-Managed Access (UMA) workflows. AM and IDM use a common installation of ForgeRock Directory Services (DS) to store user data.

For instructions on how to set up this integration, see "Integrating IDM With the ForgeRock Identity Platform" in the Samples Guide. Be sure to set up DS as the AM user data store. Once you've set up integration through that sample, you can configure AM to work with UMA. For more information, see the AM User-Managed Access (UMA) Guide. From that guide, you need to know how to:

Pay close attention to the AM documentation on configuring an OAuth 2.0 UMA Client and UMA Server. You may need to add specific grant types to each OAuth 2.0 application.

If you follow AM documentation to set up UMA, you'll see instructions on setting up users as resource owners and requesting parties. If you set up users in AM, be sure to include the following information for each user:

AM writes this information to the common DS user data store. You can then synchronize these users to the IDM Managed User data store, with a command such as:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request POST \
"http://localhost:8080/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser"

After your users have shared UMA resources from the AM Self-Service UI, they can view what they've done and shared in the IDM End User UI, by selecting the Sharing icon ().

You can configure Trusted Devices through AM, using the following sections of the AM Authentication and Single Sign-On Guide: Configuring Authentication Chains and Device ID (Match) Authentication Module. You can use the techniques described in these sections to set up different authentication chains for administrators and regular users.

You can create an AM authentication chain with the following modules and criteria:

This is different from the authentication chain described in the following section of the AM Authentication and Single Sign-On Guide: Device ID (Match) Authentication Module, as it does not include the HOTP Authentication Module

When trusted devices are enabled, users are presented with a prompt on a screen with the following question "Add to Trusted Devices?". If the user selects Yes, that user is prompted for the name of the Trusted Device.

End users can find their account details in the End User UI, by selecting the Profile icon () > Edit Personal Info. By default, user information includes at least the following properties: Username, First Name, Last Name, and Email Address.

Each user can modify this information as needed, as long as "userEditable" : true for the property in your project's managed.json file. For more information, see "Creating and Modifying Managed Object Types".

Under this tab, end users can change their passwords. They can also add, delete, or modify security questions, and link or unlink supported social identity accounts. For more information, see "Configuring Security Questions" and "Configuring Social Identity Providers".

The preferences tab allows end users to modify marketing preferences, as defined in the managed.json file, and the Managed Object User property Preferences tab. For more information, see "Configuring End User Preferences".

End users can toggle marketing preferences. When IDM includes a mapping to a marketing database, these preferences are sent to that database. This can help administrators use IDM to target marketing campaigns and identify potential leads.

A trusted device uses AM's Device ID (Match) and Device ID (Save) authentication modules, as described in the AM Authentication and Single Sign-On Guide. When such modules are configured (see "Configuring Trusted Devices on IDM"), end users can add such devices the first time they log in from a new location.

During the login process, when an end user selects Log In, that user is prompted for a Trusted Device Name. Users see their added devices under the Trusted Devices tab.

A trusted device entry is paired with a specific browser on a specific system. The next time the same end user logs in from the same browser and system, in the same location, that user should not be prompted to enter a trusted device again.

End users can remove their trusted devices from the tab.

The Authorized Applications section is specific to end users as OAuth 2 clients. and reflects the corresponding section of the AM Self-Service dashboard, as described in the following section of the AM OAuth 2.0 Guide on: User Consent Management.

This section assumes that as an administrator, you've followed the instructions in "Configuring Privacy & Consent" to enable Privacy & Consent.

End users who see a Personal Data Sharing section have control of whether personal data is shared with an external database, such as one that might contain marketing leads.

The managed object record for end users who consent to sharing such data is shown in REST output and the audit activity log as one consentedMappings object:

"consentedMappings" : [ {
   "mapping" : "managedUser_systemLdapAccounts",
   "consentDate" : "2017-08-25T18:13:08.358Z"
}

If enabled, end users will see a Personal Data Sharing section in their profiles. If they select the Allow link, they can see the data properties that would be shared with the external database.

This option supports the right to restrict processing of user personal data.

The Account Controls section allows end users to download their account data (in JSON format), and to delete their accounts from IDM.

To modify the message associated with the Delete Your Account option, refer to the following section of the public ForgeRock Identity Management (End User) Git repository on Translations. You'll find content GitHub "Customizing the End User UI", find the translation.json file, search for the deleteAccount code block, and edit text information as desired.

The options shown in this section can help meet requirements related to data portability, as well as the right to be forgotten.

If you're testing progressive profile completion, you can start from the selfservice-profile.json file in the following directory: openidm/samples/example-configurations/self-service/

Copy this file to your project's conf/ subdirectory and start IDM. After the conditions shown in this configuration file are met, end users will see a form prompting them to add a telephone number.

{
    "stageConfigs" : [
        {
            "name" : "conditionaluser",
            "identityServiceUrl" : "managed/user",
            "condition" : {
                "type" : "loginCount",
                "interval" : "at",
                "amount" : 25
            },
            "evaluateConditionOnField" : "user",
            "onConditionTrue" : {
                "name" : "attributecollection",
                "identityServiceUrl" : "managed/user",
                "uiConfig" : {
                    "displayName" : "Add your telephone number",
                    "purpose" : "Help us verify your identity",
                    "buttonText" : "Save"
                },
                "attributes" : [
                    {
                        "name" : "telephoneNumber",
                        "isRequired" : true
                    }
                ]
            }
        }
    ]
}

The following table includes a detailed list of each property shown in this file:

In some circumstances, you may wish to create a temporary role for users who are in the middle of progressive profile completion, such as if you wish to enable access to an endpoint, while prohibiting access to other parts of the End User UI (as well as the rest of IDM).

To do this, you may optionally define an authenticationRole in auth.profile.json, which you can use as a role assignment in access.js or elsewhere.

For example, if you wished to assign access to a custom endpoint for users who have incomplete profiles, you could modify auth.profile.json to include a custom authenticationRole called incomplete-profile:

{
  "profileEnhancementProcesses": [
    "selfservice/termsAndConditions",
    "selfservice/kbaUpdate",
    "selfservice/profile"
  ],
  "authenticationRole": "incomplete-profile",
  "authorizationRole": "internal/role/openidm-authorized"
}

You could then give access to this role to your custom endpoint in access.js:

{
    "pattern"    : "endpoint/extra-steps",
    "roles"      : "incomplete-profile",
    "methods"    : "read",
    ...
},

Access for these and other roles is governed by the access.js script. For more information, see "Understanding the Access Configuration Script (access.js)".

The role specified in authenticationRole can be an existing role, or it can be a placeholder string. If it is a placeholder, it will not function as a real role, but can still be used for access in access.js, and will appear in access and authentication log files in the openidim/audit directory.

Progressive profile completion requires that you track object metadata, as described in "Tracking Metadata For Managed Objects". Read that section to configure tracking of the following data:

User acceptance of Terms & Conditions is tracked by default (see "Adding Terms & Conditions").

You can manage the progressive profile completion configuration through the following endpoint: openidm/config/selfservice/profile. To review your current configuration, run the following command:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/config/selfservice/profile"

Unless you've disabled file writes per "Disabling Automatic Configuration Updates", the output will match the contents of your project's selfservice-profile.json file.

In a similar fashion, you can update this configuration by including the desired contents of the file:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
    "stageConfigs" : [
        {
            "name" : "conditionaluser",
            "identityServiceUrl" : "managed/user",
            "condition" : {
                "type" : "loginCount",
                "interval" : "at",
                "amount" : 25
            },
            "evaluateConditionOnField" : "user",
            "onConditionTrue" : {
                "name" : "attributecollection",
                "identityServiceUrl" : "managed/user",
                "uiConfig" : {
                    "displayName" : "Add your telephone number",
                    "purpose" : "Help us verify your identity",
                    "buttonText" : "Save"
                },
                "attributes" : [
                    {
                        "name" : "telephoneNumber",
                        "isRequired" : true
                    }
                ]
            }
        }
    ]
}' \
"http://localhost:8080/openidm/config/selfservice/profile"

The UI is straightforward; in the Admin UI, when you select Configure > Progressive Profile, you'll add a New Form, with:

What you configure in the Admin UI is written to the selfservice-profile.json file. The information under the following Admin UI Progressive Profile Completion page tabs is written to the following code blocks in that file:

If you want to try the IDM implementation of Terms & Conditions, look at these files from the openidm/samples/example-configurations/self-service directory:

Copy these files to your project directory and start IDM. To see how these Terms & Conditions appear to end users, create a regular user. Log into the End User UI as that user. You will be prompted to accept default Terms & Conditions.

The Terms & Conditions that you see in the End User UI come from the selfservice.terms.json file:

{
  "versions": [
    {
      "version": "2.0",
      "termsTranslations": {
        "en": "Some 2.0 fake terms",
        "fr": "More 2.0 fake terms"
      },
      "createDate": "2017-12-19T03:54:16.865Z"
    },
    {
      "version": "1.5",
      "termsTranslations": {
        "en": "Some 1.5 fake terms",
        "fr": "More 1.5 fake terms"
      },
      "createDate": "2017-11-20T04:20:11.320Z"
    }
  ],
  "active": "1.5",
  "uiConfig" : {
    "displayName" : "We've updated our terms",
    "purpose" : "You must accept the updated terms in order to proceed.",
    "buttonText" : "Accept"
  }
}

As suggested by this file, you can set up different versions of Terms & Conditions in multiple languages. What is seen by end users is driven by the active version.

For details, see the following table:

The other Terms & Conditions configuration file is selfservice-termsAndConditions.json. If it exists, end users must accept the specified Terms & Conditions before logging into IDM. As shown here, this applies Terms & Conditions to the managed/user store.

{
    "stageConfigs" : [
        {
            "name" : "conditionaluser",
            "identityServiceUrl" : "managed/user",
            "condition" : {
                "type" : "terms"
            },
            "evaluateConditionOnField" : "user",
            "onConditionTrue" : {
                "name" : "termsAndConditions"
            }
        },
        {
            "name" : "patchObject",
            "identityServiceUrl" : "managed/user"
        }
    ]
}

When a user accepts Terms & Conditions, IDM records relevant information in the _meta data for that user, as described in "Identifying When a User Accepts Terms & Conditions".

You can set up user self-registration to require acceptance of Terms & Conditions as described in "User Self-Registration".

You can manage the configuration for Terms & Conditions over the following endpoints:

For example, the following command would replace the value of buttonText:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[ {
   "operation" : "replace",
   "field" : "uiConfig/buttonText",
   "value" : "OK"
} ]' \
"http://localhost:8080/openidm/config/selfservice.terms"

You can identify when a user accepts Terms & Conditions, as well as the associated version. To do so, take the following steps:

From the Admin UI, select Configure > Terms & Conditions. You can then create a new version, which prompts you to configure the following:

Once you've added Terms & Conditions in all desired locales, select Save to save them in the selfservice.terms.json file.

Once you have at least one set of Terms & Conditions, you should see a Settings tab, where you can:

These changes are recorded in _meta data for each user and can be retrieved through REST calls described in "Identifying When a User Accepts Terms & Conditions".

The default database connection configuration file for a MySQL database follows:

{
    "driverClass" : "com.mysql.jdbc.Driver",
    "jdbcUrl" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/openidm?allowMultiQueries=true&characterEncoding=utf8",
    "databaseName" : "openidm",
    "username" : "openidm",
    "password" : "openidm",
    "connectionTimeout" : 30000,
    "connectionPool" : {
        "type" : "hikari",
        "minimumIdle" : 20,
        "maximumPoolSize" : 50
    }
}

The configuration file includes the following properties:

An excerpt of a MySQL database table configuration file follows:

{
     "dbType" : "MYSQL",
     "useDataSource" : "default",
     "maxBatchSize" : 100,
     "maxTxRetry" : 5,
     "queries" : {...},
     "commands" : {...},
     "resourceMapping" : {...}
 }

The configuration file includes the following properties:

An excerpt of a DS repository configuration file follows:

{
     "embedded" : false,
     "maxConnectionAttempts" : 5,
     "security" : {...},
     "ldapConnectionFactories" : {...},
     "queries" : {...},
     "commands" : {...},
     "rest2LdapOptions": {...},
     "indices": {...},
     "schemaProviders": {...},
     "resourceMapping" : {...}
 }

The configuration file includes the following properties:

For both generic and explicit mappings, IDM maps object types using a dnTemplate property. The dnTemplate is effectively a pointer to where the object is stored in DS. For example, the following excerpt of the default repo.ds.json file shows how configuration objects are stored under the DN ou=config,dc=openidm,dc=forgerock,dc=com:

"config": {
    "dnTemplate": "ou=config,dc=openidm,dc=forgerock,dc=com"
},

"managed/*": {
    "dnTemplate": "ou=managed,dc=openidm,dc=forgerock,dc=com"
},

"indices" : {
    ...
    "fr-idm-managed-user-json" : {
      "type" : [ "EQUALITY" ]
    },
    ...
  },
  "schemaProviders" : {
    "Managed User Json" : {
      "matchingRuleName" : "caseIgnoreJsonQueryMatchManagedUser",
      "matchingRuleOid" : "1.3.6.1.4.1.36733.2.....",
      "caseSensitiveStrings" : false,
      "fields" : [ "userName", "givenName", "sn", "mail", "telephoneNumber" ]
    },
    ...
  },
     

"managed/user" : {
    "dnTemplate": "ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com",
    "objectClasses": [ "person", "organizationalPerson", "inetOrgPerson", "fr-idm-managed-user-explicit" ],
    "properties": {
        "_id": {
            "type": "simple", "ldapAttribute": "uid", "isRequired": true, "writability": "createOnly"
        },
        "userName": {
            "type": "simple", "ldapAttribute": "cn"
        },
        "password": {
            "type": "json", "ldapAttribute": "fr-idm-password"
        },
        "accountStatus": {
            "type": "simple", "ldapAttribute": "fr-idm-accountStatus"
        },
        "roles": {
            "type": "json", "ldapAttribute": "fr-idm-role", "isMultiValued": true
        },
        "effectiveRoles": {
            "type": "json", "ldapAttribute": "fr-idm-effectiveRole", "isMultiValued": true
        },
        "effectiveAssignments": {
            "type": "json", "ldapAttribute": "fr-idm-effectiveAssignment", "isMultiValued": true
        },
        ...
    }
},

{"code":400,"reason":"Bad Request","message":"Unmapped fields...}

"resourceMapping": {
    "defaultMapping": {
        "dnTemplate": "ou=generic,dc=openidm,dc=forgerock,dc=com"
    },
    ...
    "explicitMapping": {
        "managed/user" : {
            "dnTemplate": "ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com",
            "objectClasses": [
                "person",
                "organizationalPerson",
                "inetOrgPerson",
                "fr-idm-managed-user-explicit"
            ],
            "namingStrategy" : {
                "type" : "clientDnNaming",
                "dnAttribute" : "uid"
            },
         ...
}

{
     "namingStrategy" : {
         "type" : "clientDnNaming",
         "dnAttribute" : "uid"
     },
     "properties: : {
         "_id": {
             "type": "simple",
             "ldapAttribute": "uid",
             "isRequired": true,
             "writability": "createOnly"
         },
     ...
     }
 }

Free-form commands and native queries on the repository are disallowed by default and should remain so in production to reduce the risk of injection attacks.

Common filter expressions, called with the _queryFilter keyword, enable you to form arbitrary queries on the repository, using a number of supported filter operations. For more information on these filter operations, see "Constructing Queries". Parameterized or predefined queries and commands (using the _queryId and commandId keywords) can be authorized on the repository for external calls if necessary. For more information, see "Parameterized Queries".

Running commands on the repository is supported primarily from scripts. Certain scripts that interact with the repository are provided by default, for example, the scripts that enable you to purge the repository of reconciliation audit records.

You can define your own commands, and specify them in the database table configuration file (either repo.ds.json or repo.jdbc.json). In the following simple example, a command is called to clear out UI notification entries from the repository, for specific users.

The command is defined in the repository configuration file, as follows:

"commands" : {
"delete-notifications-by-id" : "DELETE FROM ui_notification WHERE receiverId = ${username}"
...
}, 

The command can be called from a script, as follows:

openidm.action("repo/ui/notification", "command", {},
{ "commandId" : "delete-notifications-by-id", "userName" : "scarter"});

Exercise caution when allowing commands to be run on the repository over the REST interface, as there is an attached risk to the underlying data.

Single instance configuration objects correspond to services that have at most one instance per installation. JSON file views of these configuration objects are named object-name.json.

IDM stores managed objects in the repository, and exposes them under /openidm/managed. System objects on external resources are exposed under /openidm/system.

Multiple instance configuration objects correspond to services that can have many instances per installation. Multiple instance configuration objects are named objectname/instancename, for example, provisioner.openicf/csvfile.

JSON file views of these configuration objects are named objectname-instancename.json, for example, provisioner.openicf-csvfile.json.

By default, IDM installs an embedded ForgeRock Directory Services (DS) instance for use as its repository. This makes it easy to get started. Before you use IDM in production, you must replace the embedded DS repository with a supported repository. For more information, see "Selecting a Repository" in the Installation Guide.

For more information, see "Selecting a Repository" in the Installation Guide.

By default, IDM polls the JSON files in the conf directory periodically for any changes to the configuration. In a production system, it is recommended that you disable automatic polling for updates to prevent untested configuration changes from disrupting your identity service.

To disable automatic polling for configuration changes, edit the conf/system.properties file for your project, and uncomment the following line:

# openidm.fileinstall.enabled=false

This setting also disables the file-based configuration view, which means that IDM reads its configuration only from the repository.

Before you disable automatic polling, you must have started the server at least once to ensure that the configuration has been loaded into the repository. Be aware, if automatic polling is enabled, IDM immediately uses changes to scripts called from a JSON configuration file.

When your configuration is complete, you can disable writes to configuration files. To do so, add the following line to the conf/config.properties file for your project:

felix.fileinstall.enableConfigSave=false

To set up IDM to communicate through a proxy server, you can use JVM parameters that identify the proxy host system, and the IDM port number.

If you've configured IDM behind a proxy server, include JVM properties from the following table, in the IDM startup script:

If an insecure port is acceptable, you can also use the -Dhttp.proxyHost and -Dhttp.proxyPort options. You can add these JVM proxy properties to the value of OPENIDM_OPTS in your startup script (startup.sh or startup.bat):

# Only set OPENIDM_OPTS if not already set
[ -z "$OPENIDM_OPTS" ] && OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dhttps.proxyHost=localhost -Dhttps.proxyPort=8443"

At server startup, expression resolvers evaluate property values to determine the effective configuration. You must define expression values before you start the IDM server that uses them.

When configuration tokens are resolved, the result is always a string. However, you can coerce the output type of the evaluated token to match the type that is required by the property. Ultimately, the expression must return the appropriate data type for the configuration property. For example, the port property takes an integer. If you set it using an expression, the result of the evaluated expression must be an integer. If the type is wrong, the server fails to start due to a syntax error. For more information about data type coercion, see "Transforming Data Types".

Expression resolvers can obtain values from the following sources:

When configuration tokens are resolved, the result is always a string. However, you can transform the output type of the evaluated token to match the type that is required by the property.

The following example JSON expression file sets the value of the port in the LDAP connector configuration:

{
   "openidm" : {
     "provisioner" : {
       "ldap" : {
         "port" : 6389
       }
     }
   }
 }

When this expression is evaluated, the port would be evaluated as a string value, which would cause an error. To coerce the port value to an integer, you would substitute the value in the LDAP provisioner file as follows:

{
   ...
   "configurationProperties" : {
     "port" : {
       "$int" : "&{openidm.provisioner.ldap.port|1389}",
     ...
   }
 }

With this configuration, the server evaluates the LDAP port property to the integer 6389. If the server does not find a configuration token for the port, it substitutes the default (1389).

The work you've done to set up property value substitution is limited; different rules apply in the following areas:

"connectorRef" : {
    "connectorName" : "&{connectorName}",
    "bundleName" : "org.forgerock.openicf.connectors.ldap-connector",
    "bundleVersion" : "&{LDAP.BundleVersion}"
    ...
}

"connectorRef" : {
    "connectorName" : "org.identityconnectors.ldap.LdapConnector",
    "bundleName" : "org.forgerock.openicf.connectors.ldap-connector",
    "bundleVersion" : "[1.5.19.0,1.6.0.0)",
    ...
}

The ForgeRock REST API defines common filter expressions that enable you to form arbitrary queries using a number of supported filter operations. This query capability is the standard way to query data if no predefined query exists, and is supported for all managed and system objects.

Common filter expressions are useful in that they do not require knowledge of how the object is stored and do not require additions to the repository configuration.

Common filter expressions are called with the _queryFilter keyword. The following example uses a common filter expression to retrieve managed user objects whose user name is Smith:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 'http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+"smith"'

The filter is URL encoded in this example. The corresponding filter using the resource API would be:

openidm.query("managed/user", { "_queryFilter" : '/userName eq "smith"' });

Note that, this JavaScript invocation is internal and is not subject to the same URL-encoding requirements that a GET request would be. Also, because JavaScript supports the use of single quotes, it is not necessary to escape the double quotes in this example.

For a list of supported filter operations, see "Constructing Queries".

Managed objects in the supported repositories can be accessed using a parameterized query mechanism. Parameterized queries on repositories are defined in the repository configuration (repo.*.json) and are called by their _queryId.

Parameterized queries provide precise control over the query that is executed. Such control might be useful for tuning, or for performing database operations such as aggregation (which is not possible with a common filter expression.)

Parameterized queries provide security and portability for the query call signature, regardless of the backend implementation. Queries that are exposed over the REST interface must be parameterized queries to guard against injection attacks and other misuse. Queries on the officially supported repositories have been reviewed and hardened against injection attacks.

For system objects, support for parameterized queries is restricted to _queryId=query-all-ids. There is currently no support for user-defined parameterized queries on system objects. Typically, parameterized queries on system objects are not called directly over the REST interface, but are issued from internal calls, such as correlation queries.

A typical query definition is as follows:

"query-all-ids" : "SELECT objectid FROM ${_dbSchema}.${_table} LIMIT ${int:_pageSize} OFFSET ${int:_pagedResultsOffset}",

To call this query, you would reference its ID, as follows:

?_queryId=query-all-ids

The following example calls query-all-ids over the REST interface:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "http://localhost:8080/openidm/managed/user?_queryId=query-all-ids"

Native query expressions are supported for all managed objects and system objects, and can be called directly, rather than being defined in the repository configuration.

Native queries are intended specifically for internal callers, such as custom scripts, and should be used only in situations where the common filter or parameterized query facilities are insufficient. For example, native queries are useful if the query needs to be generated dynamically.

The query expression is specific to the target resource. For repositories, queries use the native language of the underlying data store. For system objects that are backed by ICF connectors, queries use the applicable query language of the system resource.

Native queries on the repository are made using the _queryExpression keyword. For example:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "http://localhost:8080/openidm/managed/user?_queryExpression=select+*+from+managed_user"

Unless you have specifically enabled native queries over REST, the previous command returns a 403 access denied error message. Native queries are not portable and do not guard against injection attacks. Such query expressions should therefore not be used or made accessible over the REST interface or over HTTP in production environments. They should be used only via the internal Resource API. If you want to enable native queries over REST for development, see "Protecting Sensitive REST Interface URLs".