As noted in the REST API Reference, Representational State Transfer (REST) is a software architecture style for exposing resources, using the technologies and protocols of the World Wide Web.

REST interfaces are commonly tested with a curl command. Many of these commands are used in this document. They work with the standard ports associated with Java EE communications, 8080 and 8443.

To run curl over the secure port, 8443, you must include either the --insecure option, or follow the instructions shown in Restrict REST Access to the HTTPS Port. You can use those instructions with the self-signed certificate generated when OpenIDM starts, or with a *.crt file provided by a certificate authority.

In many cases in this guide, curl commands to the secure port are depicted with a --cacert self-signed.crt option. Instructions for creating that self-signed.crt file are shown in the aforementioned section on Restrict REST Access to the HTTPS Port.

By default you start and stop OpenIDM in interactive mode.

The startup script starts OpenIDM, and opens an OSGi console with a -> prompt where you can issue console commands.

To stop OpenIDM interactively in the OSGi console, enter the shutdown command.

-> shutdown

To stop OpenIDM running as a background process, use the shutdown.sh script.

$ ./shutdown.sh
./shutdown.sh
Stopping OpenIDM (454)

By default, OpenIDM starts up with the configuration and script files that are located in the openidm/conf and openidm/script directories, and with the binaries that are in the default install location. You can launch OpenIDM with a different configuration and set of script files, and even with a different set of binaries, in order to test a new configuration, manage multiple different OpenIDM projects, or to run one of the included samples.

The startup.sh script enables you to specify the following elements of a running OpenIDM instance.

By default, properties files are loaded in the following order, and property values are resolved in the reverse order:

If both system and boot properties define the same attribute, the property substitution process locates the attribute in boot.properties and does not attempt to locate the property in system.properties.

You can use variable substitution in any .json configuration file with the install, working and project locations described previously. The following properties can be substituted:

Property substitution takes the following syntax:

&{launcher.property}

For example, to specify the location of the OrientDB database, you can set the dbUrl property in repo.orientdb.json as follows:

"dbUrl" : "local:&{launcher.working.location}/db/openidm",
     

The database location is then relative to a working location defined in the startup configuration.

Note that property substitution does not work for connector reference properties. So, for example, the following configuration would not be valid:

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

The "connectorName" must be the precise string from the connector configuration. If you need to specify multiple connector version numbers, use a range instead, for example:

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

OpenIDM includes a customizable information service that provides detailed information about a running OpenIDM instance. The information can be accessed over the REST interface, under the context https://localhost:8443/openidm/info.

By default, OpenIDM provides the following information:

You can extend or override the default information that is provided by creating your own script file and its corresponding configuration file in openidm/conf/info-name.json. Custom script files can be located anywhere, although a best practice is to place them in openidm/script/info. A sample customized script file for extending the default ping service is provided in openidm/samples/infoservice/script/info/customping.js. The corresponding configuration file is provided in openidm/samples/infoservice/conf/info-customping.json.

The configuration file has the following syntax:

{
    "infocontext" : "ping",
    "type" : "text/javascript",
    "file" : "script/info/customping.js"
} 
  

The parameters in the configuration file are as follows:

Additional properties can be passed to the script as depicted in this configuration file (openidm/samples/infoservice/conf/info-name.json).

Script files in openidm/samples/infoservice/script/info/ have access to the following objects:

Due to the highly modular, configurable nature of OpenIDM, it is often difficult to assess whether a system has started up successfully, or whether the system is ready and stable after dynamic configuration changes have been made.

OpenIDM provides a configurable health check service that verifies that the required modules and services for an operational system are up and running. During system startup, OpenIDM checks that these modules and services are available and reports on whether any requirements for an operational system have not been met. If dynamic configuration changes are made, OpenIDM rechecks that the required modules and services are functioning so that system operation is monitored on an ongoing basis.

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

OpenIDM checks all required modules and services. Examples of those services are shown here.

Required Modules (examples)

"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.json.resource.restlet"
"org.forgerock.commons.org.forgerock.restlet"
"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-orientdb"
"org.forgerock.openidm.config"
"org.forgerock.openidm.crypto"  
  

Required Services (examples)

"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"
     

You can replace this list, or add to it, by adding the following lines to the openidm/conf/boot/boot.properties file:

By default, OpenIDM gives the system ten seconds to start up all the required bundles and services, before the 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 miliseconds) in the openidm/conf/boot/boot.properties file. This example sets the startup time to five seconds.

openidm.healthservice.servicestartmax=5000

The health check service works in tandem with the scriptable information service. For more information see Section 2.3, "Obtaining Information About an OpenIDM Instance".

Do not use the health check service to monitor the status of external resources, such as LDAP servers, or external databases. Rather, monitor these resources over the REST interface, as described in Checking the Status of External Systems Over REST.

On a running OpenIDM instance, you can list the installed modules and their states by typing the following command in the Felix administration console. (The output will vary by configuration.)

-> scr list 
      
   Id   State          Name
[  12] [active       ] org.forgerock.openidm.endpoint
[  13] [active       ] org.forgerock.openidm.endpoint
[  14] [active       ] org.forgerock.openidm.endpoint
[  15] [active       ] org.forgerock.openidm.endpoint
[  16] [active       ] org.forgerock.openidm.endpoint

      ...

[  34] [active       ] org.forgerock.openidm.taskscanner
[  20] [active       ] org.forgerock.openidm.external.rest
[   6] [active       ] org.forgerock.openidm.router
[  33] [active       ] org.forgerock.openidm.scheduler
[  19] [unsatisfied  ] org.forgerock.openidm.external.email
[  11] [active       ] org.forgerock.openidm.sync
[  25] [active       ] org.forgerock.openidm.policy
[   8] [active       ] org.forgerock.openidm.script
[  10] [active       ] org.forgerock.openidm.recon
[   4] [active       ] org.forgerock.openidm.http.contextregistrator
[   1] [active       ] org.forgerock.openidm.config
[  18] [active       ] org.forgerock.openidm.endpointservice
[  30] [unsatisfied  ] org.forgerock.openidm.servletfilter
[  24] [active       ] org.forgerock.openidm.infoservice
[  21] [active       ] org.forgerock.openidm.authentication
->

To display additional information about a particular module or service, run the following command, substituting the Id of that module from the preceding list.

-> scr info Id

The following example displays additional information about the router service:

-> scr info 6 
      
ID: 6
Name: org.forgerock.openidm.router
Bundle: org.forgerock.openidm.core (41)
State: active
Default State: enabled
Activation: immediate
Configuration Policy: optional
Activate Method: activate (declared in the descriptor)
Deactivate Method: deactivate (declared in the descriptor)
Modified Method: modified
Services: org.forgerock.json.resource.JsonResource
Service Type: service
Reference: ref_JsonResourceRouterService_ScopeFactory
    Satisfied: satisfied
    Service Name: org.forgerock.openidm.scope.ScopeFactory
    Multiple: single
    Optional: mandatory
    Policy: dynamic
Properties:
    component.id = 6
    component.name = org.forgerock.openidm.router
    felix.fileinstall.filename = file:/openidm/samples/sample1/conf/router.json
    jsonconfig = {
    "filters" : [
        {
            "onRequest" : {
                "type" : "text/javascript",
                "file" : "bin/defaults/script/router-authz.js"
            }
        },
        {
            "onRequest" : {
                "type" : "text/javascript",
                "file" : "bin/defaults/script/policyFilter.js"
            },
            "methods" : [
                "create",
                "update"
            ]
        }
    ]
}
    openidm.restlet.path = /
    service.description = OpenIDM internal JSON resource router
    service.pid = org.forgerock.openidm.router
    service.vendor = ForgeRock AS 
->

To debug custom libraries, you can start OpenIDM with the option to use the Java Platform Debugger Architecture (JPDA).

The configexport subcommand exports all configuration objects to a specified location, enabling you to reuse a system configuration in another environment. For example, you can test a configuration in a development environment, then export it and import it into a production environment. This subcommand also enables you to inspect the active configuration of an OpenIDM instance.

OpenIDM must be running when you execute this command.

Usage is as follows:

$ ./cli.sh configexport --user username:passsword export-location
  

For example:

$ ./cli.sh configexport --user openidm-admin:openidm-admin /tmp/conf

Configuration objects are exported, as .json files, to the specified directory. The command creates the directory if needed. Configuration files that are present in this directory are renamed as backup files, with a timestamp, for example, audit.json.2014-02-19T12-00-28.bkp, and are not overwritten. The following configuration objects are exported:

The configimport subcommand imports configuration objects from the specified directory, enabling you to reuse a system configuration from another environment. For example, you can test a configuration in a development environment, then export it and import it into a production environment.

The command updates the existing configuration from the import-location over the OpenIDM REST interface. By default, if configuration objects are present in the import-location and not in the existing configuration, these objects are added. If configuration objects are present in the existing location but not in the import-location, these objects are left untouched in the existing configuration.

If you include the --replaceAll parameter, the command wipes out the existing configuration and replaces it with the configuration in the import-location. Objects in the existing configuration that are not present in the import-location are deleted.

Usage is as follows:

$ ./cli.sh configimport --user username:password [--replaceAll] import-location
  

For example:

$ ./cli.sh configimport --user openidm-admin:openidm-admin --replaceAll /tmp/conf
  

Configuration objects are imported, as .json files, from the specified directory to the conf directory. The configuration objects that are imported are outlined in the corresponding export command, described in the previous section.

The configureconnector subcommand generates a configuration for an OpenICF connector.

Usage is as follows:

$ ./cli.sh configureconnector --user username:password connector-name
  

Select the type of connector that you want to configure. The following example configures a new XML connector.

$ ./cli.sh configureconnector --user openidm-admin:openidm-admin myXmlConnector
 Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
0. Scripted SQL Connector version 1.1.0.1
1. XML Connector version 1.1.0.1
2. Database Table Connector version 1.1.0.0
3. CSV File Connector version 1.1.0.1
4. LDAP Connector version 1.1.1.2
5. Exit
Select [0..5]: 1
Edit the configuration file and run the command again. The configuration was 
saved to /openidm/temp/provisioner.openicf-myXmlConnector.json

The basic configuration is saved in a file named /openidm/temp/provisioner.openicf-connector-name.json. Edit the configurationProperties parameter in this file to complete the connector configuration. For an XML connector, you can use the schema definitions in sample 1 for an example configuration.

  "configurationProperties" : {
    "xmlFilePath" : "samples/sample1/data/resource-schema-1.xsd",
    "createFileIfNotExists" : false,
    "xsdFilePath" : "samples/sample1/data/resource-schema-extension.xsd",
    "xsdIcfFilePath" : "samples/sample1/data/xmlConnectorData.xml"
  },  
  

For more information about the connector configuration properties, see Configuring Connectors.

When you have modified the file, run the configureconnector command again so that OpenIDM can pick up the new connector configuration.

$ ./cli.sh configureconnector --user openidm-admin:openidm-admin myXmlConnector
Executing ./cli.sh...
Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
Configuration was found and read from: /path/to/openidm/temp/provisioner.openicf-myXmlConnector.json
  

You can now copy the new provisioner.openicf-myXmlConnector.json file to the conf/ subdirectory.

You can also configure connectors over the REST interface. For more information, see Creating Default Connector Configurations.

The encrypt subcommand encrypts an input string, or JSON object, provided at the command line. This subcommand can be used to encrypt passwords, or other sensitive data, to be stored in the OpenIDM repository. The encrypted value is output to standard output and provides details of the cryptography key that is used to encrypt the data.

Usage is as follows:

$ ./cli.sh encrypt [-j] string
  

The -j option specifies that the string to be encrypted is a JSON object. If you do not enter the string as part of the command, the command prompts for the string to be encrypted. If you enter the string as part of the command, any special characters, for example quotation marks, must be escaped.

The following example encrypts a normal string value:

$ ./cli.sh encrypt mypassword  
  
Executing ./cli.sh
Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
Activating cryptography service of type: JCEKS provider:  location: security/keystore.jceks
Available cryptography key: openidm-sym-default
Available cryptography key: openidm-localhost
CryptoService is initialized with 2 keys.
-----BEGIN ENCRYPTED VALUE-----
{
  "$crypto" : {
    "value" : {
      "iv" : "M2913T5ZADlC2ip2imeOyg==",
      "data" : "DZAAAM1nKjQM1qpLwh3BgA==",
      "cipher" : "AES/CBC/PKCS5Padding",
      "key" : "openidm-sym-default"
    },
    "type" : "x-simple-encryption"
  }
}
------END ENCRYPTED VALUE------ 
  

The following example encrypts a JSON object. The input string must be a valid JSON object.

$ ./cli.sh encrypt -j {\"password\":\"myPassw0rd\"}

Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
Activating cryptography service of type: JCEKS provider:  location: security/keystore.jceks
Available cryptography key: openidm-sym-default
Available cryptography key: openidm-localhost
CryptoService is initialized with 2 keys.
-----BEGIN ENCRYPTED VALUE-----
{
  "$crypto" : {
    "value" : {
      "iv" : "M2913T5ZADlC2ip2imeOyg==",
      "data" : "DZAAAM1nKjQM1qpLwh3BgA==",
      "cipher" : "AES/CBC/PKCS5Padding",
      "key" : "openidm-sym-default"
    },
    "type" : "x-simple-encryption"
  }
}
------END ENCRYPTED VALUE------  
  

The following example prompts for a JSON object to be encrypted. In this case, you need not escape the special characters.

$ ./cli.sh encrypt -j

Using boot properties at /path/to/openidm/conf/boot/boot.properties
Enter the Json value

> Press ctrl-D to finish input
Start data input:
{"password":"myPassw0rd"}
^D        

Activating cryptography service of type: JCEKS provider:  location: security/keystore.jceks
Available cryptography key: openidm-sym-default
Available cryptography key: openidm-localhost
CryptoService is initialized with 2 keys.
-----BEGIN ENCRYPTED VALUE-----
{
  "$crypto" : {
    "value" : {
      "iv" : "6e0RK8/4F1EK5FzSZHwNYQ==",
      "data" : "gwHSdDTmzmUXeD6Gtfn6JFC8cAUiksiAGfvzTsdnAqQ=",
      "cipher" : "AES/CBC/PKCS5Padding",
      "key" : "openidm-sym-default"
    },
    "type" : "x-simple-encryption"
  }
}
------END ENCRYPTED VALUE------
  

The keytool subcommand exports or imports secret key values.

The Java keytool command enables you to export and import public keys and certificates, but not secret or symmetric keys. The OpenIDM keytool subcommand provides this functionality.

Usage is as follows:

./cli.sh keytool [--export, --import] alias
  

For example, to export the default OpenIDM symmetric key, run the following command:

$ ./cli.sh keytool --export openidm-sym-default
   
Using boot properties at /openidm/conf/boot/boot.properties
Use KeyStore from: /openidm/security/keystore.jceks
Please enter the password: 
[OK] Secret key entry with algorithm AES
AES:606d80ae316be58e94439f91ad8ce1c0  
  

The default keystore password is changeit. You should change this password after installation.

To import a new secret key named my-new-key, run the following command:

$ ./cli.sh keytool --import my-new-key   
   
Using boot properties at /openidm/conf/boot/boot.properties
Use KeyStore from: /openidm/security/keystore.jceks
Please enter the password: 
Enter the key: 
AES:606d80ae316be58e94439f91ad8ce1c0 
  

If a secret key of that name already exists, OpenIDM returns the following error:

"KeyStore contains a key with this alias"

The validate subcommand validates all .json configuration files in the openidm/conf/ directory.

Usage is as follows:

$ ./cli.sh validate   
   
Executing ./cli.sh
Starting shell in /path/to/openidm
Using boot properties at /path/to/openidm/conf/boot/boot.properties
...................................................................
[Validating] Load JSON configuration files from:
[Validating] 	/path/to/openidm/conf
[Validating] audit.json .................................. SUCCESS
[Validating] authentication.json ......................... SUCCESS

    ...

[Validating] sync.json ................................... SUCCESS
[Validating] ui-configuration.json ....................... SUCCESS
[Validating] ui-countries.json ........................... SUCCESS
[Validating] ui-secquestions.json ........................ SUCCESS
[Validating] workflow.json ............................... SUCCESS
  

The default user interface is provided as a reference implementation that demonstrates the capabilities of the REST API. You can modify certain aspects of the default user interface according to the requirements of your deployment.

To access the user interface, install and start OpenIDM, then point your browser to https://localhost:8443/openidmui. If you have not installed a certificate that is trusted by a certificate authority, you are prompted with an "Untrusted Connection" warning the first time you log in to the UI.

Log in as the default administrative user (Login: openidm-admin, Password: openidm-admin) or as an existing user in the repository. The display differs, depending on the role of the user that has logged in.

For an administrative user (role openidm-admin), two tabs are displayed - Dashboard and Users. The Dashboard tab lists any tasks assigned to the user who has logged in, processes available to be invoked, and any notifications for that user.

The following image shows the Dashboard tab for the administrative user when no tasks, processes, or notifications are available.

The Users tab is only available to administrative users and provides an interface to manage user entries (OpenIDM managed objects under managed/user).

The following image shows the Users tab after with the two sample users created after a reconciliation process from Sample 2b.

You can sort the list of users alphabetically, by any of the column values. Click on the column title to sort.

The Profile link enables the user to modify his username or password. The Change Security Data link, accessed from the top of the screen, or from the user's Profile page enables the user to change his password and, if this functionality has been enabled, to select a new security question.

Password changes are subject to the default password policy, as shown in the following password update screen.

For a regular user (role openidm-authorized), the Users tab is not displayed. By default, regular users cannot manage user accounts, except for certain aspects of their own accounts.

The following sections outline the configurable aspects of the default user interface.

4.2.1. Enabling Self-Registration

Self-registration (the ability for new users to create their own accounts) is disabled by default. To enable self-registration, set "selfRegistration" to true in the UI configuration file (conf/ui-configuration.json).

{
    "configuration" : {
        "selfRegistration" : true,
...    
    

When self-registration is enabled, a "Register your account" link is provided on the login page. When a user creates an account on the account registration page, a managed object is created in the OpenIDM repository. The default policies for managed objects are applied during account creation.

User objects created using self-registration automatically have the role openidm-authorized.

4.2.2. Configuring Security Questions

In the event that a user forgets his password, a password reset function enables registered users to reset their own passwords. To guard against unauthorized access, you can specify that users be prompted with one or more security questions when they request a password reset.

Security questions are disabled by default. To enable them, set "securityQuestions" to true in the UI configuration file (conf/ui-configuration.json).

{
    "configuration" : {
        "securityQuestions" : true,
...    
   

A default set of questions is provided, but you can add to these, or overwrite them. Specify the list of questions to be asked in the conf/ui-secquestions.json file.

Refresh your browser after this configuration change for the change to be picked up by the UI.

When security questions are enabled, the following panel is included on the self registration page.

In addition, a "Reset your password" link is provided on the login page. When a user attempts to reset her password, she is prompted for the response to the security question that she set up during registration.

Note

If security questions are enabled after a specific user has registered, that particular user will be unable to use the password reset functionality.

{
    "policyId" : "minimum-length",
    "params" : {
        "minLength" : 16
    }
},

4.2.4. Enabling Site Identification

To ensure that users are entering their details onto the correct site, you can enable site identification. Site identification provides a preventative measure against phishing.

With site identification enabled, a user is presented with a range of images from which he can select when he registers his account, and prompted to specify his own site phrase. The selected site image and phrase are displayed on login, to confirm that the user is logging in to the legitimate site.

To enable site identification, set "siteIdentification" to true in the UI configuration file (conf/ui-configuration.json).

{
    "configuration" : {
        "siteIdentification" : true,
...    
    

Refresh your browser after this configuration change for the change to be picked up by the UI.

When site identification is enabled, the following panel is included on the self registration page.

A default list of four images is presented for site identification. The images are defined in the siteImages property in the conf/ui-configuration.json file:

"siteImages" : [
"images/passphrase/mail.png",
"images/passphrase/user.png",
"images/passphrase/report.png",
"images/passphrase/twitter.png"
],
...    
   

You can change the default images, and include additional images, by placing image files in the ui/extension/images folder and modifying the siteImages property in the ui-configuration.json file to point to the new images. Refresh your browser for the change to take effect.

The following example assumes an image file named my-new-image.jpg, located in ui/extension/images.

"siteImages" : [
"images/passphrase/mail.png",
"images/passphrase/user.png",
"images/passphrase/report.png",
"images/passphrase/twitter.png",
"images/my-new-image.jpg"
],
...
   

Note that the default image files are located in ui/default/enduser/public/images/passphrase.

{
    "key" : "norway",
    "value" : "Norway",
    "states" : [
        {
            "key" : "akershus",
            "value" : "Akershus"
        },
        {
            "key" : "aust-agder",
            "value" : "Aust-Agder"
        },
        {
            "key" : "buskerud",
            "value" : "Buskerud"
        },
...
   

Only administrative users (with the role openidm-admin) can add, modify, and delete user accounts. Regular users can modify certain aspects of their own accounts.

The UI is integrated with the embedded Activiti worfklow engine, enabling users to interact with workflows. Available workflows are displayed under the Processes item on the Dashboard. In order for a workflow to be displayed here, the workflow definition file must be present in the openidm/workflow directory.

A sample workflow integration with the user interface is provided in openidm/samples/workflow, and documented in Sample Workflow - Provisioning User Accounts. Follow the steps in that sample for an understanding of how the workflow integration works.

Access to workflows is based on OpenIDM roles, and is configured in the file conf/process-access.json. By default all users with the role openidm-authorized or openidm-admin can invoke any available workflow. The default process-access.json file is as follows:

{
    "workflowAccess" : [
        {
            "propertiesCheck" : {
                "property" : "_id",
                "matches" : ".*",
                "requiresRole" : "openidm-authorized"
            }
        },
        {
            "propertiesCheck" : {
                "property" : "_id",
                "matches" : ".*",
                "requiresRole" : "openidm-admin"
            }
        }
    ]
}  
  

To extend the process action definition file, identify the processes to which users should have access, and specify the qualifying user roles. For example, if you wanted to restrict access to a process definition whose ID was 567, to users with the role ldap you would add the following to the process-access.json file:

{
    "propertiesCheck" : {
        "property" : "_id",
        "matches" : "567",
        "requiresRole" : "ldap"
    }
}
  

You can customize the theme of the default user interface to apply your own branding. The easiest way to adjust the UI theme, is to edit the properties in the UI theme configuration file (/path/to/openidm/conf/ui-themeconfig.json). This file stores detailed color values, background image paths, and a number of other common styling options. Because the UI theme configuration file is part of the configuration store, it is shared by all nodes in a cluster. Changes made to this file do not have to be replicated manually across nodes.

To change theme elements that are not included in the UI theme configuration file, you can create a custom theme in the openidm/ui/extension directory. By default the user interface reads the stylesheets and images from the openidm/ui/default directory. Do not modify the files in this default directory as there is no guarantee that your changes will not be overwritten in the next OpenIDM release. Modifications made in the openidm/ui/extension directory can be maintained across product upgrades. The UI searches the extension directory first and applies any styles or images located in this directory. Note that files added to the extension directory must be manually copied between every node in a cluster.

If you want to update the view logic of the UI, you cannot simply add files to the extensions folder. It is assumed that if your deployment requires that level of control of the user interface, you are no longer going to want to be automatically upgraded with subsequent releases. As such, you need to take on the task of maintaining a fork of the UI.

$ grep "background-color" /path/to/openidm/conf/ui-themeconfig.json
"background-color" : "#ababab",
   

...
   "logo" : {
       "src" : "images/example-logo.png",
       "title" : "Example.com",
       "alt" : "Example.com",
       "height" : "80",
       "width" : "120"
   },
...

By default, the password reset mechanism is handled internally, in OpenIDM. You can reroute password reset in the event that a user has forgotten his 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.

By default, a UI session is invalidated when a user clicks on the Log out link. In certain situations your external applications might require a distinct logout URL to which users can be routed, to terminate their UI session.

The logout URL is #logout, appended to the UI URL, for example, https://localhost:8443/openidmui/index.html#logout/.

The logout URL effectively performs the same action as clicking on the Log out link of the UI.

By default, the UI is registered at a specific URL (context-root/openidmui). To override the default URL and specify your own path, edit the openidm/conf/ui.context-enduser.json file, setting the urlContextRoot property to the new URL. For example, to change the path to context-root/exampleui, edit the file as follows:

"urlContextRoot" : "/exampleui",

The UI is packaged as a separate bundle that can be disabled in the configuration before server startup. To disable the registration of the UI servlet, edit the openidm/conf/ui.context-enduser.json file, setting the enabled property to false:

"enabled" : false,

OpenIDM exposes internal configuration objects in JSON format. Configuration elements can be either single instance or multiple instance for an OpenIDM installation.

Out of the box, OpenIDM is configured to make it easy to install and evaluate. Specific configuration changes are required before you deploy OpenIDM in a production environment.

# openidm.fileinstall.enabled=false

OpenIDM exposes configuration objects under the /openidm/config context path.

You can list the configuration on the local host by performing a GET https://localhost:8443/openidm/config. The following example shows excerpts of the default configuration for an OpenIDM instance started with Sample 1.

$ curl \
 --request GET \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --cacert self-signed.crt \
 https://localhost:8443/openidm/config
   {
   "configurations": [
      {
         "factoryPid": "servletfilter",
         "pid": "servletfilter.ec099f08-bfd4-4ab4-8537-78e5b956c7cc",
         "_id": "servletfilter/gzip"
      },
      {
         "factoryPid": null,
         "pid": "router",
         "_id": "router"
      },

   ...

      {
         "factoryPid": "endpoint",
         "pid": "endpoint.7e9ec068-bb4a-4fa0-ae15-1706bb4a3a07",
         "_id": "endpoint/jqgrid"
      },
      {
         "factoryPid": "endpoint",
         "pid": "endpoint.47978983-0411-425d-8f53-4022175e146a",
         "_id": "endpoint/gettasksview"
      },

   ...

      {
         "factoryPid": "ui",
         "pid": "ui.b10eb4cb-83e3-4a4b-9d29-d91d90eb3053",
         "_id": "ui/countries"
      },
      {
         "factoryPid": "process",
         "pid": "process.9863529c-60e0-42e3-b5d5-c5c704016e95",
         "_id": "process/access"
      }
   ]
}

Single instance configuration objects are located under openidm/config/object-name. The following example shows the default audit configuration.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/config/audit"
{
   "eventTypes": {
     "recon": {},
     "activity": {
       "filter": {
         "actions": [
           "create",
           "update",
           "delete",
           "patch",
           "action"
         ]
       },
       "passwordFields": [
         "password"
       ],
       "watchedFields": []
     }
   },
   "exceptionFormatter": {
     "file": "bin/defaults/script/audit/stacktraceFormatter.js",
     "type": "text/javascript"
   },
   "logTo": [
     {
       "recordDelimiter": ";",
       "logType": "csv",
       "location": "audit"
     },
     {
       "useForQueries": true,
       "logType": "repository"
     }
   ]
}   

Multiple instance configuration objects are found under openidm/config/object-name/instance-name.

The following example shows the configuration for the XML connector provisioner, based on the first IDM sample described in the First IDM Sample in the Installation Guide of the OpenIDM Installation Guide.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/config/provisioner.openicf/xml"
{
    "operationTimeout": {
      "SCRIPT_ON_CONNECTOR": -1,
      "VALIDATE": -1,
      "SYNC": -1,
      "DELETE": -1,
      "TEST": -1,
      "UPDATE": -1,
      "CREATE": -1,
      "AUTHENTICATE": -1,
      "SEARCH": -1,
      "GET": -1,
      "SCRIPT_ON_RESOURCE": -1,
      "SCHEMA": -1
    },
    "connectorRef": {
      "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector",
      "bundleVersion": "1.1.0.1",
      "bundleName": "org.forgerock.openicf.connectors.xml-connector"
    },
    "connectorPoolingSupported": true,
    "syncFailureHandler": {
      "maxRetries": 5,
      "postRetryAction": "logged-ignore"
    },
    "configurationProperties": {
      "xsdFilePath": "samples/sample1/data/resource-schema-extension.xsd",
      "xsdIcfFilePath": "samples/sample1/data/resource-schema-1.xsd",
      "xmlFilePath": "samples/sample1/data/xmlConnectorData.xml"
    },
    "objectTypes": {
      "account": {
        "nativeType": "__ACCOUNT__",
        "$schema": "http://json-schema.org/draft-03/schema",
        "type": "object",
        "properties": {
          "securityAnswer": {
            "nativeType": "string",
            "nativeName": "securityAnswer",
            "required": true,
            "type": "string"
          },
          "securityQuestion": {
            "nativeType": "string",
            "nativeName": "securityQuestion",
            "required": true,
            "type": "string"
          },
          "password": {
            "nativeType": "string",
            "nativeName": "password",
            "type": "string"
          },
          "mobileTelephoneNumber": {
            "nativeType": "string",
            "nativeName": "mobileTelephoneNumber",
            "required": true,
            "type": "string"
          },
          "_id": {
            "nativeName": "__UID__",
            "type": "string"
          },
          "email": {
            "nativeType": "string",
            "nativeName": "email",
            "type": "string"
          },
          "description": {
            "nativeType": "string",
            "nativeName": "__DESCRIPTION__",
            "type": "string"
          },
          "name": {
            "nativeType": "string",
            "nativeName": "__NAME__",
            "required": true,
            "type": "string"
          },
          "roles": {
            "nativeType": "string",
            "nativeName": "roles",
            "required": false,
            "type": "string"
          },
          "lastname": {
            "nativeType": "string",
            "nativeName": "lastname",
            "required": true,
            "type": "string"
          },
          "firstname": {
            "nativeType": "string",
            "nativeName": "firstname",
            "type": "string"
          }
        },
        "id": "__ACCOUNT__"
      }
    },
    "operationOptions": {},
    "name": "xmlfile",
    "producerBufferSize": 100,
    "poolConfigOption": {
      "maxObjects": 10,
      "minEvictableIdleTimeMillis": 120000,
      "maxIdle": 10,
      "minIdle": 1,
      "maxWait": 150000
    }
  }

  

You can change the configuration over REST by using an HTTP PUT request to modify the required configuration object. Note that HTTP PATCH is not supported on the /config endpoint.

The following example modifies the router.json file to remove all filters, effectively bypassing any policy validation.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request PUT \
 --data '{
   "filters" : [
     {
       "onRequest" : {
         "type" : "text/javascript",
         "file" : "bin/defaults/script/router-authz.js"
       }
     }
   ]
   }' \
 "https://localhost:8443/openidm/config/router"
{
  "filters": [
    {
      "onRequest": {
        "file": "bin/defaults/script/router-authz.js",
        "type": "text/javascript"
      }
    }
  ]
} 

For more information about using the REST API to update objects, see the REST API Reference.

In an environment where you have more than one OpenIDM instance, you might require a configuration that is similar, but not identical, across the different OpenIDM hosts. OpenIDM supports variable replacement in its configuration which means that you can modify the effective configuration according to the requirements of a specific environment or OpenIDM instance.

When OpenIDM starts up, it combines the system configuration, which might contain specific environment variables, with the defined OpenIDM configuration properties. This combination makes up the effective configuration for that OpenIDM instance. By varying the environment properties, you can change specific configuration items that vary between OpenIDM instances or environments.

Property references are contained within the construct &{ }. When such references are found, OpenIDM replaces them with the appropriate property value, defined in the boot.properties file.

PROD.location=production
DEV.location=development

{
    "dbUrl" : "plocal:./db/&{&{environment}.location}-openidm",
    ...
}   

$ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Denvironment=PROD"
$ ./startup.sh

$ export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Denvironment=DEV"
$ ./startup.sh

{
    "logTo" : [
        {
            "logType" : "csv",
            "location" : "&{user.home}/audit",
            "recordDelimiter" : ";"
        }
    ]
}
   

openidm.NO.ldap.port=2389
openidm.EN.ldap.port=3389
openidm.US.ldap.port=1389

"configurationProperties" :
   {
      "credentials" : "Passw0rd",
      "port" : "&{openidm.&{user.country}.ldap.port}",
      "principal" : "cn=Directory Manager",
      "baseContexts" :
         [
            "dc=example,dc=com"
         ],
      "host" : "localhost"
   }

You can customize OpenIDM to meet the specific requirements of your deployment by adding your own RESTful endpoints. Endpoints are configured in files named conf/endpoint-name.json, where name generally describes the purpose of the endpoint.

A sample custom endpoint configuration is provided in the openidm/samples/customendpoint directory. The use of this sample is described in Section 5.6.6, "Custom Endpoint Example". Custom endpoints in OpenIDM can be written either in JavaScript or Groovy. The sample includes three files:

Endpoint configuration files have a certain structure. They may cite scripts written in JavaScript or Groovy.

The cited scripts include defined request and context global variables.

{
  "file" : "echo.groovy",
  "type" : "groovy",
  "_file" : "echo.js",
  "_type" : "text/javascript"
}    

  "context" : "endpoint/echo",
     

{
  "context": "endpoint/linkedView/*",
  "type" : "text/javascript",
  "source" : "require('linkedView').fetch(request.resourceName);"
}
     

$ curl \
 --cacert self-signed.crt \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 --data { "name": "bob"} \
 "https://localhost:8443/openidm/endpoint/test?_action=myAction"

GET https://localhost:8443/openidm/endpoint/echo?queryId=query-all-ids&_para=foo

var x = "Sample return";
functioncall();
x   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/endpoint/echo?_queryId=query-all-ids"
     
     {
 "result" : [ {
     "method" : "query",
     "resourceName" : "",
     "pagedResultsCookie" : null,
     "pagedResultsOffset" : 0,
     "pageSize" : 0,
     "queryExpression" : null,
     "queryId" : "query-all-ids",
     "queryFilter" : "null",
     "parameters" : { },
     "context" : {
       "parent" : {
         "parent" : {
           "parent" : {
             "parent" : {
               "parent" : {
                 "parent" : null,
                 "contextName" : "root",
                 "rootContext" : true,
                 "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
               },
               "contextName" : "security",
               "authenticationId" : "openidm-admin",
               "authorizationId" : {
                 "id" : "openidm-admin",
                 "component" : "repo/internal/user",
                 "roles" : [ "openidm-admin", "openidm-authorized" ]
               },
               "rootContext" : false,
               "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
             },
             "headers" : {
               "X-OpenIDM-Username" : [ "openidm-admin" ],
               "Host" : [ "localhost:8443" :8443" ],
               "Accept" : [ "*/*" ],
               "X-OpenIDM-Password" : [ "openidm-admin" ],
               "User-Agent" : [ "curl/7.19.7 (x86_64-redhat-linux-gnu)
                 libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18
                 libssh2/1.4.2" ]
             },
             "parameters" : {
               "_queryId" : [ "query-all-ids" ],
               "_prettyPrint" : [ "true" ]
             },
             "external" : true,
             "contextName" : "http",
             "method" : "GET",
             "path" : "https://localhost:8443/openidm/endpoint/echo",
             "rootContext" : false,
             "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
           },
           "contextName" : "apiInfo",
           "apiVersion" : "2.3.1-SNAPSHOT",
           "apiName" : "org.forgerock.commons.json-resource-servlet",
           "rootContext" : false,
           "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
         },
         "contextName" : "server",
         "rootContext" : false,
         "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
       },
       "uriTemplateVariables" : { },
       "contextName" : "router",
       "matchedUri" : "endpoint/echo",
       "baseUri" : "endpoint/echo",
       "rootContext" : false,
       "id" : "43576021-fe54-4468-8d10-09b14af2a36d"
     }
 } ],
 "resultCount" : 1,
 "pagedResultsCookie" : null,
 "remainingPagedResults" : -1
}  

You can set up custom configuration files in directories as defined in the openidm/conf/script.json file.

The following portion of the script.json file points to sources in installation and project directories. As implied in the section on Specifying the OpenIDM Startup Configuration , the launcher.project.location is the directory cited if you start OpenIDM with a specific project directory.

...
"sources" : {
  "default" : {
    "directory" : "&{launcher.install.location}/bin/defaults/script"
  },
  "install" : {
    "directory" : "&{launcher.install.location}"
  },
  "project" : {
    "directory" : "&{launcher.project.location}"
  },
  "project-script" : {
    "directory" : "&{launcher.project.location}/script"
  }
...

For example, if you start OpenIDM from the /path/to/openidm directory with the following command:

$ ./startup.sh -p /path/to/openidm/customconfig
   

The launcher.project.location directory would be /path/to/openidm/customconfig.

The script.json file also refers to a launcher.install.location directory, which is /path/to/openidm.

Thus, based on the way the script.json file is configured for project and project-script, you can add custom configuration and script files to the /path/to/openidm/customconfig and the /path/to/openidm/customconfig/script directories.

OpenIDM's uniform programming model means that all objects are queried and manipulated in the same way, using the Resource API. The URL or URI that is used to identify the target object for an operation depends on the object type. For an explanation of object types, see the Data Models and Objects Reference. For more information about scripts and the objects available to scripts, see the Scripting Reference.

You can use the Resource API to obtain managed objects, configuration objects, and repository objects, as follows:

val = openidm.read("managed/organization/mysampleorg")
val = openidm.read("config/custom/mylookuptable")
val = openidm.read("repo/custom/mylookuptable")
  

For information about constructing an object ID, see URI Scheme in the REST API Reference.

You can update entire objects with the update() function, as follows.

openidm.update("managed/organization/mysampleorg", mymap)
openidm.update("config/custom/mylookuptable", mymap)
openidm.update("repo/custom/mylookuptable", mymap)
  

For managed objects, you can partially update an object with the patch() function.

openidm.patch("managed/organization/mysampleorg", rev, value)
  

The create(), delete(), and query() functions work the same way.

OpenIDM provides RESTful access to data objects via a REST API. To access objects over REST, you can use a browser-based REST client, such as the Simple REST Client for Chrome, or RESTClient for Firefox. Alternatively you can use the curl command-line utility.

For a comprehensive overview of the REST API, see the REST API Reference appendix.

To obtain a managed object through the REST API, depending on your security settings and authentication configuration, perform an HTTP GET on the corresponding URL, for example https://localhost:8443/openidm/managed/organization/mysampleorg.

By default, the HTTP GET returns a JSON representation of the object.

OpenIDM supports an advanced query model that enables you to define queries, and to call them over the REST or Resource API.

"query-all-ids" : "select _openidm_id from ${unquoted:_resource}"
   

?_queryId=query-all-ids
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 "https://localhost:8443/openidm/managed/user?_queryExpression=select+from+managed_user"
   

var params = {
    '_queryFilter' : 'givenName co "' + sourceCriteria + '" or ' + 'sn co "'
                     + sourceCriteria + '"'
};
var results = openidm.query("system/ScriptedSQL/account", params)
   

External users that are stored in OpenIDM's repository are referred to as managed users. For a JDBC repository, OpenIDM stores managed users in the managedobjects table. A second table, managedobjectproperties, serves as the index table. For an OrientDB repository, managed users are stored in the managed_user table.

OpenIDM provides RESTful access to managed users, at the context path /openidm/managed/user. For more information, see To Get Started With the OpenIDM REST Interface in the Installation Guide in the Installation Guide.

OpenIDM provides support for a managed "group" object. For a JDBC repository, OpenIDM stores managed groups with all other managed objects, in the managedobjects table, and uses the managedobjectproperties for indexing. For an OrientDB repository, managed groups are stored in the managed_group table.

The managed group object is not provided by default. To use managed groups, add an object similar to the following to your conf/managed.json file:

{
    "name" : "group"
},
  

With this addition, OpenIDM provides RESTful access to managed groups, at the context path /openidm/managed/group.

For an example of a deployment that uses managed groups, see Sample 2d - Synchronizing LDAP Groups in the Installation Guide in the Installation Guide.

The default managed object model includes a managed role object that can be manipulated in the same way as any other managed object.

This section refers to two distinct types of roles - direct (static) and indirect (dynamic) roles. Direct roles refer to roles that are specifically added to the user's "roles" attribute by an administrator operation. Indirect roles might be added to the user entry as a result of a script or rule that assigns the role. For example, a user might acquire a "sales-role" as a result of being in the "sales" organization.

A managed user's "roles" attribute takes an array as a value. Currently, only flat strings are supported in this array.

The "roles" attribute includes any specifically assigned roles, and any roles assigned internally by OpenIDM. So, the "roles" attribute of a particular user entry might appear as follows:

"roles" : [
    "name" : "managed/role/sample-role",
    "name" : "openidm-authorized"
]
  

A role value that includes a / character is considered to be a URL that points to the role details on the router, for example, managed/role/sample-role.

The following sections describe basic role manipulation - how roles are defined, assigned to users, and deleted. The entitlements or assignments supplied by roles are described in the subsequent section.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-None-Match: *" \
 --request PUT \
 --data '{
 "properties":{"description":"an example role"},
 "assignments":{"ldap":{"attributes":[
 {"name":"cns",
 "assignmentOperation":"mergeWithTarget",
 "unassignmentOperation":"removeFromTarget",
 "value":["CN=employees,O=corp"]}],
 "onAssignment": {"file":"roles/onAssignment_ldap.js","type":"text/javascript"},
 "onUnassignment":{"file":"roles/onUnassignment_ldap.js",
 "type":"text/javascript"}}}}' \
 "https://localhost:8443/openidm/managed/role/newrole"
 
 {
   "assignments": {
     "ldap": {
       "attributes": [
         {
           "name": "cns",
           "unassignmentOperation": "removeFromTarget",
           "assignmentOperation": "mergeWithTarget",
           "value": [
             "CN=employees,O=corp"
           ]
         }
       ],
       "onAssignment": {
         "file": "roles/onAssignment_ldap.js",
         "type": "text/javascript"
       },
       "onUnassignment": {
         "file": "roles/onUnassignment_ldap.js",
         "type": "text/javascript"
       }
     }
   },
   "_id": "newrole",
   "properties": {
     "description": "an example role"
   },
   "_rev": "1"
 }
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/role/?_queryId=query-all-ids"
     
{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 1,
  "result": [
    {
      "_rev": "0",
      "_id": "newrole"
    }
  ]
}     
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-Match: *" \
 --request PATCH \
 --data '[
    {
        "operation": "add",
        "field": "/roles/-",
        "value": "managed/role/newrole"

    }
]' \
 "https://localhost:8443/openidm/managed/user/bjensen"
    
    
{
    "mail": "bjensen@example.com",
    "sn": "Jensen",
    "passwordAttempts": "0",
    "address2": "",
    "lastPasswordAttempt": "Thu Apr 10 2014 12:49:32 GMT+0200 (SAST)",
    "givenName": "Barbara",
    "city": "",
    "country": "",
    "_rev": "2",
    "lastPasswordSet": "",
    "postalCode": "",
    "_id": "bjensen",
    "description": "Created for OpenIDM",
    "accountStatus": "active",
    "telephoneNumber": "1-503-334-2546",
    "roles": [ "openidm-authorized", "managed/role/newrole" ],
    "effectiveAssignments" : {
      "ldap" : {
        "onUnassignment" : {
          "type" : "text/javascript",
          "file" : "roles/onUnassignment_ldap.js"
        },
        "onAssignment" : {
          "type" : "text/javascript",
          "file" : "roles/onAssignment_ldap.js"
        },
        "attributes" : [ {
          "value" : [ "CN=employees,O=corp" ],
          "assignedThrough" : "managed/role/newrole",
          "assignmentOperation" : "mergeWithTarget",
          "unassignmentOperation" : "removeFromTarget",
          "name" : "cns"
        } ]
      }
    },
    "postalAddress": "",
    "userName": "bjensen",
    "stateProvince": "",
    "displayName": "Babara Jensen"
}
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --header "If-Match: *" \
 --request PATCH \
 --data '[
    {
        "operation": "replace",
        "field": "/roles",
        "value": [
            "openidm-authorized"
        ]
    }
]' \
 "https://localhost:8443/openidm/managed/user/bjensen"

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/managed/user?_queryId=get-users-of-direct-role&role=managed/role/newrole"
     
     {
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 1,
  "result": [
    {
      "_rev": "0",
      "_id": "bjensen"
    }
  ]
}
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request DELETE \
 "https://localhost:8443/openidm/managed/role/newrole"
     
 {
   "_id" : "newrole",
   "_rev" : "2",
   "assignments" : {
     "ldap" : {
       "onUnassignment" : {
         "type" : "text/javascript",
         "file" : "roles/onUnassignment_ldap.js"
       },
       "onAssignment" : {
         "type" : "text/javascript",
         "file" : "roles/onAssignment_ldap.js"
       },
       "attributes" : [ {
         "value" : [ "CN=employees,O=corp" ],
         "assignmentOperation" : "mergeWithTarget",
         "unassignmentOperation" : "removeFromTarget",
         "name" : "cns"
       } ]
     }
   },
   "properties" : {
     "description" : "an example role"
   }
 }

    

{
     "name": "samplerole",
     "_id": "samplerole",
     "assignments": {
         "ad": {
             "attributes": [
                 {
                     "name": "cns",
                     "value": [
                         "CN=fileshare,O=corp",
                         "CN=desktop,O=corp",
                         "CN=terminal,O=corp",
                         "CN=intranet,O=corp"
                     ],
                     "assignmentOperation": "mergeWithTarget"
                 }
             ]
         },
         "ldap": {
             "attributes": [
                 {
                     "name": "cns",
                     "value": [
                         "CN=employees,O=corp"
                     ],
                     "operation": "mergeWithTarget"
                 },
                 {
                     "name": "employeeType",
                     "value": "employee"
                 }
             ]
         }
     }
}

{
     "name" : "role",
     "postCreate" : {
         "type" : "text/javascript",
         "file" : "roles/update-users-of-role.js"
     },
     "postUpdate" : {
         "type" : "text/javascript",
         "file" : "roles/update-users-of-role.js"
     },
     "postDelete" : {
         "type" : "text/javascript",
         "file" : "roles/update-users-of-role.js"
     }
}

 {
     "name" : "effectiveRoles",
     "type" : "virtual",
     "onRetrieve" : {
         "type" : "text/javascript",
         "file" : "roles/effectiveRoles.js",
         "rolesPropName" : "roles"
     }
 },
 {
     "name" : "effectiveAssignments",
     "type" : "virtual",
     "onRetrieve" : {
         "type" : "text/javascript",
         "file" : "roles/effectiveAssignments.js",
         "effectiveRolesPropName" : "effectiveRoles"
     }
 }
   

 {
    "_id":"i",
    "_rev":"1",
    "roles":[
       "openidm-authorized",
       "managed/role/sample-role"
    ],
    "effectiveRoles":[
       "openidm-authorized",
       "managed/role/sample-role"
    ],
    "effectiveAssignments":{
       "ldap":{
          "attributes":[
             {
                "value":[
                   "CN=employees,O=corp"
                ],
                "operation":"replaceTarget",
                "name":"cns",
                "assignedThrough":"managed/role/sample-role"
             },
             {
                "value":"employee",
                "name":"employeeType",
                "assignedThrough":"managed/role/sample-role"
             }
          ]
       },
       "ad":{
          "attributes":[
             {
                "value":[
                   "CN=fileshare,O=corp",
                   "CN=desktop,O=corp",
                   "CN=terminal,O=corp",
                   "CN=intranet,O=corp"
                ],
                "operation":"replaceTarget",
                "name":"cns",
                "assignedThrough":"managed/role/sample-role"
             }
          ]
       }
    }
 }

{
    "name" : "managedUser_systemLdapAccounts",
    "source" : "managed/user",
    "target" : "system/ldap/account",
    "links" : "systemLdapAccounts_managedUser",
    },
    "assignmentsToMap": [
        "ldap"
    ],
    ...
}   

The default policy is configured in two files:

...
{   "policyId" : "at-least-X-capitals",
    "policyExec" : "atLeastXCapitalLetters",
    "clientValidation": true,
    "validateOnlyIfPresent":true,
    "policyRequirements" : ["AT_LEAST_X_CAPITAL_LETTERS"]
},
...

policyFunctions.atLeastXCapitalLetters = function(fullObject, value, params, property) {
  var isRequired = _.find(this.failedPolicyRequirements, function (fpr) {
      return fpr.policyRequirement === "REQUIRED";
    }),
    isNonEmptyString = (typeof(value) === "string" && value.length),
    valuePassesRegexp = (function (v) {
      var test = isNonEmptyString ? v.match(/[(A-Z)]/g) : null;
      return test !== null && test.length >= params.numCaps;
    }(value));

  if ((isRequired || isNonEmptyString) && !valuePassesRegexp) {
    return [ { "policyRequirement" : "AT_LEAST_X_CAPITAL_LETTERS", "params" : {"numCaps": params.numCaps} } ];
  }

  return [];
}     
...     
      

{   "policyId" : "minimum-length",
    "policyExec" : "propertyMinLength",
    "clientValidation": true,
    "validateOnlyIfPresent": true,
    "policyRequirements" : ["MIN_LENGTH"]
}
      

function <name>(fullObject, value, params, propName) {	
	<implementation_logic>
}
        

function required(fullObject, value, params, propName) {
    if (value === undefined) {
        return [ { "policyRequirement" : "REQUIRED" } : "REQUIRED" } ];
    }
    return [];
}          
        

{
    "type" : "text/javascript",
    "file" : "bin/defaults/script/policy.js",
    "resources" : [
        {
            "resource" : "managed/user/*",
            "properties" : [
...
                {
                    "name" : "password",
                    "policies" : [
                        {
                            "policyId" : "required"
                        },
                        {
                            "policyId" : "not-empty"
                        },
                        {
                            "policyId" : "at-least-X-capitals",
                            "params" : {
                                "numCaps" : 1
                            }
                        },
                ...
           }
       ]
}     
       

...
    {
        "name" : "mobilePhones",
        "policies" : [
            {
                "policyId" : "required"
            },
            {
                "policyId" : "not-empty"
            }
        ]
    },
    {
        "name" : "mobilePhones[*]",
        "policies" : [
            {
                "policyId" : "not-empty"
            }
        ]
    }
...
       

You can extend the policy service by adding your own scripted policies in openidm/script and referencing them in the policy configuration file (conf/policy.json). Avoid manipulating the default policy script file (in bin/defaults/script) as doing so might result in interoperability issues in a future release. To reference additional policy scripts, set the "additionalFiles" property in conf/policy.json.

The following example creates a custom policy that rejects properties with null values. The policy is defined in a script named mypolicy.js.

var policy = {   "policyId" : "notNull",
       "policyExec" : "notNull",  
       "policyRequirements" : ["NOT_NULL"]
}

addPolicy(policy);

function notNull(fullObject, value, params, property) {
   if (value == null) {
       return [ {"policyRequirement": "NOT_NULL"}: "NOT_NULL"}];
   }
   return [];
} 
    

The mypolicy.js policy is referenced in the policy.json configuration file as follows:

{
    "type" : "text/javascript",
    "file" : "bin/defaults/script/policy.js",
    "additionalFiles" : ["script/mypolicy.js"],
    "resources" : [
        {
...
    

You can also configure policies for managed object properties as part of the property definition in the conf/managed.json file. For example, the following extract of a managed.json file shows a policy configuration for the password property.

...
"properties" : [
    {
        "name" : "password",
        "encryption" : {
            "key" : "openidm-sym-default"
        },
        "scope" : "private"
        "policies" : [
            {
                "policyId" : "required"
            },
            {
                "policyId" : "not-empty"
            },
            {
                "policyId" : "at-least-X-capitals",
                "params" : {
                "numCaps" : 1
                }
            }
        ]
    },
...
   

Policy enforcement refers to the automatic validation of data in the repository when it is created, updated, or patched. In certain situations you might want to disable policy enforcement temporarily. You might, for example, want to import existing data that does not meet the validation requirements with the intention of cleaning up this data at a later stage.

You can disable policy enforcement by setting openidm.policy.enforcement.enabled to false in the conf/boot/boot.properties file. This setting disables policy enforcement in the back-end only, and has no impact on direct policy validation calls to the Policy Service (which the user interface makes to validate input fields). So, with policy enforcement disabled, data added directly over REST is not subject to validation, but data added with the UI is still subject to validation.

Disabling policy enforcement permanently in a production system is not recommended.

You can manage the policy service over the REST interface, by calling the REST endpoint https://localhost:8443/openidm/policy, as shown in the following examples.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/policy"

{
  "resources": [
    {
      "properties": [
      {
        "name": "_id",
        "policies": [
          {
            "policyFunction":
...
      

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/policy/managed/user/*"

{
   "properties": [
     {
        "name": "_id",
        "policies": [
            {
            "policyFunction": "
               "\n  function (fullObject, value, params, property) {
               \n    var i, join = function (arr, d) {

...
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{
  "sn":"Jones",
  "givenName":"Bob",
  "_id":"bjones",
  "telephoneNumber":"0827878921",
  "passPhrase":null,
  "mail":"bjones@example.com",
  "accountStatus":"active",
  "roles":"admin",
  "userName":"bjones@example.com",
  "password":"123"}' \
 "https://localhost:8443/openidm/policy/managed/user/bjones?_action=validateObject"
       
       
 {
   "failedPolicyRequirements": [
     {
       "property": "password",
       "policyRequirements": [
         {
           "params": {
             "numCaps": 1
           },
           "policyRequirement": "AT_LEAST_X_CAPITAL_LETTERS"
         }
       ]
     },
     {
       "property": "password",
       "policyRequirements": [
         {
           "params": {
             "minLength": 8
           },
           "policyRequirement": "MIN_LENGTH"
         }
       ]
     },
     {
       "property": "passPhrase",
       "policyRequirements": [
         {
           "params": {
             "minLength": 4
           },
           "policyRequirement": "MIN_LENGTH"
         }
       ]
     }
   ],
   "result": false
 }
      

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{ "password" : "12345" }' \
 "http://localhost:8080/openidm/policy/managed/user/bjensen?_action=validateProperty"
       
       
{
    "result": false,
    "failedPolicyRequirements": [
        {
            "policyRequirements": [
                {
                    "policyRequirement": "AT_LEAST_X_CAPITAL_LETTERS",
                    "params": {
                        "numCaps": 1
                    }
                },
                {
                    "policyRequirement": "MIN_LENGTH",
                    "params": {
                        "minLength": 8
                    }
                }
            ],
            "property": "password"
        }
    ]
}                  
      

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{ "password" : "1NewPassword" }' \
 "https://localhost:8443/openidm/policy/managed/user/bjensen?_action=validateProperty"
       
       
{
    "failedPolicyRequirements": []
    "result": true,
}                      
      

OpenICF provides a common interface to allow identity services access to the resources that contain user information. OpenIDM loads the OpenICF API as one of its OSGi modules. OpenICF uses connectors to separate the OpenIDM implementation from the dependencies of the resource to which OpenIDM is connecting. A specific connector is required for each remote resource. Connectors can run either locally or remotely.

Local connectors are loaded by OpenICF as regular bundles in the OSGi container. Remote connectors must be executed on a remote connector server. Most connectors can be run locally. However, a remote connector server is required when access libraries that cannot be included as part of the OpenIDM process are needed. If a resource, such as Microsoft Active Directory, does not provide a connection library that can be included inside the Java Virtual Machine, OpenICF can use the native .dll with a remote .NET connector server. In other words, OpenICF connects to Active Directory through a remote connector server that is implemented as a .NET service.

Connections to remote connector servers are configured in a single connector info provider configuration file, located in /path/to/openidm/conf.

Connectors themselves are configured through provisioner files. One provisioner file must exist for each connector. Provisioner files are named provisioner.openicf-name where name corresponds to the name of the connector, and are also located in the /path/to/openidm/conf directory.

A number of sample connector configurations are available in the openidm/samples/provisioners directory. To use these connectors, edit the configuration files as required, and copy them to the openidm/conf directory.

The following figure shows how OpenIDM connects to resources by using connectors and remote connector servers. The figure shows one local connector (LDAP) and two remote connectors (Scripted SQL and PowerShell). In this example, the remote Scripted SQL connector uses a remote Java connector server. The remote PowerShell connector always requires a remote .NET connector server.

When you configure a remote connector, you use the connector info provider service to connect through a remote connector server. The connector info provider service configuration is stored in the file openidm/conf/provisioner.openicf.connectorinfoprovider.json. A sample configuration file is provided in the openidm/samples/provisioners/ directory. To use this sample configuration, edit the file as required, and copy it to the openidm/conf directory.

The connector info provider service takes the following configuration:

{
  "connectorsLocation"     : string,
  "remoteConnectorServers" : [remoteConnectorServer objects]
}

{
  "name"               : "dotnet",
  "host"               : "127.0.0.1",
  "port"               : 8759,
  "heartbeatInterval"  : 60,
  "useSSL"             : false,
  "timeout"            : 0,
  "key"                : "Passw0rd"
}

Connectors are configured through the OpenICF provisioner service. Each connector configuration is stored in a file in the openidm/conf/ folder, and accessible over REST at the openidm/conf endpoint. Configuration files are named openidm/conf/provisioner.openicf-name where name corresponds to the name of the connector. A number of sample connectors are available in the openidm/samples/provisioners directory. To use these connectors, edit the configuration files as required, and copy them to the openidm/conf directory.

If you are creating your own connector configuration files, do not include additional dash characters ( - ) in the connector name, as this might cause problems with the OSGi parser. For example, the name provisioner.openicf-hrdb.json is fine. The name provisioner.openicf-hr-db.json is not.

The following example shows a connector configuration for an XML file resource.

{
 "name"                    : "xml",
 "connectorRef"            : connector-ref-object,
 "poolConfigOption"        : pool-config-option-object,
 "operationTimeout"        : operation-timeout-object,
 "configurationProperties" : configuration-properties-object,
 "objectTypes"             : object-types-object,
 "operationOptions"        : operation-options-object
}

The "name" property specifies the name of the system to which you are connecting. This name must be alphanumeric.

{
  "bundleName"       : "org.forgerock.openicf.connectors.xml-connector",
  "bundleVersion"    : "[1.1,1.5]",
  "connectorName"    : "org.forgerock.openicf.connectors.xml.XMLConnector",
  "connectorHostRef" : "host"
}

{
  "maxObjects"                 : 10,
  "maxIdle"                    : 10,
  "maxWait"                    : 150000,
  "minEvictableIdleTimeMillis" : 120000,
  "minIdle"                    : 1
}

{
  "CREATE"              : -1,
  "TEST"                : -1,
  "AUTHENTICATE"        : -1,
  "SEARCH"              : -1,
  "VALIDATE"            : -1,
  "GET"                 : -1,
  "UPDATE"              : -1,
  "DELETE"              : -1,
  "SCRIPT_ON_CONNECTOR" : -1,
  "SCRIPT_ON_RESOURCE"  : -1,
  "SYNC"                : -1,
  "SCHEMA"              : -1
}

"configurationProperties" : {
    "xsdIcfFilePath" : "&{launcher.project.location}/data/resource-schema-1.xsd",
    "xsdFilePath" : "&{launcher.project.location}/data/resource-schema-extension.xsd",
    "xmlFilePath" : "&{launcher.project.location}/data/xmlConnectorData.xml"
}

system/$systemName/$objectType

{
  "account" :
  {
    "$schema" : "http://json-schema.org/draft-03/schema",
    "id" : "__ACCOUNT__",
    "type" : "object",
    "nativeType" : "__ACCOUNT__",
    "properties" :
    {
      "name" :
      {
        "type" : "string",
        "nativeName" : "__NAME__",
        "nativeType" : "JAVA_TYPE_PRIMITIVE_LONG",
        "flags" :
        [
          "NOT_CREATABLE",
          "NOT_UPDATEABLE",
          "NOT_READABLE",
          "NOT_RETURNED_BY_DEFAULT"
        ]
      },
      "groups" :
      {
        "type" : "array",
        "items" :
        {
          "type" : "string",
          "nativeType" : "string"
        },
        "nativeName" : "__GROUPS__",
        "nativeType" : "string",
        "flags" :
        [
          "NOT_RETURNED_BY_DEFAULT"
        ]
      },
      "givenName" : {
         "type" : "string",
         "nativeName" : "givenName",
         "nativeType" : "string"
         },
    }
  }
}

"operationOptions" : {
  {
    "SYNC" :
    {
      "denied" : true,
      "onDeny" : "DO_NOTHING",
      "objectFeatures" :
      {
        "__ACCOUNT__" :
        {
          "denied" : true,
          "onDeny" : "THROW_EXCEPTION",
          "operationOptionInfo" :
          {
            "$schema" : "http://json-schema.org/draft-03/schema",
            "id" : "FIX_ME",
            "type" : "object",
            "properties" :
            {
              "_OperationOption-float" :
              {
                 "type" : "number",
                 "nativeType" : "JAVA_TYPE_PRIMITIVE_FLOAT"
              }
            }
          }
        },
        "__GROUP__" :
        {
          "denied" : false,
          "onDeny" : "DO_NOTHING"
        }
      }
    }
  }
...

Connectors that use the .NET framework must run remotely. Java connectors can run locally or remotely. Connectors that run remotely require a connector server to enable OpenIDM to access the connector.

This section describes the steps to install a .NET connector server and a remote Java Connector Server.

<add name="file"
    type="System.Diagnostics.TextWriterTraceListener"
    initializeData="C:\openicf\logs\connectorserver.log"
    traceOutputOptions="DateTime">
      <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information"/>
  </add>

OpenIDM 3.0.0 provides several connectors by default, in the path/to/openidm/connectors directory. Additional connectors can be downloaded from the Open Stack download page.

This section describes the connectors that are supported for use with OpenIDM 3.0.0, and provides instructions for installing and configuring these connectors. For instructions on building connector configurations interactively, see Section 10.6, "Creating Default Connector Configurations".

{
    "connectorRef": {
        "connectorHostRef": "#LOCAL",
        "bundleName": "org.forgerock.openicf.connectors.xml-connector",
        "bundleVersion": "[1.1,1.5]",
        "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
    }
}

{
    "configurationProperties": {
        "xsdIcfFilePath" : "&{launcher.project.location}/data/resource-schema-1.xsd",
        "xsdFilePath" : "&{launcher.project.location}/data/resource-schema-extension.xsd",
        "xmlFilePath" : "&{launcher.project.location}/data/xmlConnectorData.xml"
    }
}

$ cd path/to/openidm
 $ scp -r samples/sample1/data testuser@remote-host:/home/testuser/xml-sample
 testuser@remote-host's password:
 resource-schema-1.xsd                    100% 4083     4.0KB/s   00:00
 resource-schema-extension.xsd            100% 1351     1.3KB/s   00:00
 xmlConnectorData.xml                     100% 1648     1.6KB/s   00:00

$ cd path/to/openidm
 $ scp connectors/xml-connector-1.4.0.0.jar testuser@remote-host:/path/to/openicf/bundles
 testuser@172.16.203.97's password:
 xml-connector-1.4.0.0.jar                100% 4379KB   4.3MB/s   00:00

{
    "connectorRef": {
        "connectorHostRef": "#LOCAL",
        "connectorName": "org.identityconnectors.ldap.LdapConnector",
        "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
        "bundleVersion": "[1.1,1.5]"
    }
}

"configurationProperties" : {
    "host" : "localhost",
    "port" : 1389,
    "ssl" : false,
    "principal" : "cn=Directory Manager",
    "credentials" : "password",
    "baseContexts" : [
        "dc=example,dc=com"
    ],
    "baseContextsToSynchronize" : [
        "dc=example,dc=com"
    ],
    "accountSearchFilter" : null,
    "accountSynchronizationFilter" : null,
    "groupSearchFilter" : null,
    "groupSynchronizationFilter" : null,
    "passwordAttributeToSynchronize" : null,
    "synchronizePasswords" : false,
    "removeLogEntryObjectClassFromFilter" : true,
    "modifiersNamesToFilterOut" : [ ],
    "passwordDecryptionKey" : null,
    "changeLogBlockSize" : 100,
    "attributesToSynchronize" : [ ],
    "changeNumberAttribute" : "changeNumber",
    "passwordDecryptionInitializationVector" : null,
    "filterWithOrInsteadOfAnd" : false,
    "objectClassesToSynchronize" : [
        "inetOrgPerson"
    ],
    "vlvSortAttribute" : "uid",
    "passwordAttribute" : "userPassword",
    "useBlocks" : false,
    "maintainPosixGroupMembership" : false,
    "failover" : [ ],
    "readSchema" : true,
    "accountObjectClasses" : [
        "top",
        "person",
        "organizationalPerson",
        "inetOrgPerson"
    ],
    "accountUserNameAttributes" : [
        "uid"
    ],
    "groupMemberAttribute" : "uniqueMember",
    "passwordHashAlgorithm" : null,
    "usePagedResultControl" : false,
    "blockSize" : 100,
    "uidAttribute" : "dn",
    "maintainLdapGroupMembership" : false,
    "respectResourcePasswordPolicyChangeAfterReset" : false
},

# Set the truststore
javax.net.ssl.trustStore=/path/to/openidm/security/truststore
   

$ more /path/to/openidm/script/access.js
       ...
{
    "pattern"   : "system/ActiveDirectory",
    "roles"     : "openidm-admin",
    "methods" : "action",
    "actions"   : "script"
},     

     if ($loginName -ne $NULL) {
  [System.Reflection.Assembly]::LoadWithPartialName('Microsoft.SqlServer.SMO') | Out-Null
  $sqlSrv = New-Object ('Microsoft.SqlServer.Management.Smo.Server') ('WIN-C2MSQ8G1TCA')

  $login = New-Object -TypeName ('Microsoft.SqlServer.Management.Smo.Login') ($sqlSrv, $loginName)
  $login.LoginType = 'SqlLogin'
  $login.PasswordExpirationEnabled = $false
  $login.Create('Passw0rd')
  #  The next two lines are optional, and to give the new login a server role, optional
  $login.AddToRole('sysadmin')
  $login.Alter()
 } else {
  $Error_Message = [string]"Required variables 'loginName' is missing!"
     Write-Error $Error_Message
     throw $Error_Message
 }
     

 "systemActions" : [
     {
         "_scriptId" : "ConnectorScriptName",
         "actions" : [
             {
                 "systemType" : ".*ActiveDirectoryConnector",
                 "actionType" : "Shell",
                 "actionSource" : "@echo off \r\n echo %loginName%\r\n"
             },
             {
                 "systemType" : ".*ActiveDirectoryConnector",
                 "actionType" : "PowerShell",
                 "actionFile" : "script/createUser.ps1"
             }
         ]
     }
 ]
     

$ curl \
  --cacert self-signed.crt \
  --header "X-OpenIDM-Username: openidm-admin" \
  --header "X-OpenIDM-Password: openidm-admin" \
  --header "Content-Type: application/json" \
  --request POST \
  "https://localhost:8443/openidm/system/ActiveDirectory/?_action=script&scriptId=ConnectorScriptName&scriptExecuteMode=resource&loginName=myUser"

{
  "connectorRef": {
    "connectorHostRef": "#LOCAL",
    "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector",
    "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
    "bundleVersion": "[1.1,1.5]"
  }
}

{
    "configurationProperties": {
        "filePath": "data/hr.csv",
        "uniqueAttribute": "uid"
    }
}

"configurationProperties" : {
    "host" : "localhost",
    "port" : "3306",
    ...
    "database" : "HRDB",
    "autoCommit" : false,
    "reloadScriptOnExecution" : true,
    "createScriptFileName" : "&{launcher.project.location}/tools/CreateScript.groovy",
    ...
   

"configurationProperties" :
    {
       "quoting" : "",
       "host" : "localhost",
       "port" : "3306",
       "user" : "root",
       "password" : "",
       "database" : "contractordb",
       "table" : "people",
       "keyColumn" : "UNIQUE_ID",
       "passwordColumn" : "",
       "jdbcDriver" : "com.mysql.jdbc.Driver",
       "jdbcUrlTemplate" : "jdbc:mysql://%h:%p/%d",
       "enableEmptyString" : false,
       "rethrowAllSQLExceptions" : true,
       "nativeTimestamps" : true,
       "allNative" : false,
       "validConnectionQuery" : null,
       "changeLogColumn" : "CHANGE_TIMESTEMP",
       "datasource" : "",
       "jndiProperties" : null
    },

Rather than creating provisioner files by hand, use the service that OpenIDM exposes through the REST interface to create basic connector configuration files, or use the cli.sh or cli.bat scripts to generate a basic connector configuration.

This section describes how to create connector configurations over the REST interface. For instructions on using the CLI to create connector configurations, see the configureconnector section of the CLI Interface chapter.

List available connectors using the following command.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system?_action=CREATECONFIGURATION"

The command above therefore should return the following output.

{
  "connectorRef": [
    {
      "bundleVersion": "1.1.0.1",
      "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
      "displayName": "CSV File Connector",
      "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector"
    },
    {
      "bundleVersion": "1.1.0.0",
      "bundleName": "org.forgerock.openicf.connectors.databasetable-connector",
      "displayName": "Database Table Connector",
      "connectorName": "org.identityconnectors.databasetable.DatabaseTableConnector"
    },
    {
      "bundleVersion": "1.4.0.0",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "displayName": "Scripted Poolable Groovy Connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedPoolableConnector"
    },
    {
      "bundleVersion": "1.4.0.0",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "displayName": "Scripted Groovy Connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedConnector"
    },
    {
      "bundleVersion": "1.1.1.3",
      "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
      "displayName": "LDAP Connector",
      "connectorName": "org.identityconnectors.ldap.LdapConnector"
    },
    {
      "bundleVersion": "1.1.1.0",
      "bundleName": "org.forgerock.openicf.connectors.scriptedsql-connector",
      "displayName": "Scripted SQL",
      "connectorName": "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"
    },
    {
      "bundleVersion": "1.1.0.1",
      "bundleName": "org.forgerock.openicf.connectors.xml-connector",
      "displayName": "XML Connector",
      "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
    }
  ]
}

To generate the core configuration, choose one of the available connectors by copying one of the JSON objects from the generated list into the body of the REST command, as shown below for the XML connector.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{"connectorRef":
 {"connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector",
 "displayName": "XML Connector",
 "bundleName": "org.forgerock.openicf.connectors.xml-connector",
 "bundleVersion": "1.1.0.1"}
 }' \
 "https://localhost:8443/openidm/system?_action=CREATECONFIGURATION"

This command returns a core connector configuration, similar to the following:

{
   "poolConfigOption": {
   "minIdle": 1,
   "minEvictableIdleTimeMillis": 120000,
   "maxWait": 150000,
   "maxIdle": 10,
   "maxObjects": 10
  },
   "resultsHandlerConfig": {
   "enableAttributesToGetSearchResultsHandler": true,
   "enableFilteredResultsHandler": true,
   "enableNormalizingResultsHandler": true
  },
  "operationTimeout": {
    "SCHEMA": -1,
    "SYNC": -1,
    "VALIDATE": -1,
    "SEARCH": -1,
    "AUTHENTICATE": -1,
    "CREATE": -1,
    "UPDATE": -1,
    "DELETE": -1,
    "TEST": -1,
    "SCRIPT_ON_CONNECTOR": -1,
    "SCRIPT_ON_RESOURCE": -1,
    "GET": -1,
    "RESOLVEUSERNAME": -1
  },
  "configurationProperties": {
   "xsdIcfFilePath": null,
   "xsdFilePath": null,
   "createFileIfNotExists": false,
   "xmlFilePath": null
  },
  "connectorRef": {
    "bundleVersion": "1.1.0.1",
    "bundleName": "org.forgerock.openicf.connectors.xml-connector",
    "displayName": "XML Connector",
    "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
  }
}

The configuration that is returned is not yet functional. Notice that it does not contain the required system-specific "configurationProperties", such as the host name and port for web based connectors, or the "xmlFilePath" for the XML file-based connectors. In addition, the configuration does not include the complete list of "objectTypes" and "operationOptions".

To generate the final configuration, add values for the "configurationProperties" to the core configuration, and use the updated configuration as the body for the next command.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{
  "configurationProperties":
    {
      "xsdIcfFilePath" : "samples/sample1/data/resource-schema-1.xsd",
      "xsdFilePath" : "samples/sample1/data/resource-schema-extension.xsd",
      "xmlFilePath" : "samples/sample1/data/xmlConnectorData.xml",
      "createFileIfNotExists": false
  },
  "operationTimeout": {
    "SCHEMA": -1,
    "SYNC": -1,
    "VALIDATE": -1,
    "SEARCH": -1,
    "AUTHENTICATE": -1,
    "CREATE": -1,
    "UPDATE": -1,
    "DELETE": -1,
    "TEST": -1,
    "SCRIPT_ON_CONNECTOR": -1,
    "SCRIPT_ON_RESOURCE": -1,
    "GET": -1,
    "RESOLVEUSERNAME": -1
  },
  "resultsHandlerConfig": {
    "enableAttributesToGetSearchResultsHandler": true,
    "enableFilteredResultsHandler": true,
    "enableNormalizingResultsHandler": true
  },
  "poolConfigOption": {
    "minIdle": 1,
    "minEvictableIdleTimeMillis": 120000,
    "maxWait": 150000,
    "maxIdle": 10,
    "maxObjects": 10
  },
  "connectorRef": {
    "bundleVersion": "1.1.0.1",
    "bundleName": "org.forgerock.openicf.connectors.xml-connector",
    "displayName": "XML Connector",
    "connectorName": "org.forgerock.openicf.connectors.xml.XMLConnector"
  }
}' \
 "https://localhost:8443/openidm/system?_action=CREATECONFIGURATION"

OpenIDM attempts to read the schema, if available, from the external resource in order to generate output. OpenIDM then iterates through schema objects and attributes, creating JSON representations for "objectTypes" and "operationOptions" for supported objects and operations.

The output includes the basic --data input, along with operationOptions and objectTypes.

Because OpenIDM produces a full property set for all attributes and all object types in the schema from the external resource, the resulting configuration can be large. For an LDAP server, OpenIDM can generate a configuration containing several tens of thousands of lines, for example. You might therefore want to reduce the schema to a minimum on the external resource before you run the final command.

After a connection has been configured, external systems are accessible over the REST interface at the URL https://localhost:8443/openidm/system/connector-name. Aside from accessing the data objects within the external systems, you can test the availability of the systems themselves.

To list the external systems that are connected to an OpenIDM instance, use the test action on the URL https://localhost:8443/openidm/system/. The following example shows two external LDAP servers connected to OpenIDM:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system?_action=test"
   
[
  {
    "ok": true,
    "name": "ldap1"
  },
  {
    "ok": true,
    "name": "ldap2"
  }
]

The status of the system is provided by the ok parameter. If the connection is available, the value of this parameter is true.

To obtain the status for a single system, include the name of the connector in the URL, for example:

$ curl \
 --cacert self-signed.crt \
 --header "Content-Type: application/json" \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "https://localhost:8443/openidm/system/ldap1?_action=test"
   
{
  "ok": true,
  "name": "ldap1"
}

If there is a problem with the connection, the request returns an error message. In the following example, the LDAP server named ldap1 is down.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system/ldap1?_action=test"
   {
  "error": "javax.naming.CommunicationException: localhost:1389
            [Root exception is java.net.ConnectException: Connection refused: Connection refused]",
  "name": "ldap"
}

To test the validity of a connector configuration, use the testConfig action and include the configuration in the command. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --data '{
    "name" : "xmlfile",
    "connectorRef" : {
        "bundleName" : "org.forgerock.openicf.connectors.xml-connector",
        "bundleVersion" : "1.1.0.1",
        "connectorName" : "org.forgerock.openicf.connectors.xml.XMLConnector"
    },
    "producerBufferSize" : 100,
    "connectorPoolingSupported" : true,
    "poolConfigOption" : {
        "maxObjects" : 10,
        "maxIdle" : 10,
        "maxWait" : 150000,
        "minEvictableIdleTimeMillis" : 120000,
        "minIdle" : 1
    },
    "operationTimeout" : {
        "CREATE" : -1,
        "TEST" : -1,
        "AUTHENTICATE" : -1,
        "SEARCH" : -1,
        "VALIDATE" : -1,
        "GET" : -1,
        "UPDATE" : -1,
        "DELETE" : -1,
        "SCRIPT_ON_CONNECTOR" : -1,
        "SCRIPT_ON_RESOURCE" : -1,
        "SYNC" : -1,
        "SCHEMA" : -1
    },
    "configurationProperties" : {
        "xsdIcfFilePath" : "samples/sample1/data/resource-schema-1.xsd",
        "xsdFilePath" : "samples/sample1/data/resource-schema-extension.xsd",
        "xmlFilePath" : "samples/sample1/data/xmlConnectorData.xml"
    },
    "syncFailureHandler" : {
        "maxRetries" : 5,
        "postRetryAction" : "logged-ignore"
    },
    "objectTypes" : {
        "account" : {
            "$schema" : "http://json-schema.org/draft-03/schema",
            "id" : "__ACCOUNT__",
            "type" : "object",
            "nativeType" : "__ACCOUNT__",
            "properties" : {
                "description" : {
                    "type" : "string",
                    "nativeName" : "__DESCRIPTION__",
                    "nativeType" : "string"
                },
                "firstname" : {
                    "type" : "string",
                    "nativeName" : "firstname",
                    "nativeType" : "string"
                },
                "email" : {
                    "type" : "string",
                    "nativeName" : "email",
                    "nativeType" : "string"
                },
                "_id" : {
                    "type" : "string",
                    "nativeName" : "__UID__"
                },
                "password" : {
                    "type" : "string",
                    "nativeName" : "password",
                    "nativeType" : "string"
                },
                "name" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "__NAME__",
                    "nativeType" : "string"
                },
                "lastname" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "lastname",
                    "nativeType" : "string"
                },
                "mobileTelephoneNumber" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "mobileTelephoneNumber",
                    "nativeType" : "string"
                },
                "securityQuestion" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "securityQuestion",
                    "nativeType" : "string"
                },
                "securityAnswer" : {
                    "type" : "string",
                    "required" : true,
                    "nativeName" : "securityAnswer",
                    "nativeType" : "string"
                },
                "roles" : {
                    "type" : "string",
                    "required" : false,
                    "nativeName" : "roles",
                    "nativeType" : "string"
                }
            }
        }
    },
    "operationOptions" : { }
}' \
 --request POST \
 "https://localhost:8443/openidm/system?_action=testConfig"
  

If the configuration is valid, the command returns "ok": true, for example:

{
   "ok": true,
   "name": "xmlfile"
}

You can add the attributes of your choice to a connector configuration file. Specifically, if you want to set up Property Level Extensions to one of the objectTypes such as account, use the format shown under Object Types.

You can configure connectors to enable provisioning of arbitrary property level extensions (such as image files) to system resources. For example, if you want to set up image files such as account avatars, open the appropriate provisioner file. Look for an account section similar to:

"account" : {
    "$schema" : "http://json-schema.org/draft-03/schema",
    "id" : "__ACCOUNT__",
    "type" : "object",
    "nativeType" : "__ACCOUNT__",
    "properties" : {
   

Under "properties", add one of the following code blocks. The first block works for a single photo encoded as a base64 string. The second block would address multiple photos encoded in the same way.

"attributeByteArray" : {
    "type" : "string",
    "nativeName" : "attributeByteArray",
    "nativeType" : "JAVA_TYPE_BYTE_ARRAY"
},
   

"attributeByteArrayMultivalue": {
    "type": "array",
    "items": {
        "type": "string",
        "nativeType": "JAVA_TYPE_BYTE_ARRAY"
    },
    "nativeName": "attributeByteArrayMultivalue"
},
   

Synchronization happens either when OpenIDM receives a change directly, or when OpenIDM discovers a change on an external resource.

For direct changes to OpenIDM, OpenIDM immediately pushes updates to all external resources configured to receive the updates. A direct change can originate not only as a write request through the REST interface, but also as an update resulting from reconciliation with another resource.

To determine what to synchronize, and how to carry out synchronization, OpenIDM relies on mappings configured in the /path/to/conf/sync.json file. LiveSync and automatic sync rely on the mappings configured once per OpenIDM server.

For reconciliation or LiveSync, you can schedule changes as described in Scheduling Tasks and Events.

...
"onDelete" : {
    "type" : "text/javascript",
    "file" : "ui/onDelete-user-cleanup.js"
    },
"onSync" : {
    "type" : "text/javascript",
    "file" : "compensate.js"
    },
"properties" : [
    ...
    

   ...
   "mappings" : [
     {
       "name" : "managedUser_systemAdAccounts",
       "source" : "managed/user",
       "target" : "system/ad/account",
     ...
    

if (syncResults.success) {
     logger.debug("sync was a success; no compensation necessary");
     return;
}

Identity management software tends to favor either a meta-directory data model, where all data are mirrored in a central repository, or a virtual data model, where only a minimum set of attributes are stored centrally, and most are loaded on demand from the external resources in which they are stored. The meta-directory model offers fast access at the risk of getting outdated data. The virtual model guarantees fresh data, but pays for that guarantee in terms of performance.

OpenIDM leaves the data model choice up to you. You determine the right trade offs for a particular deployment. OpenIDM does not hard code any particular schema or set of attributes stored in the repository. Instead, you define how external system objects map onto managed objects, and OpenIDM dynamically updates the repository to store the managed object attributes that you configure.

You can, for example, choose to follow the data model defined in the Simple Cloud Identity Management (SCIM) specification. The following object represents a SCIM user.

{
    "userName": "james1",
    "familyName": "Berg",
    "givenName": "James",
    "email": [
        "james1@example.com"
    ],
    "description": "Created by OpenIDM REST.",
    "password": "asdfkj23",
    "displayName": "James Berg",
    "phoneNumber": "12345",
    "employeeNumber": "12345",
    "userType": "Contractor",
    "title": "Vice President",
    "active": true
}

Data flow for synchronization involves the following elements:

{
    "name": "MyLDAP",
    "objectTypes": {
        "account": {
            "lastName": {
                "type": "string",
                "required": true,
                "nativeName": "sn",
                "nativeType": "string"
            },
            "homePhone": {
                "type": "array",
                "items": {
                    "type": "string",
                    "nativeType": "string"
                },
                "nativeName": "homePhone",
                "nativeType": "string"
            }
        }
    }
}

11.3.2. Synchronization Mappings File

The synchronization mappings file (openidm/conf/sync.json) represents the core configuration for OpenIDM synchronization.

The sync.json file describes a set of mappings. Each mapping specifies how attributes from source objects correspond to attributes on target objects. The source and target indicate the direction for the data flow, so you must define a separate mapping for each data flow. For example, if you want data flows from an LDAP server to the repository and also from the repository to the LDAP server, you must define two separate mappings.

You identify external resource sources and targets as system/name/object-type, where name is the name used in the connector configuration file, and object-type is the object defined in the connector configuration file list of object types. For objects in OpenIDM's internal repository, you use managed/object-type, where object-type is defined in openidm/conf/managed.json. The name for the mapping by convention is set to a string of the form source_target, as shown in the following example.

{
    "mappings": [
        {
            "name": "systemLdapAccounts_managedUser",
            "source": "system/MyLDAP/account",
            "target": "managed/user",
            "properties": [
                {
                    "target": "sn",
                    "source": "lastName"
                },
                {
                    "target": "telephoneNumber",
                    "source": "homePhone"
                },
                {
                    "target": "phoneExtension",
                    "default": "0047"
                },
                {
                    "target": "mail",
                    "comment": "Set mail if non-empty.",
                    "source": "email",
                    "condition": {
                        "type": "text/javascript",
                        "source": "(object.email != null)"
                    }
                },
                {
                    "target": "displayName",
                    "source": "",
                    "transform": {
                        "type": "text/javascript",
                        "source": "source.lastName +', ' + source.firstName;"
                    }
                }
            ]
        }
    ]
}

In this example, the source is the external resource, MyLDAP, and the target is OpenIDM's repository, specifically the managed user objects. The properties reflect OpenIDM attribute names. For example, the mapping has the attribute lastName defined in the MyLDAP connector configuration file mapped to sn in the OpenIDM managed user object. Notice that the attribute names come from the connector configuration, rather than the external resource itself.

You can create attributes on the target as part of the mapping. In the preceding example, a phoneExtension attribute with a default value of 0047 is created on the target. The "default" property can also be used to specify the value to assign to the target property if the "source" property and the "transform" script yield a null value. If no value is specified, the default value is null.

You can also set up conditions under which OpenIDM maps attributes as shown for the email attribute in the example. By default, OpenIDM synchronizes all attributes. In the example, the mail attribute is set only if the script for the condition returns true.

OpenIDM also enables you to transform attributes. In the example, the value of the displayName attribute is set using a combination of the lastName and firstName attribute values from the source. For transformations, the source property is optional. However, the source object is only available when you specify the source property. Therefore, in order to use source.lastName and source.firstName to calculate the displayName, the example specifies "source" : "".

To add a flow from the repository to MyLDAP, you would define a mapping with source managed/user and target system/MyLDAP/account, named for example managedUser_systemLdapAccounts.

The following image shows the paths to objects in the OpenIDM namespace.

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

By default, OpenIDM synchronizes all objects that match those defined in the connector configuration for the resource. Many connectors allow you to limit the scope of objects that the connector accesses. For example, the LDAP connector allows you to specify base DNs and LDAP filters so that you do not need to access every entry in the directory. OpenIDM also allows you to filter what is considered a valid source or valid target for synchronization by using scripts. To apply these filters, use the validSource, and validTarget properties in your mapping.

validSource

A script that determines if a source object is valid to be mapped. The script yields a boolean value: true indicates that the source object is valid; false can be used to defer mapping until some condition is met. In the root scope, the source object is provided in the "source" property. If the script is not specified, then all source objects are considered valid.

{
    "validSource": {
        "type": "text/javascript",
        "source": "source.ldapPassword != null"
    }
}

validTarget

A script, used during reconciliation's second phase, that determines if a target object is valid to be mapped. The script yields a boolean value: true indicates that the target object is valid; false indicates that the target object should not be included in reconciliation. In the root scope, the source object is provided in the "target" property. If the script is not specified, then all target objects are considered valid for mapping.

{
    "validTarget": {
        "type": "text/javascript",
        "source": "target.employeeType == 'internal'"
    }
}

During synchronization, your scripts always have access to a source object and a target object. Examples already shown in this section use source.attributeName to retrieve attributes from the source objects. Your scripts can also write to target attributes using target.attributeName syntax.

{
    "onUpdate": {
        "type": "text/javascript",
        "source": "if (source.email != null) {target.mail = source.email;}"
    }
}

See the Scripting Reference appendix for more on scripting.

By default, all mappings participate in automatic synchronization operations. You can prevent a specific mapping from participating in automatic synchronization by setting the "enableSync" property of that mapping to false. In the following example, automatic synchronization is disabled. This means that changes to objects in the internal repository are not automatically propagated to the LDAP directory. To propagate changes to the LDAP directory, reconciliation must be launched manually.

{
    "mappings" : [
        {
            "name" : "managedUser_systemLdapAccounts",
            "source" : "managed/user",
            "target" : "system/ldap/account",
            "enableSync" : false,
             ....
}
   

Note that if enableSync is set to false for a system to managed user mapping (for example "systemLdapAccounts_managedUser"), LiveSync is disabled for that mapping.

If a source resource is empty, the default behavior is for a reconciliation operation to exit, without failure, and to log a warning, similar to the following:

2014-03-20 10:41:18:918 WARN Cannot perform reconciliation with an empty source
    object set, unless explicitly configured to allow it.
   

The reconciliation summary is also logged in the reconciliation audit log.

This behavior prevents reconciliation operations from accidentally deleting everything in a target resource. For example, in the event that a source system is unavailable but erroneously reporting its status as "up", the absence of source objects should not result in objects being removed on the target resource.

There might be situations in which you do want reconciliations of an empty source resource to proceed. In this case, you can override the default behavior by setting the "allowEmptySourceSet" property to true in the mapping. For example:

{
    "mappings" : [
        {
        "name" : "systemXmlfileAccounts_managedUser",
        "source" : "system/xmlfile/account",
        "allowEmptySourceSet" : true,
        ...
   

Reconciliation of an empty source effectively wipes out the target.

You can update mappings in the synchronization configuration file (sync.json) while the server is running, provided you do not update a mapping that is currently in use by a reconciliation process.

{
    "objects": [
        {
            "name": "user",
            ...
            "properties": [
                {
                    "name": "securityAnswer",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                },
                {
                    "name": "ssn",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                },
                {
                    "name": "password",
                    "encryption": {
                        "key": "openidm-sym-default"
                    }
                }
            ],
            ...
          }
    ]
}

       "properties" : [
           {
               "name" : "securityAnswer",
               "encryption" : {
                   "key" : "openidm-sym-default"
               },
               "scope" : "private"
           },
           {
               "name" : "password",
               "encryption" : {
                   "key" : "openidm-sym-default"
               },
               "scope" : "private"
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '[
    {
    "operation":"replace",
    "field":"/givenName",
    "value":"Jon"
    }
 ]' \
 "https://localhost:8443/openidm/managed/user?_action=patch&_queryId=for-userName&uid=jdoe"
   

{
    "onCreate": {
        "type": "text/javascript",
        "source":
            "target.dn = 'uid=' + source.uid + ',ou=people,dc=example,dc=com'"
    }
}

{
    "mappings": [
        {
            "name": "systemMyLDAPAccounts_managedUser",
            "source": "system/MyLDAP/account",
            "target": "managed/user"
        },
        {
            "name": "managedUser_systemMyLDAPAccounts",
            "source": "managed/user",
            "target": "system/MyLDAP/account",
            "links": "systemMyLDAPAccounts_managedUser"
        }
    ]
}

You can trigger, cancel, and monitor reconciliation operations over REST, using the REST endpoint https://localhost:8443/openidm/recon.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser"

{"_id":"0890ad62-4738-4a3f-8b8e-f3c83bbf212e"}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon?_action=recon&mapping=systemLdapAccounts_managedUser&waitForCompletion=true"
   

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/recon/0890ad62-4738-4a3f-8b8e-f3c83bbf212e"
     {
  "ended": "2014-03-06T07:00:32.094Z",
  "_id": "7a07c100-4f11-4d7e-bf8e-fa4594f99d58",
  "mapping": "systemLdapAccounts_managedUser",
  "state": "SUCCESS",
  "stage": "COMPLETED_SUCCESS",
  "stageDescription": "reconciliation completed.",
  "progress": {
     "links": {
       "created": 0,
       "existing": {
         "total": "1",
         "processed": 1
       }
     },
     "target": {
       "created": 0,
       "existing": {
         "total": "3",
         "processed": 3
       }
     },
     "source": {
       "existing": {
         "total": "1",
         "processed": 1
       }
     }
  },
  "situationSummary": {
     "UNASSIGNED": 2,
     "TARGET_IGNORED": 0,
     "SOURCE_IGNORED": 0,
     "MISSING": 0,
     "FOUND": 0,
     "AMBIGUOUS": 0,
     "UNQUALIFIED": 0,
     "CONFIRMED": 1,
     "SOURCE_MISSING": 0,
     "ABSENT": 0
  },
  "started": "2014-03-06T07:00:31.907Z"
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon/0890ad62-4738-4a3f-8b8e-f3c83bbf212e?_action=cancel"

{
     "status":"SUCCESS",
     "action":"cancel",
     "_id":"0890ad62-4738-4a3f-8b8e-f3c83bbf212e"
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/recon"
    

{
   "reconciliations": [
     {
       "ended": "2014-03-06T06:14:11.845Z",
       "_id": "4286510e-986a-4521-bfa4-8cd1e039a7f5",
       "mapping": "systemLdapAccounts_managedUser",
       "state": "SUCCESS",
       "stage": "COMPLETED_SUCCESS",
       "stageDescription": "reconciliation completed.",
       "progress": {
         "links": {
           "created": 1,
           "existing": {
           "total": "0",
           "processed": 0
         }
       },
       "target": {
         "created": 1,
         "existing": {
           "total": "2",
           "processed": 2
         }
       },
       "source": {
         "existing": {
           "total": "1",
           "processed": 1
         }
       }
     },
     "situationSummary": {
       "UNASSIGNED": 2,
       "TARGET_IGNORED": 0,
       "SOURCE_IGNORED": 0,
       "MISSING": 0,
       "FOUND": 0,
       "AMBIGUOUS": 0,
       "UNQUALIFIED": 0,
       "CONFIRMED": 0,
       "SOURCE_MISSING": 0,
       "ABSENT": 1
     },
     "started": "2014-03-06T06:14:04.722Z"
   },
 ]
}

{
    "_rev": "4",
    "_id": "SYSTEMLDAPACCOUNT",
    "connectorData": {
        "nativeType": "integer",
        "syncToken": 1
    }
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/system/ldap/account?_action=liveSync&detailedFailure=true"

Every reconciliation operation performs a query on the source, and on the target resource, to determine which records should be reconciled. The default source and target queries are query-all-ids, which means that all records in both the source and the target are considered candidates for that reconciliation operation.

You can restrict reconciliation to specific entries by defining explicit source or target queries in the mapping configuration.

For example, to restrict reconciliation to only those records whose employeeType on the source resource is Permanent, you might specify a source query as follows:

"mappings" : [
     {
         "name" : "managedUser_systemLdapAccounts",
         "source" : "managed/user",
         "target" : "system/ldap/account",
         "sourceQuery" : : {
                "queryFilter" : "employeeType eq \"Permanent\""
            },
...
  

The format of the query can be any query type that is supported by the resource, and can include additional parameters, if applicable. OpenIDM 3.0.0 supports the following query types.

The source and target queries send the query to the resource that is defined for that source or target, by default. You can override the resource to which the query is sent by specifying a resourceName in the query. For example, to query a specific endpoint instead of the source resource, you might modify the preceding source query as follows:

"mappings" : [
    {
        "name" : "managedUser_systemLdapAccounts",
        "source" : "managed/user",
        "target" : "system/ldap/account",
        "sourceQuery" : {
            "resourceName" : "endpoint/scriptedQuery"
            "queryFilter" : "employeeType eq \"Permanent\""
        },
...
  

To override a source or target query that is defined in the mapping, you can specify the query when you call the reconciliation operation. For example, if you wanted to reconcile all employee entries, and not just the permanent employees, you would run the reconciliation operation as follows:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{"sourceQuery": {"_queryId" : "query-all-ids"}}' \
 "https://localhost:8443/openidm/recon?_action=recon&mapping=managedUser_systemLdapAccounts"

By default, a reconciliation operation runs both the source and target phase, that is both the source and the target resources are queried. To specify that either the source or target resource is not queried, set runSourcePhase or runTargetPhase to false in the mapping configuration (conf/sync.json file). For example, to prevent the target resource from being queried during the reconciliation operation configured in the previous example, you would amend the mapping configuration as follows:

{
    "mappings" : [
        {
            "name" : "systemLdapAccounts_managedUser",
            "source" : "system/ldap/account",
            "target" : "managed/user",
            "sourceQuery" : {
                "queryFilter" : "employeeType eq \"Permanent\""
            },
            "runTargetPhase" : false,
   ...
  

In the same way that you can restrict reconciliation operations to specific records by using queries, you can specify an ID to restrict a reconciliation operation to a particular record.

To restrict reconciliation to a specific ID, use the reconById action, instead of the recon action when you call the reconciliation operation. Specify the ID with the ids parameter. Currently reconciling more than one ID with the reconById action is not supported.

The following example is based on the data from Sample 2b, which maps an LDAP server with the OpenIDM repository. The example reconciles only the user bjensen, using the managedUser_systemLdapAccounts mapping to update the user account in LDAP with the data from the OpenIDM repository. The _id for bjensen in this example is b3c2f414-e7b3-46aa-8ce6-f4ab1e89288c. The example assumes that automatic synchronization has been disabled and that a reconciliation operation is required to copy changes made in the repository to the LDAP system.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/recon?_action=reconById&mapping=managedUser_systemLdapAccounts&ids=b3c2f414-e7b3-46aa-8ce6-f4ab1e89288c"

A reconciliation by ID takes the default reconciliation options that are specified in the mapping, so the source and target queries, and source and target phases described in the previous section apply equally to reconciliation by ID.

Reconciliation operations are logged in the file /path/to/openidm/audit/recon.csv and in the repository. You can read and query the reconciliation audit logs over the REST interface, as outlined in the following examples.

By default all audit/recon query responses are formatted based on the entryType of the entry. Fields that are not required for the specific entry type are stripped away from the response. For example, a summary entry would not need to include a null targetObjectId field, as this would not add information to a summary. You can specify that this auto-formatting be disabled and return the full entry for all entry types. To disable entry formatting, include formatted=false as a query parameter in the request.

To return all reconciliation operations logged in the audit log, run a RESTful GET on the audit/recon endpoint. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon"

The following code sample shows an extract of the audit log after the first reconciliation operation in Sample 1.

{
  "entries": [
    {
      "rootActionId": "d0578abf-f38e-4ede-a7dc-5ee9eaa8ce53",
      "messageDetail": null,
      "message": "Reconciliation initiated by openidm-admin",
      "timestamp": "2013-05-08T07:58:33.296Z",
      "reconId": "5cf09dfa-e85c-4d52-ab6c-8ba7c2e3d34f",
      "entryType": "start",
      "_id": "11381e20-3679-469d-a71c-c557c2bd091e",
      "status": "SUCCESS",
      "exception": "",
      "mapping": "systemXmlfileAccounts_managedUser"
    },
    {
      "messageDetail": null,
      "rootActionId": "d0578abf-f38e-4ede-a7dc-5ee9eaa8ce53",
      "situation": "ABSENT",
      "actionId": "86995423-8a43-4fc7-9c3c-9e450e0234cb",
      "targetObjectId": "managed/user/scarter",
      "action": "CREATE",
      "entryType": "",
      "_id": "9f59bb8a-31c6-41af-8f27-02094391ba0c",
      "reconId": "5cf09dfa-e85c-4d52-ab6c-8ba7c2e3d34f",
      "status": "SUCCESS",
      "exception": "",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "timestamp": "2013-05-08T07:58:33.791Z",
      "message": null,
      "sourceObjectId": "system/xmlfile/account/scarter"
    },
    {
      "messageDetail": null,
      "rootActionId": "d0578abf-f38e-4ede-a7dc-5ee9eaa8ce53",
      "situation": "ABSENT",
      "actionId": "dea9b5c5-7a75-4cab-b8e4-176bea0a94a6",
      "targetObjectId": "managed/user/bjensen",
      "action": "CREATE",
      "entryType": "",
      "_id": "4fd285ef-a409-4875-abd0-5d70965fe172",
      "reconId": "5cf09dfa-e85c-4d52-ab6c-8ba7c2e3d34f",
      "status": "SUCCESS",
      "exception": "",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "timestamp": "2013-05-08T07:58:33.793Z",
      "message": null,
      "sourceObjectId": "system/xmlfile/account/bjensen"
      },
      {
        "rootActionId": "d0578abf-f38e-4ede-a7dc-5ee9eaa8ce53",
        "messageDetail": {
          "ended": "2013-05-08T07:58:33.813Z",
          "started": "2013-05-08T07:58:33.294Z",
          "situationSummary": {
            "SOURCE_MISSING": 0,
            "FOUND": 0,
            "SOURCE_IGNORED": 0,
            "UNQUALIFIED": 0,
            "UNASSIGNED": 0,
            "TARGET_IGNORED": 0,
            "CONFIRMED": 0,
            "AMBIGUOUS": 0,
            "ABSENT": 2,
            "MISSING": 0
          },
          "progress": {
            "links": {
              "created": 2,
              "existing": {
                "total": "0",
                "processed": 0
              }
            },
            "target": {
              "created": 2,
              "existing": {
                "total": "0",
                "processed": 0
              }
            },
            "source": {
              "existing": {
                "total": "2",
                "processed": 2
              }
            }
          },
          "stageDescription": "reconciling target entries",
          "stage": "ACTIVE_RECONCILING_TARGET",
          "state": "ACTIVE",
          "mapping": "systemXmlfileAccounts_managedUser"
        },
        "message": "SOURCE_IGNORED: 0 MISSING: 0 FOUND: 0 AMBIGUOUS: 0 UNQUALIFIED: 0
           CONFIRMED: 0 SOURCE_MISSING: 0 ABSENT: 2 TARGET_IGNORED: 0 UNASSIGNED: 0 ",
        "timestamp": "2013-05-08T07:58:33.813Z",
        "reconId": "5cf09dfa-e85c-4d52-ab6c-8ba7c2e3d34f",
        "entryType": "summary",
        "_id": "a8a81f9f-fa8f-49f4-a0d6-c88b5fc4be2a",
        "status": "SUCCESS",
        "exception": "",
        "mapping": "systemXmlfileAccounts_managedUser"
      }
    ]
}    

Most of the fields in this audit log are self-explanatory. Each distinct reconciliation operation is identified by its reconId. Each entry in the log is identified by a unique _id. The first log entry indicates the status for the complete reconciliation operation. Successive entries indicate the status for each record affected by the reconciliation.

To obtain information on a specific audit log entry, include its entry _id in the URL. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon/9f59bb8a-31c6-41af-8f27-02094391ba0c"

The following sample output shows the results of a read operation on a specific reconciliation audit entry.

{
 "targetObjectId": "managed/user/5b9b75e8-2667-4040-a50d-7a644922f072",
 "sourceObjectId": "system/ldap/account/uid=jdoe,ou=People,dc=example,dc=com",
 "situation": "CONFIRMED",
 "reconciling": "source",
 "ambiguousTargetObjectIds": "",
 "action": "UPDATE",
 "actionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
 "exception": "",
 "_id": "88802a56-8be9-43bf-aaf9-d861820f3e39",
 "entryType": "",
 "timestamp": "2014-03-06T06:59:14.637Z",
 "reconId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
 "rootActionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
 "status": "SUCCESS",
 "message": null,
 "messageDetail": null
}   

To query the audit log for a particular reconciliation operation, use the audit-by-recon-id keyword, specifying the reconciliation ID, as follows:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon?_queryId=audit-by-recon-id&reconId=<reconID>"

Output similar to the following is returned, for the specified reconciliation operation:

{
 "remainingPagedResults": -1,
 "pagedResultsCookie": null,
 "resultCount": 5,
 "result": [
   {
     "mapping": "systemLdapAccounts_managedUser",
     "exception": "",
     "_id": "e8932aef-31ad-43e8-ab5a-c997b247ab9d",
     "entryType": "summary",
     "timestamp": "2014-03-06T06:59:14.691Z",
     "reconId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
     "rootActionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
     "status": "SUCCESS",
     "message": "SOURCE_IGNORED: 0 MISSING: 0 FOUND: 0 AMBIGUOUS: 0 UNQUALIFIED: 0
         CONFIRMED: 1 SOURCE_MISSING: 0 ABSENT: 0 TARGET_IGNORED: 0 UNASSIGNED: 2 ",
     "messageDetail": {
       "stage": "ACTIVE_RECONCILING_TARGET",
       "stageDescription": "reconciling target entries",
       "ended": "2014-03-06T06:59:14.691Z",
       "started": "2014-03-06T06:59:14.353Z",
       "mapping": "systemLdapAccounts_managedUser",
       "state": "ACTIVE",
       "situationSummary": {
         "SOURCE_MISSING": 0,
         "FOUND": 0,
         "SOURCE_IGNORED": 0,
         "UNQUALIFIED": 0,
         "UNASSIGNED": 2,
         "TARGET_IGNORED": 0,
         "CONFIRMED": 1,
         "AMBIGUOUS": 0,
         "ABSENT": 0,
         "MISSING": 0
       },
       "progress": {
         "links": {
           "created": 0,
           "existing": {
             "processed": 1,
             "total": "1"
           }
         },
       "source": {
         "existing": {
           "processed": 1,
           "total": "1"
         }
       },
       "target": {
         "created": 0,
         "existing": {
           "processed": 3,
           "total": "3"
         }
       }
     }
   }
 },
 {
   "targetObjectId": "managed/user/e8b93d84-5295-4286-b951-cea07550a331",
   "sourceObjectId": null,
   "situation": "UNASSIGNED",
   "reconciling": "target",
   "ambiguousTargetObjectIds": null,
   "action": "IGNORE",
   "actionId": null,
   "exception": "",
   "_id": "7878e924-0aa6-46a9-8d42-716eae098121",
   "entryType": "",
   "timestamp": "2014-03-06T06:59:14.674Z",
   "reconId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "rootActionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "status": "SUCCESS",
   "message": null,
   "messageDetail": null
 },
 {
   "targetObjectId": "managed/user/0e4cfe5e-3d9d-4d74-acf4-596f610eda5a",
   "sourceObjectId": null,
   "situation": "UNASSIGNED",
   "reconciling": "target",
   "ambiguousTargetObjectIds": null,
   "action": "IGNORE",
   "actionId": null,
   "exception": "",
   "_id": "795d1616-9ec7-44c7-80f5-bc7c566bd2fe",
   "entryType": "",
   "timestamp": "2014-03-06T06:59:14.653Z",
   "reconId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "rootActionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "status": "SUCCESS",
   "message": null,
   "messageDetail": null
 },
 {
   "targetObjectId": "managed/user/5b9b75e8-2667-4040-a50d-7a644922f072",
   "sourceObjectId": "system/ldap/account/uid=jdoe,ou=People,dc=example,dc=com",
   "situation": "CONFIRMED",
   "reconciling": "source",
   "ambiguousTargetObjectIds": "",
   "action": "UPDATE",
   "actionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "exception": "",
   "_id": "88802a56-8be9-43bf-aaf9-d861820f3e39",
   "entryType": "",
   "timestamp": "2014-03-06T06:59:14.637Z",
   "reconId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "rootActionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "status": "SUCCESS",
   "message": null,
   "messageDetail": null
 },
 {
   "mapping": "systemLdapAccounts_managedUser",
   "exception": "",
   "_id": "91c00e7f-1975-4f68-bfba-7740e8f05ec5",
   "entryType": "start",
   "timestamp": "2014-03-06T06:59:14.354Z",
   "reconId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "rootActionId": "a0c8ea66-8798-451d-a55c-9d4b95f0941e",
   "status": "SUCCESS",
   "message": "Reconciliation initiated by openidm-admin",
   "messageDetail": null
 }
]
}

To query the audit log for a specific reconciliation situation, use the audit-by-recon-id-situation keyword, specifying the reconciliation ID and the situation that you want to query. For example, the following query returns all ABSENT records found during the specified reconciliation operation:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/recon?_queryId=audit-by-recon-id-situation&situation=ABSENT&reconId=fd2a59df-1fcd-444d-97ca-2c8a7ec6dc6c"
    

Output similar to the following is returned, with one entry for each record that matches the situation queried:

{
  "result": [
    {
      "messageDetail": null,
      "rootActionId": "3c098d6f-a5e5-483c-a8ce-82911a10b0a9",
      "situation": "ABSENT",
      "actionId": "1a391fe8-201b-4f59-ad05-92ee804488a8",
      "targetObjectId": "managed/user/scarter",
      "action": "CREATE",
      "entryType": "",
      "_id": "6dc0a18a-826d-487d-a29f-5cd8d2f55465",
      "reconId": "1ef8e7b6-33dc-4f92-810a-b51913508a68",
      "status": "SUCCESS",
      "exception": "",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "timestamp": "2013-05-14T08:20:41.763Z",
      "message": null,
      "sourceObjectId": "system/xmlfile/account/scarter"
    },
    {
      "messageDetail": null,
      "rootActionId": "3c098d6f-a5e5-483c-a8ce-82911a10b0a9",
      "situation": "ABSENT",
      "actionId": "0aaba292-1dd3-4e98-a0e2-04bec9ae5209",
      "targetObjectId": "managed/user/bjensen",
      "action": "CREATE",
      "entryType": "",
      "_id": "1cda457e-54e2-451b-8a40-ef93dec7e60c",
      "reconId": "1ef8e7b6-33dc-4f92-810a-b51913508a68",
      "status": "SUCCESS",
      "exception": "",
      "reconciling": "source",
      "ambiguousTargetObjectIds": "",
      "timestamp": "2013-05-14T08:20:41.760Z",
      "message": null,
      "sourceObjectId": "system/xmlfile/account/bjensen"
    }
  ]
}   

The activity logs track all operations on internal (managed) and external (system) objects. Entries in the activity log contain identifiers for the reconciliation or synchronization action that triggered the activity, and for the original caller and the relationships between related actions.

You can access the activity logs over REST with the following call:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/activity"

The following extract of the activity log shows the last entry in the log, which was a password change for user bjensen.

{
   "entries": [
   ...
   },
     "before": null,
     "requester": "openidm-admin",
     "parentActionId": "c2c102bc-7b32-4020-b5aa-9a7d63652cb6",
     "_id": "bbaff1e0-923b-48f0-b053-b1614cbb3647",
     "activityId": "c2c102bc-7b32-4020-b5aa-9a7d63652cb6",
     "timestamp": "2014-03-13T16:20:54.811Z",
     "action": "CREATE",
     "message": "create",
     "objectId": "managed/user/4f2f5eea-918a-4ef1-9244-be41dcf128a4",
     "rev": "1",
     "rootActionId": "c2c102bc-7b32-4020-b5aa-9a7d63652cb6"
   },
   {
     "passwordChanged": true,
     "changedFields": [
     "/password"
   ],
     "status": "SUCCESS",
     "after": {
       "securityAnswer": {
         "$crypto": {
           "value": {
             "key": "openidm-sym-default",
             "iv": "8CvlA6rWN03MAhLSKJmbvw==",
             "cipher": "AES/CBC/PKCS5Padding",
             "data": "oJBTrrX+wFAygFZkLuGPrhB/jAIICcdIBuCX1eEbpS0="
           },
           "type": "x-simple-encryption"
         }
       },
   ...
  

To return activity information for a specific action, include the _id of the action in the endpoint, for example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/activity/22ef6d20-bd84-4267-9db8-745825a46ad1"

Results similar to the following are returned:

{
  "passwordChanged": true,
  "changedFields": [
    "/password"
  ],
  "status": "SUCCESS",
  "after": {
    "securityAnswer": {
      "$crypto": {
      "value": {
        "key": "openidm-sym-default",
        "iv": "HpsyTtTXc2pfNrXlYbro7Q==",
        "cipher": "AES/CBC/PKCS5Padding",
        "data": "0M6O7geNjalJ7e0EGSG9B90eaeF8zJuogdL74hcAIRg="
      },
      "type": "x-simple-encryption"
    }
  },
  "userName": "bjensen@example.com",
  "stateProvince": "",
  "postalAddress": "",
  "effectiveAssignments": {},
  "roles": "openidm-authorized",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "password": {
    "$crypto": {
      "value": {
        "key": "openidm-sym-default",
        "iv": "dkRjURz761HaObBuLl+EkA==",
        "cipher": "AES/CBC/PKCS5Padding",
        "data": "9chNPUlXotHy195ERj6vlg=="
      },
      "type": "x-simple-encryption"
    }
  },
  "effectiveRoles": [
    "openidm-authorized"
  ],
  "givenName": "Barbara",
  "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
  "address2": "",
  "passwordAttempts": "0",
  "sn": "Jensen",
  "mail": "bjensen@example.com",
  "securityQuestion": "1",
  "city": "",
  "country": "",
  "_rev": "7",
  "lastPasswordSet": "",
  "postalCode": "",
  "_id": "bjensen",
  "description": "Created By XML1"
},
  "before": {
  "securityAnswer": "Some security answer",
  "userName": "bjensen@example.com",
  "stateProvince": "",
  "postalAddress": "",
  "roles": "openidm-authorized",
  "telephoneNumber": "1234567",
  "password": {
    "$crypto": {
      "value": {
        "key": "openidm-sym-default",
        "iv": "bqhRyLW1lI+KZROcpgyukg==",
        "cipher": "AES/CBC/PKCS5Padding",
        "data": "qO8A76GqNqftVVwOlasyPw=="
      },
      "type": "x-simple-encryption",
    "securityQuestion": "1",
  "givenName": "Barbara",
  "address2": "",
  "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
  "passwordAttempts": "0",
  "sn": "Jensen",
  "mail": "bjensen@example.com",
  "country": "",
  "city": "",
  "_rev": "7",
  "lastPasswordSet": "",
  "postalCode": "",
  "_id": "bjensen",
  "description": "Created By XML1",
  "accountStatus": "active"
},
"requester": "openidm-admin",
"parentActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
"_id": "ee88adb8-3329-4f81-a8f2-d9c8e0fbf72b",
"activityId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
"timestamp": "2014-03-13T16:21:27.086Z",
"action": "UPDATE",
"message": "update",
"objectId": "managed/user/bjensen",
"rev": "7",
"rootActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5"
}    

Each action in the activity log has a rootActionId and a parentActionId. The rootActionId is the ID that was assigned to the incoming or initiating request. The parentActionId is the ID that is associated with the overall action. So, for example, if an HTTP request invokes a script that changes a user's password, the HTTP request is assigned the rootActionId and the action taken by the script is assigned the parentActionId. You can query the activity log for the details of a specific action by including the parentActionId in the query. For example:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/audit/activity?_queryId=audit-by-activity-parent-action&parentActionId=0aaba292-1dd3-4e98-a0e2-04bec9ae5209"

The following sample output shows the result of a query that requests details of the password change for bjensen.

{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 2,
  "result": [
    {
      "rootActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
      "changedFields": [
        "/password"
    ],
      "action": "UPDATE",
      "objectId": "managed/user/bjensen",
      "before": {
        "securityAnswer": "Some security answer",
        "userName": "bjensen@example.com",
        "stateProvince": "",
        "postalAddress": "",
        "roles": "openidm-authorized",
        "telephoneNumber": "1234567",
        "password": "CAngetin1",
        "securityQuestion": "1",
        "givenName": "Barbara",
        "address2": "",
        "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
        "passwordAttempts": "0",
        "sn": "Jensen",
        "mail": "bjensen@example.com",
        "country": "",
        "city": "",
        "_rev": "7",
        "lastPasswordSet": "",
        "postalCode": "",
        "_id": "bjensen",
        "description": "Created By XML1",
        "accountStatus": "active"
      },
      "status": "SUCCESS",
      "_rev": "1",
      "_id": "ee88adb8-3329-4f81-a8f2-d9c8e0fbf72b",
      "parentActionId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
      "timestamp": "2014-03-13T16:21:27.086Z",
      "message": "update",
      "activityId": "71ddeed8-9006-4578-b869-13e15a3ce6b5",
      "after": {
        "securityAnswer": {
          "$crypto": {
            "value": {
              "key": "openidm-sym-default",
              "iv": "HpsyTtTXc2pfNrXlYbro7Q==",
              "cipher": "AES/CBC/PKCS5Padding",
              "data": "0M6O7geNjalJ7e0EGSG9B90eaeF8zJuogdL74hcAIRg="
            },
            "type": "x-simple-encryption"
          }
        },
        "userName": "bjensen@example.com",
        "stateProvince": "",
        "postalAddress": "",
        "effectiveAssignments": {},
        "roles": "openidm-authorized",
        "telephoneNumber": "1234567",
        "accountStatus": "active",
        "password": {
          "$crypto": {
            "value": {
              "key": "openidm-sym-default",
              "iv": "dkRjURz761HaObBuLl+EkA==",
              "cipher": "AES/CBC/PKCS5Padding",
              "data": "9chNPUlXotHy195ERj6vlg=="
          },
        "type": "x-simple-encryption"
      }
    },
    "effectiveRoles": [
       "openidm-authorized"
    ],
    "givenName": "Barbara",
    "lastPasswordAttempt": "Thu Mar 13 2014 07:23:12 GMT-0800 (GMT-08:00)",
    "address2": "",
    "passwordAttempts": "0",
    "sn": "Jensen",
    "mail": "bjensen@example.com",
    "securityQuestion": "1",
    "city": "",
    "country": "",
    "_rev": "7",
    "lastPasswordSet": "",
    "postalCode": "",
    "_id": "bjensen",
    "description": "Created By XML1"
  },
  "rev": "7",
  "requester": "openidm-admin",
  "passwordChanged": true
  }
 ]
}

For more information about the entries in these logs, see the chapter that covers Using Audit Logs.

OpenIDM enables you to specify what should happen if a LiveSync operation reports a failure for an operation. By configuring the LiveSync retry policy, you can specify how many times a failed modification should be reattempted and what should happen in the event that the modification is unsuccessful after the specified number of attempts. If no retry policy is configured, OpenIDM reattempts the change an infinite number of times, until the change is successful. This behavior can increase data consistency in the case of transient failures (for example, when the connection to the database is temporarily lost). However, in situations where the cause of the failure is permanent (for example, if the change does not meet certain policy requirements) the change will never succeed, regardless of the number of attempts. In this case, the infinite retry behavior can effectively block subsequent LiveSync operations from starting.

Generally, a scheduled reconciliation operation will eventually force consistency. However, to prevent repeated retries that block the LiveSync mechanism, you should restrict the number of times OpenIDM reattempts the same modification. You can then specify what OpenIDM does with failed LiveSync changes. The failed modification can be stored in a "dead letter queue", discarded, or reapplied. Alternatively, an administrator can be notified of the failure by email or by some other means. This behavior can be scripted. The default configuration, in the samples provided with OpenIDM, is to retry a failed modification five times, and then to log and ignore the failure.

The LiveSync retry policy is configured in the connector configuration file (provisioner.openicf-*.json). The sample connector configuration files have a retry policy defined as follows:

"syncFailureHandler" : {
  "maxRetries" : 5,
  "postRetryAction" : "logged-ignore"
},
   

The maxRetries field specifies the number of attempts that OpenIDM should make to process the failed modification. The value of this property must be a positive integer, or -1. A value of zero indicates that failed modifications should not be reattempted. In this case, the post retry action is executed immediately when a LiveSync operation fails. A value of -1 (or omitting the maxRetries property, or the entire syncFailureHandler from the configuration) indicates that failed modifications should be retried an infinite number of times. In this case, no post retry action is executed.

The default retry policy relies on the scheduler, or whatever invokes the LiveSync operation. Therefore, if retries are enabled and a LiveSync modification fails, OpenIDM will retry the modification the next time that LiveSync is invoked.

The postRetryAction field indicates what action OpenIDM should take in the event that the maximum number of retries has been reached (or if maxRetries has been set to zero). The post retry action can be one of the following:

The following sample provisioner configuration file extract shows a LiveSync retry policy that specifies a maximum of four retries before the failed modification is sent to the dead letter queue.

...
"connectorName" : "org.identityconnectors.ldap.LdapConnector"
    },
    "syncFailureHandler" : {
        "maxRetries" : 4,
        "postRetryAction" : dead-letter-queue
    },
    "poolConfigOption" : {
...
    

In the case of a failed modification, a message similar to the following is output to the log file:

INFO: sync retries = 1/4, retrying

OpenIDM reattempts the modification, the specified number of times. If the modification is still unsuccessful, a message similar to the following is logged:

INFO: sync retries = 4/4, retries exhausted
Jul 19, 2013 11:59:30 AM
    org.forgerock.openidm.provisioner.openicf.syncfailure.DeadLetterQueueHandler invoke
INFO: uid=jdoe,ou=people,dc=example,dc=com saved to dead letter queue
    

The log message indicates the entry for which the modification failed (uid=jdoe, in this example).

You can view the failed modification in the dead letter queue, over the REST interface, as follows:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/repo/synchronisation/deadLetterQueue/ldap?_queryId=query-all-ids"
     {
       "query-time-ms": 2,
       "result":
       [
           {
               "_id": "4",
               "_rev": "0"
           }
       ],
       "conversion-time-ms": 0
    }

To view the details of a specific failed modification, include its ID in the URL:

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/repo/synchronisation/deadLetterQueue/ldap/4"
     {
  "objectType": "account",
  "systemIdentifier": "ldap",
  "failureCause": "org.forgerock.openidm.sync.SynchronizationException:
            org.forgerock.openidm.objset.ConflictException:
            org.forgerock.openidm.sync.SynchronizationException:
            org.forgerock.openidm.script.ScriptException:
            ReferenceError: \"bad\" is not defined.
            (PropertyMapping/mappings/0/properties/3/condition#1)",
  "token": 4,
  "failedRecord": "complete record, in xml format"
  "uid": "uid=jdoe,ou=people,dc=example,dc=com",
  "_rev": "0",
  "_id": "4"
}   

During synchronization, OpenIDM categorizes objects according to their situation. Situations are characterized by whether an object exists on a source or target system, whether OpenIDM has registered a link between the source object and the target object, and whether the object is considered valid, as assessed by the validSource and validTarget scripts. OpenIDM then takes a specific action, depending on the situation.

You can define actions for particular situations in the policies section of a synchronization mapping, as shown in the following excerpt.

{
    "policies": [
        {
            "situation": "CONFIRMED",
            "action": "UPDATE"
        },
        {
            "situation": "FOUND",
            "action": "UPDATE"
        },
        {
            "situation": "ABSENT",
            "action": "CREATE"
        },
        {
            "situation": "AMBIGUOUS",
            "action": "EXCEPTION"
        },
        {
            "situation": "MISSING",
            "action": "EXCEPTION"
        },
        {
            "situation": "UNQUALIFIED",
            "action": "DELETE"
        },
        {
            "situation": "UNASSIGNED",
            "action": "EXCEPTION"
        }
    ]
}

If you do not define a policy for a particular situation, OpenIDM takes the default action for the situation.

The following sections describe the possible situations and their default corresponding actions.

{
    "situation" : "ABSENT",
    "action" : {
        "workflowName" : "managedUserApproval",
        "type" : "text/javascript",
        "file" : "workflow/triggerWorkflowFromSync.js"
    }
}
   

Reconciliation can work in tandem with workflows to provide additional business logic to the reconciliation process. You can define scripts to determine the action that should be taken for a particular reconciliation situation. A reconciliation process can launch a workflow after it has assessed a situation, and then perform the reconciliation, or some other action.

For example, you might want a reconciliation process to assess new user accounts that need to be created on a target resource. However, new user account creation might require some kind of approval from a manager before the accounts are actually created. The initial reconciliation process can assess the accounts that need to be created, launch a workflow to request management approval for those accounts, and then relaunch the reconciliation process to create the accounts, once the management approval has been received.

In this scenario, the defined script returns IGNORE for new accounts and the reconciliation engine does not continue processing the given object. The script then initiates an asynchronous process which calls back and completes the reconciliation process at a later stage.

A sample configuration for this scenario is available in openidm/samples/sample9, and described in Sample 9 - Asynchronous Reconciliation Using Workflows in the Installation Guide in the Installation Guide.

By default, OpenIDM is case-sensitive, which means that case is taken into account when comparing IDs during reconciliation. For data stores that are case-insensitive, such as OpenDJ, IDs and links that are created by a reconciliation process may be stored with a different case to the way in which they are stored in the OpenIDM repository. Such a situation can cause problems during a reconciliation operation, as the links for these IDs may not match.

For such data stores, you can configure OpenIDM to ignore case during reconciliation operations. With case sensitivity turned off in OpenIDM, for those specific mappings, comparisons are done without regard to case.

To specify that data stores are not case-sensitive, set the "sourceIdsCaseSensitive" or "targetIdsCaseSensitive" property to false in the mapping for those links. For example, if the LDAP data store is case-insensitive, set the mapping from the LDAP store to the managed user repository as follows:

"mappings" : [
{
"name" : "systemLdapAccounts_managedUser",
"source" : "system/ldap/account",
"sourceIdsCaseSensitive" : false,
"target" : "managed/user",
"properties" : [
...
   

If a mapping inherits links by using the "links" property, it is not necessary to set case sensitivity, because the mapping uses the setting of the referred links.

Note that configuring OpenIDM to be case-insensitive when comparing links does not make the OpenICF provisioner case-insensitive when it requests data. For example, if a user entry is stored with the ID testuser and you make a request for https://localhost:8443/openidm/managed/TESTuser, most provisioners will filter out the match because of the difference in case, and will indicate that the record is not found. To prevent the provisioner from performing this secondary filtering, set the enableFilteredResultsHandler property to false in the provisioner configuration. For example:

"resultsHandlerConfig" :
{
    "enableFilteredResultsHandler":false,
}, 

By default, reconciliation is configured to function in an optimized way. Some of these optimizations might, however, be unsuitable for your environment. The following sections describe the optimizations and how they can be configured.

{
    "mappings": [
        {
            "name"                     : "systemMyLDAPAccounts_managedUser",
            "source"                   : "system/MyLDAP/account",
            "target"                   : "managed/user",
            "correlateEmptyTargetSet"  : true
        },
    ]
}

{
    "mappings": [
        {
            "name": "systemMyLDAPAccounts_managedUser",
            "source": "system/MyLDAP/account",
            "target": "managed/user"
            "prefetchLinks" : false
        }
    ]
}

    "mappings" : [
        {
            "name" : "systemXmlfileAccounts_managedUser",
            "source" : "system/xmlfile/account",
            "target" : "managed/user",
            "taskThreads" : 20
            ...
         }
    ]
}

Every time OpenIDM creates an object through synchronization, it creates a link between the source and target objects. OpenIDM then uses the link to determine the object's situation during later synchronization operations.

Initial, bulk synchronization operations can involve correlating many objects that exist both on source and target systems. In this case, OpenIDM uses correlation queries to find target objects that already exist, and that correspond to source objects. For the target objects that match a correlation query, OpenIDM needs only to create a link, rather than a new target object.

Correlation queries run against target resources. The query syntax therefore depends on the target system, and is either specific to the data store underlying the OpenIDM repository, or to OpenICF query capabilities.

"for-userName" : "SELECT * FROM ${unquoted:_resource} WHERE userName = ${uid}"

{
  "correlationQuery": {
    "type": "text/javascript",
    "source":
      "var query = {'_queryId' : 'for-userName', 'uid' : source.name}; query;"
  }
}

var map = {"_queryFilter": 'uid eq "' + source.userName + '"'};
map;
   

Section 11.3, "Basic Data Flow Configuration" shows how to trigger scripts when objects are created and updated. Other situations require you to trigger scripts in response to other synchronization actions. For example, you might not want OpenIDM to delete a managed user directly when an external account is deleted, but instead unlink the objects and deactivate the user in another resource. (Alternatively, you might delete the object in OpenIDM but nevertheless execute a script.) The following example shows a more advanced mapping configuration.

{
    "mappings": [
        {
            "name": "systemLdapAccount_managedUser",
            "source": "system/ldap/account",
            "target": "managed/user",
            "validSource": {
                "type": "text/javascript",
                "file": "script/isValid.js"
            },
            "correlationQuery" : {
                "type" : "text/javascript",
                "source" : "var map = {'_queryFilter': 'uid eq \"' +
                     source.userName + '\"'}; map;"
            },
            "properties": [
                {
                    "source": "uid",
                    "transform": {
                        "type": "text/javascript",
                        "source": "source.toLowerCase()"
                    },
                    "target": "userName"
                },
                {
                    "source": "",
                    "transform": {
                        "type": "text/javascript",
                        "source": "if (source.myGivenName)
                            {source.myGivenName;} else {source.givenName;}"
                    },
                    "target": "givenName"
                },
                {
                    "source": "",
                    "transform": {
                        "type": "text/javascript",
                        "source": "if (source.mySn)
                            {source.mySn;} else {source.sn;}"
                    },
                    "target": "familyName"
                },
                {
                    "source": "cn",
                    "target": "fullname"
                },
                {
                    "comment": "Multi-valued in LDAP, single-valued in AD.
                        Retrieve first non-empty value.",
                    "source": "title",
                    "transform": {
                        "type": "text/javascript",
                        "file": "script/getFirstNonEmpty.js"
                    },
                    "target": "title"
                },
                {
                    "condition": {
                        "type": "text/javascript",
                        "source": "var clearObj = openidm.decrypt(object);
                            ((clearObj.password != null) &&
                            (clearObj.ldapPassword != clearObj.password))"
                    },
                    "transform": {
                        "type": "text/javascript",
                        "source": "source.password"
                    },
                    "target": "__PASSWORD__"
                }
            ],
            "onCreate": {
                "type": "text/javascript",
                "source": "target.ldapPassword = null;
                    target.adPassword = null;
                    target.password = null;
                    target.ldapStatus = 'New Account'"
            },
            "onUpdate": {
                "type": "text/javascript",
                "source": "target.ldapStatus = 'OLD'"
            },
            "onUnlink": {
                "type": "text/javascript",
                "file": "script/triggerAdDisable.js"
            },
            "policies": [
                {
                    "situation": "CONFIRMED",
                    "action": "UPDATE"
                },
                {
                    "situation": "FOUND",
                    "action": "UPDATE"
                },
                {
                    "situation": "ABSENT",
                    "action": "CREATE"
                },
                {
                    "situation": "AMBIGUOUS",
                    "action": "EXCEPTION"
                },
                {
                    "situation": "MISSING",
                    "action": "EXCEPTION"
                },
                {
                    "situation": "UNQUALIFIED",
                    "action": "UNLINK"
                },
                {
                    "situation": "UNASSIGNED",
                    "action": "EXCEPTION"
                }
            ]
        }
    ]
}

Your scripts can get data from any connected system at any time by using the openidm.read(id) function, where id is the identifier of the object to read.

The following example reads a managed user object from the repository.

repoUser = openidm.read("managed/user/ddoe");

The following example reads an account from an external LDAP resource.

externalAccount = openidm.read("system/ldap/account/uid=ddoe,ou=People,dc=example,dc=com");

Note that the query targets a DN rather than a UID, as it did in the previous example. The attribute that is used for the _id is defined in the connector configuration file and, in this example, is set to "uidAttribute" : "dn". Although it is possible to use a DN (or any unique attribute) for the _id, as a best practice, you should use an attribute that is both unique and immutable.

You can schedule synchronization operations, such as LiveSync and reconciliation, using cron-like syntax.

This section describes scheduling for reconciliation and LiveSync, however, you can also use OpenIDM's scheduler service to schedule any other event by supplying a link to a script file, in which that event is defined. For information about scheduling other events, and for a deeper understanding of the OpenIDM scheduler service, see Scheduling Tasks and Events.

{
 "enabled"       : true,
 "persisted"     : false,
 "type"          : "cron",
 "startTime"     : "(optional) time",
 "endTime"       : "(optional) time",
 "schedule"      : "cron expression",
 "misfirePolicy" : "optional, string",
 "timeZone"      : "(optional) time zone",
 "invokeService" : "service identifier",
 "invokeContext" : "service specific context info"
}
   

{
    "invokeService": "sync",
    "invokeContext": {
        "action": "reconcile",
        "mapping": "systemLdapAccount_managedUser"
    }
}
   

{
    "invokeService": "provisioner",
    "invokeContext": {
        "action": "liveSync",
        "source": "system/OpenDJ/__ACCOUNT__"
    }
}
   

{
    "enabled": true,
    "type": "cron",
    "schedule": "0 08 16 * * ?",
    "invokeService": "sync",
    "invokeContext": {
        "action": "reconcile",
        "mapping": {
            "name": "CSV_XML",
            "source": "system/Ldap/account",
            "target": "managed/user",
            "properties": [
                {
                    "source": "firstname",
                    "target": "firstname"
                },
                ...
            ],
            "policies": [...]
        }
    }
}
   

In the boot properties configuration file (openidm/conf/boot/boot.properties), the instance type is standalone and persistent schedules are enabled by default:

# valid instance types for node include standalone, clustered-first, and clustered-additional
openidm.instance.type=standalone

# enables the execution of persistent schedulers
openidm.scheduler.execute.persistent.schedules=true
  

The scheduler service configuration file (openidm/conf/scheduler.json) governs the configuration for a specific scheduler instance, and has the following format:

{
 "threadPool" : {
     "threadCount" : "10"
 },
 "scheduler" : {
     "executePersistentSchedules" : "&{openidm.scheduler.execute.persistent.schedules}"
 }
}
  

For details of all the configurable properties for the Quartz Scheduler, see the Quartz Scheduler Configuration Reference.

Each schedule configuration file, openidm/conf/schedule- schedule-name.json has the following format:

{
 "enabled"             : true,
 "persisted"           : false,
 "concurrentExecution" : false,
 "type"                : "cron",
 "startTime"           : "(optional) time",
 "endTime"             : "(optional) time",
 "schedule"            : "cron expression",
 "misfirePolicy"       : "optional, string",
 "timeZone"            : "(optional) time zone",
 "invokeService"       : "service identifier",
 "invokeContext"       : "service specific context info",
 "invokeLogLevel"      : "(optional) debug"
}

By default, scheduling information, such as schedule state and details of the schedule execution, is stored in RAM. This means that such information is lost when OpenIDM is rebooted. The schedule configuration itself (defined in the openidm/conf/schedule- schedule-name.json file) is not lost when OpenIDM is shut down, and normal scheduling continues when the server is restarted. However, there are no details of missed schedule executions that should have occurred during the period the server was unavailable.

You can configure schedules to be persistent, which means that the scheduling information is stored in the internal repository rather than in RAM. With persistent schedules, scheduling information is retained when OpenIDM is shut down. Any previously scheduled jobs can be rescheduled automatically when OpenIDM is restarted.

Persistent schedules also enable you to manage scheduling across a cluster (multiple OpenIDM instances). When scheduling is persistent, a particular schedule will be executed only once across the cluster, rather than once on every OpenIDM instance. For example, if your deployment includes a cluster of OpenIDM nodes for high availability, you can use persistent scheduling to start a reconciliation action on only one node in the cluster, instead of starting several competing reconciliation actions on each node.

You can use persistent schedules with the default OrientDB repository, or with the MySQL repository (see Installing a Repository For Production in the Installation Guide).

To configure persistent schedules, set the "persisted" property to true in the schedule configuration file (schedule-schedule-name.json).

If OpenIDM is down when a scheduled task was set to occur, one or more executions of that schedule might be missed. To specify what action should be taken if schedules are missed, set the misfirePolicy in the schedule configuration file. The misfirePolicy determines what OpenIDM should do if scheduled tasks are missed. Possible values are as follows:

The following example shows a schedule for reconciliation that is not enabled. When enabled ("enabled" : true,), reconciliation runs every 30 minutes, starting on the hour.

{
    "enabled": false,
    "persisted": false,
    "type": "cron",
    "schedule": "0 0/30 * * * ?",
    "invokeService": "sync",
    "invokeContext": {
        "action": "reconcile",
        "mapping": "systemLdapAccounts_managedUser"
    }
}

The following example shows a schedule for LiveSync enabled to run every 15 seconds, starting at the beginning of the minute. The schedule is persisted, that is, stored in the internal repository rather than in memory. If one or more LiveSync executions are missed, as a result of OpenIDM being unavailable, the first execution of the LiveSync action is executed when the server is back online. Subsequent executions are discarded. After this, the normal schedule is resumed.

{
    "enabled": false,
    "persisted": true,
    "misfirePolicy" : "fireAndProceed",
    "type": "cron",
    "schedule": "0/15 * * * * ?",
    "invokeService": "provisioner",
    "invokeContext": {
        "action": "liveSync",
        "source": "system/ldap/account"
    }
}

OpenIDM exposes the scheduler service under the /openidm/scheduler context path. The following examples show how schedules can be created, read, updated, and deleted, over REST, like any other object.

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request PUT \
 --data '{
    "enabled":true,
    "type":"cron",
    "schedule":"0/1 * * * * ?",
    "persisted":true,
    "misfirePolicy":"fireAndProceed",
    "invokeService":"script",
    "invokeContext": {
        "script": {
            "type":"text/javascript",
            "file":"script/testlog.js"
        }
    }
 }' \
 "https://localhost:8443/openidm/scheduler/testlog-schedule"
{
  "type": "cron",
  "invokeService": "script",
  "persisted": true,
  "_id": "testlog-schedule",
  "schedule": "0/1 * * * * ?",
  "misfirePolicy": "fireAndProceed",
  "enabled": true,
  "invokeContext": {
    "script": {
      "file": "script/testlog.js",
      "type": "text/javascript"
    }
  }
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 --data '{
    "enabled":true,
    "type":"cron",
    "schedule":"0/1 * * * * ?",
    "persisted":true,
    "misfirePolicy":"fireAndProceed",
    "invokeService":"script",
    "invokeContext": {
        "script": {
            "type":"text/javascript",
            "file":"script/testlog.js"
        }
    }
 }' \
 "https://localhost:8443/openidm/scheduler?_action=create"
{
  "type": "cron",
  "invokeService": "script",
  "persisted": true,
  "_id": "d6d1b256-7e46-486e-af88-169b4b1ad57a",
  "schedule": "0/1 * * * * ?",
  "misfirePolicy": "fireAndProceed",
  "enabled": true,
  "invokeContext": {
    "script": {
      "file": "script/testlog.js",
      "type": "text/javascript"
    }
  }
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/scheduler/d6d1b256-7e46-486e-af88-169b4b1ad57a"
{
  "_id": "d6d1b256-7e46-486e-af88-169b4b1ad57a",
  "schedule": "0/1 * * * * ?",
  "misfirePolicy": "fireAndProceed",
  "startTime": null,
  "invokeContext": {
    "script": {
      "file": "script/testlog.js",
      "type": "text/javascript"
    }
  },
  "enabled": true,
  "concurrentExecution": false,
  "persisted": true,
  "timeZone": null,
  "type": "cron",
  "invokeService": "org.forgerock.openidm.script",
  "endTime": null,
  "invokeLogLevel": "info"
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request PUT \
 --data '{
    "enabled":false,
    "type":"cron",
    "schedule":"0/1 * * * * ?",
    "persisted":true,
    "misfirePolicy":"fireAndProceed",
    "invokeService":"script",
    "invokeContext": {
        "script": {
            "type":"text/javascript",
            "file":"script/testlog.js"
        }
    }
 }' \
 "https://localhost:8443/openidm/scheduler/d6d1b256-7e46-486e-af88-169b4b1ad57a"
   null

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/scheduler?_queryId=query-all-ids"
{
  "remainingPagedResults": -1,
  "pagedResultsCookie": null,
  "resultCount": 2,
  "result": [
    {
      "_id": "d6d1b256-7e46-486e-af88-169b4b1ad57a"
    },
    {
      "_id": "recon"
    }
  ]
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request DELETE \
 "https://localhost:8443/openidm/scheduler/d6d1b256-7e46-486e-af88-169b4b1ad57a"
null

In addition to the fine-grained scheduling facility described previously, OpenIDM provides a task scanning mechanism. The task scanner enables you to perform a batch scan on a specified property in OpenIDM, at a scheduled interval, and then to execute a task when the value of that property matches a specified value.

When the task scanner identifies a condition that should trigger the task, it can invoke a script created specifically to handle the task.

For example, the task scanner can scan all managed/user objects for a "sunset date" and can invoke a script that executes a "sunset task" on the user object when this date is reached.

{
    "enabled" : true,
    "type" : "cron",
    "schedule" : "0 0 * * * ?",
    "concurrentExecution" : false,
    "invokeService" : "taskscanner",
    "invokeContext" : {
        "waitForCompletion" : false,
        "maxRecords" : 2000,
        "numberOfThreads" : 5,
        "scan" : {
            "_queryId" : "scan-tasks",
            "property" : "sunset/date",
            "condition" : {
                "before" : "${Time.now}"
            },
            "taskState" : {
                "started" : "sunset/task-started",
                "completed" : "sunset/task-completed"
            },
            "recovery" : {
                "timeout" : "10m"
            }
        },
        "task" : {
            "script" : {
                "type" : "text/javascript",
                "file" : "script/sunset.js"
            }
        }
    }
}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/taskscanner?_action=execute&name=schedule/taskscan_sunset"
   

{"_id":"edfaf59c-aad1-442a-adf6-3620b24f8385"}

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/taskscanner?_action=execute&name=schedule/taskscan_sunset&waitForCompletion=true"
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Content-Type: application/json" \
 --request POST \
 "https://localhost:8443/openidm/taskscanner/edfaf59c-aad1-442a-adf6-3620b24f8385?_action=cancel"
    

    {"_id":"edfaf59c-aad1-442a-adf6-3620b24f8385",
     "action":"cancel",
     "status":"SUCCESS"}
    

$ curl \
 --cacert self-signed.crt \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "https://localhost:8443/openidm/taskscanner"
    

{
 "tasks": [
    {
      "ended": 1352455546182
      "started": 1352455546149,
      "progress": {
        "failures": 0
        "successes": 2400,
        "total": 2400,
        "processed": 2400,
        "state": "COMPLETED",
      },
      "_id": "edfaf59c-aad1-442a-adf6-3620b24f8385",
    }
  ]
}
    

A password policy is a set of rules defining what sequence of characters constitutes an acceptable password. Acceptable passwords generally are too complex for users or automated programs to generate or guess.

Password policies set requirements for password length, character sets that passwords must contain, dictionary words and other values that passwords must not contain. Password policies also require that users not reuse old passwords, and that users change their passwords on a regular basis.

OpenIDM enforces password policy rules as part of the general policy service. For more information about the policy service, see Using Policies to Validate Data. The default password policy applies the following rules to passwords as they are created and updated:

You can remove these validation requirements, or include additional requirements, by configuring the policy for passwords. For more information, see Configuring the Default Policy.

Password synchronization intercepts user password changes, and ensures uniform password changes across resources that store the password. Following password synchronization, the user authenticates using the same password on each resource. No centralized directory or authentication server is required for performing authentication. Password synchronization reduces the number of passwords users need to remember, so they can use fewer, stronger passwords.

OpenIDM can propagate passwords to the resources that store a user's password, and can intercept and synchronize passwords that are changed natively in OpenDJ and Active Directory.

When you use password synchronization, set up password policy enforcement on OpenDJ or Active Directory rather than on OpenIDM. Alternatively, ensure that all password policies that are enforced are identical to prevent password updates on one resource from being rejected by OpenIDM or by another resource.

The password synchronization plugins intercept password changes on the resource before the passwords are stored in encrypted form. The plugins then send intercepted password values to OpenIDM over an encrypted channel.

In the event that the OpenIDM instance is unavailable when a password is changed, the plugin intercepts the change, encrypts the password, and stores the encrypted password in a JSON file. The plugin then checks whether the OpenIDM instance is available, at a predefined interval. When OpenIDM becomes available, the plugin performs a PATCH on the user record, to replace the password with the encrypted password stored in the JSON file.

To be able to synchronize the passwords, the plugin requires that the managed/user object exist in the OpenIDM repository. Users have typically been created by a reconciliation or liveSync process.

The OpenDJ password sync plugin is supported for OpenDJ versions 2.4.6, 2.5, and 2.6. The Active Directory password sync plugin is supported on Windows 2008 RC 2, Active Directory version 47.

The sample provided in /path/to/openidm/samples/misc/managed.json shows password synchronization between three systems - OpenIDM, OpenDJ, and Active Directory. The sample assumes that the following steps have been performed:

While OpenIDM authenticates internal and managed users with the DELEGATED module, there are differences between these two types of users.

OpenIDM does not allow access to the REST interface without authentication.

User self-registration requires anonymous access. For that purpose, OpenIDM includes an anonymous user, with the following password: anonymous. For more information, see Section 14.1.1, "Internal Users".

In production, only applications are expected to access the REST interface.

For more information about the OpenIDM authentication mechanism, see Use Message Level Security.

You can change the attributes used by OpenIDM to store user login and password values. Attribute names are shown in a database query listed in openidm/conf/repo.repo-type.json.

The openidm/conf/authentication.json file defines the active query with the queryId property. In the following example, credential-query is the queryId identifier used in a queryRequest to validate credentials.

{
    "queryId" : "credential-query",
    "queryOnResource" : "managed/user",
...
}

You can explicitly define the properties that constitute passwords or roles with the propertyMapping object in the conf/authentication.json file. The default property mapping is shown here:

 ...
    "propertyMapping" : {
        "authenticationId" : "username",
        "userCredential" : "password",
        "userRoles" : "roles"
    },
 ... 
 

In addition to the internal and managed user authentication modules, OpenIDM 3.0.0 supports a delegated authentication mechanism. With delegated authentication, the username and password included with the REST request are validated against those stored in a remote system, such as an LDAP server.

Delegated authentication for OpenIDM 3.0.0 includes the functionality associated with the PASSTHROUGH, MANAGED_USER, and INTERNAL_USER modules. OpenIDM 3.0.0 includes those modules as aliases for the DELEGATED module.

The samples listed in the OpenIDM Installation Guide in the Installation Guide include multiple options for authentication mechanisms.

You can add the delegated authentication module to the conf/authentication.json file. For example, the following excerpt illustrates one way to implement the DELEGATED configuration object. For descriptive purposes, you can substitute the PASSTHROUGH alias for DELEGATED.

"authModules" : [
   {
      "name" : "DELEGATED",
      "properties" : {
         "augmentSecurityContext": {
            "type" : "text/javascript",
            "file" : "auth/populateAsManagedUser.js"
         },
         "queryOnResource" : "system/ldap/account",
         "propertyMapping" : {
            "authenticationId" : "uid",
            "groupMembership" : "memberOf"
         },
         "groupRoleMapping" : {
            "openidm-admin" : ["cn=admins"]
         },
         "managedUserLink" : "systemLdapAccounts_managedUser",
         "defaultUserRoles" : [
            "openidm-authorized"
         ]
      },
      "enabled" : true
   },
   ...
]
  

The properties shown from this excerpt are defined in Section 14.6.3, "Properties for Authentication and Roles"