ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: Connectors in IDM

Last updated Nov 10, 2021

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.


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.


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).


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)

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