<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-resource-conf'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>Resource Connector Configuration</title>

<para>This chapter describes how to connect to external resources such

as LDAP, Active Directory, flat files, and others. Configurations shown

here are simplified to show essential aspects. Not all resources are

suited to all OpenIDM operations, though the resources shown here support

most of CRUD, and also reconciliation and LiveSync.</para>

<para>In OpenIDM, <firstterm>resources</firstterm> are external systems,

databases, directory servers, and other sources of user data to be maintained

and audited by the identity management system. OpenIDM connects to resources

through the identity connector framework, <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/">OpenICF</link>. OpenICF aims to

avoid the need to install agents to access resources, instead using the

resources' native protocols. For example, OpenICF connects to database

resources using the database's Java connection libraries or JDBC driver.

It connects to directory servers over JNDI. It connects to operating systems

by using <command>ssh</command>.</para>

<section xml:id="openidm-openicf">

<title>OpenIDM &amp; OpenICF</title>

<para>The following figure shows how OpenIDM can connect to resources through

an OpenICF server. In most cases, the OpenICF server runs as part of

OpenIDM.</para>

<mediaobject>

<alt>OpenICF architecture</alt>

<imageobject>

<imagedata fileref="images/OpenICFarc.png" format="PNG" />

</imageobject>

<textobject>

<para>The figure shows the basic architecture of OpenIDM with two connector

servers, one built-in local java server, and another remote, .NET

server.</para>

</textobject>

</mediaobject>

<para>OpenICF provides a common service provider interface to allow identity

services access to the resources containing user information. OpenICF uses

a connection server that can run as a local connector server inside OpenIDM,

or as a remote connector server that is a stand-alone process.</para>

<para>You might use a remote connector server when you need to access

libraries that cannot be included as part of the OpenIDM process. If a

resource, such as Microsoft ADSI, does not provide a connection library that

you can include inside the Java Virtual Machine, then OpenICF can use the

native .dll with a remote connector server. (OpenICF connects to ADSI through

a remote connector server implemented as a .NET service.)</para>

</section>

<section xml:id="connector-info-provider-conf">

<title>Connector Info Provider Service</title>

<para>The connector info provider service takes this configuration.</para>

<programlisting language="javascript">

{

"connectorsLocation" : <replaceable>string</replaceable>,

"remoteConnectorServers" : [<replaceable>remoteConnectorServer objects</replaceable>]

}</programlisting>

<variablelist>

<varlistentry>

<term>connectorsLocation</term>

<listitem>

<para>string, optional</para>

<para>Specifies the directory where OpenICF connectors are located. The

default location is <filename>connectors</filename>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>remoteConnectorServers</term>

<listitem>

<para>array of RemoteConnectorServer objects, optional</para>

<para>A list of remote connector servers managed by this service.</para>

</listitem>

</varlistentry>

</variablelist>

<para>The following example shows a <literal>remoteConnectorServer</literal>

object configuration.</para>

<programlisting language="javascript">

{

"name" : "testServer",

"host" : "127.0.0.1",

"port" : 8759,

"useSSL" : false,

"timeout" : 0,

"key" : "Passw0rd",

"trustManagers" :

[

"X509TrustManager",

"BlindTrustManager"

]

}</programlisting>

<variablelist xml:id="remote-connector-server-object-properties">

<title>Remote Connector Server Object Properties</title>

<para>OpenIDM supports the following remote connector server object

properties.</para>

<varlistentry>

<term>name</term>

<listitem>

<para>string, required</para>

<para>The name of the remote connector server object. Used to identify the

remote connector server in connector reference object.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>host</term>

<listitem>

<para>string, required</para>

<para>Remote host to connect to.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>port</term>

<listitem>

<para>string, optional</para>

<para>

Remote port to connect to. Default value: 8759</para>

</listitem>

</varlistentry>

<varlistentry>

<term>useSSL</term>

<listitem>

<para>boolean, optional</para>

<para>Specifies to use or not SSL to connect. Default value:

<literal>false</literal></para>

</listitem>

</varlistentry>

<varlistentry>

<term>timeout</term>

<listitem>

<para>integer, optional</para>

<para>Specifies the timeout (in milliseconds) to use for the connection.

Default value: 0</para>

</listitem>

</varlistentry>

<varlistentry>

<term>key</term>

<listitem>

<para>string, required</para>

<para>The secret key to use to authenticate to the remote connector

server.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>trustManagers</term>

<listitem>

<para>not specified</para>

<para>Not implemented yet. The service uses the default JVM

<literal>TrustManager</literal>.</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="openicf-provisioner-conf">

<title>OpenICF Provisioner Service</title>

<para>The following example shows an OpenICF provisioner service

configuration.</para>

<programlisting language="javascript">{

"name" : "xml",

"connectorRef" : <link linkend="connector-reference">connector-ref-object</link>,

"poolConfigOption" : <link linkend="pool-configuration-option">pool-config-option-object</link>,

"operationTimeout" : <link linkend="operation-timeout">operation-timeout-object</link>,

"configurationProperties" : <link linkend="configuration-properties">configuration-properties-object</link>,

"objectTypes" : <link linkend="object-types">object-types-object</link>,

"operationOptions" : <link linkend="operation-options">operation-options-object</link>

}</programlisting>

<variablelist xml:id="connector-reference">

<title>Connector Reference</title>

<para>The following example shows a connector reference object.</para>

<programlisting language="javascript">

{

"bundleName" : "org.forgerock.openicf.connectors.file.xml",

"bundleVersion" : "1.1.0.0-SNAPSHOT",

"connectorName" : "com.forgerock.openicf.xml.XMLConnector",

"connectorHostRef" : "host"

}</programlisting>

<varlistentry>

<term>bundleName</term>

<listitem>

<para>string, required</para>

<para>The <replaceable>ConnectorBundle-Name</replaceable> of the OpenICF

connector.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>bundleVersion</term>

<listitem>

<para>string, required</para>

<para>The <replaceable>ConnectorBundle-Version</replaceable> of the

OpenICF connector.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>connectorName</term>

<listitem>

<para>string, required</para>

<para>The Connector implementation class name.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>connectorHostRef</term>

<listitem>

<para>string, optional</para>

<para>The name of the RemoteConnectorServer object.</para>

<itemizedlist>

<listitem>

<para>If the connector server is local and the connector .jar is

installed in <filename>openidm/bundle/</filename>, then the value

must be

<literal>"osgi:service/org.forgerock.openicf.framework.api.osgi.ConnectorManager"</literal>.</para>

</listitem>

<listitem>

<para>If the connector server is local and the connector .jar is

installed in <filename>openidm/connectors/</filename>, then the value

must be <literal>"#LOCAL"</literal>.</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

</variablelist>

<variablelist xml:id="pool-configuration-option">

<title>Pool Configuration Option</title>

<para>The following example shows a pool configuration option object

for the connection pool between OpenIDM and the OpenICF connector

server.</para>

<programlisting language="javascript">

{

"maxObjects" : 10,

"maxIdle" : 10,

"maxWait" : 150000,

"minEvictableIdleTimeMillis" : 120000,

"minIdle" : 1

}</programlisting>

<varlistentry>

<term>maxObjects</term>

<listitem>

<para>TODO</para>

</listitem>

</varlistentry>

<varlistentry>

<term>maxIdle</term>

<listitem>

<para>TODO</para>

</listitem>

</varlistentry>

<varlistentry>

<term>maxWait</term>

<listitem>

<para>TODO</para>

</listitem>

</varlistentry>

<varlistentry>

<term>minEvictableIdleTimeMillis</term>

<listitem>

<para>TODO</para>

</listitem>

</varlistentry>

<varlistentry>

<term>minIdle</term>

<listitem>

<para>TODO</para>

</listitem>

</varlistentry>

</variablelist>

<variablelist xml:id="operation-timeout">

<title>Operation Timeout</title>

<para>This configuration sets the timeout per operation type.</para>

<programlisting language="javascript">

{

"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

}</programlisting>

<varlistentry>

<term><replaceable>operation-name</replaceable></term>

<listitem>

<para>Timeout in milliseconds</para>

<para>A value of <literal>-1</literal> disables the timeout.</para>

</listitem>

</varlistentry>

</variablelist>

<variablelist xml:id="configuration-properties">

<title>Configuration Properties</title>

<para>This object contains the configuration for the connection between

the connection server and the resource, and is therefore resource

specific.</para>

<para>The following example shows a configuration properties object for

the default XML sample resource connector.</para>

<programlisting language="javascript">

{

"xsdIcfFilePath": "samples/sample1/data/resource-schema-1.xsd",

"xsdFilePath": "samples/sample1/data/resource-schema-extension.xsd",

"xmlFilePath": "samples/sample1/data/xmlConnectorData.xml"

}</programlisting>

<varlistentry>

<term><replaceable>property</replaceable></term>

<listitem>

<para>Individual properties depend on the type of connector.</para>

</listitem>

</varlistentry>

</variablelist>

<variablelist xml:id="object-types">

<title>Object Types</title>

<para>This configuration object specifies the supported object types. The

property name defines the <literal>objectType</literal> used in the

URI: <literal>system/$<replaceable >systemName</replaceable>/$<replaceable

>objectType</replaceable></literal></para>

<para>The configuration is based on <link xlink:show="new"

xlink:href="http://tools.ietf.org/html/draft-zyp-json-schema-03">JSON

Schema</link> with extensions described below.</para>

<para>Attribute names with start and end with <literal>__</literal> are

resource type specific attributes used by OpenICF for particular

purposes, such as <literal>__NAME__</literal> as the naming attribute

for objects on a resource.</para>

<programlisting language="javascript">

{

"account" :

{

"$schema" : "http://json-schema.org/draft-03/schema",

"id" : "__ACCOUNT__",

"type" : "object",

"nativeType" : "__ACCOUNT__",

"properties" :

{

"name" :

{

"type" : "string",

"nativeName" : "__NAME__",

"nativeType" : "JAVA_TYPE_PRIMITIVE_LONG",

"flags" :

[

"NOT_CREATABLE",

"NOT_UPDATEABLE",

"NOT_READABLE",

"NOT_RETURNED_BY_DEFAULT"

]

},

"groups" :

{

"type" : "array",

"items" :

{

"type" : "string",

"nativeType" : "string"

},

"nativeName" : "__GROUPS__",

"nativeType" : "string",

"flags" :

[

"NOT_RETURNED_BY_DEFAULT"

]

}

}

}

}</programlisting>

<varlistentry>

<term>Object Level Extensions</term>

<listitem>

<variablelist>

<varlistentry>

<term>nativeType</term>

<listitem>

<para>string, optional</para>

<para>The native OpenICF object type.</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

<varlistentry>

<term>Property Level Extensions</term>

<listitem>

<variablelist>

<varlistentry>

<term>nativeType</term>

<listitem>

<para>string, optional</para>

<para>The native OpenICF attribute type.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>nativeName</term>

<listitem>

<para>string, optional</para>

<para>The native OpenICF attribute name.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>flags</term>

<listitem>

<para>string, optional</para>

<para>The native OpenICF attribute flags. The

<replaceable>required</replaceable> and

<replaceable>multivalued</replaceable> flags are defined by the JSON

schema.</para>

<literallayout class="monospaced"

><replaceable>required</replaceable> = <literal

>"required" : true</literal></literallayout>

<literallayout class="monospaced"

><replaceable>multivalued</replaceable> = <literal

>"type" : "array"</literal></literallayout>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

</variablelist>

<variablelist xml:id="operation-options">

<title>Operation Options</title>

<para>Operation options define how to act on specified operations.

You can for example deny operations on specific resources to avoid

OpenIDM accidentally updating a read-only resource during a synchronization

operation.</para>

<programlisting language="javascript">

{

"SYNC" :

{

"denied" : true,

"onDeny" : "DO_NOTHING",

"objectFeatures" :

{

"__ACCOUNT__" :

{

"denied" : true,

"onDeny" : "THROW_EXCEPTION",

"operationOptionInfo" :

{

"$schema" : "http://json-schema.org/draft-03/schema",

"id" : "FIX_ME",

"type" : "object",

"properties" :

{

"_OperationOption-float" :

{

"type" : "number",

"nativeType" : "JAVA_TYPE_PRIMITIVE_FLOAT"

}

}

}

},

"__GROUP__" :

{

"denied" : false,

"onDeny" : "DO_NOTHING"

}

}

}

}</programlisting>

<itemizedlist>

<para>The list of operations is as follows.</para>

<listitem>

<para><literal>AUTHENTICATE</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/AuthenticationApiOp.html"

>AuthenticationApiOp</link></para>

</listitem>

<listitem>

<para><literal>CREATE</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/CreateApiOp.html"

>CreateApiOp</link></para>

</listitem>

<listitem>

<para><literal>DELETE</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/DeleteApiOp.html"

>DeleteApiOp</link></para>

</listitem>

<listitem>

<para><literal>GET</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/GetApiOp.html"

>GetApiOp</link></para>

</listitem>

<listitem>

<para><literal>RESOLVEUSERNAME</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/ResolveUsernameApiOp.html"

>ResolveUsernameApiOp</link></para>

</listitem>

<listitem>

<para><literal>SCHEMA</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/SchemaApiOp.html"

>SchemaApiOp</link></para>

</listitem>

<listitem>

<para><literal>SCRIPT_ON_CONNECTOR</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/ScriptOnConnectorApiOp.html"

>ScriptOnConnectorApiOp</link></para>

</listitem>

<listitem>

<para><literal>SCRIPT_ON_RESOURCE</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/ScriptOnResourceApiOp.html"

>ScriptOnResourceApiOp</link></para>

</listitem>

<listitem>

<para><literal>SEARCH</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/SearchApiOp.html"

>SearchApiOp</link></para>

</listitem>

<listitem>

<para><literal>SYNC</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/SyncApiOp.html"

>SyncApiOp</link></para>

</listitem>

<listitem>

<para><literal>TEST</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/TestApiOp.html"

>TestApiOp</link></para>

</listitem>

<listitem>

<para><literal>UPDATE</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/UpdateApiOp.html"

>UpdateApiOp</link></para>

</listitem>

<listitem>

<para><literal>VALIDATE</literal>: <link xlink:show="new"

xlink:href="http://openicf.forgerock.org/connector-framework/apidocs/org/identityconnectors/framework/api/operations/ValidateApiOp.html"

>ValidateApiOp</link></para>

</listitem>

</itemizedlist>

<varlistentry>

<term>denied</term>

<listitem>

<para>boolean, optional</para>

<para>This property prevents operation execution if the value is

<literal>true</literal>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>onDeny</term>

<listitem>

<para>string, optional</para>

<para>If <literal>denied</literal> is <literal>true</literal>, then the

service uses this value. Default value:

<literal>DO_NOTHING</literal>.</para>

<itemizedlist>

<listitem>

<para><literal>DO_NOTHING</literal>: On operation the service does

nothing.</para>

</listitem>

<listitem>

<para><literal>THROW_EXCEPTION</literal>: On operation the service

throws a <literal>ForbiddenException</literal> exception.</para>

</listitem>

</itemizedlist>

</listitem>

</varlistentry>

</variablelist>

</section>

<section><title>XML File Resource</title>

<section><title>Example connectorRef</title>

<para>The following code example shows a typical part of the provisioner configuration for an XML file connector.</para>

<example>

<title>Typical connectorRef for an XML resource configuration (provisioner-json)</title>

<programlisting>

"connectorRef" : {

"connectorHostRef" : "#LOCAL",

"bundleName" : "org.forgerock.openicf.connectors.file.file.openicf-xml-connector",

"bundleVersion" : "1.1.0.0-EA",

"connectorName" : "com.forgerock.openicf.xml.XMLConnector"

},

</programlisting>

</example>

<para>The connectorHostRef is optional if the connector server is local.</para>

</section>

<section><title>Typical configurationProperties configuration</title>

<example>

<title>configurationProperties of an XML connector configuration (provisioner-json)</title>

<programlisting>

"configurationProperties" : {

"xsdIcfFilePath" : "data/resource-schema-1.xsd",

"xsdFilePath" : "data/resource-schema-extension.xsd",

"xmlFilePath" : "data/xmlConnectorData.xml"

},

</programlisting>

</example>

<para>Where:</para>

<itemizedlist>

<listitem><para>xmlFilePath: references the xml file which contains the account entries</para></listitem>

<listitem><para>xsdIcfFilePath: references the xsd file with a schema common to all xml file resources; the file is not supposed to be changed</para></listitem>

<listitem><para>xsdFilePath: references a kind of custom schema; here any project individual attributes are defined</para></listitem>

</itemizedlist>

</section>

</section>

<section><title>Generic LDAP Connector</title>

<section><title>Example connectorRef</title>

<example>

<title>Example connectorRef for an LDAP connector configuration (provisioner-json)</title>

<programlisting>

"connectorRef" :

{

"connectorHostRef" : "#LOCAL",

"connectorName" : "org.identityconnectors.ldap.LdapConnector",

"bundleName" : "org.forgerock.openicf.connectors.ldap.openicf-ldap-connector",

"bundleVersion" : "1.1.0.0-EA"

},

</programlisting>

</example>

<para>In case of a local or built in connector server the connectorHostRef is optional if the connector jar is in openidm/connectors.</para>

</section>

<section><title>Typical configurationProperties configuration</title>

<example>

<title>configurationProperties of an XML connector configuration (provisioner-json)</title>

<programlisting>

{

"accountSynchronizationFilter" : null,

"passwordAttributeToSynchronize" : null,

"synchronizePasswords" : false,

"removeLogEntryObjectClassFromFilter" : true,

"modifiersNamesToFilterOut" : [...],

"passwordDecryptionKey" : null,

"credentials" : "Passw0rd",

"changeLogBlockSize" : 100,

"baseContextsToSynchronize" : [...],

"attributesToSynchronize" : [...],

"changeNumberAttribute" : "changeNumber",

"passwordDecryptionInitializationVector" : null,

"filterWithOrInsteadOfAnd" : false,

"objectClassesToSynchronize" : ["inetOrgPerson"],

"port" : 1389,

"vlvSortAttribute" : "uid",

"passwordAttribute" : "userPassword",

"useBlocks" : true,

"maintainPosixGroupMembership" : false,

"failover" : [...],

"ssl" : false,

"principal" : "cn=Directory Manager",

"baseContexts" : ["dc=example,dc=com"],

"readSchema" : true,

"accountObjectClasses" : ["top","person","organizationalPerson","inetOrgPerson"],

"accountUserNameAttributes" : ["uid","cn"],

"host" : "localhost",

"groupMemberAttribute" : "uniqueMember",

"accountSearchFilter" : null,

"passwordHashAlgorithm" : null,

"usePagedResultControl" : false,

"blockSize" : 100,

"uidAttribute" : "entryUUID",

"maintainLdapGroupMembership" : false,

"respectResourcePasswordPolicyChangeAfterReset" : false

},

</programlisting>

</example>

<para>Where:</para>

<itemizedlist>

<listitem><para>"accountSynchronizationFilter" : null-&gt;A filter used during synchronization actions to filter out ldap accounts</para></listitem>

<listitem><para>"accountObjectClasses" : ["top","person","organizationalPerson","inetOrgPerson"] -&gt; The object class or classes that will be used when creating new user objects in the LDAP tree. When entering more than one object class, each entry should be on its own line; do not use commas or semi-colons to separate multiple object classes. Some object classes may require that you specify all object classes in the class hierarchy.</para></listitem>

<listitem><para>"accountSearchFilter" : null -&gt; A search filter that any account needs to match in order to be returned.</para></listitem>

<listitem><para>"accountUserNameAttributes" : ["uid","cn"] -&gt; Attribute or attributes which holds the account''s user name. They will be used when authenticating to find the LDAP entry for the user name to authenticate.</para></listitem>

<listitem><para>"attributesToSynchronize" : [...] -&gt; List of attributes which should be used during object synchronization.This ignores updates from the change log if they do not update any of the named attributes. If empty, all changes will be used.</para></listitem>

<listitem><para>"baseContexts" : ["dc=example,dc=com"] -&gt; The base DNs for operations on the server.</para></listitem>

<listitem><para>"baseContextsToSynchronize" : [...] -&gt; the base contexts which will be taken into account durning synchronization</para></listitem>

<listitem><para>"blockSize" : 100 -&gt; The block size for simple paged results and VLV index searches. It is the maximum number of accounts that can be in a block when retrieving accounts in blocks.</para></listitem>

<listitem><para>"changeLogBlockSize" : 100 -&gt; The number of change log entries to fetch per query.</para></listitem>

<listitem><para>"changeNumberAttribute" : "changeNumber" -&gt; The name of the attribute which contains the last change number in the change log.</para></listitem>

<listitem><para>"credentials" : "Passw0rd" -&gt; The password of the user which is used to connect to the ldap server</para></listitem>

<listitem><para>"failover" : [...] -&gt; LDAP URL's to connect to if the main server specified through the host and port properties is not available.</para></listitem>

<listitem><para>"filterWithOrInsteadOfAnd" : false -&gt; Normally the the filter used to fetch change log entries is an and-based filter retrieving an interval of change entries. If this property is set, the filter will "or together" the required change numbers instead.</para></listitem>

<listitem><para>"groupMemberAttribute" : "uniqueMember" -&gt; The LDAP attribute holding the member for non-POSIX static groups.</para></listitem>

<listitem><para>"host" : "localhost" -&gt; The LDAP host server to connect to.</para></listitem>

<listitem><para>"maintainLdapGroupMembership" : false -&gt; If true, will modify group membership of renamed/deleted entries.</para></listitem>

<listitem><para>"maintainPosixGroupMembership" : false -&gt; If true, will modify POSIX group membership of renamed/deleted entries.</para></listitem>

<listitem><para>"modifiersNamesToFilterOut" : [...] -&gt; Useful to avoid loops caused by own changes.</para></listitem>

<listitem><para>"objectClassesToSynchronize" : ["inetOrgPerson"] -&gt; ObjectClasses to be used during synchronization. I.e. only objects with this objectClasses will be synchronized.</para></listitem>

<listitem><para>"passwordAttribute" : "userPassword" -&gt; The name of the attribute which the predefined PASSWORD attribute will be written to.</para></listitem>

<listitem><para>"passwordAttributeToSynchronize" : null -&gt; See above.</para></listitem>

<listitem><para>"passwordDecryptionInitializationVector" : null -&gt; Password Decryption Initialization Vector</para></listitem>

<listitem><para>"passwordDecryptionKey" : null -&gt; The key to decrypt passwords with when performing password synchronization.</para></listitem>

<listitem><para>"passwordHashAlgorithm" : null -&gt; If the server stores passwords in clear text, we will hash them with the algorithm specified here.</para></listitem>

<listitem><para>"port" : 1389 -&gt; The port the ldap server is listening on.</para></listitem>

<listitem><para>"principal" : "cn=Directory Manager" -&gt; The bind DN for performing operations on the server.</para></listitem>

<listitem><para>"readSchema" : true -&gt; Whether to read the schema from the server.</para></listitem>

<listitem><para>"removeLogEntryObjectClassFromFilter" : true -&gt; If this property is set (the default), the filter used to fetch change log entries does not contain the "changeLogEntry" object class, expecting that there are no entries of other object types in the change log.</para></listitem>

<listitem><para>"respectResourcePasswordPolicyChangeAfterReset" : false -&gt; If true, when binding check for the Password Expired control (and also Password Policy control) and throw exceptions (PasswordExpiredException, etc.) appropriately.</para></listitem>

<listitem><para>"ssl" : false -&gt; Whether the port is a secure SSL port.</para></listitem>

<listitem><para>"synchronizePasswords" : false -&gt; Whether passwords should be synchronized</para></listitem>

<listitem><para>"uidAttribute" : "entryUUID" -&gt; The LDAP attribute to map Uid to.</para></listitem>

<listitem><para>"useBlocks" : true -&gt; Whether to use block-based LDAP controls like simple paged results or VLV control.</para></listitem>

<listitem><para>"usePagedResultControl" : false -&gt; If true, simple paged search will be preferred over VLV index search when both are available.</para></listitem>

<listitem><para>"vlvSortAttribute" : "uid" -&gt; The attribute used as the sort key for the VLV index.</para></listitem>

</itemizedlist>

</section>

</section>

<section><title>Active Directory Connector</title>

<section><title>The .net Connection Server</title>

<para>In opposite to most other connectors, the AD connector is not written in java but .net. The reason is that OpenICF should connect to AD by ADSI, the native connection protocol of AD, which needs to have access to the ADSI dlls.</para>

</section>

<section><title>Installation of the .net Connector Server</title>

<para>Information on how to install a .net Connector Server can be found [here|http://openicf.forgerock.org/connector-framework-internal/connector_server.html].

It is important to set the key as described in the [installation description|http://openicf.forgerock.org/connector-framework-internal/connector_server.html] after installation!</para>

</section>

<section><title>Example connectorRef</title>

<example>

<title>Example connectorRef for an AD connector configuration (provisioner-json)</title>

<programlisting>

"connectorHostRef" : "dotnet",

"connectorName" : "Org.IdentityConnectors.ActiveDirectory.ActiveDirectoryConnector",

"bundleName" : "ActiveDirectory.Connector",

"bundleVersion" : "1.0.0.6109"

</programlisting>

</example>

<para>Where:</para>

<para>*connectorHostRef:* must point to an existing connector info provider configuration with this name. It is usually stored in its own file with the name "provisioner.openicf.connectorinfoprovider.json".

The connectorHostRef is NOT optional in this case since the AD connector needs to be installed on a .net connector server which is always remote due to it's non java nature!</para>

<example>

<title>Example of a connector info provider configuration (in a file named "provisioner.openicf.connectorinfoprovider.json")</title>

<programlisting>

"connectorsLocation" : "connectors",

"remoteConnectorServers" :

[

{

"name" : "dotnet",

"host" : "10.0.0.10",

"port" : 8759,

"useSSL" : false,

"timeout" : 0,

"key" : "Passw0rd"

}

]

</programlisting>

</example>

</section>

<section><title>Typical configurationProperties configuration</title>

<example>

<title>configurationProperties of an AD connector configuration (provisioner-json)</title>

<programlisting>

"DirectoryAdminName" : "EXAMPLE\\Administrator",

"DirectoryAdminPassword" : "password",

"ObjectClass" : "User",

"Container" : "dc=example,dc=com",

"CreateHomeDirectory" : true,

"LDAPHostName" : "127.0.0.1",

"SearchChildDomains" : false,

"DomainName" : "example",

"SyncGlobalCatalogServer" : null,

"SyncDomainController" : null,

"SearchContext" : "dc=example,dc=com"

</programlisting>

</example>

<para>Where:</para>

<itemizedlist>

<listitem><para>DirectoryAdminName: Account which will be used to authenticate; can be a domainname\user combination or just the user name</para></listitem>

<listitem><para>DirectoryAdminPassword: credentials for the connection</para></listitem>

<listitem><para>ObjectClass: AD objectclass for user objects. </para></listitem>

<listitem><para>Container: the basecontext for all searches</para></listitem>

<listitem><para>CreateHomeDirectory: whether a home directory should be created for new users</para></listitem>

<listitem><para>LDAPHostName: only used if a connection to a particular AD server should be enforced. </para></listitem>

<listitem><para>SearchChildDomains: true or false; settings of SyncGlobalCatalogServer and SyncDomainController depend on this setting</para></listitem>

<listitem><para>DomainName: name of the windows domain</para></listitem>

<listitem><para>SyncGlobalCatalogServer: Name of the global catalog server. This is needed only if searching child domains. </para></listitem>

<listitem><para>SyncDomainController: Domain controller to use during sync. Only used if not searching child domains. </para></listitem>

<listitem><para>SearchContext: Reserved for future use.</para></listitem>

</itemizedlist>

</section>

</section>

<section><title>CSV File Connector</title>

<para>The background for using this connector is very often initial or continues user import. In this case the CSV file serves as kind of the change log and often contains only the user records which have received a change. </para>

<section><title>Example connectorRef</title>

<para>The background for using this connector is very often initial or continues user import. In this case the CSV file serves as kind of the change log and often contains only the user records which have received a change. </para>

<example>

<title>Typical connectorRef for an CSV resource configuration (provisioner-json)</title>

<programlisting>

"connectorRef" : {

"connectorHostRef" : "osgi:service/org.forgerock.openicf.framework.api.osgi.ConnectorManager",

"connectorName" : "org.forgerock.openicf.csvfile.CSVFileConnector",

"bundleName" : "org.forgerock.openicf.connectors.file.openicf-csvfile-connector",

"bundleVersion" : "1.1.0.0-EA"

},

</programlisting>

</example>

<para>The connectorHostRef has to be set like above if the default connector jar is used since it resides in the openidm/bundle folder.</para>

</section>

<section><title>Typical configurationProperties configuration</title>

<example>

<title>configurationProperties of an CSV connector configuration (provisioner-json)</title>

<programlisting>

"configurationProperties" : {

"filePath" : "data/hr.csv",

"uniqueAttribute" : "uid"

},

</programlisting>

</example>

<para>Where:</para>

<itemizedlist>

<listitem><para>filePath: references the CSV file which contains the account entries</para></listitem>

<listitem><para>uniqueAttribute: serves as kind of primary key in the CSV file</para></listitem>

</itemizedlist>

<para>Other useful options to set here are:</para>

<itemizedlist>

<listitem><para>encoding: default is "utf-8"</para></listitem>

<listitem><para>fieldDelimiter: default is ","</para></listitem>

<listitem><para>multivalueDelimiter: for multivalued attributes; default is ";"</para></listitem>

<listitem><para>usingMultivalue: boolean value; default is false</para></listitem>

<listitem><para>passwordAttribute: if authentication is used, this is the attribute which contains the password</para></listitem>

</itemizedlist>

</section>

</section>

<section><title>Scripted SQL Connector</title>

<section><title>Example connectorRef</title>

<para>The Scripted SQL Connector opens a lot of flexibility since the actual db interaction is done by means of customizable Groovy scripts. There is one script of each of the following actions against the external data base:</para>

<itemizedlist>

<listitem><para>Create</para></listitem>

<listitem><para>Delete</para></listitem>

<listitem><para>Search</para></listitem>

<listitem><para>Sync</para></listitem>

<listitem><para>Test</para></listitem>

<listitem><para>Update</para></listitem>

</itemizedlist>

</section>

</section>

</chapter>