ICF 1.5.20.21

Configure connectors

You configure connectors through the ICF provisioner service, and access them over REST at the openidm/conf endpoint.

Connector configurations are stored in files in your project’s conf/ directory, and are named project-dir/conf/provisioner.openicf-name where name corresponds to the name of the connector. If you are creating your own connector configuration files, do not include additional dash characters (-) in the connector name, as this can cause problems with the OSGi parser. For example, provisioner.openicf-hrdb.json is acceptable, and provisioner.openicf-hr-db.json is not.

You can create a connector configuration in the following ways:

Sample provisioner files

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

The following example shows a high-level connector configuration. The individual configuration objects are described in detail later in this section:

{
  "connectorRef"              : connector-ref-object,
  "producerBufferSize"        : integer,
  "connectorPoolingSupported" : boolean, true/false,
  "poolConfigOption"          : pool-config-option-object,
  "operationTimeout"          : operation-timeout-object,
  "configurationProperties"   : configuration-properties-object,
  "syncFailureHandler"        : sync-failure-handler-object,
  "resultsHandlerConfig"      : results-handler-config-object,
  "excludeUnmodified"         : boolean, true/false,
  "objectTypes"               : object-types-object,
  "operationOptions"          : operation-options-object
}

Configure connectors with the admin UI

To configure connectors in the admin UI, select Configure > Connector.

If your project has an existing connector configuration (for example, if you have started IDM with one of the sample configurations), click on that connector to edit it. If you’re starting with a new project, click New Connector to configure a new connector.

The connectors displayed on the Connectors page reflect the provisioner files in your project’s conf/ directory. To add a new connector configuration, you can also copy a provisioner file from the /path/to/openidm/samples/example-configurations/provisioners directory, then edit it to fit your deployment.

When you add a new connector, the Connector Type dropdown list reflects the connector .jar files that are in the /path/to/openidm/connectors directory. You can have more than one connector configuration for a specific connector type. For example, you might use the LDAP connector to set up two connector configurations—one to an Active Directory server and one to a ForgeRock Directory Services (DS) instance.

The Connector Types listed here do not include all supported connectors. The scripted connectors (such as scripted Groovy, scripted REST, scripted SQL, and PowerShell) are not available in the list of connector types. In general, the scripted connectors require extensive custom configuration changes, and a single HTML template to cover all possible permutations is not feasible. To add a scripted connector configuration, configure the connector over REST.

Alternatively, copy one of the example provisioner files in /path/to/openidm/samples/example-configurations/provisioners into your project’s conf directory and edit the configuration directly in the provisioner file.

Additional connectors are available from the ForgeRock BackStage download site site. For connectors that are not bundled with IDM, the UI displays a generic template, based on the schema provided by the connector.

The tabs on the connector configuration screens correspond to the objects and properties described in the remaining sections of this chapter.

When a connector configuration is complete, and IDM is able to establish the connection to the remote resource, the Data tab displays the objects in that remote resource. For example, the following image shows the contents of a connected LDAP resource:

connector-config-data
Figure 1. Data Tab For a Connected LDAP Resource

You can search through these objects with either the Basic Filter shown in each column, or the Advanced Filter option, which lets you build many of the queries shown in Define and call data queries.

Configure connectors over REST

To create a new connector configuration over REST, follow these steps:

  1. List the available connectors.

  2. Generate the core configuration.

  3. Add the target system properties, then connect to the target system to generate the final configuration.

  4. Submit the final configuration to IDM.

This procedure walks you through creating a connector configuration over REST, for a CSV file connector.

  1. List the available connectors.

    In a default IDM installation, the available connectors are installed in the openidm/connectors directory. If you are using a remote connector server, additional connectors might be available in the openicf/connectors directory on the remote server.

    Run the following command to list the available connectors:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system?_action=availableConnectors"

    On a default IDM installation, this command returns the following output:

    Sample output 
    {
  "connectorRef": [
    {
      "displayName": "SSH Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.ssh-connector",
      "connectorName": "org.forgerock.openicf.connectors.ssh.SSHConnector"
    },
    {
      "displayName": "ServiceNow Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.servicenow-connector",
      "connectorName": "org.forgerock.openicf.connectors.servicenow.ServiceNowConnector"
    },
    {
      "displayName": "Scripted SQL Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.scriptedsql-connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"
    },
    {
      "displayName": "Scripted REST Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"
    },
    {
      "displayName": "SCIM Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.scim-connector",
      "connectorName": "org.forgerock.openicf.connectors.scim.ScimConnector"
    },
    {
      "displayName":"Salesforce Connector",
      "bundleVersion":"1.5.20.21",
      "systemType":"provisioner.openicf",
      "bundleName":"org.forgerock.openicf.connectors.salesforce-connector",
      "connectorName":"org.forgerock.openicf.connectors.salesforce.SalesforceConnector"
    },
    {
      "displayName":"MSGraphAPI Connector",
      "bundleVersion":"1.5.20.21",
      "systemType":"provisioner.openicf",
      "bundleName":"org.forgerock.openicf.connectors.msgraphapi-connector",
      "connectorName":"org.forgerock.openicf.connectors.msgraphapi.MSGraphAPIConnector"
    },
    {
      "displayName": "MongoDB Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.mongodb-connector",
      "connectorName": "org.forgerock.openicf.connectors.mongodb.MongoDBConnector"
    },
    {
      "displayName": "Marketo Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.marketo-connector",
      "connectorName": "org.forgerock.openicf.connectors.marketo.MarketoConnector"
    },
    {
      "displayName": "LDAP Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
      "connectorName": "org.identityconnectors.ldap.LdapConnector"
    },
    {
      "displayName": "Kerberos Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.kerberos-connector",
      "connectorName": "org.forgerock.openicf.connectors.kerberos.KerberosConnector"
    },
    {
      "displayName": "Scripted Poolable Groovy Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedPoolableConnector"
    },
    {
      "displayName": "Scripted Groovy Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedConnector"
    },
    {
      "displayName": "GoogleApps Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.googleapps-connector",
      "connectorName": "org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector"
    },
    {
      "displayName": "Database Table Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.databasetable-connector",
      "connectorName": "org.identityconnectors.databasetable.DatabaseTableConnector"
    },
    {
      "displayName": "CSV File Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
      "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector"
    },
    {
      "displayName": "Adobe Marketing Cloud Connector",
      "bundleVersion": "1.5.20.21",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.adobecm-connector",
      "connectorName": "org.forgerock.openicf.acm.ACMConnector"
    }
  ]
}

  2. Generate a core configuration.

    Locate the connector to configure from the previous step’s output, and copy the JSON object to insert as the value of the "connectorRef" property in the data payload of the following command.

    This example generates a core configuration for the CSV file connector:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{"connectorRef":
  {
    "systemType": "provisioner.openicf",
    "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
    "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector",
    "displayName": "CSV File Connector",
    "bundleVersion": "1.5.20.21"
  }
}' \
"http://localhost:8080/openidm/system?_action=createCoreConfig"

    The command returns a connector configuration, similar to the following:

    {
  "connectorRef": {
    "systemType": "provisioner.openicf",
    "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
    "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector",
    "displayName": "CSV File Connector",
    "bundleVersion": "1.5.20.21"
  },
  "poolConfigOption": {
    "maxObjects": 10,
    "maxIdle": 10,
    "maxWait": 150000,
    "minEvictableIdleTimeMillis": 120000,
    "minIdle": 1
  },
  "resultsHandlerConfig": {
    "enableNormalizingResultsHandler": false,
    "enableFilteredResultsHandler": false,
    "enableCaseInsensitiveFilter": false,
    "enableAttributesToGetSearchResultsHandler": true
  },
  "operationTimeout": {
    "CREATE": -1,
    "UPDATE": -1,
    "DELETE": -1,
    "TEST": -1,
    "SCRIPT_ON_CONNECTOR": -1,
    "SCRIPT_ON_RESOURCE": -1,
    "GET": -1,
    "RESOLVEUSERNAME": -1,
    "AUTHENTICATE": -1,
    "SEARCH": -1,
    "VALIDATE": -1,
    "SYNC": -1,
    "SCHEMA": -1
  },
  "configurationProperties": {
    "headerPassword": "password",
    "spaceReplacementString": "_",
    "csvFile": null,
    "newlineString": "\n",
    "headerUid": "uid",
    "quoteCharacter": "\"",
    "escapeCharacter": "\\",
    "fieldDelimiter": ",",
    "syncFileRetentionCount": 3
  }
}

  3. Connect to the target system to generate the final configuration.

    The configuration returned in the previous step is not functional. It does not include the required configurationProperties that are specific to the target system (such as the host name and port number of the target system, or the csvFile for a CSV file connector). It also doesn’t include the complete list of objectTypes and operationOptions.

    To connect to the target system, add values for the required configurationProperties, and submit the updated configuration in the data payload of the following command.

    This example connects to the specified CSV file:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "configurationProperties": {
    "headerPassword": "password",
    "spaceReplacementString": "_",
    "csvFile": "&{idm.instance.dir}/data/csvConnectorData.csv",
    "newlineString": "\n",
    "headerUid": "uid",
    "quoteCharacter": "\"",
    "fieldDelimiter": ",",
    "syncFileRetentionCount": 3
  },
  "connectorRef": {
    "systemType": "provisioner.openicf",
    "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
    "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector",
    "displayName": "CSV File Connector",
    "bundleVersion": "1.5.20.21"
  },
  "poolConfigOption": {
    "maxObjects": 10,
    "maxIdle": 10,
    "maxWait": 150000,
    "minEvictableIdleTimeMillis": 120000,
    "minIdle": 1
  },
  "resultsHandlerConfig": {
    "enableNormalizingResultsHandler": true,
    "enableFilteredResultsHandler": true,
    "enableCaseInsensitiveFilter": false,
    "enableAttributesToGetSearchResultsHandler": true
  },
  "operationTimeout": {
    "CREATE": -1,
    "UPDATE": -1,
    "DELETE": -1,
    "TEST": -1,
    "SCRIPT_ON_CONNECTOR": -1,
    "SCRIPT_ON_RESOURCE": -1,
    "GET": -1,
    "RESOLVEUSERNAME": -1,
    "AUTHENTICATE": -1,
    "SEARCH": -1,
    "VALIDATE": -1,
    "SYNC": -1,
    "SCHEMA": -1
  }
}' \
"http://localhost:8080/openidm/system?_action=createFullConfig"
    The single quotes around the JSON object in the --data parameter prevent the command from being executed when a new line is encountered in the content. You can therefore include line feeds for readability.

    With this command, IDM connects to the target resource, and attempts to read the schema, if it is available. It then iterates through the schema objects and attributes, and creates JSON representations of the supported objects and operations. The command output includes the JSON payload that you submitted, along with the operationOptions and objectTypes.

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

  4. When you have the final configuration, use a PUT request to add it to the IDM configuration, in the JSON payload of the following command:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{complete-configuration}' \
"http://localhost:8080/openidm/config/provisioner.openicf/connector-name"

    Alternatively, you can save the complete configuration in a file named provisioner.openicf-connector-name.json, and place the file in the conf directory of your project.

Connector reference properties

The following example shows a connector reference object:

"connectorRef" : {
    "bundleName"    : "org.forgerock.openicf.connectors.csvfile-connector",
    "bundleVersion" : "[1.5.0.0,1.6.0.0)",
    "connectorName" : "org.forgerock.openicf.csvfile.CSVFileConnector",
    "connectorHostRef" : "csv"
}
bundleName

string, required

The ConnectorBundle-Name of the ICF connector.

bundleVersion

string, required

The ConnectorBundle-Version of the ICF connector. The value can be a single version (such as 1.4.0.0) or a range of versions, which lets you support multiple connector versions in a single project.

You can specify a range of versions as follows:

  • [1.1.0.0,1.4.0.0] indicates that all connector versions from 1.1 to 1.4, inclusive, are supported.

  • [1.1.0.0,1.4.0.0) indicates that all connector versions from 1.1 to 1.4, including 1.1 but excluding 1.4, are supported.

  • (1.1.0.0,1.4.0.0] indicates that all connector versions from 1.1 to 1.4, excluding 1.1 but including 1.4, are supported.

  • (1.1.0.0,1.4.0.0) indicates that all connector versions from 1.1 to 1.4, exclusive, are supported.

When a range of versions is specified, IDM uses the latest connector that is available within that range. If your project requires a specific connector version, you must explicitly state the version in your connector configuration file, or constrain the range to address only the version that you need.

connectorName

string, required

The connector implementation class name.

connectorHostRef

string, optional

If the connector runs remotely, the value of this field must match the name field of the RemoteConnectorServers object in the connector server configuration file (provisioner.openicf.connectorinfoprovider.json). For example:

...
    "remoteConnectorServers" :
        [
            {
                "name" : "dotnet",
                ...
            }
        ]
...

If the connector runs locally, the value of this field can be one of the following:

  • If the connector .jar is installed in openidm/connectors/ , the value must be "#LOCAL". This is currently the default, and recommended location.

  • If the connector .jar is installed in openidm/bundle/ (not recommended), the value must be "osgi:service/org.forgerock.openicf.framework.api.osgi.ConnectorManager".

Pool configuration

The poolConfigOption specifies the pool configuration for poolable connectors only (connectors that have "connectorPoolingSupported" : true). Non-poolable connectors ignore this parameter.

The following example shows a pool configuration option object for a poolable connector:

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

The maximum number of idle and active instances of the connector.

maxIdle

The maximum number of idle instances of the connector.

maxWait

The maximum time, in milliseconds, that the pool waits for an object before timing out. A value of 0 means that there is no timeout.

minEvictableIdleTimeMillis

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.

minIdle

The minimum number of idle instances of the connector.

Operation timeouts

The operation timeout property enables you to configure timeout values per operation type. By default, no timeout is configured for any operation type. A sample configuration follows:

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

Timeout in milliseconds

A value of -1 disables the timeout.

Connection configuration

The configurationProperties object specifies the configuration for the connection between the connector and the resource, and is therefore resource-specific.

The following example shows a configuration properties object for the default CSV sample resource connector:

"configurationProperties" : {
    "csvFile" : "&{idm.instance.dir}/data/csvConnectorData.csv"
}
property

Individual properties depend on the type of connector.

Synchronization failure configuration

The syncFailureHandler object specifies what should happen if a liveSync operation reports a failure for an operation. The following example shows a synchronization failure configuration:

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

positive integer or -1, required

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

postRetryAction

string, required

The action that should be taken if the synchronization operation fails after the specified number of attempts. The post retry action can be one of the following:

  • logged-ignore - IDM ignores the failed modification, and logs its occurrence.

  • dead-letter-queue - IDM saves the details of the failed modification in a table in the repository (accessible over REST at repo/synchronisation/deadLetterQueue/provisioner-name).

  • script specifies a custom script that should be executed when the maximum number of retries has been reached.

For more information, refer to Configure the LiveSync Retry Policy.

Configure how results are handled

The resultsHandlerConfig object specifies how OpenICF returns results. These configuration properties do not apply to all connectors and depend on the interfaces that are implemented by each connector. For information about the interfaces that connectors support, refer to the Connector reference.

The following example shows a results handler configuration object:

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

boolean, false by default

When this property is enabled, ICF normalizes returned attributes to ensure that they are filtered consistently. If the connector implements the attribute normalizer interface, enable the interface by setting this property to true. If the connector does not implement the attribute normalizer interface, the value of this property has no effect.

enableFilteredResultsHandler

boolean, false by default

Most connectors use the filtering and search capabilities of the remote connected system. In these cases, you can leave this property set to false. If the connector does not use the remote system’s filtering and search capabilities, you must set this property to true.

All the non-scripted connectors, except for the CSV connector, use the filtering mechanism of the remote system. In the case of the CSV connector, the remote resource has no filtering mechanism, so you must set enableFilteredResultsHandler to true. For the scripted connectors, the setting will depend on how you have implemented the connector.

enableCaseInsensitiveFilter

boolean, false by default

This property applies only if enableFilteredResultsHandler is set to true. The filtered results handler is case-sensitive by default. For example, a search for lastName = "Jensen" will not match a stored user with lastName : jensen. When the filtered results handler is enabled, you can use this property to enable case-insensitive filtering. If you leave this property set to false, searches on that resource will be case-sensitive.

enableAttributesToGetSearchResultsHandler

boolean, false by default

By default, IDM determines which attributes should be retrieved in a search. If you set this property to true, the ICF framework removes all attributes from the READ/QUERY response, except for those that are specifically requested. For performance reasons, you should set this property to false for local connectors and to true for remote connectors.

Specify which attributes are updated

The excludeUnmodified property determines which properties are updated during synchronization. When this property is set to true, synchronization operations update only the modified properties on a target resource, rather than the whole target object. The default behavior is to include all attributes. In the sample LDAP provisioner files provided with IDM, excludeUnmodified is set to true, so unmodified attributes are excluded during update operations.

Set the supported object types

The objectTypes configuration specifies the object types (user, group, account, and so on) that are supported by the connector. The object names that you define here determine how the object is accessed in the URI. For example:

system/systemName/objectType

This configuration is based on the JSON Schema with the extensions described in the following section.

Attribute names that start or end with __ are regarded as special attributes by OpenICF. The purpose of the special attributes in ICF is to enable someone who is developing a new connector to create a contract regarding how a property can be referenced, regardless of the application that is using the connector. In this way, the connector can map specific object information between an arbitrary application and the resource, without knowing how that information is referenced in the application.

These attributes have no specific meaning in the context of IDM, although some of the connectors that are bundled with IDM use these attributes. The generic LDAP connector, for example, can be used with ForgeRock Directory Services (DS), Active Directory, OpenLDAP, and other LDAP directories. Each of these directories might use a different attribute name to represent the same type of information. For example, Active Directory uses unicodePassword and DS uses userPassword to represent the same thing, a user’s password. The LDAP connector uses the special OpenICF __PASSWORD__ attribute to abstract that difference. In the same way, the LDAP connector maps the __NAME__ attribute to an LDAP dn.

The ICF __UID__ is a special case. The __UID__ must not be included in the IDM configuration or in any update or create operation. This attribute denotes the unique identity attribute of an object and IDM always maps it to the _id of the object.

The following excerpt shows the configuration of an account object type:

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

ICF supports an __ALL__ object type that ensures that objects of every type are included in a synchronization operation. The primary purpose of this object type is to prevent synchronization errors when multiple changes affect more than one object type.

For example, imagine a deployment synchronizing two external systems. On system A, the administrator creates a user, jdoe, then adds the user to a group, engineers. When these changes are synchronized to system B, if the __GROUPS__ object type is synchronized first, the synchronization will fail, because the group contains a user that does not yet exist on system B. Synchronizing the __ALL__ object type ensures that user jdoe is created on the external system before he is added to the group engineers.

The __ALL__ object type is assumed by default - you do not need to declare it in your provisioner configuration file. If it is not declared, the object type is named __ALL__. If you want to map a different name for this object type, declare it in your provisioner configuration. The following excerpt from a sample provisioner configuration uses the name allobjects:

"objectTypes": {
    "allobjects": {
        "$schema": "http://json-schema.org/draft-03/schema",
        "id": "__ALL__",
        "type": "object",
        "nativeType": "__ALL__"
    },
    ...
}

A liveSync operation invoked with no object type assumes an object type of __ALL__. For example, the following call invokes a liveSync operation on all defined object types in an LDAP system:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/ldap?_action=liveSync"

Using the __ALL__ object type requires a mechanism to ensure the order in which synchronization changes are processed. Servers that use the cn=changelog mechanism to order sync changes, such as ForgeRock Directory Services (DS), Oracle DSEE, and the legacy Sun Directory Server, cannot use the __ALL__ object type by default. Such servers must be forced to use timestamps to order their sync changes. For these LDAP server types, set useTimestampsForSync to true in the provisioner configuration.

Additionally, you can use the timestampSyncOffset LDAP configuration property to account for replication delays between LDAP instances. Refer to LDAP connector.

LDAP servers that use timestamps rather than change logs (such as Active Directory GCs and OpenLDAP) can use the __ALL__ object type without any additional configuration. Active Directory and Active Directory LDS, which use Update Sequence Numbers, can also use the __ALL__ object type without additional configuration.

Add objects and properties through the UI

To add object types and properties to a connector configuration by using the admin UI, select Configure > Connectors. Select the connector that you want to change, then select the Object Types tab.

In the case of the LDAP connector, the connector reads the schema from the remote resource to determine the object types and properties that can be added to its configuration. When you select one of these object types, you can think of it as a template. Edit the basic object type, as required, to suit your deployment.

To add a property to an object type, select the Edit icon next to the object type, then select Add Property.

Specify object types on the external resource

At the object level, the nativeType property refers to an object type supported by a connector or external resource. For example, an LDAP connector might have object types such as __ACCOUNT__ and __GROUP__.

nativeType

string, optional

The native ICF object type.

The value of this property must be an object type supported by the resource or the connector.

Behavior for empty attributes

The absentIfEmpty and absentIfNull object class properties enable you to specify how attributes are handled during synchronization if their values are null (for single-valued attributes) or empty (for multi-valued attributes). You can set these properties per object type.

By default, these properties are set as follows:

"absentIfEmpty" : false

Multi-valued attributes whose values are empty are included in the resource response during synchronization.

"absentIfNull" : true

Single-valued attributes whose values are null are removed from the resource response during synchronization.

Specify attribute types on the external resource

At the property level, nativeType refers to the data type of an attribute on the external resource.

nativeType

string, optional

The native ICF attribute type.

The following native types are supported:

JAVA_TYPE_BIGDECIMAL
JAVA_TYPE_BIGINTEGER
JAVA_TYPE_BYTE
JAVA_TYPE_BYTE_ARRAY
JAVA_TYPE_CHAR
JAVA_TYPE_CHARACTER
JAVA_TYPE_DATE
JAVA_TYPE_DOUBLE
JAVA_TYPE_FILE
JAVA_TYPE_FLOAT
JAVA_TYPE_GUARDEDBYTEARRAY
JAVA_TYPE_GUARDEDSTRING
JAVA_TYPE_INT
JAVA_TYPE_INTEGER
JAVA_TYPE_LONG
JAVA_TYPE_OBJECT
JAVA_TYPE_PRIMITIVE_BOOLEAN
JAVA_TYPE_PRIMITIVE_BYTE
JAVA_TYPE_PRIMITIVE_DOUBLE
JAVA_TYPE_PRIMITIVE_FLOAT
JAVA_TYPE_PRIMITIVE_LONG
JAVA_TYPE_STRING

  • IDM only handles JSON primitive types (boolean, map, list, number, and string). You must encode any non-JSON primitive types so that they can be stored as JSON.

    As a general rule, your connector configurations should always map the property type on the external resource (nativeType) to a supported JSON primitive type in IDM. If you are synchronizing pre-hashed passwords, set the nativeType to a JAVA_TYPE_BYTE_ARRAY, and the IDM type to a string, for example:

    ...
    "userPassword" : {
        "type" : "string",
        "nativeName" : "userPassword",
        "nativeType" : "JAVA_TYPE_BYTE_ARRAY"
    },
...

    With this configuration, when a userPassword is read from the remote system, it is returned as a Byte[] by the connector. It is then converted to a String (Base64-encoded Byte[]) by IDM.

    Alternatively, you can make sure that any non-JSON primitive types returned by your connector are appropriately transformed into an encoded string value in your mapping. For example:

    {
    "source": "password",
    "target": "password",
    "transform": {
        "type": "text/javascript",
        "source": "source.toString();"
    }
},

  • The JAVA_TYPE_DATE property is deprecated. Functionality may be removed in a future release. This type is an alias for string. Any dates with this type should be formatted according to ISO 8601.
nativeName

string, optional

The native ICF attribute name.

flags

string, optional

The native ICF attribute flags. ICF supports the following attribute flags:

MULTIVALUED

The property can be multivalued.

For multi-valued properties, if the property value type is anything other than a string, you must include an items property that declares the data type.

The following example shows the entries property of the authentication object in a provisioner file. The entries property is multi-valued, and its elements are of type object:

"authentication" : {
    ...
    "properties" : {
        ...
        "entries" : {
            "type" : "object",
            "required" : false,
            "nativeName" : "entries",
            "nativeType" : "object",
                "items" : {
                    "type" : "object"
                },
            "flags" : [
                "MULTIVALUED"
            ]
        },
        ...
    },
    ...
}
When comparing multi-valued properties across systems, the order of the values is important. Two properties with the same values, but in different orders, will be seen as a change during reconciliation, regardless of whether the value has actually changed.
NOT_CREATABLE, NOT_READABLE, NOT_UPDATEABLE

In some cases, the connector might not support manipulating an attribute because the attribute can only be changed directly on the remote system. For example, if the name attribute of an account can only be created by Active Directory, and never changed by IDM, you would add NOT_CREATABLE and NOT_UPDATEABLE to the provisioner configuration for that attribute.

NOT_RETURNED_BY_DEFAULT

Some attributes, such as LDAP groups or other calculated attributes, can be expensive to read. To avoid returning these attributes in a default read of the object, unless they are explicitly requested, add the NOT_RETURNED_BY_DEFAULT flag to the provisioner configuration for that attribute.

You can also use this flag to prevent properties from being read by default during a synchronization operation. To synchronize changes to a target object, IDM performs an UPDATE rather than a PATCH. This causes all attributes that are mapped from the source to the target to be modified when the synchronization is processed (rather than only those attributes that have changed). Although the value of a property might not change, the property still registers an update. This behavior can be problematic for properties such as the password, which might have restrictions on updating with a similar value. To prevent such properties from being updated during synchronization, set the NOT_RETURNED_BY_DEFAULT flag, which effectively prevents the property from being read from the source during the synchronization. For example:

"__PASSWORD__" : {
    "type" : "string",
    "nativeName" : "__PASSWORD__",
    "nativeType" : "JAVA_TYPE_GUARDEDSTRING",
    "flags" : [
        "NOT_RETURNED_BY_DEFAULT"
    ],
    "runAsUser" : true
}

You can configure connectors to enable provisioning of any arbitrary property. For example, the following property definitions would enable you to provision image files, used as avatars, to account objects in a system resource. The first definition would work for a single photo encoded as a base64 string. The second definition would work for multiple photos encoded in the same way:

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

Do not use the dash character ( - ) in property names, like last-name. Dashes in names make JavaScript syntax more complex. If you cannot avoid the dash, write source['last-name'] instead of source.last-name in your JavaScript scripts.

Configure operation options

The operationOptions object enables you to deny specific operations on a resource. For example, you can use this configuration object to deny CREATE and DELETE operations on a read-only resource to avoid IDM accidentally updating the resource during a synchronization operation.

The following example defines the options for the "SYNC" operation:

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

The ICF Framework supports the following operations:

  • AUTHENTICATE

  • CREATE

  • DELETE

  • GET

  • RESOLVEUSERNAME

  • SCHEMA

  • SCRIPT_ON_CONNECTOR

  • SCRIPT_ON_RESOURCE

  • SEARCH

  • SYNC

  • TEST

  • UPDATE

  • VALIDATE

For detailed information on these operations, refer to the ICF API documentation.

The operationOptions object has the following configurable properties:

denied

boolean, optional

This property prevents operation execution if the value is true.

onDeny

string, optional

If denied is true, then the service uses this value. Default value: DO_NOTHING.

  • DO_NOTHING: On operation the service does nothing.

  • THROW_EXCEPTION: On operation the service throws a ForbiddenException exception.

Copyright © 2010-2024 ForgeRock, all rights reserved.