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?
- Q. How are the useBlocks and blockSize properties used in the LDAP connector?
- Q. How else can I improve large search results in the LDAP connector?
- Q. What value should uidAttribute be mapped to in the LDAP connector?
- Q. How is the ldapGroups property used by the connectors?
- Q. Can I use the StartTLS protocol with the LDAP connector?
- Q. How does IDM check that it can connect to a directory server via the LDAP connector?
- Q. Can I configure scripted connectors via the Admin UI?
- Q. What APIs do the Google Apps connector use?
- Q. What attribute maps to primaryEmail in the Google Apps connector?
- Q. How do I reduce the number of REST calls made by IDM to a data source when using the Scripted REST connector?
- Q. How do I pass variables through the Scripted SQL connector to a Groovy script that is called via REST?
- Q. How do I ensure the Scripted SQL connector removes stale or closed connections from its pool?
- Q. How do I get operations executed in parallel with the Powershell connector?
- Q. How do I add a multi-valued attribute to a connector?
- Q. Do I have to do anything to the password if the nativeType is set to JAVA_TYPE_BYTE_ARRAY?
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.
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.
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. How does IDM check that it can connect to a directory server via the LDAP connector?
A. IDM performs the following checks to test if it can connect to the directory server via the LDAP connector:
- Validates the configuration.
- Checks the connection by retrieving the
subschemaSubentryattribute. - Validates all the configured baseContexts.
Q. Can I configure scripted connectors via the Admin UI?
A. No, scripted connectors (such as Groovy, Scripted REST and Scripted SQL) are not available in the drop-down list of connectors in the Admin UI. Configuring these scripted connectors involves a lot of custom configuration changes and pointing to scripts, which makes their configuration unsuited to the UI. You should use REST instead: Configure connectors over REST.
Refer to the documentation for further information on these scripted connectors:
- Groovy connector Toolkit
- PowerShell connector Toolkit
- SCIM connector
- Scripted REST connector
- Scripted SQL connector
- SSH connector
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?
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"
- IDM 6.x: $ 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. 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 get operations executed in parallel with the Powershell connector?
A. You can set the following properties to control the pool size:
MinInterpretersPoolSize MaxInterpretersPoolSizeSee Configure 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
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 (IDM 6.x) instead.
If the password is not base-64 encoded, you will see errors such as the following:
Failed build userPassword attributeSee Also
How do I create a new connector configuration via REST in IDM (All versions)?