Connectors in IDM

This book provides information on the connectors available in IDM, including known issues (with solutions).


Remote Connector Server


How do I upgrade the Remote Connector Server (RCS) for Identity Cloud and IDM?

The purpose of this article is to provide instructions on how to upgrade the RCS for Identity Cloud and IDM.

Upgrading the RCS

You can upgrade the RCS as follows:

  1. Download the new RCS package from BackStage.
  2. Stop the RCS by pressing CTRL + C, or q in the terminal where you started the server.
  3. Rename the existing RCS directory to create a backup, for example:$ mv /path/to/openicf /path/to/openicf_old
  4. Unpack the RCS package you downloaded (you should unpack this to the original directory to keep paths etc the same), for example:$ unzip openicf-zip-1.5.20.0.zip
  5. Copy the following files from your backup to the new RCS directory to retain all your previous settings:
    • conf/ConnectorServer.properties
    • lib/framework/logback.xml (if you have set up the RCS for debug logging)

For example:$ cd /path/to/openicf $ cp /path/to/openicf_old/conf/ConnectorServer.properties conf/ $ cp /path/to/openicf_old/lib/framework/logback.xml lib/framework/

  1. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /run

See Also

Using Checksums

How do I implement a Remote Connector Server (RCS) for Identity Cloud?

Remote Connectors


How do I run a Remote Connector Server (RCS) as a Service?

The purpose of this article is to provide instructions on running the RCS as a service, which allows you to stop and start the RCS using systemd if you are using a Linux® system.

Overview

The following instructions were tested on Ubuntu 20.04 LTS but they should work (with no/minimal changes) on any Linux distribution using systemd.

These instructions assume you have unpacked the RCS package into the /opt directory and left the unpacked directory name unchanged (openicf). If you have any variations to these path locations, you must update the service file accordingly when following the instructions in Step 2.

Configuring RCS as a service

  1. Create a service file (called rcs.service) in the /etc/systemd/system directory, for example:$ sudo vim /etc/systemd/system/rcs.service
  2. Add the following content to this file, update as needed and save: [Unit] SourcePath=/opt/openicf/bin Description=ForgeRock Remote Connector Server (systemd init) After=network.target Conflicts=shutdown.target [Service] Type=simple Restart=always RestartSec=5sec IgnoreSIGPIPE=no KillMode=process Environment="OPENICF_OPTS=-Xmx1024m" ExecStart=/opt/openicf/bin/ConnectorServer.sh /run [Install] WantedBy=multi-user.target
  3. Make the new service launch on startup by running the following command:$ sudo systemctl enable rcs.service
  4. Check the service is enabled:$ systemctl is-enabled rcs.serviceThis command simply returns enabled or disabled as appropriate.

Starting, stopping and restarting the RCS service

Once you have configured RCS as a service and checked it is enabled, you can use the following commands to start, stop and restart the RCS service:

  • Start:$ sudo systemctl start rcs.service
  • Stop:$ sudo systemctl stop rcs.service
  • Restart:$ sudo systemctl restart rcs.service

Checking the service status

You can check that the RCS service has started or stopped as expected using the following command:$ systemctl status rcs.service

This command will return the service state and the first few entries in the log file. For example, the status command’s output will look similar to the following, where systemd messages indicate that the init script has started and the RCS service is running:

● rcs.service - ForgeRock Remote Connector Server (systemd init)   Loaded: loaded (/opt/openicf/bin; enabled; vendor preset: enabled)    Active: active (running) since Mon 2021-03-08 12:45:16 GMT; 22s ago  Main PID: 3080 (java)     Tasks: 35 (limit: 4684)    CGroup: /system.slice/rcs.service            └─3080 java -Xmx512m -server -classpath /opt/openicf/lib/framework/*:/opt/openicf/lib/framework/ org.forgerock.openicf.framework.server.Main -run -properties /opt/openicf/conf/ConnectorServer.properties Mar 08 12:45:29 forgerock-VirtualBox ConnectorServer.sh[3080]: Mar 08, 2021 12:45:29 pm INFO  o.f.o.f.c.ClientRemoteConnectorInfoManager: privateConnections size: 0; privateTCPConnections size 0. Mar 08 12:45:29 forgerock-VirtualBox ConnectorServer.sh[3080]: Mar 08, 2021 12:45:29 pm INFO  o.f.o.f.c.ClientRemoteConnectorInfoManager: Entering connection housekeeping... 0 active WebSocket(s), 2 available permits, 3 permitted permits Mar 08 12:45:29 forgerock-VirtualBox ConnectorServer.sh[3080]: Mar 08, 2021 12:45:29 pm INFO  o.f.o.f.c.ClientRemoteConnectorInfoManager: 0 active WebSocket(s), 2 remaining permits

See Also

How do I implement a Remote Connector Server (RCS) for Identity Cloud?

How do I upgrade the Remote Connector Server (RCS) for Identity Cloud and IDM?

Sync Identities


How do I enable debug logging and log rotation for the Remote Connector Server (RCS)?

The purpose of this article is to provide information on enabling debug logging and log rotation for the Java® RCS.

Overview

By default, logging is not enabled for the Java RCS. Additionally, log files are not set to rotate by default, which means they will grow in size indefinitely when logging is enabled.

If you want to enable logging for the RCS, it is strongly recommended that you also configure the log files to rotate as described in this article.

Debug Logging

You can enable debug logging as follows:

  1. Edit the logback.xml file (which is located in the /path/to/openicf/lib/framework/ directory) and uncomment the following section: <logger name="org.identityconnectors.framework.impl.api.LoggingProxy" level="DEBUG" additivity="false">         <appender-ref ref="TRACE-FILE"/>     </logger>
  2. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /runThe debug logs will be written to the ConnectorServer.log (located in the /path/to/openicf/logs directory).

Rotating Log Files

You can configure the RCS to rotate log files as follows:

  1. Edit the logback.xml file and replace the following section (appender class: ch.qos.logback.core.FileAppender for the ConnectorServer.log file): <appender name="SERVER-FILE" class="ch.qos.logback.core.FileAppender">         <file>logs/ConnectorServer.log</file>         <append>true</append>         <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">             <fileNamePattern>logs/ConnectorServer-%d{yyyyMMdd}.log</fileNamePattern>         </rollingPolicy>         <encoder>             <pattern>%date{"MMM dd, yyyy h:mm:ss a"} %-5level %logger{35}: %msg %n</pattern>         </encoder>     </appender>With this section:<appender name="SERVER-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">        <file>logs/ConnectorServer.log</file>         <append>true</append>         <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">             <fileNamePattern>logs/ConnectorServer-%d{yyyyMMdd}.log</fileNamePattern>             <!-- keep 30 days of logs capped at 1GB total size -->             <maxHistory>30</maxHistory>             <totalSizeCap>1GB</totalSizeCap>         </rollingPolicy>         <encoder>             <pattern>%date{"MMM dd, yyyy h:mm:ss a"} %-5level %logger{35}: %msg %n</pattern>         </encoder>     </appender>Where:
    • The appender class is changed to ch.qos.logback.core.rolling.RollingFileAppender to rotate the logs.
    • The maxHistory and totalSizeCap properties are added to ensure old logs are removed. This example configures them so that 30 days of logs are kept, capped at 1GB in size, but you can set them as needed for your environment.
  2. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /run

See Also

RCS in Identity Cloud

Related Issue Tracker IDs

OPENICF-1638 (RCS logback.xml should be configured for rolling log files with max age/size over a single ever growing file by default)


Known Issues


Identity Cloud or IDM fail to connect to the Remote Connector Server (RCS) with a Failed to validate and load script error

The purpose of this article is to provide assistance if you see "Failed to validate and load script" errors when Identity Cloud or IDM fail to connect to the RCS. This issue only occurs when you are using scripted connectors.

Symptoms

Identity Cloud or IDM fail to connect to the RCS and you see errors similar to the following in the RCS logs:2021-09-22 10:22:03,537 ERROR o.f.o.c.g.ScriptedConfiguration: Failed to validate and load script: CreateScript.groovy Method: validateScript org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed: IO Exception attempting to load global transforms:/tmp/bundle-1192785746/lib/groovy-3.0.7.jar

See How do I enable debug logging and log rotation for the Remote Connector Server (RCS)? for further information on debugging.

In IDM, you will also see a similar error occurring:WARNING: Failure to activate connector. org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed: IO Exception attempting to load global transforms:/tmp/bundle-1192785746/lib/groovy-3.0.7.jar

Recent Changes

Configured a scripted connector for the RCS.

Causes

When the RCS initially starts up, it creates temporary connector bundle files in the JVM temp directory (/tmp by default on Unix® and Linux® systems). These files are required to compile scripted connectors.

When Identity Cloud or IDM attempts to connect to the RCS, the RCS uses these temporary files to compile the scripted connectors being used. Assuming they exist, the connection proceeds and everything functions as expected. If these files cannot be found, Identity Cloud or IDM will fail to connect with the “Failed to validate and load script” error seen above.

Some operating systems have a watcher process that deletes files from the temp directory automatically after a certain period of time. If this happens, the RCS will continue to operate without any errors but if something subsequently causes Identity Cloud or IDM to try to reconnect to the RCS (for example, a promotion in Identity Cloud or restarting IDM), the connection will fail because the temporary connector bundle files are missing.

Solution

This issue can be resolved by creating a dedicated temp directory for the temporary connector bundle files so they're not deleted by any watcher processes. You can do this as follows:

  1. Create a temp directory for the bundle files, for example:$ cd /path/to/openicf $ mkdir bundle_tmp
  2. If you are running RCS as a service: edit the service file (for example, rcs.service in the /etc/systemd/system directory) and update the Environment line to include the temp directory you created in step 1:-Djava.io.tmpdir=/path/to/openicf/bundle_tmpThe Environment line should now look similar to this:Environment="OPENICF_OPTS=-Xmx1024m -Djava.io.tmpdir=/path/to/openicf/bundle_tmp"
  3. Restart the RCS as follows depending on whether you are running it as a service or not; if you are not running it as a service, you will need to set the temp directory when you start it:
    • RCS as a service:$ sudo systemctl restart rcs.service
    • RCS not as a service and deployed on Unix and Linux systems:$ cd /path/to/openicf/bin $ export OPENICF_OPTS="-Djava.io.tmpdir=/path/to/openicf/bundle_tmp" $ ./ConnectorServer.sh /run
    • RCS not as a service and deployed on Microsoft® Windows® systems:C:\> cd \path\to\openicf\bin C:\path\to\openicf\bin> set OPENICF_OPTS=-Djava.io.tmpdir=/path/to/openicf/bundle_tmp  C:\path\to\openicf\bin> ConnectorServer.bat /run
  4. Verify this change has taken effect by checking that the bundle files have been created under the new temp directory (/path/to/openicf/bundle_tmp) after restarting the RCS.

See Also

RCS in Identity Cloud


All Connectors


FAQ: Connectors in IDM

The purpose of this FAQ is to provide answers to commonly asked questions regarding connectors in IDM.

Frequently asked questions

Q. Can I copy a new version of the provisioner file over the old one to replace it after making changes?

A. No, you should stop the IDM server, delete the old provisioner file and then add the new version. If you just copy the new file over the old one while the server is running, you will end up with multiple versions of the file which is likely to cause errors.

You may also need to amend the new provisioner file prior to adding depending on where it came from:

  • Same instance - no changes are needed if the provisioner file comes from the same instance since the password property (if it exists) will be encrypted with same key.
  • Different instance - you must change the password property to use clear text so that IDM can re-encrypt it using the correct key.

Q. How are the useBlocks and blockSize properties used in the LDAP Connector?

A. When used together, the useBlocks and blockSize properties allow IDM to control the rate at which the LDAP connector returns the results of an LDAP search operation. For example, if useBlocks is true, blockSize is 100 and the ldapsearch result set contains 300 results, the results will be returned in 3 sets of 100 (as opposed to all 300 results at once).

This can be useful when the search result set is very large and IDM does not have sufficient resources to efficiently read the entire result set at once.

Note

If useBlocks is false, setting blockSize has no effect.

See LDAP Connector for further information.

Q. How else can I improve large search results in the LDAP Connector?

A. You can set both the useBlocks and usePagedResultControl properties to true (providing you do not have a VLV index configured in DS for the configured filter in the provisioner file). This returns search results as simple paged results, which is better suited to large search result sets.

See LDAP Connector for further information.

Q. What value should uidAttribute be mapped to in the LDAP connector?

A. You should map the uidAttribute to one of the following attributes to be immutable, depending on your directory server:

  • DS - map to entryUUID.
  • ODSEE - map to nsUniqueId.
  • Active Directory® (AD) - map to objectGUID.

If you create a LDAP connector via the Admin UI, the correct default value is used; however, there is a known issue where uidAttribute is set to dn if you use a sample provisioner file in IDM 5: OPENIDM-3330 (inconsistent use of uidAttribute in Ldap Provisioner Config). The value of uidAttribute was corrected in IDM 6.

See How do I update the uidAttribute map value in the LDAP provisioner configuration to entryUUID in IDM 5.x and OpenIDM 4.x? for information on correcting this if you used the sample.

Q. How is the ldapGroups property used by the connectors?

A. The ldapGroups property in the LDAP provisioner file (provisioner.openicf-ldap.json) does not map directly to the nativeName of any attributes in the directory server. Instead, the connector uses ldapGroups as a reference to the actual group membership attribute specified in the groupMemberAttribute property found in the configurationProperties section. You can set groupMemberAttribute to whichever attribute is appropriate on the remote LDAP system.

A sample LDAP provisioner file (provisioner.openicf-ldap.json) with groupMemberAttribute set to the DS attribute uniqueMember can be found in the /path/to/idm/samples/example-configurations/provisioners​ directory (IDM 5.5 and later) or the /path/to/idm/samples/provisioners​ directory (IDM 5).

See LDAP Connector for further information.

Q. Can I use the StartTLS protocol with the LDAP connector?

A. Yes you can. See LDAP Connector for further information.

Q. What APIs do the Google Apps connector use?

A. The Google Apps connector uses the following APIs:

Q. What attribute maps to primaryEmail in the Google Apps connector?

A. The OpenICF __NAME__ attribute maps to primaryEmail and is used as the naming attribute. You should therefore use the __NAME__ attribute in the correlation query.

Q. How do I reduce the number of REST calls made by IDM to a data source when using the Scripted REST connector?

A. You can define a sourceQuery to grab every single object in your source fully and set the sourceQueryFullEntry property to true. The sourceQueryFullEntry property set to true indicates that the objects returned by your sourceQuery are entire objects, not partial matches. This allows you to use a single initial query to pre-load the source (and targets if you use targetQuery and targetQueryFullEntry) within memory on the IDM machine, which reduces the number of initial reads being performed from two to one.

Note

This additional memory usage also impacts the JVM requirements, so ensure you tune your JVM heap accordingly: How do I change the JVM heap size for IDM (All versions)?

Q. How do I pass variables through the Scripted SQL connector to a Groovy script that is called via REST?

A. You can include the required variables in your REST call, for example:

  • IDM 7 and later: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d '{ "myCustomVariable" : "myCustomValue" }' "http://localhost:8080/openidm/system/scriptedsql?_action=script&scriptId=customUpdate" Pre-IDM 7: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" -d '{ "myCustomVariable" : "myCustomValue" }' "http://localhost:8080/openidm/system/scriptedsql?_action=script&scriptId=customUpdate"

This REST call would make the myCustomVariable available within the customUpdate.groovy script.

Q. How do I ensure the Scripted SQL connector removes stale or closed connections from its pool?

A. You can set the following properties in the provisioner file to ensure stale or closed connections are removed from the pool correctly:

  • validationQuery - if the validationQuery finds a stale connection, it should release it to the pool. By default, validationQuery is not set.
  • testOnBorrow - set to true.

See Configuration Properties for further information on these properties.

Q. How do I get operations executed in parallel with the Powershell connector?

A. You can set the following properties to control the pool size:

MinInterpretersPoolSize MaxInterpretersPoolSize

See Configuring the PowerShell Connector for further information on these properties.

Q. How do I add a multi-valued attribute to a connector?

A. You can use one of the following methods to define an attribute as an array of strings to allow it to accept multiple values:

  • array type: "groups": {        "type": "array",         "items": {                 "type": "string",                 "nativeType": "string"         },         "nativeName": "groups",         "nativeType": "string" },
  • string type: "groups" : {                    "type" : "string",                     "nativeName" : "groups",                     "nativeType" : "string",                     "flags" : [                         "MULTIVALUED"                     ]                 },

You can see this being used in the provisioner file in the scripted-rest-with-dj sample (located in the /path/to/idm/samples directory).

Note

In IDM 5.5 and later, you must include an items property if the property type is anything other than strings. See Extending the Property Type Configuration for further information.

Q. Do I have to do anything to the password if the nativeType is set to JAVA_TYPE_BYTE_ARRAY?

A. Yes, if you set the nativeType to JAVA_TYPE_BYTE_ARRAY in the provisioner file, you must base64-encode the password before passing it to the connector. If this is not possible or desirable, you should set nativeType to JAVA_TYPE_GUARDEDSTRING (IDM 7 and later) or string (Pre-IDM 7) instead.

If the password is not base-64 encoded, you will see errors such as the following:

Failed build userPassword attribute

See Also

How do I create a new connector configuration via REST in IDM (All versions)?

How do I find the available parameters for inclusion in the provisioner configuration file for a connector in IDM (All versions)?

Connectors in IDM

Connectors Guide

Samples Guide

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)


How do I enable debug logging for connectors in IDM (All versions)?

The purpose of this article is to provide information on enabling debug logging for connectors in IDM to assist in troubleshooting. It also provides details on restricting logging to a particular connector.

Enabling debug logging for connectors

You can enable debug logging for the OpenICF framework, all connectors or a specific connector as follows:

  1. Shutdown the IDM instance:$ cd /path/to/idm $ ./shutdown.sh
  2. Increase the logging level for the OpenICF framework and/or connectors by adding the following properties to the logging.properties file (located in the /path/to/idm/conf directory) depending on what you want to debug:
    • Debug the OpenICF framework (you can use this in conjunction with all connector debugging or specific connector debugging):org.forgerock.openidm.provisioner.openicf.level = FINEST
    • Debug all connectors:org.forgerock.openicf.connectors.level = FINEST org.identityconnectors.level = FINEST
    • Debug a specific connector - see the table below for which properties should be added for each connector.
  3. Restart the IDM instance:$ cd /path/to/idm $ ./startup.sh

Once you have reproduced the problem and collected the logs, you should remove or comment out the properties you added in step 2 to avoid filling up the disks where the logs are stored.

Debug properties for connectors

The following table shows which properties should be added to the logging.properties file to enable debug logging for a specific connector:

Connector Required Properties
Adobe Marketing Cloud Connector org.forgerock.openicf.acm.level = FINEST
CSV File Connector org.forgerock.openicf.csvfile.level = FINEST
Database Table Connector org.identityconnectors.databasetable.level = FINEST
DocuSign Connector org.forgerock.openicf.connectors.docusign.level = FINEST
Google Apps Connector org.forgerock.openicf.connectors.googleapps.level = FINEST
Groovy Connector Toolkit org.forgerock.openicf.connectors.groovy.level = FINEST
HubSpot Connector rg.forgerock.openicf.connectors.hubspot.level = FINEST
Kerberos Connector org.forgerock.openicf.connectors.kerberos.level = FINEST
LDAP Connector org.identityconnectors.ldap.level = FINEST
Marketo Connector org.forgerock.openicf.connectors.marketo.level = FINEST
MongoDB Connector org.forgerock.openicf.connectors.mongodb.level = FINEST
MS Graph API Java Connector org.forgerock.openicf.connectors.msgraphapi.level = FINEST
PowerShell Connector Toolkit Org.ForgeRock.OpenICF.Connectors.MsPowerShell.level = FINEST
Salesforce Connector org.forgerock.openicf.connectors.salesforce.level = FINEST
SAP Connector org.forgerock.openicf.connectors.sap.level=FINEST scripts.sap.r3.level=FINEST scripts.sap.hr.level=FINEST scripts.sap.level=FINEST
SCIM Connector org.forgerock.openicf.connectors.scim.level = FINEST
Scripted REST Connector org.forgerock.openicf.connectors.scriptedrest.level = FINEST
Scripted SQL Connector org.forgerock.openicf.connectors.scriptedsql.level = FINEST
ServiceNow Connector org.forgerock.openicf.connectors.servicenow.level = FINEST
SSH Connector org.forgerock.openicf.connectors.ssh.level = FINEST
Workday Connector org.forgerock.openicf.connectors.workday.level = FINEST

See Also

Troubleshooting IDM

Troubleshooting Connectors

Configure Server Logs

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure pooled connections for a connector in IDM (All versions)?

The purpose of this article is to provide information on configuring pooled connections for a connector in IDM. This information applies to all poolable connectors (such as the LDAP connector). Poolable connectors create another instance of the connection if one is not available when it needs to do an operation or if it needs to do multiple operations in parallel. Increasing the number of connector instances in the connection pool can improve reconciliation performance.

Configuring pooled connections

You can configure the settings used for pooled connections in your provisioner configuration file (for example, provisioner.openicf-ldap.json), which is located in the /path/to/idm/conf directory.

This file has a poolConfigOption section, with default settings as follows:

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

You can amend these settings as needed to configure how the pooled connections are used, where:

Setting Description
maxObjects The maximum number of instances permitted in the pool (total active and idle connections).
maxIdle The maximum number of idle instances allowed in the pool.
maxWait The maximum time (in milliseconds) that the pool waits for an instance to become available before timing out.
minEvictableIdleTimeMillis

In IDM 7 and later, a connection pool cleaner thread runs every minute and removes connections whose lastUsed time is larger than the minEvictableIdleTimeMillis. As such, the description for this setting varies between versions:

  • IDM 7 and later: The minimum period to wait (in milliseconds) before evicting an idle connector instance from the pool.
  • Pre-IDM 7: The maximum time, in milliseconds, that an object can be idle before it is removed. A value of 0 means that there is no idle timeout.

The default is 120000ms (2 minutes).

minIdle The minimum number of idle instances allowed in the pool. Once the idle timeout is reached, idle instances will be removed from the pool to bring the number of instances available down to the minIdle value. For example, if you set minIdle to 0, the pool would be emptied of idle instances when the idle timeout is reached.

You should bear the following in mind when adjusting these settings:

  • You should ensure maxObjects and maxIdle are always set to the same value to allow pooling to work efficiently and prevent excessive CPU usage. Failure to use the same value will cause excessive churn within the connector instance pool and cause an excessive number of new connections to be established.
  • You can increase maxObjects and maxIdle to increase the number of connector instances available. You should experiment to determine the best settings for your setup; a good starting point is to double these values to 20.
  • You should also increase the number of recontask threads as the number of connector instances increase. You can do this by increasing the value of the taskThreads property in the sync.json file to a value other than the default of 10. See Synchronization Guide › Running Parallel Reconciliation Threads for further information.

See Also

How do I identify reconciliation performance issues in IDM (All versions)?

Connectors Guide › Configure Connectors

Connectors Guide › Connection Pooling Configuration

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)

Related Issue Tracker IDs

N/A


How do I create a new connector configuration via REST in IDM (All versions)?

The purpose of this article is to provide information on creating a new connector configuration (provisioner file) via REST in IDM. This article demonstrates creating an LDAP connector configuration, but you can use the same principles to create any connector configuration via the REST API.

Creating a connector configuration

To create an LDAP connector configuration:

  1. Output all the configuration details using the following curl command:
    • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" http://localhost:8080/openidm/config
    • Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" http://localhost:8080/openidm/config

This command returns a full list of the different configuration IDs, with each one representing a subsystem or component in your IDM instance. The following details are relevant for creating the LDAP connector:{     "_id": "provisioner.openicf/ldap",       "pid": "provisioner.openicf.7132376d-a10d-4ffd-8b34-633f6d44e985",       "factoryPid": "provisioner.openicf" }

  1. Output details for the standard LDAP connector configuration using the following curl command with the _id value identified in step 1:
    • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" http://localhost:8080/openidm/config/provisioner.openicf/ldap
    • Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" http://localhost:8080/openidm/config/provisioner.openicf/ldap

This command returns the entire JSON configuration object for the LDAP connector, for example:{ "_id": "provisioner.openicf/ldap",   "name": "ldap",   "connectorRef": {     "bundleName": "org.forgerock.openicf.connectors.ldap-connector",     "bundleVersion": "[1.4.0.0,2.0.0.0)",     "connectorName": "org.identityconnectors.ldap.LdapConnector"   },   "configurationProperties": {     "host": "localhost",     "port": 1389,     "ssl": false,     "principal": "uid=admin",     "credentials": {       "$crypto": {         "value": {           "iv": "l0X7XU5U5cICjOOoab7c+g==",           "data": "56txTbcXYQDwPgL5R140Fg==",           "cipher": "AES/CBC/PKCS5Padding",           "key": "openidm-sym-default"         },         "type": "x-simple-encryption"       }     },     "baseContexts": [       "dc=example,dc=com"     ],     "baseContextsToSynchronize": [       "dc=example,dc=com"     ],     "accountSearchFilter": null, [...] }

  1. Create a new LDAP connector configuration using the output returned in step 2 as a template. You will need to change at least the "_id", "name" and "credentials" plus customize any other details required for your new connector. You should enter the credentials as clear text. For example, to create a new connector configuration with an _id of ldapNew:
    • IDM 7 and later: $ curl -X PUT -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d '{     "_id": "provisioner.openicf/ldapNew",     "name": "ldapNew",     "connectorRef": {       "bundleName": "org.forgerock.openicf.connectors.ldap-connector",       "bundleVersion": "[1.4.0.0,2.0.0.0)",       "connectorName": "org.identityconnectors.ldap.LdapConnector"     },     "configurationProperties": {       "host": "localhost",       "port": 1389,       "ssl": false,       "principal": "uid=admin",       "credentials": "Passw0rd",       "baseContexts": [         "dc=example,dc=com"       ],       "baseContextsToSynchronize": [         "dc=example,dc=com"       ],       "accountSearchFilter": null, [...]  }' http://localhost:8080/openidm/config/provisioner.openicf/ldapNew
    • Pre-IDM 7: $ curl -X PUT -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" -d '{     "_id": "provisioner.openicf/ldapNew",     "name": "ldapNew",     "connectorRef": {       "bundleName": "org.forgerock.openicf.connectors.ldap-connector",       "bundleVersion": "[1.4.0.0,2.0.0.0)",       "connectorName": "org.identityconnectors.ldap.LdapConnector"     },     "configurationProperties": {       "host": "localhost",       "port": 1389,       "ssl": false,       "principal": "cn=Directory Manager",       "credentials": "Passw0rd",       "baseContexts": [         "dc=example,dc=com"       ],       "baseContextsToSynchronize": [         "dc=example,dc=com"       ],       "accountSearchFilter": null, [...]  }' http://localhost:8080/openidm/config/provisioner.openicf/ldapNew

This command creates the connector configuration and the corresponding provisioner.openicf-ldapNew.json file in the /path/to/idm/conf directory.

See Also

How do I find the available parameters for inclusion in the provisioner configuration file for a connector in IDM (All versions)?

How do I configure the LDAP connector in IDM (All versions) for LDAP failover?

How do I configure pooled connections for a connector in IDM (All versions)?

Connectors Guide › Configure Connectors

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I find the available parameters for inclusion in the provisioner configuration file for a connector in IDM (All versions)?

The purpose of this article is to provide information on finding the available parameters for inclusion in the provisioner configuration file for a connector in IDM. This information applies to all connectors (Adobe Marketing Cloud Connector, CSV File Connector, Database Table Connector, Google Apps Connector, Groovy Connector, HubSpot Connector, Kerberos Connector, LDAP Connector, Marketo Connector, PowerShell Connector, Salesforce Connector, SAP Connector, SCIM Connector, Scripted REST Connector, Scripted SQL Connector, ServiceNow Connector, SSH Connector and Workday Connector).

Finding available parameters

You can use a curl command that includes the connectorHostRef parameter in the createCoreConfig action to return all the available parameters that can be included in the provisioner configuration file for a connector. The connectorHostRef parameter must be set as described in the Connectors Guide.

For example, for a remote Powershell connector named dotnet, the curl command would look like this:

  • IDM 7 and later: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d '{"connectorRef" {"connectorName":"Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector", "displayName":"Scripted PS Connector", "bundleName":"MsPowerShell.Connector", "connectorHostRef" : "dotnet", "bundleVersion":"1.4.6.0"} }' "https://localhost:8080/openidm/system?_action=createCoreConfig&_prettyPrint=true”
  • Pre-IDM 7: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" -d '{"connectorRef" {"connectorName":"Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector", "displayName":"Scripted PS Connector", "bundleName":"MsPowerShell.Connector", "connectorHostRef" : "dotnet", "bundleVersion":"1.4.6.0"} }' "https://localhost:8080/openidm/system?_action=createCoreConfig&_prettyPrint=true”

See Also

FAQ: Connectors in IDM

Empty path name is not legal error with the PowerShell connector in IDM (All versions)

Empty path name is not legal error with the Groovy connector in IDM (All versions)

Connectors Guide › Configure Connectors

Connectors Guide › Creating Connector Configurations Over REST

Related Training

N/A

Related Issue Tracker IDs

N/A


Known Issues


IDM (All versions) connector returns null search result

The purpose of this article is to provide assistance if your IDM connector (Active Directory®, LDAP etc) returns a null search result for attribute queries even though the record can be found. That is, native queries performed directly against these external systems (such as a Connector Server search against Active Directory or a ldapsearch on DS) find the record.

Symptoms

With a query such as:

var params = {"query":{"Equals":{"field" : "samaccountname","values":[tempSamAccountName]}}};

where the attribute name is sAMAccountName rather than the all lower case version included in the query.

Note

This issue affects any command that searches an external system, where the case used in the command does not match the case of the attribute name stored in IDM.

The log from the connector shows the record has been found:

ConnectorServer.exe Information: 0 : Setting search string to '(&(ObjectCategory=Person)(&(objectclass=User (samaccountname=Test)))' DateTime=2014-04-14T18:58:14.6545244Z  ConnectorServer.exe Information: 0 : Search: Performing query  DateTime=2014-04-14T18:58:14.6545244Z  ConnectorServer.exe Information: 0 : Found object LDAP://10.10.100.10/CN=Core,OU=employees,DC=admin,DC=test,DC=example,DC=com  DateTime=2014-04-14T18:58:14.6545244Z  ConnectorServer.exe Information: 0 : Returning ''LDAP://10.10.100.10/CN=Core,OU=employees,DC=admin,DC=test,DC=example,DC=com''  DateTime=2014-04-14T18:58:14.6545244Z  ConnectorServer.exe Information: 0 : Search: found 1 results  DateTime=2014-04-14T18:58:14.6545244Z

But the log from IDM shows a null result:

FINEST: Request: { "type": "resource", "uuid": "3fc900a3-1f54-4297-b05a-14b4c0eefd86", "parent": { "id": null, "_isDirectHttp": true, "value": [ { "replace": "examplecomStatus", "value": [ "Emp:1", "Employee:Core", "Admin:A" ] } ], "parent": { "type": "http", "uuid": "a9f07a2e-9425-43cb-9bd4-3ae140f3ff9e", "parent": { "type": "root", "uuid": "b445ab80-a7e5-41ba-b674-9f5d9625c261", "parent": null }, "security": { "username": "openidmadmin", "userid": { "component": "internal/user", "id": "openidmadmin" }, "openidm-roles": [ "openidm-admin", "openidm-authorized" ] }, "method": "POST", "path": "/openidm/managed/user", "query": { "_action": "patch", "email": "core@example.com", "_queryId": "for-email" }, "headers": { "Host": "localhost:8080", "Content-Length": "98", "User-Agent": "curl/1.10.1 (x86_64-redhat-linux-gnu) libcurl/1.10.1 NSS/3.14.3.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2", "X-OpenIDM-Username": "openidmadmin", "Content-Type": "application/json", "Accept": "*/*" } }, "method": "action", "uuid": "22b9f099-2f2f-4098-b689-58df95cd9b51", "params": { "_action": "patch", "email": "core@example.com", "_queryId": "for-email" }, "type": "resource" }, "method": "query", "id": "system/core/account", "params": { "query": { "Equals": { "field": "samaccountname", "values": [ "Test" ] } } } }, Response: { "result": [ ] }

Recent Changes

N/A

Causes

Attribute names in IDM are case sensitive by default, whereas attribute names in many external systems such as LDAP servers (including DS) and Active Directory are not; therefore, the connector can find the record regardless of the attribute case but IDM cannot unless the case in the query exactly matches the attribute name.

Solution

This issue can be resolved in one of two ways:

  • Standardize the data in your external system so that all attribute names use the same case as IDM.
  • Disable the FilteredResultsHandler to make the search case insensitive.

You can disable the FilteredResultsHandler by including the following in your provisioner configuration file (for example, provisioner.openicf-ad.json or provisioner.openicf-ldap.json), which is located in the /path/to/idm/conf directory:

"resultsHandlerConfig" :       {           "enableNormalizingResultsHandler" : true,           "enableFilteredResultsHandler" : false,           "enableAttributesToGetSearchResultsHandler" : true        }
Note

You must include all three result handlers to override the defaults; the three results handlers are enabled by default if the resultsHandlerConfig is not specified.

See Also

Error when deleting an object from DS using the REST API in IDM (All versions)

Synchronization Guide › Reconcile With Case-Insensitive Data Stores

Related Training

N/A

Related Issue Tracker IDs

N/A


LDAP Connector


How do I configure the LDAP connector in IDM (All versions) for LDAP failover?

The purpose of this article is to provide information on configuring the LDAP connector in IDM for LDAP failover, when DS is being used as your LDAP servers. This article assumes replication is enabled on your DS servers.

Overview

You can configure the LDAP connector for failover in your provisioner configuration file (for example, provisioner.openicf-ldap.json), which is located in the /path/to/idm/conf directory. This allows you to specify a primary DS server and alternative secondary DS servers. When failover is configured: if IDM cannot connect to the primary DS server, it will attempt to connect to one of the secondary DS servers (in the order they are specified) until a connection is successful. If the primary server subsequently becomes available again, IDM will re-connect to the primary server.

Note

This article does not apply to failover of the DS repository just the LDAP connector. If you are using DS as an external repository, see Configure Two DS Repositories in an Active/Passive Deployment for further information.

Configuring the LDAP connector for failover

To configure the LDAP connector for failover:

  1. Set the host and port properties in your provisioner configuration file to point to the primary DS server, for example: "configurationProperties" : {    "host" : "ds1.example.com",     "port" : 1389,
  2. Set the failover property in your provisioner configuration file to point to one or more secondary DS servers by specifying the full LDAP URLs, for example: "failover" : [    "ldap://ds1.example.com:18080",     "ldap://ds2.example.com:28080" ],

See Also

Best practice for LiveSync in IDM (All versions) with multiple DS instances

LDAP Connector

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I test LDAP search filters in the Generic LDAP Connector for IDM (All versions)?

The purpose of this article is to provide assistance on testing LDAP search filters in the Generic LDAP Connector for IDM. LDAP search filters can be used in the Generic LDAP Connector to filter users during synchronization activities (accountSynchronizationFilter) and during searches (accountSearchFilter).

Testing LDAP search filters

Filters such as accountSynchronizationFilter and accountSearchFilter in the Generic LDAP Connector are standard LDAP search filters.

As such, you can test them using the DS ldapsearch command against the required LDAP server to check if they return (or exclude) the expected results.

Examples

  • An example ldapsearch command for including all users who are a direct member of one of two groups: $ ./ldapsearch --port 4444 --baseDN dc=example,dc=com "(|(memberOf=cn=internal,ou=employees,ou=north,dc=example,dc=com)(memberOf=cn=internal,ou=employees,ou=south,dc=example,dc=com))"
  • An example ldapsearch command for excluding a specific user (by employee ID): $ ./ldapsearch --port 4444 --baseDN dc=example,dc=com "(!(&(ObjectCategory=Person)(&(objectclass=User)(employeeID=1234))))"

See Also

How do I exclude specific users from syncing during LiveSync in IDM (All versions)?

Tools Reference › ldapsearch

LDAP User Guide › LDAP Search

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I disable a user account in DS using IDM (All versions)?

The purpose of this article is to provide information on disabling a user account in DS when the user is disabled in IDM. This article assumes you are using the LDAP connector.

Overview

The DS ds-pwp-account-disabled attribute is used to determine if a user is active or not. This is an operational attribute and the correct way to set this attribute is using the manage-account command in DS. For example:

  • DS 7.1 and later: $ ./manage-account set-account-is-disabled --hostname localhost --port 4444 --bindDN uid=admin --bindPassword password --operationValue true --targetDN uid=jdoe,ou=People,dc=example,dc=com --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin
  • DS 7: $ ./manage-account set-account-is-disabled --hostname localhost --port 4444 --bindDN uid=admin --bindPassword password --operationValue true --targetDN uid=jdoe,ou=People,dc=example,dc=com --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin
  • Pre-DS 7: $ ./manage-account set-account-is-disabled --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --operationValue true --targetDN uid=jdoe,ou=People,dc=example,dc=com --trustAll

Response:Account Is Disabled: true

However, it is possible to set it via the LDAP connector in IDM (as shown in this article) or you can set it via the REST API as detailed in: FAQ: REST API in IDM (Q. Can I lock and unlock a user's account in DS via the IDM REST API?).

LDAP Connector

If you want to do this via the LDAP connector, you must:

  1. Add a new property to the managed.json file to store the account status in IDM. These examples use a property called accountDisabled, but you can use any name you want. See Define the Schema for further information.
  2. Configure the LDAP connector to allow accounts to be disabled/enabled.

You can then disable/enable user accounts in IDM and observe the DS ds-pwp-account-disabled attribute being updated as a result.

Configuring the LDAP connector in IDM

You should configure IDM as follows to allow user accounts to be disabled/enabled in DS:

  1. Add a disabled property to your provisioner configuration file (for example, provisioner.openicf-ldap.json), which is located in the /path/to/idm/conf directory. This property should define the ds-pwp-account-disabled value as a string: "disabled" : {      "type" : "string",       "nativeName" : "ds-pwp-account-disabled",       "nativeType" : "string",       "required" : false    }
  2. Add a mapping to the sync.json file for the disabled attribute you created. This example shows a simple mapping that sets the value to either true or false when the managed object is updated directly with a true or false value: {   "target" : "disabled",    "source" : "accountDisabled" }

Disabling a user account

This example assumes you have implicit synchronization enabled to push changes to DS.

  1. Update one of your managed objects to change the accountDisabled value to true, for example:
    • IDM 7 and later: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: password" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -H "X-HTTP-Method-Override: PATCH" -d '[{   "operation":"replace",   "field":"accountDisabled",   "value":"true" }]' "http://localhost:8080/openidm/managed/user/5768a5aa-e370-479b-9c02-04681fbf22d6" Pre-IDM 7: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: password" -H "Content-Type: application/json" -H "X-HTTP-Method-Override: PATCH" -d '[{   "operation":"replace",   "field":"accountDisabled",   "value":"true" }]' "http://localhost:8080/openidm/managed/user/5768a5aa-e370-479b-9c02-04681fbf22d6"
  2. Verify the user has been successfully updated in DS using a ldapsearch command such as the following (you need to include + to return the ds-pwp-account-disabled value because it is an operational attribute):
    • DS 7.1 and later: $ ./ldapsearch --hostname localhost --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password --baseDN "uid=jdoe,ou=People,dc=example,dc=com" "objectClass=*" +
    • DS 7: $ ./ldapsearch --hostname localhost --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password --baseDN "uid=jdoe,ou=People,dc=example,dc=com" "objectClass=*" +
    • Pre-DS 7: $ ./ldapsearch --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "uid=jdoe,ou=People,dc=example,dc=com" "objectClass=*" +

Example response, which shows the ds-pwp-account-disabled property set to true:

dn: uid=jdoe,ou=People,dc=example,dc=com ds-pwp-account-disabled: true entryUUID: 1ff2e78f-4c4c-300c-b8f7-c2ab160061e0 modifyTimestamp: 20210706104217Z modifiersName: uid=admin etag: 0000000041018991 structuralObjectClass: inetOrgPerson pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config isMemberOf: cn=openidm,ou=Groups,dc=example,dc=com numSubordinates: 0 hasSubordinates: false subschemaSubentry: cn=schema entryDN: uid=jdoe,ou=people,dc=example,dc=com

  1. Update the accountDisabled value again to set the ds-pwp-account-disabled attribute back to false:
    • IDM 7 and later: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: password" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -H "X-HTTP-Method-Override: PATCH" -d '[{  "operation":"replace",   "field":"accountDisabled",   "value":"false" }]' "http://localhost:8080/openidm/managed/user/5768a5aa-e370-479b-9c02-04681fbf22d6"
    • Pre-IDM 7: $ curl -X POST -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: password" -H "Content-Type: application/json" -H "X-HTTP-Method-Override: PATCH" -d '[{  "operation":"replace",   "field":"accountDisabled",   "value":"false" }]' "http://localhost:8080/openidm/managed/user/5768a5aa-e370-479b-9c02-04681fbf22d6"
  2. Check the user has been updated successfully in DS:
    • DS 7.1 and later: $ ./ldapsearch --hostname localhost --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password --baseDN "uid=jdoe,ou=People,dc=example,dc=com" "objectClass=*" +
    • DS 7: $ ./ldapsearch --hostname localhost --port 1636 --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --bindDN uid=admin --bindPassword password --baseDN "uid=jdoe,ou=People,dc=example,dc=com" "objectClass=*" +
    • Pre-DS 7: $ ./ldapsearch --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "uid=jdoe,ou=People,dc=example,dc=com" "objectClass=*" +

Example response, which shows the ds-pwp-account-disabled property set back to false:

dn: uid=jdoe,ou=People,dc=example,dc=com ds-pwp-account-disabled: false entryUUID: 1ff2e78f-4c4c-300c-b8f7-c2ab160061e0 modifyTimestamp: 20210706104723Z modifiersName: uid=admin etag: 00000000bdf589de structuralObjectClass: inetOrgPerson pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config isMemberOf: cn=openidm,ou=Groups,dc=example,dc=com numSubordinates: 0 hasSubordinates: false subschemaSubentry: cn=schema entryDN: uid=jdoe,ou=people,dc=example,dc=com

See Also

LDAP Connector

Types of Synchronization

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I merge multiple external accounts to a single managed/user object in IDM (All versions)?

The purpose of this article is to provide information on merging multiple external accounts to a single managed/user object in IDM. This is useful when you hold data in multiple external accounts that you want to bring together in IDM and assumes that there is a common naming attribute in all the external accounts. You can then synchronize this managed/user object (with merged data) to an external account such as DS.

Merging multiple accounts

Note

You can also link multiple accounts from the same target system to a managed user record as detailed in Synchronization Guide › Map a Single Source Object to Multiple Target Objects and Samples Guide › Link Multiple Accounts to a Single Identity.

For the following scenario:

  • 2 external source accounts (LDAP1 and LDAP2)
  • Common naming attribute = mail (email address)
  • 1 external destination account (DS)

You can merge these accounts to a single managed/user object in IDM as follows:

  1. Create and configure separate LDAP connector provisioner configuration files in the /path/to/idm/conf directory for your external accounts (for example, provisioner.openicf-ldap1.json and provisioner.openicf-ldap2.json).
  2. Create separate mappings for each external account to your managed/user object in the sync.json file (located in the /path/to/idm/conf directory), defining which attributes you want from each account.
  3. Determine which source will be the Primary source (used to create managed/user objects during reconciliation) and which source will be the Secondary source.

The Primary source must have the ABSENT situation action set to CREATE within its mappings' policies. Reconciliation must be performed against the Primary source initially in order to create the Managed User objects within the IDM repository.

  1. Update the policies for the Secondary source mapping within the sync.json file by setting the ABSENT situation action to UPDATE. For example: {    "situation" : "ABSENT",     "action" : "UPDATE" },

When performing reconciliation against the Secondary source, any attributes which are common to the two source systems will be overwritten by the Secondary source, unless you explicitly add business logic to either merge or selectively overwrite attribute values.

  1. Define a correlation query based on the common mail naming attribute for each mapping. For example: "correlationQuery" : {    "type" : "text/javascript",     "source" : "var query = {'_queryId' : 'get-by-field-value', 'field' : 'mail', 'value' : source.mail}; query;" },
  2. Create a mapping in the sync.json file from your managed/user to DS.
Note

The sync-with-ldap sample (sample2) is a good starting point as it includes LDAP connector configurations and a basic mapping for an external LDAP account to the managed/user object.

See Also

How do I provision external accounts in a pre-defined order in IDM (All versions)?

Connectors Guide › LDAP Connector

Synchronization Guide › Mapping Data Between Resources

Synchronization Guide › Correlating Source Objects With Existing Target Objects

Samples Guide › One Way Synchronization From LDAP to IDM

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)

Related Issue Tracker IDs

N/A


How do I configure the userAccountControl property in the LDAP and .NET Connectors in IDM (All versions)?

The purpose of this article is to provide assistance on configuring the userAccountControl property in the IDM LDAP and .NET Connectors. userAccountControl is an Active Directory® attribute that provides information about a user's account status.

Setting up userAccountControl

Add the following text to the account properties section in your provisioner configuration file (for example, provisioner.openicf-ldap.json or provisioner.openicf-ad.json), which is located in the /path/to/idm/conf directory:

"userAccountControl" : {          "type" : "string",            "nativeName" : "userAccountControl",            "nativeType" : "string"  }

The ENABLE property is used to enable or disable a user's account in Active Directory. See How do I use the LDAP Connector in IDM (All versions) to update the ENABLE property in Active Directory? for further information.

If you want to synchronize this attribute from Active Directory to IDM, you need to add the following to the systemAdAccounts_managedUser mapping in the sync.json file (located in the /path/to/idm/conf directory):

{         "source" : "userAccountControl",          "target" : "userAccountControl" }

See Also

How do I use the LDAP Connector in IDM (All versions) to update the ENABLE property in Active Directory?

Connectors Guide › LDAP Connector

How to use the UserAccountControl flags to manipulate user account properties

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I use the LDAP Connector in IDM (All versions) to update the ENABLE property in Active Directory?

The purpose of this article is to provide information on using the LDAP Connector in IDM to update the ENABLE property in Active Directory® using the userAccountControl property. userAccountControl is an Active Directory attribute that provides information about a user's account status; the ENABLE property is used to enable or disable a user's account in Active Directory.

Background setup

The LDAP connector allows you to update the ENABLE property to enable or disable a user's account in Active Directory.

Before attempting to change the ENABLE property, you must ensure the following is true:

  • The LDAP connector is configured for SSL.
  • The provisioner configuration file (for example, provisioner.openicf-ldap.json located in the /path/to/idm/conf directory) contains the following attributes at a minimum: "account" : {   "$schema" : "http://json-schema.org/draft-03/schema",    "id" : "__ACCOUNT__",    "type" : "object",    "nativeType" : "__ACCOUNT__",    "properties" : {       "__ENABLE__" : {         "type" : "boolean",         "nativeName" : "__ENABLE__",         "nativeType" : "JAVA_TYPE_PRIMITIVE_BOOLEAN"       },       "dn" : {         "type" : "string",         "required" : true,         "nativeName" : "__NAME__",         "nativeType" : "string"       },       "cn" : {         "type" : "string",         "nativeName" : "cn",         "nativeType" : "string",         "flags" : [            "NOT_CREATABLE",            "NOT_UPDATEABLE"         ]       },       "sAMAccountName" : {         "type" : "string",         "nativeName" : "sAMAccountName",         "nativeType" : "string"       },       "userAccountControl" : {         "type" : "string",         "nativeName" : "userAccountControl",         "nativeType" : "string"      },      "password" : {        "type" : "string",        "nativeName" : "__PASSWORD__",        "nativeType" : "JAVA_TYPE_GUARDEDSTRING",        "flags" : [           "NOT_READABLE",           "NOT_RETURNED_BY_DEFAULT"        ],        "runAsUser" : true      },

Creating the Connector through the Admin UI

An easy way to create the connector is through the Admin UI as described in Connectors Guide › Creating Connector Configurations With the Admin UI. You can create the connector by selecting type "AD LDAP Configuration".

When you create the LDAP connector via the Admin UI, the following happens:

  • The following account search filter is created: "accountSearchFilter" : "(&(!(userAccountControl:1.2.840.113556.1.4.803:=2))(!(objectClass=Computer)))"This search filter means disabled users are not returned and are not available for REST calls. You must remove this search filter to allow users to be enabled and disabled through REST calls. It should be noted though that this will make disabled users available for all other REST calls as well, which may not be desirable. One way to work around this would be to create a separate connector for the same AD instance with this search filter removed and use that connector only for the purpose of enabling and disabling accounts.
  • The following entry may be created in the properties section of the provisioner configuration file:  "isActive" : {    "type" : "boolean",     "nativeName" : "__ENABLE__",     "nativeType" : "boolean",     "flags" : [         "NOT_CREATABLE",         "NOT_UPDATEABLE"     ] },Where the property name is "isActive" instead of "__ENABLE__" as shown in the sample above. If this entry is created, you must remove the "NOT_CREATABLE" and "NOT_UPDATABLE" flags to make it usable.

Changing the ENABLE property

You can change the ENABLE property using a PUT request such as the following (where the user's account is currently disabled but does not require a password):

$ PUT -H "If-Match: *" http://localhost:8080/openidm/system/AD/account/<GUID=f2e08a5c-473f-4798-a2d5-d5cc27c862a9> { "__ENABLE__": true }
Note

You must pass the HTTP header "If-Match: *" in order to perform an update, otherwise it is interpreted as a create operation, which will fail if the entry already exists.

Example result returned (with irrelevant attributes removed):

{   "lastLogon": "0",    "__PASSWORD_NOTREQD__": true,    "__PASSWORD_EXPIRED__": true,    "pwdLastSet": "0",    "__LOCK_OUT__": false,    "__DONT_EXPIRE_PASSWORD__": false,    "userAccountControl": "544",    "__SMARTCARD_REQUIRED__": false,    "__ENABLE__": true, }

Important attributes to note are:

  • "__PASSWORD_NOTREQD__": true - confirms the password is not required.
  • "userAccountControl": "544" - indicates the user account is now enabled and the password is not required. The actual number may differ, but the flag with value 2 indicating that the account is disabled should not be set.
  • "__ENABLE__": true - confirms the account is now enabled.

See Also

Attribute value conflicts with the attribute's schema definition on operation UPDATE for system object

How do I configure the userAccountControl property in the LDAP and .NET Connectors in IDM (All versions)?

Connectors Guide › Using the Generic LDAP Connector With Active Directory

Related Training

N/A

Related Issue Tracker IDs

N/A


Best practice for LiveSync in IDM (All versions) with Active Directory

The purpose of this article is to provide best practice advice on using LiveSync in IDM with Active Directory® when you are using the LDAP connector; this information does not apply to Azure® Active Directory. This article also discusses high availability in this scenario.

LiveSync with Active Directory

LiveSync captures the changes that occur in Active Directory and pushes them to IDM.

The LiveSync mechanism for Active Directory is based on the uSNChanged and highestCommittedUSN attributes. The LiveSync synchronization token is set to the uSNCHanged (USN) number for the last update that was processed and subsequent LiveSync attempts query the Active Directory instance for changes since then.

Caution

The USN numbers are unique per Domain Controller (DC) and therefore the LDAP connector must point to a single DC (no load balancer in between). Failover to an alternate DC may cause LiveSync to break as the USN numbers are not replicated across DCs, meaning the USN numbers will be inconsistent.

You do not need to make any changes to the provisioner configuration file (for example, provisioner.openicf-ldap.json) to specify the attributes used by LiveSync if you are using Active Directory.

Note

You should consider configuring the LiveSync retry policy to determine 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. This is discussed in: Synchronization Guide › Configure the LiveSync Retry Policy. If no retry policy is configured, IDM reattempts the change an infinite number of times, until the change is successful.

High availability

Since you can only point to one DC, using LiveSync is not an option if you require high availability. As an alternative, you can use the timestamp mechanism instead for synchronizing changes and point to a Global Catalog (GC). Timestamps are maintained per entry for create and modify operations; however, delete operations cannot be detected via timestamps. If delete synchronization is a high priority, you should continue to use LiveSync.

There are two constraints you should be aware of if you use a GC:

  • GC only contains a partial attribute set. This means not all attributes are replicated from the DC to GC, although this is configurable.
  • Groups and their members are only properly handled if the groups are universal.

To use the timestamp mechanism, you should add the following property to your provisioner configuration file (for example, provisioner.openicf-ldap.json, located in the /path/to/idm/conf directory):

"useTimestampsForSync" : "true",

See Also

Best practice for LiveSync in IDM (All versions) with multiple DS instances

Synchronization Guide › Types of Synchronization

Connectors Guide › Using the Generic LDAP Connector With Active Directory

Connectors Guide › The ForgeRock Identity Connector Framework (ICF)

Samples Guide › Connect to a MySQL Database With ScriptedSQL

Related Training

N/A

Related Issue Tracker IDs

N/A


Best practice for LiveSync in IDM (All versions) with multiple DS instances

The purpose of this article is to provide best practice advice on using LiveSync in IDM when there are multiple DS instances and you are using the LDAP connector.

Warning

Do not compress, tamper with, or otherwise alter changelog database files directly unless specifically instructed to do so by a qualified ForgeRock technical support engineer. External changes to changelog database files can render them unusable by the server. By default, changelog database files are located under the /path/to/ds/changelogDb directory.

LiveSync best practice

There are two approaches to using LiveSync in IDM with DS:

With both approaches, you should avoid having a load balancer in front of DS as explained here: Configuration Guide › On Load Balancers. You can configure your LDAP connector for failover: How do I configure the LDAP connector in IDM (All versions) for LDAP failover?

Timestamp mechanism

Timestamps are maintained per entry for create and modify operations; however, delete operations cannot be detected via timestamps. If delete synchronization is a high priority, you should continue to use the changelog for LiveSync.

If you want to use timestamps, you should set the following property in your provisioner configuration file (for example, provisioner.openicf-ldap.json), which is located in the /path/to/idm/conf directory:

"useTimestampsForSync" : "true",
Caution

You should thoroughly test LiveSync with the timestamp mechanism in a development environment first to ensure it meets your needs. Using LiveSync with timestamps can potentially cause performance issues if the DS instance is managing millions of entries; the timestamp search can have a high cost when there are many entries.

LiveSync retry policy

You should consider configuring the LiveSync retry policy to define 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. This is discussed in: Synchronization Guide › Configure the LiveSync Retry Policy. If no retry policy is configured, IDM reattempts the change an infinite number of times, until the change is successful.

See Also

Best practice for LiveSync in IDM (All versions) with Active Directory

How do I configure the LDAP connector in IDM (All versions) for LDAP failover?

Connectors Guide › LDAP Connector

Setup Guide › Property Value Substitution

Synchronization Guide › Configure the LiveSync Retry Policy

Connectors Guide › The ForgeRock Identity Connector Framework (ICF)

Samples Guide › Connect to a MySQL Database With ScriptedSQL

Related Training

N/A

Related Issue Tracker IDs

N/A


Known Issues


Attribute value conflicts with the attribute's schema definition on operation error in IDM (All versions)

The purpose of this article is to provide assistance if you receive an "Attribute value conflicts with the attribute's schema definition on operation UPDATE for system object" error in IDM when you try to update a boolean attribute in Active Directory® or OpenLDAP. Similar errors occur for CREATE, PUT and PATCH operations.

Symptoms

The following error is shown when you try to update a boolean attribute in Active Directory or OpenLDAP from IDM.  Similar errors may display for CREATE, PUT, and PATCH operations.

Attribute value conflicts with the attribute's schema definition on operation UPDATE for system object

An error similar to the following is shown in the IDM log:

FINE: Attribute value conflicts with the attribute's schema definition on operation UPDATE for system object org.identityconnectors.framework.common.exceptions.InvalidAttributeValueException: Malformed 'msNPAllowDialin' attribute value

Recent Changes

N/A

Causes

This error occurs because Active Directory and OpenLDAP are case-sensitive for boolean attributes. These LDAP target resources usually require uppercase TRUE and FALSE for boolean attributes, whereas JSON requires lowercase true and false.

Solution

This issue can be resolved as follows:

  1. Configure the boolean attribute as a string in the LDAP provisioner configuration file (for example, provisioner.openicf-ldap.json located in the /path/to/idm/conf directory). For example: "msNPAllowDialin": {                     "type": "string",                     "nativeName": "msNPAllowDialin",                     "nativeType": "string"                 },
  2. Use a script to set the attribute value with an uppercase string of TRUE or FALSE. For example: openidm.patch("system/ad/account/" + id,null,[{"operation":"replace","field":"/msNPAllowDialin","value":"TRUE"}]); Example result returned (with irrelevant attributes removed): ​{
     "fromEntry": "TRUE",
     "passwordNotRequired": false,
     "msNPAllowDialin": "TRUE",
     "passwordExpired": false,
     "lockOut": false,
    "isActive": true,
     "smartcardRequired": false }
Note

Some Active Directory attributes such as isActive are, by default, configured as boolean and can be updated using lowercase true and false. This is because these attributes are actually userAccountControl flags, but are displayed as booleans by the connector. See How do I use the LDAP Connector in IDM (All versions) to update the ENABLE property in Active Directory? for further information.

See Also

How do I use the LDAP Connector in IDM/OpenIDM (All versions) to update the ENABLE property in Active Directory?

Scripting Guide › Scripting Function Reference

Scripting Guide

Section 3.3.3 of RFC 4517

Section 3 of RFC 7159

Related Training

N/A

Related Issue Tracker IDs

N/A


Synchronization fails in IDM (All versions) for attributes that are zero-length or have an empty or null value

The purpose of this article is to provide assistance if you encounter LDAP: error code 21 exceptions in IDM when syncing data to DS and see errors relating to invalid attribute values according to the syntax, where the attribute has a zero-length value, or an empty or null value. Common errors seen include: "The operation attempted to assign a zero-length value to an attribute with the directory string syntax" or "The provided value is not a valid telephone number because it is empty or null".

Symptoms

Data synchronization to DS fails and you see LDAP: error code 21 exceptions. This can happen for most syntaxes but commonly affects Directory String and Telephone Number as shown in these example IDM log entries (for an attribute called Attribute1):

  • Directory String syntax:Caused by: org.identityconnectors.framework.common.exceptions.ConnectorException: javax.naming.directory.InvalidAttributeValueException: [LDAP: error code 21 - Entry "employeeId=user10,ou=Users,dc=example,dc=com" contains a value "" for attribute Attribute1 that is invalid according to the syntax for that attribute: The operation attempted to assign a zero-length value to an attribute with the directory string syntax]; remaining name 'employeeId=user10,ou=Users,dc=example,dc=com' Caused by: javax.naming.directory.InvalidAttributeValueException: [LDAP: error code 21 - When attempting to modify entry cn=John,ou=People,dc=example,dc=com to replace the set of values for attribute Attribute1, value "" was found to be invalid according to the associated syntax: The operation attempted to assign a zero-length value to an attribute with the directory string syntax]; remaining name 'cn=John,ou=People,dc=example,dc=com'
  • Telephone Number syntax:Caused by: org.identityconnectors.framework.common.exceptions.InvalidAttributeValueException: [LDAP: error code 21 - When attempting to modify entry employeeId=user10,ou=Users,dc=example,dc=com to replace the set of values for attribute Attribute1, value \"\" was found to be invalid according to the associated syntax: The provided value is not a valid telephone number because it is empty or null] Caused by: javax.naming.directory.InvalidAttributeValueException: [LDAP: error code 21 - Entry "uid=jdoe,dc=example,dc=com" contains a value "" for attribute Attribute1 that is invalid according to the syntax for that attribute: The provided value is not a valid telephone number because it is empty or null]; remaining name 'uid=jdoe,dc=example,dc=com'

These errors are not seen if the attribute has a value in IDM; it only happens if the attribute has an empty value.

You will see similar errors in the DS Access logs when this happens, for example:

  • Directory String syntax:{"eventName":"DJ-LDAP","client":{"ip":"198.51.100.0","port":8443},"server":{"ip":"198.51.100.0","port":1636},"request":{"protocol":"LDAPS","operation":"ADD","connId":291,"msgId":47,"dn":"uid=jdoe,ou=People,ou=employees,dc=example,dc=com"},"transactionId":"0","response":{"status":"FAILED","statusCode":"21","elapsedTime":1,"elapsedTimeUnits":"MILLISECONDS","detail":"Entry uid=jdoe,ou=People,ou=employees,dc=example,dc=com contains a value "" for attribute Attribute1 that is invalid according to the syntax for that attribute: The operation attempted to assign a zero-length value to an attribute with the directory string syntax"},"timestamp":"2021-08-08T14:22:43.683Z","_id":"c2a5dbd3-4960-b7d2-96e2-20370bf25b31-737"}
  • Telephone Number syntax:{"eventName":"DJ-LDAP","client":{"ip":"198.51.100.0","port":8443},"server":{"ip":"198.51.100.0","port":1636},"request":{"protocol":"LDAPS","operation":"MODIFY","connId":2131,"msgId":47,"dn":"uid=jdoe,ou=People,ou=employees,dc=example,dc=com"},"transactionId":"0","response":{"status":"FAILED","statusCode":"21","elapsedTime":1,"elapsedTimeUnits":"MILLISECONDS","detail":"When attempting to modify entry uid=jdoe,ou=People,ou=employees,dc=example,dc=com to replace the set of values for attribute Attribute1, value \"\" was found to be invalid according to the associated syntax: The provided value is not a valid telephone number because it is empty or null"},"timestamp":"2021-08-08T14:22:43.683Z","_id":"c2a5dbd3-4960-b7d2-96e2-20370bf25b31-737"}

Recent Changes

Configured the LDAP connector to synchronize data to DS.

Updated the mapping configuration file (sync.json, located in the /path/to/idm/conf directory).

Causes

By default, DS does not allow empty string values (zero-length-values) for most syntaxes. Notably, this applies to attributes that have a syntax of Directory String (per the RFC 4517 standard - A zero-length character string is not permitted) but this is also true of attributes with most other syntaxes (excluding IA5String and DN). See Syntaxes for further information.

The LDAP result code: 21 is caused by an invalid attribute syntax. This error is received when the requested operation failed because it violated the syntax for a specified attribute.

Note

Although it is possible to change the schema for attributes with a syntax of Directory String to allow zero-length-values, it is not recommended. Permitting empty string values is against the standard and may cause issues with other systems that do implement the LDAP standard correctly.

Solution

You can resolve this issue by adding a transform script to the sync.json file for any affected attributes to allow empty string values to be stored as null values. 

For example, the following simple transform script checks if the source property has an empty string value, and if so, sets the target property value to null. If the value is not empty, then the target property value is updated to match the source property value:

{      "source" : "Attribute1",       "target" : "Attribute1",                     "transform" : {                         "type" : "text/javascript",                         "source" : "if(source.ATTRIBUTE1 === ""){value = null} else{value = source.ATTRIBUTE1}" }

This transform script has been included in the sync.json file; alternatively, you could include this transform script in a separate file and call the file from sync.json instead, for example:

{      "source" : "Attribute1",       "target" : "Attribute1",                     "transform" : {                         "type" : "text/javascript",                         "file" : "script/DirectoryStringTransform.js" }

See Also

How do I update attributes stored in arrays in IDM (All versions) using JavaScript?

How do I provision external accounts in a pre-defined order in IDM (All versions)?

Transform Attributes in a Mapping

Configuring Connections Between Resources

Invalid Attribute Syntax 

Syntaxes

RFC 4517: Directory String

Related Training

N/A

Related Issue Tracker IDs

N/A


IDM (All versions) LiveSync syncToken is out of sync with the DS changelog number

The purpose of this article is to provide assistance if the IDM LiveSync syncToken is out of sync with the DS changelog number, meaning no changes are detected and LiveSync stops working. You will see the following error when this happens: "The current SyncToken value (n+x) is greater than the lastChangeNumber value (n)".

Warning

Do not compress, tamper with, or otherwise alter changelog database files directly unless specifically instructed to do so by a qualified ForgeRock technical support engineer. External changes to changelog database files can render them unusable by the server. By default, changelog database files are located under the /path/to/ds/changelogDb directory.

Symptoms

LiveSync fails to detect any changes, and the syncToken and DS changelog numbers are out of sync.

The following error is shown when this happens:

WARNING: The current SyncToken value (15,187) is greater than the lastChangeNumber value (12,872) Sep 21, 2016 8:22:30 AM org.identityconnectors.ldap.LdapConnector doSync

Recent Changes

Configured or changed your LiveSync configuration.

Updated the DS instance's changelog after the last successful LiveSync was performed.

Causes

The syncToken is based on the last highest value seen within the DS changelog and is stored within the IDM repository.

The syncToken and changelog number can get out of sync for one of the following reasons:

  • IDM is connected to DS via a load balancer and the changelog numbers are out of sync between the servers.
  • The repository used by IDM (repo.jdbc.json) contains old data from a previous IDM instance, which was pointed to an alternative DS instance that had a different changelog number.
  • The changelog associated with the DS instance was modified or purged without having reset the syncToken which is cached in the IDM repository.

Solution

Note

You should disable the LiveSync schedule if the interval is very small (few seconds) so that the DELETE request can match the rev. The rev changes every few seconds when the LiveSync interval is very small, which would make the DELETE request difficult to apply unless the schedule is disabled.

You can use the resetSyncToken configuration property to address these possible inconsistencies. See Connectors Guide › Configuration Properties for further information on setting this property.

You should also refer to Best practice for LiveSync in IDM (All versions) with multiple DS instances to ensure your configuration is correct to avoid similar issues in the future.

See Also

How do I read and set the LiveSync syncToken using REST in IDM (All versions)?

Best practice for LiveSync in IDM (All versions) with multiple DS instances

Related Training

N/A

Related Issue Tracker IDs

N/A


Database Table Connector


LiveSync fails with ORA-01843 or ORA-01861 error when using the Database Table Connector in IDM (All versions)

The purpose of this article is to provide assistance if you see one of the following errors when LiveSync fails in IDM: "ORA-01843: not a valid month" or "ORA-01861: literal does not match format string". These errors occur when using the Database Table Connector to connect to a table on an Oracle® database.

Symptoms

You will see one of the following errors when LiveSync fails depending on the data type as explained in the Causes section:

2017-01-22T12:09:42.062+0000 WARNING org.forgerock.openidm.quartz.impl.SchedulerServiceJob execute org.forgerock.openidm.quartz.impl.SchedulerServiceJob: Scheduled service "scheduler-service-group.sync_systemSunidmAccount_managedUser" invocation reported failure: org.forgerock.json.resource.InternalServerErrorException: Failed to get OperationOptionsBuilder: Can not read from the table or view 'sunidm_openidm.account'.^_ org.forgerock.openidm.quartz.impl.ExecutionException: org.forgerock.json.resource.InternalServerErrorException: Failed to get OperationOptionsBuilder: Can not read from the table or view 'sunidm_openidm.account'.     at org.forgerock.openidm.provisioner.impl.SystemObjectSetService.execute(SystemObjectSetService.java:412)     at org.forgerock.openidm.quartz.impl.SchedulerServiceJob.execute(SchedulerServiceJob.java:133)     at org.quartz.core.JobRunShell.run(JobRunShell.java:223)     at org.quartz.simpl.SimpleThreadPool$WorkerThread.run(SimpleThreadPool.java:549)  Caused by: org.forgerock.json.resource.InternalServerErrorException: Failed to get OperationOptionsBuilder: Can not read from the table or view 'sunidm_openidm.account'.     at org.forgerock.openidm.provisioner.openicf.impl.OpenICFProvisionerService.liveSynchronize(OpenICFProvisionerService.java:2166)     at org.forgerock.openidm.provisioner.impl.SystemObjectSetService.liveSync(SystemObjectSetService.java:449)     at org.forgerock.openidm.provisioner.impl.SystemObjectSetService.execute(SystemObjectSetService.java:407)  ... 3 more  Caused by: org.identityconnectors.framework.common.exceptions.ConnectorException: Can not read from the table or view 'sunidm_openidm.account'.     at org.identityconnectors.databasetable.DatabaseTableConnector.sync(DatabaseTableConnector.java:644)     at org.identityconnectors.framework.impl.api.local.operations.SyncImpl.sync(SyncImpl.java:73)     at sun.reflect.GeneratedMethodAccessor86.invoke(Unknown Source)     at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)     at java.lang.reflect.Method.invoke(Method.java:498)     at org.identityconnectors.framework.impl.api.local.operations.ConnectorAPIOperationRunnerProxy.invoke(ConnectorAPIOperationRunnerProxy.java:104)     at com.sun.proxy.$Proxy31.sync(Unknown Source)     at sun.reflect.GeneratedMethodAccessor86.invoke(Unknown Source)     at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)     at java.lang.reflect.Method.invoke(Method.java:498)     at org.identityconnectors.framework.impl.api.local.operations.ThreadClassLoaderManagerProxy.invoke(ThreadClassLoaderManagerProxy.java:96)     at com.sun.proxy.$Proxy31.sync(Unknown Source)     at sun.reflect.GeneratedMethodAccessor86.invoke(Unknown Source)     at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)     at java.lang.reflect.Method.invoke(Method.java:498)     at org.identityconnectors.framework.impl.api.BufferedResultsProxy$BufferedResultsHandler.run(BufferedResultsProxy.java:157)  Caused by: java.sql.SQLDataException: ORA-01843: not a valid month Mar 03, 2017 2:50:16 PM org.forgerock.openidm.servlet.internal.ServletConnectionFactory$4 handleException WARNING: Resource exception: 500 Internal Server Error: "Failed to get OperationOptionsBuilder: Can not read from the table or view 'DB_TABLE'." org.forgerock.json.resource.InternalServerErrorException: Failed to get OperationOptionsBuilder: Can not read from the table or view 'DB_TABLE'.   at org.forgerock.openidm.provisioner.impl.SystemObjectSetService.actionInstance(SystemObjectSetService.java:318)    at org.forgerock.json.resource.InterfaceSingletonHandler.handleAction(InterfaceSingletonHandler.java:34) ... Caused by: org.forgerock.json.resource.InternalServerErrorException: Failed to get OperationOptionsBuilder: Can not read from the table or view 'DB_TABLE'.    at org.forgerock.openidm.provisioner.openicf.impl.OpenICFProvisionerService.liveSynchronize(OpenICFProvisionerService.java:2330)    at org.forgerock.openidm.provisioner.impl.SystemObjectSetService.liveSync(SystemObjectSetService.java:448)    at org.forgerock.openidm.provisioner.impl.SystemObjectSetService.actionInstance(SystemObjectSetService.java:300) ... 130 more Caused by: org.identityconnectors.framework.common.exceptions.ConnectorException: Can not read from the table or view 'DB_TABLE'.    at org.identityconnectors.databasetable.DatabaseTableConnector.sync(DatabaseTableConnector.java:628)    at org.identityconnectors.framework.impl.api.local.operations.SyncImpl.sync(SyncImpl.java:73)    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)    at java.lang.reflect.Method.invoke(Method.java:606)    at org.identityconnectors.framework.impl.api.local.operations.ConnectorAPIOperationRunnerProxy.invoke(ConnectorAPIOperationRunnerProxy.java:104)    at com.sun.proxy.$Proxy26.sync(Unknown Source)    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)    at java.lang.reflect.Method.invoke(Method.java:606)    at org.identityconnectors.framework.impl.api.local.operations.ThreadClassLoaderManagerProxy.invoke(ThreadClassLoaderManagerProxy.java:96)    at com.sun.proxy.$Proxy26.sync(Unknown Source)    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)    at java.lang.reflect.Method.invoke(Method.java:606)    at org.identityconnectors.framework.impl.api.BufferedResultsProxy$BufferedResultsHandler.run(BufferedResultsProxy.java:157) Caused by: java.sql.SQLDataException: ORA-01861: literal does not match format string

Recent Changes

Implemented the Database Table Connector.

Causes

The Database Table Connector cannot handle Oracle's TIMESTAMP or DATE data type. This issue will affect you when the field specified as the changeLogColumn in your provisioner configuration is of type TIMESTAMP or DATE.

The error you see is dependent on your data type as follows:

  • TIMESTAMP: ORA-01843: not a valid month
  • DATE: ORA-01861: literal does not match format string

Solution

This issue can be resolved as follows:

  1. Update your provisioner configuration file (for example, provisioner.openicf-contractordb.json in the /path/to/idm/conf directory) to ensure the allNative and nativeTimestamps configuration properties are set to true as follows: "allNative" : "true",     "changeLogColumn" : "LAST_MODIFIED",      "nativeTimestamps" : "true",By default, allNative is set to false and changeLogColumn is typically set to LAST_MODIFIED, which has a data type of TIMESTAMP. You should amend changeLogColumn to match your settings if you use a different field.
  2. Add the following JVM option to the Java execution line in the startup.sh or startup.bat file: -Doracle.jdbc.J2EE13Compliant=true

See Also

Connectors Guide › Database Table Connector

Related Training

N/A

Related Issue Tracker IDs

N/A


PowerShell Connector Toolkit


Empty path name is not legal error with the PowerShell connector in IDM (All versions)

The purpose of this article is to provide assistance if you get an "Empty path name is not legal" error with the PowerShell connector toolkit in IDM.

Symptoms

The following error is shown when using the PowerShell connector toolkit:

Empty path name is not legal

Recent Changes

Implemented the PowerShell connector toolkit.

Causes

The format of the script file names (for example, updateScriptFileName or searchScriptFileName) is incorrect in your provisioner configuration file (for example, provisioner.openicf-powershell.json), which is located in the /path/to/idm/conf directory.

Solution

This issue can be resolved by correcting the format of the script file names.

The script file names should contain the full path and name of the required script with double backslashes as the path delimiter, for example:

"updateScriptFileName" : "C:\\Scripts\\PowerShell\\UpdateScript.ps1",

See Also

Empty path name is not legal error with the Groovy connector in IDM (All versions)

Connectors Guide › PowerShell Connector Toolkit

Samples Guide › Connect to Active Directory With the PowerShell Connector

Related Training

N/A

Related Issue Tracker IDs

N/A


Groovy Connector Toolkit


Empty path name is not legal error with the Groovy connector in IDM (All versions)

The purpose of this article is to provide assistance if you get an "Empty path name is not legal" error with the Groovy connector toolkit in IDM.

Symptoms

The following error is shown when using the Groovy connector toolkit:

Empty path name is not legal

Recent Changes

Implemented the Groovy connector toolkit.

Causes

The format of the script file names (for example, updateScriptFileName or searchScriptFileName) is incorrect in your provisioner configuration file (for example, provisioner.openicf-groovy.json), which is located in the /path/to/idm/conf directory.

Solution

This issue can be resolved by correcting the format of the script file names.

The path of the directory where the scripts are all located should be specified as follows depending on the version of IDM:

  • IDM 6 and later: specify the location in the scriptRoots, for example:
  • "scriptRoots" : [        "&{idm.instance.dir}/tools"],
  • IDM 5.x: specify the location in the scriptRoots, for example: "scriptRoots" : [        "&{launcher.project.location}/tools"],

Where idm.instance.dir or launcher.project.location equates to the /path/to/idm directory.

The script file names should then just contain the name of the required script, for example:

"updateScriptFileName" : "UpdateScript.groovy",

See Also

Empty path name is not legal error with the PowerShell connector in IDM (All versions)

Connectors Guide › Groovy Connector Toolkit

Samples Guide › Connect to DS With ScriptedREST

Samples Guide › Connect to a MySQL Database With ScriptedSQL

Related Training

N/A

Related Issue Tracker IDs

N/A


.NET Connector Server


How do I enable OpenICF logging for the .NET Connector Server in IDM (All versions) to investigate server crashes?

The purpose of this article is to provide information on enabling OpenICF logging for the .NET Connector Server in IDM. Enabling logging is useful for investigating .NET Connector Server crashes.

Enabling OpenICF logging

In the ConnectorServer.exe.Config file (located in the directory in which the Connector Server is installed), you should make the following changes:

  1. Change the value of the add key property from false to true: <add key="logging.proxy" value="true"/>
  2. Change the initializeData type to Error (it is set to Information by default): <filter type="System.Diagnostics.EventTypeFilter" initializeData="Error"/>
Note

There are other logging levels available, which can be set by changing the initializeData type. The available levels are Error, Warning, Information (default) Verbose and All. Verbose and All output very detailed logging; the level of logging has a direct effect on the performance of the .NET Connector Server so care should be taken when changing this setting.

Your file should now look similar to this:

<configuration> <appSettings>   <add key="logging.proxy" value="true"/> </appSettings> <system.diagnostics>   <trace autoflush="true" indentsize="4">     <listeners>       <remove name="Default" />       <add           name="myListener"           type="System.Diagnostics.TextWriterTraceListener"          initializeData="c:\connectorserver.log"           traceOutputOptions="DateTime">          <filter             type="System.Diagnostics.EventTypeFilter"             initializeData="Error"/>       </add>     </listeners>   </trace> </system.diagnostics> </configuration>
Note

You should also enable Microsoft® Windows® crash dumps as described here: Collecting User-Mode Dumps

See Also

How do I enable database logging in IDM (All versions)?

Troubleshooting IDM

Connectors Guide › Install a Remote Connector Server

Related Training

N/A

Related Issue Tracker IDs

N/A


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

This content has been optimized for printing.