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

<chapter xml:id='chap-samples'

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

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

<title>More OpenIDM Samples</title>

<para>The current distribution of OpenIDM comes with a variety of samples

in <filename>openidm/samples/</filename>. Sample 1 is described in

<link xlink:href="install-guide#chap-sample"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>First OpenIDM

Sample</citetitle></link>. This chapter describes the remaining OpenIDM

samples.</para>

<section xml:id="before-you-begin-samples">

<title>Before You Begin</title>

<para>Install OpenIDM, as described in <link

xlink:href="install-guide#chap-install"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Installing

OpenIDM Services</citetitle></link>.</para>

<para>OpenIDM comes with an internal noSQL database, OrientDB, for use as

the internal repository out of the box. This makes it easy to get started

with OpenIDM. OrientDB is not yet supported for production use, however,

so use a supported JDBC database when moving to production.</para>

<section xml:id="install-samples">

<title>Installing the Samples</title>

<indexterm>

<primary>Installing</primary>

<secondary>Samples</secondary>

</indexterm>

<para>

Each sample directory in <filename>openidm/samples/</filename> contains a

number of subdirectories, such as <filename>conf/</filename> and

<filename>script/</filename>. To start OpenIDM with a sample configuration,

navigate to the <filename>/path/to/openidm</filename> directory and use the

<literal>-p</literal> option of the <command>startup</command> command to

point to the sample whose configuration you want to use. Some, but not all

samples require additional software, such as an external LDAP server or

database.

</para>

<para>

When you move from one sample to the next, bear in mind that you are

changing the OpenIDM configuration. For information on how configuration

changes work, see <link xlink:href="integrators-guide#when-configuring-notes"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Changing the

Configuration</citetitle></link> in the <citetitle>Integrator's

Guide</citetitle>.

</para>

<para>

The command-line examples in this chapter (and throughout the OpenIDM

documentation) assume a UNIX shell. If you are running these samples on

Windows, adjust the command-line examples accordingly. For an indication of

what the corresponding Windows command would look like, see the examples in

the <link xlink:show="new" xlink:href="install-guide#chap-sample"

xlink:role="http://docbook.org/xlink/role/olink" ><citetitle>First OpenIDM

Sample</citetitle></link>.

</para>

</section>

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

<title>Preparing OpenIDM</title>

<para>Install an instance of OpenIDM specifically to try the samples. That

way you can experiment as much as you like, and discard the result if you

are not satisfied.</para>

<para>

If you are using the same instance of OpenIDM for multiple samples, it is

helpful to clear out the repository created for an earlier sample. To do so,

shut down OpenIDM and delete the <filename>openidm/db/openidm</filename>

directory.

</para>

<screen>$ rm -rf /path/to/openidm/db/openidm</screen>

<para>

OpenIDM should now be ready to start with a new sample. For a number of

the following samples, users are created either at the UI or with a

commons REST call. Once added, and when reconciliation is complete, such

users should be able to log into the UI.

</para>

</section>

</section>

<section xml:id="more-sample1">

<title>Sample 1 - XML File</title>

<para>Sample 1 is described in the chapter, <link

xlink:href="install-guide#chap-sample"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>First OpenIDM

Sample</citetitle></link>.</para>

</section>

<section xml:id="more-sample2">

<title>Sample 2 - LDAP One Way</title>

<indexterm>

<primary>Samples</primary>

<secondary>Sample 2 - LDAP one way</secondary>

</indexterm>

<para>

Sample 2 resembles the first sample, but in sample 2 OpenIDM is connected to

a local LDAP server. The sample has been tested with <link xlink:show="new"

xlink:href="http://www.forgerock.org/opendj.html">OpenDJ</link>, but should

work with any LDAPv3 compliant server.

</para>

<para>

Sample 2 demonstrates how OpenIDM can pick up new or changed objects from an

external resource. The sample contains only one mapping, from the external

LDAP server resource to the OpenIDM repository. The sample therefore does not

push any changes made to OpenIDM managed user objects out to the LDAP server.

</para>

<section xml:id="external-ldap-config-2">

<title>LDAP Server Configuration</title>

<itemizedlist>

<para>

Sample 2 expects the following configuration for the external LDAP server:

</para>

<listitem>

<para>

The LDAP server runs on the local host.

</para>

</listitem>

<listitem>

<para>

The LDAP server listens on port 1389.

</para>

</listitem>

<listitem>

<para>

A user with DN <literal>cn=Directory Manager</literal> and password

<literal>password</literal> has read access to the LDAP server.

</para>

</listitem>

<listitem>

<para>

Directory data for that server is stored under base DN

<literal>dc=example,dc=com</literal>.

</para>

</listitem>

<listitem>

<para>

User objects for that server are stored under base DN

<literal>ou=People,dc=example,dc=com</literal>.

</para>

</listitem>

<listitem>

<para>

User objects have the object class <literal>inetOrgPerson</literal>.

</para>

</listitem>

<listitem>

<para>

User objects have the following attributes:

</para>

<itemizedlist>

<listitem>

<para>

<literal>cn</literal>

</para>

</listitem>

<listitem>

<para>

<literal>description</literal>

</para>

</listitem>

<listitem>

<para>

<literal>givenName</literal>

</para>

</listitem>

<listitem>

<para>

<literal>mail</literal>

</para>

</listitem>

<listitem>

<para>

<literal>sn</literal>

</para>

</listitem>

<listitem>

<para>

<literal>telephoneNumber</literal>

</para>

</listitem>

<listitem>

<para>

<literal>uid</literal>

</para>

</listitem>

<listitem>

<para>

<literal>userPassword</literal>

</para>

</listitem>

</itemizedlist>

<para>

An example user object follows.

</para>

<programlisting language="ldif">

dn: uid=jdoe,ou=People,dc=example,dc=com

objectClass: person

objectClass: organizationalPerson

objectClass: inetOrgPerson

objectClass: top

givenName: John

uid: jdoe

cn: John Doe

telephoneNumber: 1-415-523-0772

sn: Doe

mail: jdoe@example.com

description: Created by OpenIDM

userPassword: password</programlisting>

</listitem>

</itemizedlist>

<para>

A sample LDIF file, with two users, is provided in

<filename>openidm/samples/sample2/data/Example.ldif</filename>.

</para>

<para>

The following steps provide setup instructions for an OpenDJ server. Adjust

these instructions if you are using an alternative LDAP server.

</para>

<procedure>

<step>

<para>

Download and extract the OpenDJ zip archive.

</para>

<para>

Find a link to the OpenDJ download page at <link xlink:show="new"

xlink:href="http://forgerock.com/download-stack/" />.

</para>

</step>

<step>

<para>

Install OpenDJ using the command-line setup. During the install, import

the LDIF data required for this sample:

</para>

<screen><userinput>$ cd /path/to/opendj

$ /setup --cli \

--hostname localhost \

--ldapPort 1389 \

--rootUserDN "cn=Directory Manager" \

--rootUserPassword password \

--adminConnectorPort 4444 \

--baseDN dc=com \

--ldifFile /path/to/openidm/samples/sample2/data/Example.ldif \

--acceptLicense \

--no-prompt</userinput>

<computeroutput>...

Configuring Directory Server ..... Done.

Importing LDIF file /path/to/openidm/samples/sample2/data/Example.ldif ...... Done.

Starting Directory Server ...... Done..

...</computeroutput></screen>

</step>

</procedure>

</section>

<section xml:id="install-sample2">

<title>Install the Sample</title>

<para>

Prepare OpenIDM as described in <xref linkend="preparing-openidm"/>, then

start OpenIDM with the configuration for sample 2.

</para>

<screen>$ cd /path/to/openidm

$ /startup.sh -p samples/sample2</screen>

</section>

<section xml:id="run-sample2">

<title>Reconcile the Repository</title>

<para>

The mapping configuration file (<filename>sync.json</filename>) for this

sample includes the mapping <literal>systemLdapAccounts_managedUser</literal>,

which synchronize users from the source LDAP server with the target

OpenIDM repository.

</para>

<para>

You can run this part of the sample by using the <literal>curl</literal>

command-line utility, or by using the OpenIDM Administration UI. This

section provides instructions for both methods.

</para>

<procedure>

<title>To Run the Sample Using the Command Line</title>

<step>

<para>

Reconcile the repository by running the following command:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/recon?_action=recon&amp;mapping=systemLdapAccounts_managedUser&amp;waitForCompletion=true"</userinput>

<computeroutput>{

"state": "SUCCESS",

"_id": "f3c618aa-cc3b-49ed-9a3a-00b012db2513"

}</computeroutput>

</screen>

<para>

The reconciliation operation creates the two users from the LDAP server in

the OpenIDM repository, assigning the new objects random unique IDs.

</para>

</step>

<step>

<para>

To retrieve the users from the repository, query their IDs as follows:

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 2,

"result": [

{

"_rev": "0",

"_id": "0a5546d6-149b-4f8b-b3be-4afa8a267d45"

},

{

"_rev": "0",

"_id": "840394b9-ced0-4f13-a5ad-6a0d825f0705"

}

]

}</computeroutput></screen>

</step>

<step>

<para>

To retrieve individual user objects, include the ID in the URL, for

example:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user/0a5546d6-149b-4f8b-b3be-4afa8a267d45"</userinput>

<computeroutput>{

"displayName": "Barbara Jensen",

"stateProvince": "",

"userName": "bjensen",

"postalAddress": "",

"effectiveAssignments": {},

"roles": [

"openidm-authorized"

],

"country": "",

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "Barbara",

"address2": "",

"lastPasswordAttempt": "Mon Nov 24 2014 21:17:19 GMT+0200 (SAST)",

"passwordAttempts": "0",

"sn": "Jensen",

"mail": "bjensen@example.com",

"city": "",

"lastPasswordSet": "",

"postalCode": "",

"_id": "0a5546d6-149b-4f8b-b3be-4afa8a267d45",

"_rev": "1",

"accountStatus": "active",

"description": "Created for OpenIDM",

"telephoneNumber": "1-360-229-7105"

}</computeroutput> </screen>

</step>

</procedure>

<procedure>

<title>To Run the Sample Using the Admin UI</title>

<step>

<para>

Log in to the Admin UI at the URL

<literal>https://localhost:8443/admin</literal> as the default

administrative user (<literal>openidm-admin</literal>) with password

<literal>openidm-admin</literal>.

</para>

<para>

The first time you log into the Admin UI, you are prompted to change your

password. If you do not want to change your password at this time, simply

click X to close this window, and continue with the sample.

</para>

</step>

<step>

<para>

Select the Mappings tab.

</para>

<para>

This tab shows one configured mapping, from the <literal>ldap</literal>

server to the OpenIDM repository (<literal>managed/user</literal>).

</para>

<mediaobject>

<alt>Mappings tab showing the mapping for Sample 2</alt>

<imageobject>

<imagedata fileref="images/sample2-mappings.png" format="PNG"/>

</imageobject>

</mediaobject>

</step>

<step>

<para>

Click anywhere on the mapping and click Reconcile Now.

</para>

<para>

The reconciliation operation creates the two users from the LDAP server in

the OpenIDM repository.

</para>

</step>

<step>

<para>

Retrieve the users in the repository by clicking the Data Management View

link at the top right of the Admin UI.

</para>

<para>

This link opens the Data Management UI. If you did not change your

password in the first step, you are prompted to change your password

again. You can bypass this by clicking X to close the password

prompt window.

</para>

</step>

<step>

<para>

Select the Users tab.

</para>

<mediaobject>

<alt>Users tab showing the users in the repo for Sample 2</alt>

<imageobject>

<imagedata fileref="images/sample2-users.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The two users from the LDAP server have been reconciled to the OpenIDM

repository.

</para>

</step>

<step>

<para>

To retrieve the details of a specific user, click that username on the

Users tab.

</para>

<para>

The following image shows the details of user <literal>bjensen</literal>.

</para>

<mediaobject>

<alt>User details for a specific user</alt>

<imageobject>

<imagedata fileref="images/sample2-bjensen.png" format="PNG" />

</imageobject>

</mediaobject>

</step>

</procedure>

</section>

</section>

<section xml:id="more-sample2b">

<title>Sample 2b - LDAP Two Way</title>

<indexterm>

<primary>Samples</primary>

<secondary>Sample 2b - LDAP two way</secondary>

</indexterm>

<para>

Like sample 2, sample 2b connects to an external LDAP server. However,

sample 2b has two mappings configured, one from the LDAP server to the

OpenIDM repository, and the other from the OpenIDM repository to the LDAP

server.

</para>

<section xml:id="external-ldap-config-2b">

<title>External LDAP Configuration</title>

<para>

Configure the LDAP server as for sample 2,

<xref linkend="external-ldap-config-2" />. The LDAP user must have write

access to create users from OpenIDM on the LDAP server. When you configure

the LDAP server, import the appropriate LDIF file

(<filename>openidm/samples/sample2b/data/Example.ldif).</filename>

</para>

</section>

<section xml:id="install-sample2b">

<title>Install the Sample</title>

<para>

Prepare OpenIDM as described in <xref linkend="preparing-openidm"/>, then

start OpenIDM with the configuration for sample 2b.

</para>

<screen>$ cd /path/to/openidm

$ /startup.sh -p samples/sample2b</screen>

</section>

<section xml:id="run-sample2b">

<title>Run the Sample</title>

<para>

The mapping configuration file (<filename>sync.json</filename>) for this

sample includes two mappings, <literal>systemLdapAccounts_managedUser</literal>,

which synchronizes users from the source LDAP server with the target

OpenIDM repository, and <literal>managedUser_systemLdapAccounts</literal>,

which synchronizes changes from the OpenIDM repository to the LDAP server.

</para>

<para>

You can run this part of the sample by using the <literal>curl</literal>

command-line utility, or by using the OpenIDM Administration UI. This

section provides instructions for both methods.

</para>

<procedure>

<title>To Run the Sample Using the Command Line</title>

<step>

<para>

Reconcile the repository over the REST interface by running the following

command:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/recon?_action=recon&amp;mapping=systemLdapAccounts_managedUser&amp;waitForCompletion=true"</userinput>

<computeroutput>{

"state": "SUCCESS",

"_id": "027e25e3-7a33-4858-9080-161c2b40a6bf"

}</computeroutput></screen>

<para>

The reconciliation operation returns a reconciliation run ID and the

status of the operation. Reconciliation creates user objects from LDAP in

the OpenIDM repository, assigning the new objects random unique IDs.

</para>

</step>

<step>

<para>

To retrieve the users from the repository, query their IDs as follows:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 2,

"result": [

{

"_rev": "0",

"_id": "2cb34789-ee67-4f50-88f2-022460c37253"

},

{

"_rev": "0",

"_id": "625942ac-3cb8-47aa-9de1-217d24967b3b"

}

]

}</computeroutput></screen>

</step>

<step>

<para>

To retrieve individual user objects, include the ID in the URL, for

example:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user/625942ac-3cb8-47aa-9de1-217d24967b3b"</userinput>

<computeroutput>{

"displayName": "Barbara Jensen",

"stateProvince": "",

"userName": "bjensen",

"postalAddress": "",

"effectiveAssignments": {},

"roles": [

"openidm-authorized"

],

"country": "",

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "Barbara",

"address2": "",

"lastPasswordAttempt": "Tue Nov 25 2014 12:29:15 GMT+0200 (SAST)",

"passwordAttempts": "0",

"sn": "Jensen",

"mail": "bjensen@example.com",

"city": "",

"lastPasswordSet": "",

"postalCode": "",

"_id": "625942ac-3cb8-47aa-9de1-217d24967b3b",

"_rev": "1",

"description": "Created for OpenIDM",

"accountStatus": "active",

"telephoneNumber": "1-360-229-7105"

}</computeroutput></screen>

</step>

<step>

<para>

Test the second mapping by creating a user in the OpenIDM repository.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '{

"mail":"fdoe@example.com",

"sn":"Doe",

"telephoneNumber":"555-1234",

"userName":"fdoe",

"givenName":"Felicitas",

"description":"Felicitas Doe",

"displayName":"fdoe"}' \

"https://localhost:8443/openidm/managed/user?_action=create"</userinput>

<computeroutput>{

"displayName": "fdoe",

"stateProvince": "",

"userName": "fdoe",

"postalAddress": "",

"effectiveAssignments": {},

"roles": [

"openidm-authorized"

],

"country": "",

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "Felicitas",

"address2": "",

"lastPasswordAttempt": "Tue Nov 25 2014 12:49:06 GMT+0200 (SAST)",

"passwordAttempts": "0",

"sn": "Doe",

"mail": "fdoe@example.com",

"city": "",

"_rev": "1",

"lastPasswordSet": "",

"postalCode": "",

"_id": "c462fac4-528a-45c5-ba76-d2744952d418",

"description": "Felicitas Doe",

"accountStatus": "active",

"telephoneNumber": "555-1234"

}</computeroutput></screen>

</step>

<step>

<para>

By default, <emphasis>implicit synchronization</emphasis> is enabled for

mappings <emphasis>from</emphasis> the <literal>managed/user</literal>

repository <emphasis>to</emphasis> any external resource. This means that

when you update a managed object, any mappings defined in the

<filename>sync.json</filename> file that have the managed object as the

source are automatically executed to update the target system. For more

information, see <link xlink:href="integrators-guide#synchronization-mappings-file"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Synchronization

Mappings File</citetitle></link> in the <citetitle>Integrator's

Guide</citetitle>.

</para>

<para>

Test that the implicit reconciliation has been successful by querying the

users in the LDAP directory over REST, as follows:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/ldap/account?_queryId=query-all-ids"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 3,

"result": [

{

"_id": "uid=jdoe,ou=People,dc=example,dc=com",

"dn": "uid=jdoe,ou=People,dc=example,dc=com"

},

{

"_id": "uid=bjensen,ou=People,dc=example,dc=com",

"dn": "uid=bjensen,ou=People,dc=example,dc=com"

},

{

"_id": "uid=fdoe,ou=People,dc=example,dc=com",

"dn": "uid=fdoe,ou=People,dc=example,dc=com"

}

]

}</computeroutput></screen>

<para>

Note the new entry for user <literal>fdoe</literal>.

</para>

</step>

<step>

<para>

Query the complete entry by including <literal>fdoe</literal>'s ID in

the URL.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/ldap/account/uid=fdoe,ou=People,dc=example,dc=com"</userinput>

<computeroutput>{

"_id": "uid=fdoe,ou=People,dc=example,dc=com",

"dn": "uid=fdoe,ou=People,dc=example,dc=com",

"mail": "fdoe@example.com",

"uid": "fdoe",

"ldapGroups": [],

"cn": "fdoe",

"givenName": "Felicitas",

"telephoneNumber": "555-1234",

"description": "Felicitas Doe",

"sn": "Doe"

}</computeroutput></screen>

</step>

</procedure>

<procedure>

<title>To Run the Sample Using the Admin UI</title>

<step>

<para>

Log in to the Admin UI at the URL

<literal>https://localhost:8443/admin</literal> as the default

administrative user (<literal>openidm-admin</literal>) with password

<literal>openidm-admin</literal>.

</para>

<para>

The first time you log into the Admin UI, you are prompted to change your

password. If you do not want to change your password at this time, simply

click X to close this window, and continue with the sample.

</para>

</step>

<step>

<para>

Select the Mappings tab.

</para>

<para>

This tab shows two configured mappings, one from the

<literal>ldap</literal> server to the OpenIDM repository

(<literal>managed/user</literal>) and one from the OpenIDM repository to

the <literal>ldap</literal> server.

</para>

<mediaobject>

<alt>Mappings tab showing the mapping for Sample 2b</alt>

<imageobject>

<imagedata fileref="images/sample2b-mappings.png" format="PNG"/>

</imageobject>

</mediaobject>

</step>

<step>

<para>

Click anywhere on the first mapping and click Reconcile Now.

</para>

<mediaobject>

<alt>Mappings tab showing reconciliation for Sample 2b</alt>

<imageobject>

<imagedata fileref="images/sample2b-reconcile.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The reconciliation operation creates the two users from the LDAP server in

the OpenIDM repository.

</para>

</step>

<step>

<para>

Retrieve the users in the repository by clicking the Data Management View

link at the top right of the Admin UI.

</para>

<para>

This link opens the Data Management UI. If you did not change your

password in the first step, you are prompted to change your password

again. You can bypass this by clicking X to close the password prompt

window.

</para>

</step>

<step>

<para>

Select the Users tab.

</para>

<mediaobject>

<alt>Users tab showing the users in the repo for Sample 2b</alt>

<imageobject>

<imagedata fileref="images/sample2-users.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The two users from the LDAP server have been reconciled to the OpenIDM

repository.

</para>

</step>

<step>

<para>

To retrieve the details of a specific user, click that username on the

Users tab.

</para>

<para>

The following image shows the details of user <literal>bjensen</literal>.

</para>

<mediaobject>

<alt>User details for a specific user</alt>

<imageobject>

<imagedata fileref="images/sample2-bjensen.png" format="PNG" />

</imageobject>

</mediaobject>

</step>

<step>

<para>

Add a new user in the OpenIDM repository by clicking Add User on the Users

tab.

</para>

<para>

Complete the user details and click Create.

</para>

<para>

The following image shows a new record being created for user

<literal>fdoe</literal>.

</para>

<mediaobject>

<alt>New user record for fdoe</alt>

<imageobject>

<imagedata fileref="images/sample2b-new-user.png" format="PNG" />

</imageobject>

</mediaobject>

</step>

<step>

<para>

By default, <emphasis>implicit synchronization</emphasis> is enabled for

mappings <emphasis>from</emphasis> the <literal>managed/user</literal>

repository <emphasis>to</emphasis> any external resource. This means that

when you update a managed object, any mappings defined in the

<filename>sync.json</filename> file that have the managed object as the

source are automatically executed to update the target system. For more

information, see <link xlink:href="integrators-guide#synchronization-mappings-file"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Synchronization

Mappings File</citetitle></link> in the <citetitle>Integrator's

Guide</citetitle>.

</para>

<para>

To test that the implicit reconciliation has been successful, look at

<literal>fdoe</literal>'s record in the Data Management UI. At the

bottom of the user profile, the Linked Systems panel indicates the

external resource to which this user entry is mapped.

</para>

<para>

The following image shows that <literal>fdoe</literal> now exists in the

linked resource <literal>ldap account</literal>, and shows her entry as it

appears on the LDAP server.

</para>

<mediaobject>

<alt>New user record for fdoe</alt>

<imageobject>

<imagedata fileref="images/sample2b-fdoe.png" format="PNG" />

</imageobject>

</mediaobject>

</step>

</procedure>

</section>

</section>

<section xml:id="more-sample2c">

<title>Sample 2c - Synchronizing LDAP Group Membership</title>

<indexterm>

<primary>Samples</primary>

<secondary>Sample 2c - Synchronizing LDAP Group Membership</secondary>

</indexterm>

<para>

Like sample 2b, sample 2c connects to an external LDAP server and has

mappings from the LDAP server to the OpenIDM repository, and from the

OpenIDM repository to the LDAP server. However, in sample 2c, LDAP group

memberships are synchronized, in addition to user entries.

</para>

<section xml:id="external-ldap-config-2c">

<title>External LDAP Configuration</title>

<para>

Configure the LDAP server as for sample 2,

<xref linkend="external-ldap-config-2" />. The LDAP user must have write

access to create users from OpenIDM on the LDAP server. When you configure

the LDAP server, import the appropriate LDIF file

(<filename>openidm/samples/sample2c/data/Example.ldif</filename>). This file

includes the following two LDAP groups:

</para>

<programlisting language="ldif">

dn: ou=Groups,dc=example,dc=com

ou: Groups

objectClass: organizationalUnit

objectClass: top

dn: cn=openidm,ou=Groups,dc=example,dc=com

uniqueMember: uid=jdoe,ou=People,dc=example,dc=com

cn: openidm

objectClass: groupOfUniqueNames

objectClass: top

dn: cn=openidm2,ou=Groups,dc=example,dc=com

uniqueMember: uid=bjensen,ou=People,dc=example,dc=com

cn: openidm2

objectClass: groupOfUniqueNames

objectClass: top</programlisting>

<para>

The users with DNs <literal>uid=jdoe,ou=People,dc=example,dc=com</literal>

and <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> are also

imported with the <filename>Example.ldif</filename> file.

</para>

</section>

<section xml:id="install-sample2c">

<title>Install the Sample</title>

<para>

Prepare OpenIDM as described in <xref linkend="preparing-openidm"/>,

then start OpenIDM with the configuration for sample 2c.

</para>

<screen>$ cd /path/to/openidm

$ /startup.sh -p samples/sample2c</screen>

</section>

<section xml:id="run-sample2c">

<title>Run the Sample</title>

<para>

The mapping configuration file (<filename>sync.json</filename>) for this

sample includes two mappings, <literal>systemLdapAccounts_managedUser</literal>,

which synchronizes users from the source LDAP server with the target

OpenIDM repository, and <literal>managedUser_systemLdapAccounts</literal>,

which synchronizes changes from the OpenIDM repository to the LDAP server.

</para>

<para>

You can run this part of the sample by using the <literal>curl</literal>

command-line utility, or by using the OpenIDM Administration UI. This

section provides instructions for both methods.

</para>

<procedure>

<title>To Run the Sample Using the Command Line</title>

<step>

<para>

Reconcile the repository over the REST interface by running the following

command:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/recon?_action=recon&amp;mapping=systemLdapAccounts_managedUser&amp;waitForCompletion=true"</userinput>

<computeroutput>{

"state": "SUCCESS",

"_id": "8a25d1ca-c0f3-4e0f-82a0-b5c346282782"

}</computeroutput></screen>

<para>

The reconciliation operation returns a reconciliation run ID and the

status of the operation. Reconciliation creates user objects from LDAP in

the OpenIDM repository, assigning the new objects random unique IDs.

</para>

</step>

<step>

<para>

To retrieve the users from the repository, query their IDs as follows:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 2,

"result": [

{

"_rev": "0",

"_id": "40f41f52-44a0-40fe-83ab-a95b92a25805"

},

{

"_rev": "0",

"_id": "cec9e2d7-cb6c-4622-94a8-2cb43695476f"

}

]

}</computeroutput></screen>

</step>

<step>

<para>

To retrieve individual user objects, include the ID in the URL. The

following request retrieves the user object for John Doe:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user/cec9e2d7-cb6c-4622-94a8-2cb43695476f"</userinput>

<computeroutput>{

"displayName": "John Doe",

"userName": "jdoe",

"stateProvince": "",

"postalAddress": "",

"ldapGroups": [

"cn=openidm,ou=Groups,dc=example,dc=com"

],

"effectiveAssignments": {},

"roles": [

"openidm-authorized"

],

"country": "",

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "John",

"address2": "",

"lastPasswordAttempt": "Wed Nov 26 2014 14:30:58 GMT+0200 (SAST)",

"passwordAttempts": "0",

"sn": "Doe",

"mail": "jdoe@example.com",

"city": "",

"lastPasswordSet": "",

"postalCode": "",

"_id": "cec9e2d7-cb6c-4622-94a8-2cb43695476f",

"_rev": "1",

"description": "Created for OpenIDM",

"accountStatus": "active",

"telephoneNumber": "1-415-599-1100"

}</computeroutput></screen>

<para>

Note that John Doe's user object contains an <literal>ldapGroups</literal>

property, the value of which indicates his groups on the LDAP server:

</para>

<programlisting>"ldapGroups":["cn=openidm,ou=Groups,dc=example,dc=com"]</programlisting>

</step>

<step>

<para>

Update John Doe's <literal>ldapGroups</literal> property, to change his

membership from the <literal>openidm</literal> group to the

<literal>openidm2</literal> group.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '[

{

"operation":"replace",

"field":"/ldapGroups",

"value": ["cn=openidm2,ou=Groups,dc=example,dc=com"]

}

]' \

"https://localhost:8443/openidm/managed/user?_action=patch&amp;_queryId=for-userName&amp;uid=jdoe"</userinput>

<computeroutput>{

"displayName": "John Doe",

"userName": "jdoe",

"stateProvince": "",

"postalAddress": "",

"effectiveAssignments": {},

"ldapGroups": [

"cn=openidm2,ou=Groups,dc=example,dc=com"

],

"roles": [

"openidm-authorized"

],

"city": "",

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "John",

"lastPasswordAttempt": "Wed Nov 26 2014 14:30:58 GMT+0200 (SAST)",

"address2": "",

"passwordAttempts": "0",

"sn": "Doe",

"mail": "jdoe@example.com",

"country": "",

"_rev": "2",

"lastPasswordSet": "",

"postalCode": "",

"_id": "cec9e2d7-cb6c-4622-94a8-2cb43695476f",

"description": "Created for OpenIDM",

"accountStatus": "active",

"telephoneNumber": "1-415-599-1100"

}</computeroutput> </screen>

<para>

This command changes John Doe's <literal>ldapGroups</literal> property in

the OpenIDM repository, from

<literal>"cn=openidm,ou=Groups,dc=example,dc=com"</literal> to

<literal>"cn=openidm2,ou=Groups,dc=example,dc=com"</literal>. As a result

of implicit synchronization, the change is propagated to the LDAP server.

John Doe is removed from the first LDAP group and added to the second LDAP

group in OpenDJ.

</para>

</step>

<step>

<para>

You can verify this change by querying John Doe's record on the LDAP

server, as follows:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/ldap/account/uid=jdoe,ou=People,dc=example,dc=com"</userinput>

<computeroutput>{

"_id": "uid=jdoe,ou=People,dc=example,dc=com",

"telephoneNumber": "1-415-599-1100",

"description": "Created for OpenIDM",

"sn": "Doe",

"dn": "uid=jdoe,ou=People,dc=example,dc=com",

"ldapGroups": [

"cn=openidm2,ou=Groups,dc=example,dc=com"

],

"uid": "jdoe",

"cn": "John Doe",

"givenName": "John",

"mail": "jdoe@example.com"

}</computeroutput>

</screen>

</step>

</procedure>

<procedure>

<title>To Run the Sample Using the Admin UI</title>

<step>

<para>

Log in to the Admin UI at the URL

<literal>https://localhost:8443/admin</literal> as the default

administrative user (<literal>openidm-admin</literal>) with password

<literal>openidm-admin</literal>.

</para>

<para>

The first time you log into the Admin UI, you are prompted to change your

password. If you do not want to change your password at this time, simply

click X to close this window, and continue with the sample.

</para>

</step>

<step>

<para>

Select the Mappings tab.

</para>

<para>

This tab shows two configured mappings, one from the

<literal>ldap</literal> server to the OpenIDM repository

(<literal>managed/user</literal>) and one from the OpenIDM repository to

the <literal>ldap</literal> server.

</para>

<mediaobject>

<alt>Mappings tab showing the mapping for Sample 2c</alt>

<imageobject>

<imagedata fileref="images/sample2b-mappings.png" format="PNG"/>

</imageobject>

</mediaobject>

</step>

<step>

<para>

Click anywhere on the first mapping and click Reconcile Now.

</para>

<mediaobject>

<alt>Mappings tab showing reconciliation for Sample 2c</alt>

<imageobject>

<imagedata fileref="images/sample2b-reconcile.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The reconciliation operation creates the two users from the LDAP server in

the OpenIDM repository.

</para>

</step>

<step>

<para>

Retrieve the users in the repository by clicking the Data Management View

link at the top right of the Admin UI.

</para>

<para>

This link opens the Data Management UI. If you did not change your

password in the first step, you are prompted to change your password

again. You can bypass this by clicking X to close the password prompt

window.

</para>

</step>

<step>

<para>

Select the Users tab.

</para>

<mediaobject>

<alt>Users tab showing the users in the repo for Sample 2c</alt>

<imageobject>

<imagedata fileref="images/sample2-users.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The two users from the LDAP server have been reconciled to the OpenIDM

repository.

</para>

</step>

<step>

<para>

To retrieve the details of a specific user, click that username on the

Users tab.

</para>

<para>

The following image shows the details of user <literal>jdoe</literal>.

</para>

<mediaobject>

<alt>User details for a specific user</alt>

<imageobject>

<imagedata fileref="images/sample2c-jdoe.png" format="PNG" />

</imageobject>

</mediaobject>

<para>

Note the Linked Systems section of John Doe's profile. The Linked Resource

item indicates the external resource on which John Doe's managed object

is mapped, in this case, <literal>ldap account</literal>.

</para>

<para>

In this linked resource, John Doe's <literal>ldapGroups</literal> are

displayed. Currently, John Doe is a member of

<literal>cn=openidm,ou=Groups,dc=example,dc=com</literal>.

</para>

</step>

<step>

<para>

Update John Doe's <literal>ldapGroups</literal> property, in the

repository, to change his membership from the <literal>openidm</literal>

group to the <literal>openidm2</literal> group.

</para>

<para>

In the current default version of the Data Management UI, only specific

properties of a managed object can be edited. It is therefore not possible

to update John Doe's <literal>ldapGroups</literal> property using the UI.

</para>

<para>

Instead, update his managed/user object over REST, as follows:

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '[

{

"operation":"replace",

"field":"/ldapGroups",

"value": ["cn=openidm2,ou=Groups,dc=example,dc=com"]

}

]' \

"https://localhost:8443/openidm/managed/user?_action=patch&amp;_queryId=for-userName&amp;uid=jdoe"</userinput>

<computeroutput>{

"displayName": "John Doe",

"userName": "jdoe",

"stateProvince": "",

"postalAddress": "",

"effectiveAssignments": {},

"ldapGroups": [

"cn=openidm2,ou=Groups,dc=example,dc=com"

],

"roles": [

"openidm-authorized"

],

"city": "",

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "John",

"lastPasswordAttempt": "Wed Nov 26 2014 14:30:58 GMT+0200 (SAST)",

"address2": "",

"passwordAttempts": "0",

"sn": "Doe",

"mail": "jdoe@example.com",

"country": "",

"_rev": "2",

"lastPasswordSet": "",

"postalCode": "",

"_id": "cec9e2d7-cb6c-4622-94a8-2cb43695476f",

"description": "Created for OpenIDM",

"accountStatus": "active",

"telephoneNumber": "1-415-599-1100"

}</computeroutput> </screen>

<para>

This command changes John Doe's <literal>ldapGroups</literal> property in

the OpenIDM repository, from

<literal>"cn=openidm,ou=Groups,dc=example,dc=com"</literal> to

<literal>"cn=openidm2,ou=Groups,dc=example,dc=com"</literal>. As a result

of implicit synchronization, the change is propagated to the LDAP server.

John Doe is removed from the first LDAP group and added to the second LDAP

group in OpenDJ.

</para>

</step>

<step>

<para>

You can verify this change by reloading John Doe's user profile in the

Data Management UI, and looking at the value of his

<literal>ldapGroups</literal> property in the Linked Systems panel.

</para>

<para>

The following image shows the updated record for John Doe, with a new

<literal>ldapGroups</literal> value of

<literal>cn=openidm2,ou=Groups,dc=example,dc=com</literal>.

</para>

<mediaobject>

<alt>Updated ldapGroups property for John Doe</alt>

<imageobject>

<imagedata fileref="images/sample2c-jdoe2.png" format="PNG" />

</imageobject>

</mediaobject>

</step>

</procedure>

</section>

</section>

<section xml:id="more-sample2d">

<title>Sample 2d - Synchronizing LDAP Groups</title>

<indexterm>

<primary>Samples</primary>

<secondary>Sample 2d - Synchronizing LDAP Groups</secondary>

</indexterm>

<para>Sample 2d also connects to an external LDAP server. This sample

focuses on LDAP Group synchronization.</para>

<section xml:id="external-ldap-config-2d">

<title>External LDAP Configuration</title>

<para>Configure the LDAP server as for sample 2,

<xref linkend="external-ldap-config-2" />. The LDAP user must have write

access to create users from OpenIDM on the LDAP server.</para>

<para>In addition, two LDAP Groups should be created, which can be found in

the LDIF file: <filename>openidm/samples/sample2d/data/Example.ldif</filename>

(if they have not already been added through sample 2c):</para>

<programlisting language="ldif">

dn: ou=Groups,dc=example,dc=com

ou: Groups

objectClass: organizationalUnit

objectClass: top

dn: cn=openidm,ou=Groups,dc=example,dc=com

uniqueMember: uid=jdoe,ou=People,dc=example,dc=com

cn: openidm

objectClass: groupOfUniqueNames

objectClass: top

dn: cn=openidm2,ou=Groups,dc=example,dc=com

uniqueMember: uid=bjensen,ou=People,dc=example,dc=com

uniqueMember: uid=jdoe,ou=People,dc=example,dc=com

cn: openidm2

objectClass: groupOfUniqueNames

objectClass: top

</programlisting>

<para>The user with dn <literal>uid=jdoe,ou=People,dc=example,dc=com</literal>

is also imported with the <filename>Example.ldif</filename> file.</para>

<para>There is an additional user, <literal>bjensen</literal> in the

sample LDIF file. This user is essentially a "dummy" user, provided for

compliance with RFC 4519, which stipulates that every

<literal>groupOfUniqueNames</literal> object must contain at least one

<literal>uniqueMember</literal>. <literal>bjensen</literal> is not actually

used in this sample.</para>

</section>

<section xml:id="install-sample2d">

<title>Install the Sample</title>

<para>Prepare OpenIDM as described in <xref linkend="preparing-openidm"/>,

then start OpenIDM with the configuration for sample 2d.</para>

<screen>$ cd /path/to/openidm

$ /startup.sh -p samples/sample2d</screen>

</section>

<section xml:id="run-sample2d">

<title>Running the Sample</title>

<para>

The mapping configuration file (<filename>sync.json</filename>) for this

sample includes three mappings:

</para>

<itemizedlist>

<listitem>

<para><literal>systemLdapAccounts_managedUser</literal></para>

<para>

Synchronizes users from the source LDAP server with the target

OpenIDM repository,

</para>

</listitem>

<listitem>

<para><literal>managedUser_systemLdapAccounts</literal></para>

<para>

Synchronizes changes from the OpenIDM repository to the LDAP server.

</para>

</listitem>

<listitem>

<para><literal>systemLdapGroups_managedGroup</literal></para>

<para>

Synchronizes groups from the source LDAP server with the target OpenIDM

repository.

</para>

</listitem>

</itemizedlist>

<para>

Due to the similarity with other OpenIDM samples, especially samples 2b

and 2c, the focus of this sample is on the mapping unique to this sample,

<literal>systemLdapGroups_managedGroup</literal>.

</para>

<para>

You can run this part of the sample by using the <literal>curl</literal>

command-line utility, or by using the OpenIDM Administration UI. This

section provides instructions for both methods.

</para>

<procedure>

<title>To Run the Sample Using the Command Line</title>

<step>

<para>

Reconcile the repository over the REST interface for the group mapping,

<literal>systemLdapGroups_managedGroup</literal> by running the following

command:

</para>

<screen>$ <userinput> curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/recon?_action=recon&amp;mapping=systemLdapGroups_managedGroup&amp;waitForCompletion=true"</userinput></screen>

<para>

The reconciliation operation returns a reconciliation run ID, and the status

of the operation.

</para>

</step>

<step>

<para>

With the configuration of sample 2d, OpenIDM creates group objects from

LDAP in OpenIDM. To list group objects by ID, run a query over the REST

interface.

</para>

<screen>$ <userinput> curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/group?_queryFilter=true"</userinput></screen>

<para>

The resulting JSON object should include content similar to the

following.

</para>

<programlisting language="javascript">

{

"result" : [ {

"dn" : "cn=openidm,ou=Groups,dc=example,dc=com",

"_id" : "837df489-35d6-48d1-81a5-23792b49838a",

"_rev" : "1",

"description" : [ ],

"uniqueMember" : [ "uid=jdoe,ou=People,dc=example,dc=com" ],

"name" : [ "openidm" ]

}, {

"dn" : "cn=openidm2,ou=Groups,dc=example,dc=com",

"_id" : "7575c1c7-86cf-43bc-bf1d-5c9cfc539124",

"_rev" : "1",

"description" : [ ],

"uniqueMember" : [ "uid=bjensen,ou=People,dc=example,dc=com" ],

"name" : [ "openidm2" ]

} ],

"resultCount" : 2,

"pagedResultsCookie" : null,

"remainingPagedResults" : -1

}</programlisting>

</step>

</procedure>

<procedure>

<title>To Run the Sample Using the Admin UI</title>

<step>

<para>

Log in to the Admin UI at the URL

<literal>https://localhost:8443/admin</literal> as the default

administrative user (<literal>openidm-admin</literal>) with password

<literal>openidm-admin</literal>.

</para>

<para>

The first time you log into the Admin UI, you are prompted to change your

password. If you do not want to change your password at this time,

click X to close this window, and continue with the sample.

</para>

</step>

<step>

<para>

Select the Mappings tab.

</para>

<para>

This tab shows three configured mappings, from the

<literal>ldap</literal> server accounts repository to the OpenIDM

repository (<literal>managed/user</literal>), from the OpenIDM repository

back to the <literal>ldap</literal> server, and from the

<literal>ldap</literal> server group accounts repository to the OpenIDM

<literal>managed/group</literal> repository.

</para>

<mediaobject>

<alt>Mappings tab showing the mapping for Sample 2d</alt>

<imageobject>

<imagedata fileref="images/sample2d-mappings.png" format="PNG"/>

</imageobject>

</mediaobject>

</step>

<step>

<para>

Click anywhere on the third mapping and click Reconcile Now.

</para>

<mediaobject>

<alt>Mappings tab showing reconciliation for Sample 2b</alt>

<imageobject>

<imagedata fileref="images/sample2d-reconcile.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The reconciliation operation creates the two groups from the LDAP server in

the OpenIDM repository.

</para>

</step>

<step>

<para>

Retrieve the groups in the repository by clicking the Correlation link

below the mapping. Scroll down to Data Association Management.

</para>

<mediaobject>

<alt>Data Association Management showing groups for Sample 2d</alt>

<imageobject>

<imagedata fileref="images/sample2d-groups.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The two groups from the LDAP server (source) have been reconciled to the

OpenIDM repository (target).

</para>

</step>

</procedure>

</section>

</section>

<section xml:id="samples-groovy-connector-toolkit">

<title>Using the Groovy Connector Toolkit to Create Scripted Connectors</title>

<para>

OpenICF 1.4 introduces a generic Groovy Connector Toolkit that enables you to

run Groovy scripts on any external resource.

</para>

<para>

The Groovy Connector Toolkit is not a complete connector, in the traditional

sense. Rather, it is a framework within which you must write your own Groovy

scripts to address the requirements of your implementation. Specific scripts

are provided within these samples, which demonstrate how the Groovy Connector

Toolkit can be used. These scripts cannot be used "as is" in your deployment,

but are a good starting point on which to base your customization.

</para>

<section xml:id="more-sample3">

<title>Sample 3 - Using the Groovy Connector Toolkit to Connect to MySQL With ScriptedSQL</title>

<para>

This sample uses a ScriptedSQL implementation of the Groovy Connector

Toolkit in which an instance of the ScriptedSQL framework is made to work

with the <literal>hrdb</literal> schema. The "connector" in this sample is

therefore really an <literal>hrdb</literal> connector that is implemented

with the help of the Groovy Connector Toolkit.

</para>

<para>

The Groovy Connector Toolkit is bundled with OpenIDM ${docTargetVersion}, in

the JAR <filename>openidm/connectors/groovy-connector-${openicf.groovyconnector.version}.jar</filename>.

The connector configuration file for this sample

(<filename>sample3/conf/provisioner.openicf-scriptedsql.json</filename>)

indicates the ScriptedSQL implementation of the Groovy connector as follows:

</para>

<programlisting language="javascript">{

"name" : "scriptedsql",

"connectorRef" : {

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

"bundleVersion" : "[1.4.0.0,2.0.0.0)",

"connectorName" : "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"

},

... </programlisting>

<para>

This sample demonstrates the use of <firstterm>complex data types</firstterm>.

Complex data types can be stored, retrieved and synchronized like any other

object property. They are stored in the managed data as JSON, represented as

a string, but can be mapped to external resources in any format required.

You can customize the mapping to do additional work with or transformations

on those data types. The sample defines one complex data type,

<literal>cars</literal>, discussed in more detail later in this section.

</para>

<para>

The mapping in this sample shows the use of event hooks to perform an

action. The mapping configuration from the internal repository to the

external <literal>hrdb</literal> database system

(<literal>managedUser_systemHrdb</literal>), defined in the

<filename>sync.json</filename> file, includes two script hooks. The first is

for an <literal>onCreate</literal> event and the second for an

<literal>onUpdate</literal> event. For both events, OpenIDM logs a statement

to the log when a user is created or updated in the external system. The

script source is included in the mapping, but can also be called from an

external file. For more information, see the <link xlink:show="new"

xlink:href="integrators-guide#appendix-scripting"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Scripting

Appendix</citetitle></link> in the <citetitle>Integrators Guide</citetitle>.

</para>

<para>

This sample also demonstrates the configuration of custom scripted

endpoints, defined in the connector configuration

(<filename>provisioner.openicf-scriptedsql.json</filename>).

</para>

<caution>

<para>

Because MySQL cannot "un-hash" user passwords there is no way for a

reconciliation operation to retrieve and store the password from MySQL and

store it in the managed user object. This issue might impact

configurations that support multiple external resources in that passwords

might not be synchronized immediately after reconciliation from MySQL to

the managed/user repository. Users who are missing from managed/user will

be created by the reconciliation but their passwords will be empty. When

those users are synchronized to other external resources, they will have

empty passwords in those resources. Additional scripting might be required

to handle this situation, depending on the requirements of your

deployment.

</para>

</caution>

<para>

This sample configuration assumes a MySQL server, running on the localhost,

and listening on port 3306. The sample database, <literal>hrdb</literal>,

is created over REST.

</para>

<para>

The Groovy scripts required for the sample are located in the

<filename>sample3/tools</filename> directory. You will need to customize

these scripts to address the requirements of your specific deployment,

however, the sample scripts are a good starting point on which to base your

customization.

</para>

<para>

Prepare a fresh installation of OpenIDM before trying this sample.

</para>

<section xml:id="setup-sample3">

<title>Setting Up the Sample</title>

<para>

This sample requires an installed, running MySQL instance. The connection to

the MySQL server is defined in the connector configuration file

(<filename>sample3/conf/provisioner.openicf-scriptedsql.json</filename>).

The default connector configuration file assumes the following connection

details:

</para>

<programlisting language="javascript">"configurationProperties" : {

"username" : "root",

"password" : "password",

"driverClassName" : "com.mysql.jdbc.Driver",

"url" : "jdbc:mysql://localhost:3306/hrdb",

</programlisting>

<itemizedlist>

<para>

As indicated in the preceding excerpt of the connector configuration file,

the sample expects the following MySQL configuration:

</para>

<listitem>

<para>

The database is available on the localhost.

</para>

</listitem>

<listitem>

<para>

The database listens on port 3306.

</para>

</listitem>

<listitem>

<para>

You can connect over the network to the database with user

<literal>root</literal> and password <literal>password</literal>.

</para>

</listitem>

</itemizedlist>

<para>

If you have an existing MySQL instance, running on a different host, or

port, adjust the connector configuration accordingly.

</para>

<procedure>

<step>

<para>

Prepare OpenIDM as described in <xref linkend="preparing-openidm"/>.

</para>

</step>

<step>

<para>

Download the <link xlink:show="new"

xlink:href="http://dev.mysql.com/downloads/connector/j/5.1.html">MySQL

Driver</link>, (MySQL Connector/J, version 5.1 or later) from the MySQL

website. Unpack the download and copy the .jar into the

<filename>openidm/bundle</filename> directory.

</para>

<screen>$ cp mysql-connector-java-<replaceable>version</replaceable>-bin.jar /path/to/openidm/bundle/</screen>

</step>

<step>

<para>

Create an empty <literal>hrdb</literal> database.

</para>

<screen>$ <userinput>mysql -u root -p</userinput>

<computeroutput>Enter password:

Welcome to the MySQL monitor. Commands end with ; or \g.

Your MySQL connection id is 2

Server version: 5.5.25a MySQL Community Server (GPL)</computeroutput>

mysql> <userinput>CREATE DATABASE hrdb CHARACTER SET utf8 COLLATE utf8_bin;</userinput>

<computeroutput>Query OK, 1 row affected (0.00 sec)</computeroutput>

mysql> <userinput>quit</userinput>

<computeroutput>Bye</computeroutput></screen>

</step>

<step>

<para>

Start OpenIDM with the configuration for sample 3.

</para>

<screen>$ <userinput>cd /path/to/openidm</userinput>

$ <userinput>/startup.sh -p samples/sample3</userinput>

<computeroutput>Executing /startup.sh...

Using OPENIDM_HOME: /path/to/openidm

Using PROJECT_HOME: /path/to/openidm/samples/sample3/

Using OPENIDM_OPTS: -Xmx1024m -Xms1024m

Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/samples/sample3/

/conf/logging.properties

Using boot properties at /path/to/openidm/samples/sample3/conf/boot/boot.properties

OpenIDM version "${docTargetVersion}" (revision: 0) null null

-> OpenIDM ready</computeroutput></screen>

</step>

<step>

<para>

Populate the MySQL database with sample data.

</para>

<para>

This step executes a custom script, over the REST interface, that resets

and populates the <literal>hrdb</literal> database.

</para>

<para>

The script is referenced in a system action, defined in the connector

configuration file

(<filename>conf/provisioner.openicf-scriptedsql.json</filename>) as

follows:

</para>

<programlisting language="json">"systemActions" : [

{

"scriptId" : "ResetDatabase",

"actions" : [

{

"systemType" : ".*ScriptedSQLConnector",

"actionType" : "Groovy",

"actionFile" : "tools/ResetDatabaseScript.groovy" }

]

}

... </programlisting>

<para>

You can run this script again, at any point, to reset the database.

Currently, only Groovy script is supported for these types of actions.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/system/scriptedsql?_action=script&amp;scriptId=ResetDatabase"</userinput>

<computeroutput>{

"actions": [

{

"result": "Database reset successful."

}

]

}</computeroutput></screen>

<para>

The <literal>hrdb</literal> database should now be populated with sample

data.

</para>

<para>

You can review the contents of the database as follows:

</para>

<screen><userinput>$ mysql -u root -p</userinput>

mysql &gt; <userinput>use hrdb;</userinput>

<computeroutput>Reading table information for completion of table and column names

You can turn off this feature to get a quicker startup with -A

Database changed</computeroutput>

mysql &gt; <userinput>select * from users;</userinput>

<computeroutput>

+----+--------+--------------+-----------+----------+---------------+--------...

| id | uid | password | firstname | lastname | fullname | email ...

+----+--------+------------------------------------------+-----------+-------...

| 1 | bob | e38ad2149... | Bob | Fleming | Bob Fleming | Bob.Fle...

| 2 | rowley | 2aa60a8ff... | Rowley | Birkin | Rowley Birkin | Rowley....

| 3 | louis | 1119cfd37... | Louis | Balfour | Louis Balfour | Louis.B...

| 4 | john | a1d7584da... | John | Smith | John Smith | John.Sm...

| 5 | jdoe | edba955d0... | John | Doe | John Doe | John.Do...

+----+--------+------------------------------------------+-----------+-------...

5 rows in set (0.00 sec)

</computeroutput></screen>

<note>

<para>

The passwords in the output shown above are hashed to the SHA-1 standard,

as they cannot be read into OpenIDM as clear text. The SHA-1 Hash

function is used for compatibility reasons. Use a more secure algorithm

in a production database.

</para>

</note>

</step>

</procedure>

</section>

<section xml:id="run-sample3">

<title>Reconciling the Repository</title>

<procedure>

<step>

<para>

The mapping configuration file (<filename>sync.json</filename>) for this

sample includes the mapping <literal>systemHrdb_managedUser</literal>,

which synchronize users from the source <literal>hrdb</literal> database

with the target OpenIDM repository.

</para>

<para>

You can test this part of the sample by using the <literal>curl</literal>

command-line utility, or the OpenIDM Administration UI.

</para>

<stepalternatives>

<step>

<para>

To reconcile the repository by using the Administration UI:

</para>

<orderedlist>

<listitem>

<para>

Log in to the Admin UI at the URL

<literal>https://localhost:8443/admin</literal> as the default

administrative user (<literal>openidm-admin</literal>) with password

<literal>openidm-admin</literal>.

</para>

<para>

The first time you log into the Admin UI, you are prompted to change

your password. If you do not want to change your password at this

time, simply click X to close this window, and continue with the

sample.

</para>

</listitem>

<listitem>

<para>

Select the Mappings tab.

</para>

<para>

This tab shows two configured mappings, one from the

<literal>hrdb</literal> database to the OpenIDM repository

(<literal>managed/user</literal>), and one in the opposite direction.

</para>

<mediaobject>

<alt>Mappings tab showing the two mappings for Sample 3</alt>

<imageobject>

<imagedata fileref="images/sample3-mappings.png" format="PNG"/>

</imageobject>

</mediaobject>

</listitem>

<listitem>

<para>

Click on the first mapping (the mapping from

<literal>system/scriptedsql/account</literal> to

<literal>managed/user</literal>).

</para>

</listitem>

<listitem>

<para>

Click Reconcile Now.

</para>

</listitem>

</orderedlist>

</step>

<step>

<para>

To reconcile the repository by using the command-line, launch the

reconciliation operation with the following command:

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/recon?_action=recon&amp;mapping=systemHrdb_managedUser&amp;waitForCompletion=true"</userinput>

<computeroutput>{

"state": "SUCCESS",

"_id": "f3c618aa-cc3b-49ed-9a3a-00b012db2513"

}</computeroutput></screen>

</step>

</stepalternatives>

<para>

The reconciliation operation creates the five users from the MySQL

database in the OpenIDM repository.

</para>

</step>

<step>

<para>

Retrieve the list of users from the repository.

</para>

<stepalternatives>

<step>

<para>

To retrieve the users in the repository by using the Administration UI:

</para>

<orderedlist>

<listitem>

<para>

Click the Data Management View link at the top right of the Admin UI.

</para>

<para>

This opens the Data Management UI. If you did not change your password

in the first step, you are prompted to change your password again.

You can bypass this by simply clicking X to close the password prompt

window.

</para>

</listitem>

<listitem>

<para>

Select the Users tab.

</para>

<mediaobject>

<alt>Mappings tab showing the users in the repo for Sample 3</alt>

<imageobject>

<imagedata fileref="images/sample3-users.png" format="PNG"/>

</imageobject>

</mediaobject>

<para>

The five users from the <literal>hrdb</literal> database have been

reconciled to the OpenIDM repository.

</para>

</listitem>

<listitem>

<para>

To retrieve the details of a specific user, click that username on the

Users tab.

</para>

<para>

The following image shows the details for the user Rowley Birkin.

</para>

<mediaobject>

<alt>Mappings tab showing the users in the repo for Sample 3</alt>

<imageobject>

<imagedata fileref="images/sample3-rowley.png" format="PNG"/>

</imageobject>

</mediaobject>

</listitem>

</orderedlist>

</step>

<step>

<para>

To retrieve the users from the repository by using the command-line,

query the IDs in the repository as follows:

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 5,

"result": [

{

"_rev": "0",

"_id": "9ee75d24-899c-4221-97a0-0aca298febd6"

},

{

"_rev": "0",

"_id": "25be1c4c-0c2a-48b6-96f6-58d2e4d2357d"

},

{

"_rev": "0",

"_id": "2850c77b-f51a-4fb2-8cc4-4c1d03108ac2"

},

{

"_rev": "0",

"_id": "126d74e1-1c03-4774-b18d-bd4d1dfdf884"

},

{

"_rev": "0",

"_id": "46570045-0644-45c6-af10-c88ad3df93cc"

}

]

}</computeroutput></screen>

<para>

To retrieve a complete user record, query for an individual user, by his

userName. The following example returns the record for the user

<literal>Rowley Birkin</literal>.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user/?_queryId=for-userName&amp;uid=rowley"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 1,

"result": [

{

"stateProvince": "",

"userName": "rowley",

"postalAddress": "",

"effectiveAssignments": null,

"roles": [

"openidm-authorized"

],

"telephoneNumber": "",

"country": "",

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "Rowley",

"address2": "",

"lastPasswordAttempt": "Wed Nov 05 2014 10:02:02 GMT+0200 (SAST)",

"passwordAttempts": "0",

"sn": "Birkin",

"mail": "Rowley.Birkin@example.com",

"city": "",

"lastPasswordSet": "",

"organization": "SALES",

"postalCode": "",

"_id": "126d74e1-1c03-4774-b18d-bd4d1dfdf884",

"_rev": "1",

"cars": [

{

"model": "328ci",

"year": "2013",

"make": "BMW"

},

{

"model": "ES300",

"year": "2010",

"make": "Lexus"

}

],

"accountStatus": "active"

}

]

} </computeroutput></screen>

</step>

</stepalternatives>

<para>

Regardless of how you have retrieved Rowley Birkin's entry, note the

<literal>"cars"</literal> property in this user's entry. This property

demonstrates a complex object, stored in JSON format in the user

entry, as a list that contains multiple objects. In the MySQL database,

the <literal>car</literal> table joins to the <literal>users</literal>

table through a <literal>cars.users_id</literal> column. The Groovy

scripts read this data from MySQL and repackage it in a way that OpenIDM

can understand. With support for complex objects, the data is passed

through to OpenIDM as a list of <literal>car</literal> objects. Data is

synchronized from OpenIDM to MySQL in the same way. Complex objects can

also be nested to any depth.

</para>

<para>

Group membership (not demonstrated here) is maintained with a traditional

"join table" in MySQL (<literal>groups_users</literal>). OpenIDM does not

maintain group membership in this way, so the Groovy scripts do the work

to translate membership between the two resources.

</para>

</step>

</procedure>

</section>

<section xml:id="sample3-paging">

<title>Using Paging With Sample 3</title>

<para>

All OpenICF ${openicfBundleVersion} connectors support the use of paging

parameters to restrict query results. The following command indicates that

only two records should be returned (<literal>_pageSize=2</literal>) and

that the records should be sorted according to their

<literal>timestamp</literal> and <literal>_id</literal>

(<literal>_sortKeys=timestamp,id</literal>). Including the

<literal>timestamp</literal> in the sort ensures that, as you page through

the set, changes to records that have already been visited are not lost.

Instead, those records are pushed onto the last page.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

'https://localhost:8443/openidm/system/scriptedsql/account?_queryFilter=uid+sw+""&amp;_fields=id,uid&amp;_pageSize=2&amp;_sortKeys=timestamp,id'</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": "2014-09-10 12:18:46.0,2",

"resultCount": 2,

"result": [

{

"_id": "1",

"uid": "bob"

},

{

"_id": "2",

"uid": "rowley"

}

]

}

</computeroutput></screen>

<para>

The <literal>"pagedResultsCookie"</literal> is used by the server to keep

track of the position in the search results. You can ignore the

<literal>"remainingPagedResults": -1</literal> in the output. The real value

of this property is not returned because the scripts that the connector uses

do not do any counting of the records in the resource.

</para>

<para>

Using the <literal>"pagedResultsCookie"</literal> from the previous step,

run a similar query, to retrieve the following set of records in the

database. You must URL-encode the space character between the date and time

in the <literal>"pagedResultsCookie"</literal> value, with

<literal>%20</literal>, as shown in the following example:

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/scriptedsql/account?_queryId=query-all-ids&amp;_pageSize=2&amp;_sortKeys=timestamp,id&amp;_pagedResultsCookie2014-09-10%2012:18:46.0,2"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": "2014-09-10 12:18:46.0,4",

"resultCount": 2,

"result": [

{

"_id": "3",

"uid": "louis"

},

{

"_id": "4",

"uid": "john"

}

]

}</computeroutput></screen>

<para>

For more information about paging support, see <link xlink:show="new"

xlink:href="integrators-guide#paging-query-results"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Paging Query

Results</citetitle></link> in the <citetitle>Integrator's Guide</citetitle>.

</para>

</section>

<section xml:id="sample3-updating-mysql">

<title>Reconciling the MySQL Database</title>

<procedure>

<para>

The second mapping defined in the mapping configuration file for this

sample (<literal>managedUser_systemHrdb</literal>) synchronizes users from

the source OpenIDM repository to the target <literal>hrdb</literal>

database. Instead of running a manual reconciliation operation to

synchronize these resources, edit one of the user records in the

OpenIDM UI.

</para>

<step>

<para>

Log in to the OpenIDM UI (https://localhost:8443/openidmui) as any one of

the users that was created in the repository by the previous

reconciliation operation.

</para>

<para>

The initial clear text passwords of these users can be seen in the

<literal>sample3/tools/ResetDatabaseScript.groovy</literal> script and are

provided here for ease of reference:

<literallayout>"bob", "password1"

"rowley", "password2"

"louis", "password3"

"john", "password4"

"jdoe", "password5"</literallayout>

</para>

<para>

Regular users can update their profiles or passwords. Any changes are

automatically synchronized back to the <literal>hrdb</literal> database,

through the implicit synchronization mechanism.

</para>

<para>

For example, log into the UI as user <literal>john</literal> with the

password <literal>password4</literal>.

</para>

<mediaobject>

<imageobject>

<imagedata fileref="images/john-login.png" format="PNG" />

</imageobject>

</mediaobject>

</step>

<step>

<para>

Update the password or profile of the user <literal>john</literal> (or the

user as whom you logged in in the previous step).

</para>

<para>

The following example updates the email address for user

<literal>john</literal> to <literal>John.P.Smith@example.com</literal>.

</para>

<mediaobject>

<imageobject>

<imagedata fileref="images/john-address-change.png" format="PNG" />

</imageobject>

</mediaobject>

</step>

<step>

<para>

Changes are automatically synchronized to the <literal>hrdb</literal>

database. Retrieve user <literal>john</literal>'s record from the database

by including his <literal>_id</literal> in a query on the system endpoint,

for example:

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/scriptedsql/account/4"</userinput>

<computeroutput>{

"_id": "4",

"email": "John.P.Smith@example.com",

"organization": "SUPPORT",

"firstName": "John",

"lastName": "Smith",

"uid": "john",

"fullName": "John Smith"

}</computeroutput></screen>

</step>

</procedure>

</section>

</section>

<section xml:id="sample-scripted-rest">

<title>Sample - Using the Groovy Connector Toolkit to Connect to OpenDJ With ScriptedREST</title>

<indexterm>

<primary>Samples</primary>

<secondary>ScriptedREST Connector</secondary>

</indexterm>

<para>

This sample uses the Groovy Connector Toolkit to implement a ScriptedREST

connector, which interacts with the OpenDJ REST API.

</para>

<para>

The Groovy Connector Toolkit is bundled with OpenIDM ${docTargetVersion}, in

the JAR <filename>openidm/connectors/groovy-connector-${openicf.groovyconnector.version}.jar</filename>.

</para>

<para>

The connector configuration file for this sample

(<filename>samples/scriptedrest2dj/conf/provisioner.openicf-scriptedrest.json</filename>)

indicates the ScriptedREST implementation of the Groovy connector as follows:

</para>

<programlisting language="javascript">{

"name": "scriptedrest",

"connectorRef": {

"connectorHostRef": "#LOCAL",

"connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector",

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

"bundleVersion": "[1.4.0.0,2.0.0.0)"

},

... </programlisting>

<para>

The Groovy scripts required for the sample are located in the

<filename>samples/scriptedrest2dj/tools</filename> directory. You will need to

customize these scripts to address the requirements of your specific

deployment, however, the sample scripts are a good starting point on which to

base your customization.

</para>

<section xml:id="sample-scripted-rest-opendj">

<title>Setting Up OpenDJ</title>

<para>

This sample assumes an OpenDJ server, running on the localhost. Follow these

steps to install and configure an OpenDJ instance.

</para>

<procedure>

<step>

<para>

Download and extract the OpenDJ zip archive.

</para>

<para>

Find a link to the OpenDJ download page from the <link xlink:show="new"

xlink:href="http://forgerock.com/download-stack/" />.

</para>

</step>

<step>

<para>

Install OpenDJ using the command-line setup, as follows:

</para>

<screen><userinput>$ cd /path/to/opendj

$ /setup --cli \

--hostname localhost \

--ldapPort 1389 \

--rootUserDN "cn=Directory Manager" \

--rootUserPassword password \

--adminConnectorPort 4444 \

--addBaseEntry \

--baseDN dc=com \

--acceptLicense \

--no-prompt</userinput>

<computeroutput>...

Configuring Directory Server ..... Done.

Creating Base Entry dc=com ..... Done.

Starting Directory Server ....... Done.

...</computeroutput>

</screen>

<para>

The sample assumes the following configuration:

</para>

<itemizedlist>

<listitem>

<para>

The server is installed on the localhost.

</para>

</listitem>

<listitem>

<para>

The server listens for LDAP connections on port 1389.

</para>

</listitem>

<listitem>

<para>

The administration connector port is 4444.

</para>

</listitem>

<listitem>

<para>

The root user DN is <literal>cn=Directory Manager</literal>.

</para>

</listitem>

<listitem>

<para>

The root user password is <literal>password</literal>.

</para>

</listitem>

</itemizedlist>

</step>

<step>

<para>

Configure the OpenDJ server for replication.

</para>

<para>

To enable LiveSync, this server must be configured for replication, even

if it does not actually participate in a replication topology. The

following commands configure the server for replication.

</para>

<screen><userinput>$ cd /path/to/opendj/bin

$ /dsconfig create-replication-server \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--provider-name "Multimaster Synchronization" \

--set replication-port:8989 \

--set replication-server-id:2 \

--type generic \

--trustAll \

--no-prompt

$ /dsconfig create-replication-domain \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--provider-name "Multimaster Synchronization" \

--domain-name example_com \

--set base-dn:dc=example,dc=com \

--set replication-server:localhost:8989 \

--set server-id:3 \

--type generic \

--trustAll \

--no-prompt</userinput>

</screen>

</step>

<step>

<para>

Enable HTTP access to the OpenDJ directory server as follows:

</para>

<screen><userinput>$ /dsconfig set-connection-handler-prop \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--handler-name "HTTP Connection Handler" \

--set enabled:true \

--set listen-port:8090 \

--no-prompt \

--trustAll</userinput>

</screen>

</step>

<step>

<para>

Enable the OpenDJ HTTP access log.

</para>

<screen><userinput>$ /dsconfig set-log-publisher-prop \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--publisher-name "File-Based HTTP Access Logger" \

--set enabled:true \

--no-prompt \

--trustAll</userinput></screen>

</step>

<step>

<para>

Import the LDIF data required for the sample.

</para>

<screen><userinput>$ /ldapmodify \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--hostname localhost \

--port 1389 \

--filename /path/to/openidm/samples/scriptedrest2dj/data/ldap.ldif</userinput>

<computeroutput>Processing ADD request for dc=example,dc=com

ADD operation successful for DN dc=example,dc=com

Processing ADD request for ou=Administrators,dc=example,dc=com

ADD operation successful for DN ou=Administrators,dc=example,dc=com

Processing ADD request for uid=idm,ou=Administrators,dc=example,dc=com

ADD operation successful for DN uid=idm,ou=Administrators,dc=example,dc=com

Processing ADD request for ou=People,dc=example,dc=com

ADD operation successful for DN ou=People,dc=example,dc=com

Processing ADD request for ou=Groups,dc=example,dc=com

ADD operation successful for DN ou=Groups,dc=example,dc=com</computeroutput>

</screen>

</step>

<step>

<para>

To configure the mapping between JSON resources and LDAP entries, copy the

the configuration file for the HTTP connection handler

(<filename>/path/to/openidm/samples/scriptedrest2dj/data/http-config.json</filename>)

to OpenDJ's configuration directory.

</para>

<screen><userinput>$ cd /path/to/opendj

$ cp /path/to/openidm/samples/scriptedrest2dj/data/http-config.json config/</userinput></screen>

</step>

<step>

<para>

Restart OpenDJ for the configuration change to take effect.

</para>

<screen><userinput>$ cd /path/to/opendj/bin

$ /stop-ds --restart</userinput>

<computeroutput>Stopping Server...

The Directory Server has started successfully</computeroutput></screen>

</step>

</procedure>

<para>

OpenDJ is now configured for this sample.

</para>

</section>

<section xml:id="sample-scripted-rest-running">

<title>Running the Sample</title>

<para>

This section illustrates the basic CRUD operations on users and groups using

the ScriptedREST connector and the OpenDJ REST API. Note that the power of

the Groovy connector is in the associated Groovy scripts, and their

application in your specific deployment. The scripts provided with this

sample are specific to the sample and customization of the scripts is

required.

</para>

<procedure>

<step>

<para>

Start OpenIDM with the configuration for the ScriptedREST sample.

</para>

<screen><userinput>$ cd /path/to/openidm

$ /startup.sh -p samples/scriptedrest2dj/</userinput></screen>

</step>

<step>

<para>

Check the connector configuration is correct by obtaining the status of

the connector, over REST.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/system/scriptedrest?_action=test"</userinput>

<computeroutput>{

"ok": true,

"connectorRef": {

"bundleVersion": "[1.4.0.0,2.0.0.0)",

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

"connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"

},

"objectTypes": [

"group",

"account"

],

"config": "config/provisioner.openicf/scriptedrest",

"enabled": true,

"name": "scriptedrest"

}</computeroutput>

</screen>

</step>

<step>

<para>

Create a group entry on the OpenDJ server.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '{

"_id" : "group1"

}' \

"https://localhost:8443/openidm/system/scriptedrest/group?_action=create"</userinput>

<computeroutput>{

"_id": "group1",

"cn": "group1",

"members": null,

"lastModified": null,

"created": "2014-09-24T17:34:27Z",

"displayName": "group1"

}</computeroutput></screen>

</step>

<step>

<para>

Create a user entry on the OpenDJ server.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '{

"givenName" : "Steven",

"familyName" : "Carter",

"emailAddress" : "scarter@example.com",

"telephoneNumber" : "444-444-4444",

"password" : "Passw0rd",

"displayName" : "Steven.Carter",

"uid" : "scarter"

}' \

https://localhost:8443/openidm/system/scriptedrest/account?_action=create</userinput>

<computeroutput>{

"_id": "scarter",

"displayName": "Steven.Carter",

"uid": "scarter",

"groups": null,

"familyName": "Carter",

"emailAddress": "steven.carter@example.com",

"givenName": "Steven",

"created": "2014-09-24T17:35:46Z",

"telephoneNumber": "444-444-4444"

}</computeroutput></screen>

<para>

Notice that at this stage, the user is not a member of any group.

</para>

</step>

<step>

<para>

Update Steven Carter's entry, by modifying his telephone number.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request PUT \

--data '{

"givenName" : "Steven",

"familyName" : "Carter",

"emailAddress" : "scarter@example.com",

"telephoneNumber" : "555-555-5555",

"password" : "Passw0rd",

"displayName" : "Steven.Carter",

"uid" : "scarter"

}' \

https://localhost:8443/openidm/system/scriptedrest/account/scarter</userinput>

<computeroutput>{

"_id": "scarter",

"displayName": "Steven.Carter",

"uid": "scarter",

"groups": null,

"familyName": "Carter",

"emailAddress": "steven.carter@example.com",

"givenName": "Steven",

"created": "2014-09-24T17:35:46Z",

"telephoneNumber": "555-555-5555"

}</computeroutput></screen>

</step>

<step>

<para>

Add Steven Carter to the group you created previously, by updating the

group entry.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request PUT \

--data '{

"_id" : "group1",

"members" : [{"_id" : "scarter"}]

}' \

https://localhost:8443/openidm/system/scriptedrest/group/group1</userinput>

<computeroutput>{

"_id": "group1",

"cn": "group1",

"members": [

{

"displayName": "Steven.Carter",

"_id": "scarter"

}

],

"lastModified": "2014-09-24T17:31:42Z",

"created": "2014-09-24T17:27:37Z",

"displayName": "group1"

}</computeroutput></screen>

</step>

<step>

<para>

Read Steven Carter's entry, to verify that he is now a member of group1.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

https://localhost:8443/openidm/system/scriptedrest/account/scarter</userinput>

<computeroutput>{

"_id": "scarter",

"displayName": "Steven.Carter",

"uid": "scarter",

"groups": [

{

"_id": "group1"

}

],

"familyName": "Carter",

"emailAddress": "steven.carter@example.com",

"givenName": "Steven",

"created": "2014-09-24T17:31:04Z",

"telephoneNumber": "555-555-5555"

}</computeroutput></screen>

</step>

<step>

<para>

Read the group entry to verify its members.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

https://localhost:8443/openidm/system/scriptedrest/group/group1</userinput>

<computeroutput>{

"_id": "group1",

"cn": "group1",

"members": [

{

"displayName": "Steven.Carter",

"_id": "scarter"

}

],

"lastModified": "2014-09-24T17:31:42Z",

"created": "2014-09-24T17:27:37Z",

"displayName": "group1"

}</computeroutput></screen>

</step>

<step>

<para>

Delete the user and group entries, returning the OpenDJ server to its

initial state.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request DELETE \

https://localhost:8443/openidm/system/scriptedrest/account/scarter</userinput>

<computeroutput>{

"_id": "scarter"

}</computeroutput>

<userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request DELETE \

https://localhost:8443/openidm/system/scriptedrest/group/group1</userinput>

<computeroutput>{

"_id": "group1"

}</computeroutput>

</screen>

</step>

</procedure>

</section>

</section>

<section xml:id="sample-scripted-crest">

<title>Sample - Using the Groovy Connector Toolkit to Connect to OpenDJ With ScriptedCREST</title>

<indexterm>

<primary>Samples</primary>

<secondary>ScriptedCREST Connector</secondary>

</indexterm>

<para>

This sample uses the Groovy Connector Toolkit to implement a ScriptedCREST

connector, which interacts with the ForgeRock Commons REST (CREST) API to

connect to an OpenDJ instance. The main difference between a CREST-based API

and a generic REST API is that the CREST API is inherently recognizable by

all ForgeRock products. As such, the sample can leverage CREST resources in

the groovy scripts, to create CREST requests.

<!--TODO link to CREST vs REST section when OPENIDM-2339 is resolved

</para>

<para>

The Groovy Connector Toolkit is bundled with OpenIDM ${docTargetVersion}, in

the JAR <filename>openidm/connectors/groovy-connector-${openicf.groovyconnector.version}.jar</filename>.

</para>

<para>

The connector configuration file for this sample

(<filename>samples/scriptedcrest2dj/conf/provisioner.openicf-scriptedcrest.json</filename>)

indicates the ScriptedCREST implementation of the Groovy Connector Toolkit

as follows:

</para>

<programlisting language="javascript">{

"name": "scriptedcrest",

"connectorRef": {

"connectorHostRef": "#LOCAL",

"connectorName": "org.forgerock.openicf.connectors.scriptedcrest.ScriptedCRESTConnector",

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

"bundleVersion": "[1.4.0.0,2.0.0.0)"

},

... </programlisting>

<para>

The Groovy scripts required for the sample are located in the

<filename>samples/scriptedcrest2dj/tools</filename> directory. You will need

to customize these scripts to address the requirements of your specific

deployment, however, the sample scripts are a good starting point on which to

base your customization.

</para>

<section xml:id="sample-scripted-crest-opendj">

<title>Setting Up OpenDJ</title>

<para>

This sample assumes an OpenDJ server, running on the localhost. Follow these

steps to install and configure an OpenDJ instance.

</para>

<procedure>

<step>

<para>

Download and extract the OpenDJ zip archive.

</para>

<para>

Find a link to the OpenDJ download page from the <link xlink:show="new"

xlink:href="http://forgerock.com/download-stack/" />.

</para>

</step>

<step>

<para>

Install OpenDJ using the command-line setup, as follows:

</para>

<screen><userinput>$ cd /path/to/opendj

$ /setup --cli \

--hostname localhost \

--ldapPort 1389 \

--rootUserDN "cn=Directory Manager" \

--rootUserPassword password \

--adminConnectorPort 4444 \

--addBaseEntry \

--baseDN dc=com \

--acceptLicense \

--no-prompt</userinput>

<computeroutput>...

Configuring Directory Server ..... Done.

Creating Base Entry dc=com ..... Done.

Starting Directory Server ....... Done.

...</computeroutput>

</screen>

<para>

The sample assumes the following configuration:

</para>

<itemizedlist>

<listitem>

<para>

The server is installed on the localhost.

</para>

</listitem>

<listitem>

<para>

The server listens for LDAP connections on port 1389.

</para>

</listitem>

<listitem>

<para>

The administration connector port is 4444.

</para>

</listitem>

<listitem>

<para>

The root user DN is <literal>cn=Directory Manager</literal>.

</para>

</listitem>

<listitem>

<para>

The root user password is <literal>password</literal>.

</para>

</listitem>

</itemizedlist>

</step>

<step>

<para>

Configure the OpenDJ server for replication.

</para>

<para>

To enable liveSync, this server must be configured for replication, even

if it does not actually participate in a replication topology. The

following commands configure the server for replication.

</para>

<screen><userinput>$ cd /path/to/opendj/bin

$ /dsconfig create-replication-server \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--provider-name "Multimaster Synchronization" \

--set replication-port:8989 \

--set replication-server-id:2 \

--type generic \

--trustAll \

--no-prompt

$ /dsconfig create-replication-domain \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--provider-name "Multimaster Synchronization" \

--domain-name example_com \

--set base-dn:dc=example,dc=com \

--set replication-server:localhost:8989 \

--set server-id:3 \

--type generic \

--trustAll \

--no-prompt</userinput>

</screen>

</step>

<step>

<para>

Enable HTTP access to the OpenDJ directory server as follows:

</para>

<screen><userinput>$ /dsconfig set-connection-handler-prop \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--handler-name "HTTP Connection Handler" \

--set enabled:true \

--set listen-port:8090 \

--no-prompt \

--trustAll</userinput>

</screen>

</step>

<step>

<para>

Enable the OpenDJ HTTP access log.

</para>

<screen><userinput>$ /dsconfig set-log-publisher-prop \

--hostname localhost \

--port 4444 \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--publisher-name "File-Based HTTP Access Logger" \

--set enabled:true \

--no-prompt \

--trustAll</userinput></screen>

</step>

<step>

<para>

Import the LDIF data required for the sample.

</para>

<screen><userinput>$ /ldapmodify \

--bindDN "cn=Directory Manager" \

--bindPassword password \

--hostname localhost \

--port 1389 \

--filename /path/to/openidm/samples/scriptedcrest2dj/data/ldap.ldif</userinput>

<computeroutput>Processing ADD request for dc=example,dc=com

ADD operation successful for DN dc=example,dc=com

Processing ADD request for ou=Administrators,dc=example,dc=com

ADD operation successful for DN ou=Administrators,dc=example,dc=com

Processing ADD request for uid=idm,ou=Administrators,dc=example,dc=com

ADD operation successful for DN uid=idm,ou=Administrators,dc=example,dc=com

Processing ADD request for ou=People,dc=example,dc=com

ADD operation successful for DN ou=People,dc=example,dc=com

Processing ADD request for ou=Groups,dc=example,dc=com

ADD operation successful for DN ou=Groups,dc=example,dc=com</computeroutput>

</screen>

</step>

<step>

<para>

To configure the mapping between JSON resources and LDAP entries, copy the

the configuration file for the HTTP connection handler

(<filename>/path/to/openidm/samples/scriptedcrest2dj/data/http-config.json</filename>)

to OpenDJ's configuration directory.

</para>

<screen><userinput>$ cd /path/to/opendj

$ cp /path/to/openidm/samples/scriptedcrest2dj/data/http-config.json config/</userinput></screen>

</step>

<step>

<para>

Restart OpenDJ for the configuration change to take effect.

</para>

<screen><userinput>$ cd /path/to/opendj/bin

$ /stop-ds --restart</userinput>

<computeroutput>Stopping Server...

The Directory Server has started successfully</computeroutput></screen>

</step>

</procedure>

<para>

OpenDJ is now configured for this sample.

</para>

</section>

<section xml:id="sample-scripted-crest-running">

<title>Running the Sample</title>

<para>

This section illustrates the basic CRUD operations on users and groups using

the ScriptedCREST connector implementation and the OpenDJ REST API. Note

that the power of the Groovy connector is in the associated Groovy scripts,

and their application in your specific deployment. The scripts provided with

this sample are specific to the sample and customization of the scripts is

required.

</para>

<procedure>

<step>

<para>

Start OpenIDM with the configuration for the ScriptedCREST sample.

</para>

<screen><userinput>$ cd /path/to/openidm

$ /startup.sh -p samples/scriptedcrest2dj/</userinput></screen>

</step>

<step>

<para>

Check the connector configuration is correct by obtaining the status of

the connector, over REST.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/system/scriptedcrest?_action=test"</userinput>

<computeroutput>{

"ok": true,

"connectorRef": {

"bundleVersion": "[1.4.0.0,2.0.0.0)",

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

"connectorName": "org.forgerock.openicf.connectors.scriptedcrest.ScriptedCRESTConnector"

},

"objectTypes": [

"groups",

"users"

],

"config": "config/provisioner.openicf/scriptedcrest",

"enabled": true,

"name": "scriptedcrest"

}</computeroutput>

</screen>

</step>

<step>

<para>

Create a group entry on the OpenDJ server.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '{

"_id" : "group1"

}' \

"https://localhost:8443/openidm/system/scriptedcrest/groups?_action=create"</userinput>

<computeroutput>{

"_rev": "0000000028f53bdf",

"_id": "group1",

"displayName": "group1",

"meta": {

"created": "2014-10-17T07:43:13Z"

}

}</computeroutput></screen>

</step>

<step>

<para>

Create a user entry on the OpenDJ server.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "Content-Type: application/json" \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request POST \

--data '{

"name": {

"familyName": "Carter",

"givenName" : "Steven"

},

"contactInformation": {

"emailAddress" : "scarter@example.com",

"telephoneNumber" : "444-444-4444"

},

"password" : "TestPassw0rd",

"displayName" : "Steven.Carter",

"_id" : "scarter"

}' \

"https://localhost:8443/openidm/system/scriptedcrest/users?_action=create"</userinput>

<computeroutput>{

"_rev": "00000000d84482de",

"meta": {

"created": "2014-10-17T08:07:46Z"

},

"userName": "scarter@example.com",

"contactInformation": {

"emailAddress": "scarter@example.com",

"telephoneNumber": "444-444-4444"

},

"name": {

"givenName": "Steven",

"familyName": "Carter"

},

"displayName": "Steven.Carter",

"_id": "scarter"

}</computeroutput></screen>

<para>

Notice that at this stage, the user is not a member of any group.

</para>

</step>

<step>

<para>

Update Steven Carter's entry, by modifying his telephone number.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request PUT \

--data '{

"name": {

"familyName": "Carter",

"givenName" : "Steven"

},

"contactInformation": {

"emailAddress" : "scarter@example.com",

"telephoneNumber" : "555-555-5555"

},

"password" : "TestPassw0rd",

"displayName" : "Steven.Carter",

"_id" : "scarter"

}' \

"https://localhost:8443/openidm/system/scriptedcrest/users/scarter"</userinput>

<computeroutput>{

"_rev": "00000000eb8ba31c",

"meta": {

"created": "2014-10-17T08:07:46Z",

"lastModified": "2014-10-17T08:25:05Z"

},

"userName": "scarter@example.com",

"contactInformation": {

"emailAddress": "scarter@example.com",

"telephoneNumber": "555-555-5555"

},

"name": {

"givenName": "Steven",

"familyName": "Carter"

},

"displayName": "Steven.Carter",

"_id": "scarter"

}</computeroutput></screen>

</step>

<step>

<para>

Add Steven Carter to the group you created previously, by updating the

members of the group entry.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request PUT \

--data '{

"_id" : "group1",

"members" : [{"_id" : "scarter"}]

}' \

"https://localhost:8443/openidm/system/scriptedcrest/groups/group1"</userinput>

<computeroutput>{

"_rev": "0000000011ed6ea1",

"members": [

{

"displayName": "Steven.Carter",

"_id": "scarter"

}

],

"_id": "group1",

"displayName": "group1",

"meta": {

"created": "2014-10-17T07:43:13Z",

"lastModified": "2014-10-17T08:26:41Z"

}

}</computeroutput></screen>

</step>

<step>

<para>

Read Steven Carter's entry, to verify that he is now a member of group1.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/scriptedcrest/users/scarter"</userinput>

<computeroutput>{

"_rev": "00000000eb8ba31c",

"groups": [

{

"_id": "group1"

}

],

"meta": {

"created": "2014-10-17T08:07:46Z",

"lastModified": "2014-10-17T08:25:05Z"

},

"userName": "scarter@example.com",

"contactInformation": {

"emailAddress": "scarter@example.com",

"telephoneNumber": "555-555-5555"

},

"name": {

"givenName": "Steven",

"familyName": "Carter"

},

"displayName": "Steven.Carter",

"_id": "scarter"

}</computeroutput></screen>

</step>

<step>

<para>

Read the group entry to verify its members.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/scriptedcrest/groups/group1"</userinput>

<computeroutput>{

"_rev": "0000000011ed6ea1",

"members": [

{

"displayName": "Steven.Carter",

"_id": "scarter"

}

],

"_id": "group1",

"displayName": "group1",

"meta": {

"created": "2014-10-17T07:43:13Z",

"lastModified": "2014-10-17T08:26:41Z"

}

}</computeroutput></screen>

</step>

<step>

<para>

Delete the user and group entries, returning the OpenDJ server to its

initial state.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request DELETE \

"https://localhost:8443/openidm/system/scriptedcrest/users/scarter"</userinput>

<computeroutput>{

"_id": "scarter"

}</computeroutput>

<userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request DELETE \

"https://localhost:8443/openidm/system/scriptedcrest/groups/group1"</userinput>

<computeroutput>{

"_id": "group1"

}</computeroutput>

</screen>

</step>

</procedure>

</section>

</section>

<section xml:id="samples-azure">

<title>Sample - Using the Groovy Connector Toolkit to Connect to

Microsoft Azure AD</title>

<indexterm>

<primary>Samples</primary>

<secondary>Microsoft Azure AD Connector</secondary>

</indexterm>

<!-- ref http://azure.microsoft.com/en-us/overview/what-is-azure/ -->

<para>

This sample uses the Groovy Connector Toolkit to implement a Microsoft Azure

AD connector, which interacts with the ForgeRock Commons REST (CREST) API to

connect to an Azure-based instance of Active Directory. The main difference

between a CREST-based API and a generic REST API is that the CREST API is

inherently recognizable by all ForgeRock products. As such, the sample can

leverage CREST resources in the groovy scripts, to create CREST requests.

</para>

<para>

As noted on the <link xlink:show="new"

xlink:href="http://azure.microsoft.com/en-us/overview/what-is-azure/">

<citetitle>Microsoft Azure AD web site</citetitle></link>, Azure is

Microsoft's cloud platform for building, deploying, and

managing applications and services.

</para>

<para>

This section assumes that you have a working knowledge of the Microsoft

Azure AD platform, and can adjust and modify the configuration as needed to

get the information needed to configure a Microsoft Azure AD connector.

</para>

<para>

You will also need to set up OpenIDM as a Microsoft Azure AD website and as

a web application. When you do, retain the values of the URI of the website,

<literal>redirectURI</literal>, the <literal>APP ID URI</literal>, which

corresponds to the <literal>resourceURI</literal>, the

<literal>client ID</literal>, and the <literal>client Secret</literal>.

</para>

<para>

The Groovy Connector Toolkit is bundled with OpenIDM ${docTargetVersion}, in

the following JAR file:

<filename>openidm/connectors/groovy-connector-${openicf.groovyconnector.version}.jar</filename>.

</para>

<para>

The connector configuration file for this sample

(<filename>samples/scriptedazure/conf/provisioner.openicf-scriptedazure.json</filename>)

indicates the Scripted Azure AD implementation of the Groovy Connector

Toolkit as follows:

</para>

<programlisting language="javascript">{

"name": "scriptedazure",

"connectorRef": {

"connectorHostRef": "#LOCAL",

"connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedConnector",

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

"bundleVersion": "[1.4.0.0,2.0.0.0)"

},

... </programlisting>

<para>

The Groovy scripts required for the sample are located in the

<filename>samples/scriptedazure/tools</filename> directory. You will need

to customize these scripts to address the requirements of your specific

deployment, however, the sample scripts are a good starting point on which to

base your customization.

</para>

<section xml:id="azure-setup">

<title>Identifying Appropriate Information from Microsoft Azure AD</title>

<para>

Microsoft Azure AD supports RESTful communication with the <link xlink:show="new"

xlink:href="http://msdn.microsoft.com/en-us/library/azure/hh974476.aspx">

<citetitle>Azure AD Graph API</citetitle></link>. As suggested by the name,

the API supports access to the Azure-based instance of Active Directory.

</para>

<para>

To get an OAuth 2 access token, you will need to add information to the

Scripted Azure AD provisioner file,

<filename>provisioner.openicf-scriptedazure.json</filename>. Substitute

for the <literal>__configureme__</literal> entries shown.

</para>

<programlisting language="javascript">...

"customConfiguration":"

graphServiceUrl = 'https://graph.windows.net/__configureme__';

oauth2 {

authority = 'https://login.windows.net/__configureme__';

redirectURI = '__configureme__';

resourceURI = 'https://graph.windows.net'

}",

"customSensitiveConfiguration": "

oauth2 {

clientId = '__configureme__';

clientSecret = '__configureme__';

username = '__configureme__';

password = '__configureme__'

}",... </programlisting>

<para>

The following list assumes that you have configured

<literal>contoso.com</literal> as the Azure AD domain tenant. Substitute

appropriately. Except for the first item, the following list of items are

required for an OAuth 2 access token.

</para>

<para>

You should be able to get some of the items needed for the OAuth 2 token

in the Azure AD configuration menu related to the OpenIDM web application.

</para>

<itemizedlist>

<listitem>

<para><literal>graphServiceUrl</literal></para>

<para>

For a domain tenant of <literal>contoso.com</literal>, set this to

<literal>'https://graph.windows.net/contoso.onmicrosoft.com</literal>

</para>

</listitem>

<listitem>

<para><literal>authority</literal></para>

<para>

Set to <literal>'https://login.windows.net/contoso.onmicrosoft.com'</literal>

</para>

</listitem>

<listitem>

<para><literal>redirectURI</literal></para>

<para>

Set to <literal>'https://localhost:8443/admin/index.html#azureCallback'</literal>

</para>

</listitem>

<listitem>

<para><literal>resourceURI</literal></para>

<para>

Keep the following Graph API setting:

<literal>'https://graph.windows.net'</literal>

</para>

</listitem>

<listitem>

<para><literal>clientId</literal></para>

<para>

Set to the Client ID shown in the Configure menu of the Azure AD web

application.

</para>

</listitem>

<listitem>

<para><literal>clientSecret</literal></para>

<para>

Set to the Client Secret shown when you added or configured the web

application. In Azure AD, the Client Secret is the <literal>key</literal>

associated with the Client ID.

</para>

</listitem>

<listitem>

<para><literal>username</literal></para>

<para>

Set to the administrative username for Azure AD.

</para>

</listitem>

<listitem>

<para><literal>password</literal></para>

<para>

Set to the administrative password for Azure AD.

</para>

</listitem>

</itemizedlist>

</section>

<section xml:id="sample-azure-running">

<title>Running the Sample</title>

<para>

This section illustrates basic CRUD operations on users and groups using

the scripted Azure AD connector. Note that the power of the Groovy

connector is in the associated Groovy scripts, and their application in

your specific deployment. The scripts provided with this sample are

specific to the sample and customization of the scripts is required.

</para>

<procedure>

<step>

<para>

Start OpenIDM with the configuration for the scripted Azure AD sample.

</para>

<screen><userinput>$ cd /path/to/openidm

$ /startup.sh -p samples/scriptedazure/</userinput></screen>

</step>

<step>

<para>

Check the connector configuration. Obtain its status over REST.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/system/scriptedazure?_action=test"</userinput>

<computeroutput>

{

"ok": true,

"connectorRef": {

"bundleVersion": "[1.4.0.0,2.0.0.0)",

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

"connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedConnector"

},

"objectTypes": [

"User",

"Device",

"Contact",

"DeviceConfiguration",

"ServicePrincipal",

"Group",

"ExtensionProperty",

"OAuth2PermissionGrant",

"DirectoryRole",

"DirectoryObject",

"DirectoryRoleTemplate",

"AppRoleAssignment",

"DirectoryLinkChange",

"Application",

"__ALL__",

"SubscribedSku",

"TenantDetail"

],

"config": "config/provisioner.openicf/scriptedazure",

"enabled": true,

"name": "scriptedazure"

}</computeroutput>

</screen>

</step>

<step>

<para>

Create a group entry on the Azure AD server.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '{

"_id": "fake placeholder value",

"mailEnabled": false,

"displayName": "Azure AD Test Group",

"mailNickname": "Test_Group",

"securityEnabled": "true",

"description": "Azure AD Test Group"

}' \

"https://localhost:8443/openidm/system/scriptedazure/group?_action=create"

</userinput>

<computeroutput>

{

"mailEnabled":false,

"__NAME__":"ab347420f-4e8e-f045-a437b62c0f3-636e",

"mailNickname":"Test_Group",

"displayName":"Azure AD Test Group",

"mail":null,

"onPremisesSecurityIdentifier":null,

"lastDirSyncTime":null,

"dirSyncEnabled":null,

"description":"Azure AD Test Group",

"proxyAddresses":[

],

"securityEnabled":true,

"provisioningErrors":[

],

"_id":"ab347420f-4e8e-f045-a437b62c0f3-636e"

}</computeroutput>

</screen>

</step>

<step>

<para>

Create a user entry on the Azure AD server.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '{

"_id": "fake placeholder value",

"accountEnabled": true,

"displayName": "Alex Wu",

"mailNickname": "AlexW",

"passwordProfile": { "password" : "Test1234", "forceChangePasswordNextLogin": false },

"userPrincipalName": "Alex@contoso.onmicrosoft.com"

}' \

"https://localhost:8443/openidm/system/scriptedazure/User?_action=create"

</userinput><computeroutput>

{

"userType":"Member",

"assignedLicenses":[

],

"passwordPolicies":null,

"immutableId":null,

"surname":null,

"provisionedPlans":[

],

"state":null,

"accountEnabled":true,

"telephoneNumber":null,

"physicalDeliveryOfficeName":null,

"mail":null,

"__NAME__":"744aa30f-55e0-4559-b956-985b77d80814",

"proxyAddresses":[

],

"otherMails":[

],

"passwordProfile":null,

"assignedPlans":[

],

"facsimileTelephoneNumber":null,

"displayName":"Alex Wu",

"onPremisesSecurityIdentifier":null,

"userPrincipalName":"Alex@contoso.onmicrosoft.com",

"mobile":null,

"dirSyncEnabled":null,

"jobTitle":null,

"givenName":null,

"department":null,

"usageLocation":null,

"preferredLanguage":null,

"sipProxyAddress":null,

"country":null,

"mailNickname":"AlexW",

"postalCode":null,

"lastDirSyncTime":null,

"city":null,

"provisioningErrors":[

],

"streetAddress":null,

"_id":"744aa30f-55e0-4559-b956-985b77d80814"

}</computeroutput></screen>

</step>

<step>

<para>

Update Alex Wu's entry, by modifying his telephone number.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request PUT \

--data '{

"telephoneNumber" : "555-1234"

}' \

"https://localhost:8443/openidm/system/scriptedazure/User/744aa30f-55e0-4559-b956-985b77d80814"</userinput>

<computeroutput>...

"telephoneNumber" : "555-1234"

...</computeroutput>

</screen>

</step>

<step>

<para>

Confirm the result. Get the data for Alex Wu, by <literal>_id</literal>.

</para>

<screen>$ curl \

--cacert self-signed.crt \

--header "Content-Type: application/json" \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/scriptedazure/User/744aa30f-55e0-4559-b956-985b77d80814"</screen>

</step>

<step>

<para>

Get information on the test group, also by <literal>_id</literal>.

</para>

<screen>$ curl \

--cacert self-signed.crt \

--header "Content-Type: application/json" \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/scriptedazure/Group/ab347420f-4e8e-f045-a437b62c0f3-636e"</screen>

</step>

<step>

<para>

Delete the entry for user Alex Wu.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "Content-Type: application/json" \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request DELETE \

"https://localhost:8443/openidm/system/scriptedazure/User/744aa30f-55e0-4559-b956-985b77d80814"

</userinput>

<computeroutput>{

"_id": "744aa30f-55e0-4559-b956-985b77d80814"

}</computeroutput>

</screen>

</step>

<step>

<para>

Delete the group created earlier.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "Content-Type: application/json" \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request DELETE \

"https://localhost:8443/openidm/system/scriptedazure/Group/ab347420f-4e8e-f045-a437b62c0f3-636e"

</userinput>

<computeroutput>{

"_id": "ab347420f-4e8e-f045-a437b62c0f3-636e"

}</computeroutput></screen>

</step>

</procedure>

</section>

</section>

</section>

<section xml:id="samples-powershell">

<title>Sample - Using the PowerShell Connector Toolkit to Create Scripted Connectors</title>

<para>

OpenICF 1.4 introduces a generic PowerShell Connector Toolkit that enables

you to run PowerShell scripts on any external resource.

</para>

<para>

The PowerShell Connector Toolkit is not a complete connector, in the

traditional sense. Rather, it is a framework within which you must write

your own PowerShell scripts to address the requirements of your Microsoft

Windows ecosystem. You can use the PowerShell Connector Toolkit to create

connectors that can provision any Microsoft system.

</para>

<para>

The PowerShell Connector Toolkit is available, with a subscription, from

<link xlink:show="new" xlink:href="https://backstage.forgerock.com/">ForgeRock

Backstage</link>.

</para>

<para>

This sample provides a number of PowerShell scripts that enable you to

perform basic CRUD (create, read, update, delete) operations on an Active

Directory server. The samples use the MS Active Directory PowerShell module.

For more information on this module, see the corresponding <link xlink:show="new"

xlink:href="http://technet.microsoft.com/en-us/library/hh852274.aspx">Microsoft

documentation</link>.

</para>

<para>

The sample assumes that OpenIDM is running on the localhost, and that Active

Directory runs on a remote server. The remote server also runs the OpenICF

.NET connector server.

</para>

<section xml:id="powershell-setup">

<title>Setting Up the PowerShell Sample</title>

<procedure>

<step>

<para>

Install, configure, and start the .NET connector server on the machine

that is running an Active Directory Domain Controller or on a workstation

on which the Microsoft Active Directory PowerShell module is installed.

</para>

<para>

For instructions on installing the .NET connector server, see <link

xlink:show="new" xlink:href="integrators-guide#net-connector-install"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Installing the

.NET Connector Server</citetitle></link> in the <emphasis>Integrator's

Guide</emphasis>.

</para>

</step>

<step>

<para>

Configure OpenIDM to connect to the .NET connector server.

</para>

<para>

To do so, copy the remote connector provisioner file from the

<literal>openidm/samples/provisioners</literal> directory to the

<literal>openidm/conf</literal> directory, and edit the file according to

your configuration.

</para>

<screen>$ <userinput>cd /path/to/openidm</userinput>

$ <userinput>cp samples/provisioners/provisioner.openicf.connectorinfoprovider.json conf/</userinput></screen>

<para>

For instructions on editing this file, see <link

xlink:show="new" xlink:href="integrators-guide#net-connector-openidm"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

OpenIDM to Connect to the .NET Connector Server</citetitle></link> in the

<emphasis>Integrator's Guide</emphasis>.

</para>

</step>

<step>

<para>

Download the PowerShell Connector Toolkit archive

(<filename>mspowershell-connector-1.4.1.0.zip</filename>) from <link

xlink:show="new" xlink:href="https://backstage.forgerock.com/">ForgeRock

Backstage</link>.

</para>

<para>

Extract the archive and move the <filename>MsPowerShell.Connector.dll</filename>

to the folder in which the connector server application

(<filename>connectorserver.exe</filename>) is located.

</para>

</step>

<step>

<para>

Copy the PowerShell scripts from the <literal>tools</literal> folder in

this sample directory, to the machine on which the connector server is

installed.

</para>

<screen>C:\><userinput>dir openidm\powershell2AD\tools</userinput>

<computeroutput>Directory of C:\openidm\powershell2AD\tools

11/27/2014 12:53 PM &lt;DIR> .

11/27/2014 12:53 PM &lt;DIR> ..

11/26/2014 02:32 PM 2,813 ADAuthenticate.ps1

11/26/2014 02:32 PM 8,546 ADCreate.ps1

11/26/2014 02:32 PM 2,530 ADDelete.ps1

11/26/2014 02:32 PM 2,617 ADResolveUsername.ps1

11/26/2014 02:32 PM 8,644 ADSchema.ps1

11/26/2014 02:32 PM 3,458 ADSearch.ps1

11/26/2014 02:32 PM 4,585 ADSync.ps1

11/26/2014 02:32 PM 2,075 ADTest.ps1

11/26/2014 02:32 PM 8,488 ADUpdate.ps1

9 File(s) 43,756 bytes

2 Dir(s) 23,696,863,232 bytes free

C:\></computeroutput></screen>

</step>

<step>

<para>

Edit the PowerShell search and sync scripts (<filename>ADSearch.ps1</filename>)

and (<filename>ADSync.ps1</filename>) to specify the base suffix for your

Active Directory Domain Controller.

</para>

<para>

Specifically, change the value of the <literal>$searchBase</literal>

parameter in these files to match the suffix in your environment. The

default suffix is:

</para>

<screen>$searchBase = 'CN=Users,DC=example,DC=com'</screen>

</step>

<step>

<para>

Copy the sample connector configuration for the PowerShell connector

from the samples directory to your <literal>conf</literal> directory.

</para>

<screen>$ <userinput>cd /path/to/openidm</userinput>

$ <userinput>cp samples/provisioners/provisioner.openicf-adpowershell.json conf/</userinput></screen>

<para>

The following excerpt of the sample connector configuration shows the

configuration properties:

</para>

<programlisting> "configurationProperties" : {

"AuthenticateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADAuthenticate.ps1",

"CreateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADCreate.ps1",

"DeleteScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADDelete.ps1",

"ResolveUsernameScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADResolveUsername.ps1",

"SchemaScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADSchema.ps1",

"SearchScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADSearch.ps1",

"SyncScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADSync.ps1",

"TestScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADTest.ps1",

"UpdateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADUpdate.ps1",

"VariablesPrefix" : "Connector",

"QueryFilterType" : "AdPsModule",

"ReloadScriptOnExecution" : true,

"UseInterpretersPool" : true,

"SubstituteUidAndNameInQueryFilter" : true,

"UidAttributeName" : "ObjectGUID",

"NameAttributeName" : "DistinguishedName",

"PsModulesToImport" : [ "ActiveDirectory" ],

"Host" : "",

"Port" : null,

"Login" : "",

"Password" : null

},</programlisting>

<para>

The sample connector configuration assumes that the scripts are located in

<filename>C:/openidm/samples/powershell2AD/tools/</filename>. If you

copied your scripts to a different location, adjust your connector

configuration file accordingly.

</para>

<para>

Note that the OpenICF framework requires the path to use forward slash

characters and not the backslash characters that you would expect in a

Windows path.

</para>

<para>

The host, port, login and password of the machine on which Active

Directory runs do not need to be specified here. By default the Active

Directory cmdlets pick up the first available Domain Controller. In

addition, the scripts are executed using the credentials of the .Net

connector server.

</para>

<note>

<para>

The <literal>"ReloadScriptOnExecution"</literal> property is set to

<literal>true</literal> in this sample configuration. This setting causes

script files to be reloaded each time the script is invoked. Having

script files reloaded each time is suitable for debugging purposes.

However, this property should be set to <literal>false</literal> in

production environments, as the script reloading can have a negative

performance impact.

</para>

</note>

<para>

In addition, make sure that the value of the

<literal>"connectorHostRef"</literal> property in the connector

configuration file matches the value that you specified in the remote

connector configuration file, in step 2 of this procedure. For example:

</para>

<screen>"connectorHostRef" : "dotnet",</screen>

</step>

</procedure>

</section>

<section xml:id="powershell-test">

<title>Testing the PowerShell Sample</title>

<para>

Because you have copied all of the required configuration files into the

default OpenIDM project, you can start OpenIDM with the default

configuration (that is, without the <literal>-p</literal> option).

</para>

<screen>$ cd /path/to/openidm

$ /startup.sh</screen>

<para>

When OpenIDM has started, you can test the sample by using the

<literal>curl</literal> command-line utility. The following examples test

the scripts that were provided in the <literal>tools</literal> directory.

</para>

<procedure>

<step>

<para>

Test the connector configuration, and whether OpenIDM is able to connect

to the .NET connector server with the following request.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/system?_action=test"</userinput>

<computeroutput>[

{

"ok": true,

"connectorRef": {

"bundleVersion": "1.4.1.0",

"bundleName": "MsPowerShell.Connector",

"connectorName": "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector"

},

"objectTypes": [

"__ALL__",

"group",

"account"

],

"config": "config/provisioner.openicf/adpowershell",

"enabled": true,

"name": "adpowershell"

}

]</computeroutput> </screen>

</step>

<step>

<para>

Query the users in your Active Directory with the following request:

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/adpowershell/account?_queryId=query-all-ids"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 1257,

"result": [

{

"_id": "7c41496a-9898-4074-a537-bed696b6be92",

"distinguishedName": "CN=Administrator,CN=Users,DC=example,DC=com"

},

{

"_id": "f2e08a5c-473f-4798-a2d5-d5cc27c862a9",

"distinguishedName": "CN=Guest,CN=Users,DC=example,DC=com"

},

{

"_id": "99de98a3-c125-48dd-a7c2-e21f1488ab06",

"distinguishedName": "CN=Ben Travis,CN=Users,DC=example,DC=com"

},

{

"_id": "0f7394cc-c66a-404f-ad6d-38dbb4b6526d",

"distinguishedName": "CN=Barbara Jensen,CN=Users,DC=example,DC=com"

},

{

"_id": "3e6fa858-ed3a-4b58-9325-1fca144eb7c7",

"distinguishedName": "CN=John Doe,CN=Users,DC=example,DC=com"

},

{

"_id": "6feef4a0-b121-43dc-be68-a96703a49aba",

"distinguishedName": "CN=Steven Carter,CN=Users,DC=example,DC=com"

},

...</computeroutput></screen>

</step>

<step>

<para>

To return the complete record of a specific user, include the ID of the

user in the URL. The following request returns the record for Steven

Carter.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/adpowershell/account/6feef4a0-b121-43dc-be68-a96703a49aba"</userinput>

<computeroutput>{

"_id": "6feef4a0-b121-43dc-be68-a96703a49aba",

"postalCode": null,

"passwordNotRequired": false,

"cn": "Steven Carter",

"name": "Steven Carter",

"trustedForDelegation": false,

"uSNChanged": "47219",

"manager": null,

"objectGUID": "6feef4a0-b121-43dc-be68-a96703a49aba",

"modifyTimeStamp": "11/27/2014 3:37:16 PM",

"employeeNumber": null,

"sn": "Carter",

"userAccountControl": 512,

"passwordNeverExpires": false,

"displayName": "Steven Carter",

"initials": null,

"pwdLastSet": "130615726366949784",

"scriptPath": null,

"badPasswordTime": "0",

"employeeID": null,

"badPwdCount": "0",

"accountExpirationDate": null,

"userPrincipalName": "steve.carter@ad0.example.com",

"sAMAccountName": "steve.carter",

"mail": "steven.carter@example.com",

"logonCount": "0",

"cannotChangePassword": false,

"division": null,

"streetAddress": null,

"allowReversiblePasswordEncryption": false,

"description": null,

"whenChanged": "11/27/2014 3:37:16 PM",

"title": null,

"lastLogon": "0",

"company": null,

"homeDirectory": null,

"whenCreated": "6/23/2014 2:50:48 PM",

"givenName": "Steven",

"telephoneNumber": "555-2518",

"homeDrive": null,

"uSNCreated": "20912",

"smartcardLogonRequired": false,

"distinguishedName": "CN=Steven Carter,CN=Users,DC=example,DC=com",

"createTimeStamp": "6/23/2014 2:50:48 PM",

"department": null,

"memberOf": [

"CN=employees,DC=example,DC=com"

],

"homePhone": null

}</computeroutput></screen>

</step>

<step>

<para>

Test whether you can authenticate as one of the users in your Active

Directory. The username that you specify here can be either an ObjectGUID,

UPN, sAMAccountname or CN.

</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

"https://localhost:8443/openidm/system/adpowershell/account?_action=authenticate&amp;username=Steven+Carter&amp;password=Passw0rd"</userinput>

<computeroutput>{

"_id": "6feef4a0-b121-43dc-be68-a96703a49aba"

}</computeroutput></screen>

<para>

The request returns the ObjectGUID if the authentication is successful.

</para>

</step>

<step>

<para>

You can return the complete record for a specific user, using the query

filter syntax described in <link xlink:show="new"

xlink:href="integrators-guide#constructing-queries"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Constructing

Queries</citetitle></link> in the <emphasis>Integrator's Guide</emphasis>.

</para>

<para>

The following query returns the record for the guest user.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/system/adpowershell/account?_queryFilter=cn+eq+guest"</userinput>

<computeroutput>{

"remainingPagedResults": -1,

"pagedResultsCookie": null,

"resultCount": 1,

"result": [

{

"_id": "f2e08a5c-473f-4798-a2d5-d5cc27c862a9",

"postalCode": null,

"passwordNotRequired": true,

"cn": "Guest",

"name": "Guest",

"trustedForDelegation": false,

"uSNChanged": "8197",

"manager": null,

"objectGUID": "f2e08a5c-473f-4798-a2d5-d5cc27c862a9",

"modifyTimeStamp": "6/9/2014 12:35:16 PM",

"employeeNumber": null,

"userAccountControl": 66082,

"whenChanged": "6/9/2014 12:35:16 PM",

"initials": null,

"pwdLastSet": "0",

"scriptPath": null,

"badPasswordTime": "0",

"employeeID": null,

"badPwdCount": "0",

"accountExpirationDate": null,

"sAMAccountName": "Guest",

"logonCount": "0",

"cannotChangePassword": true,

"division": null,

"streetAddress": null,

"allowReversiblePasswordEncryption": false,

"description": "Built-in account for guest access to the computer/domain",

"userPrincipalName": null,

"title": null,

"lastLogon": "0",

"company": null,

"homeDirectory": null,

"whenCreated": "6/9/2014 12:35:16 PM",

"givenName": null,

"homeDrive": null,

"uSNCreated": "8197",

"smartcardLogonRequired": false,

"distinguishedName": "CN=Guest,CN=Users,DC=example,DC=com",

"createTimeStamp": "6/9/2014 12:35:16 PM",

"department": null,

"memberOf": [

"CN=Guests,CN=Builtin,DC=example,DC=com"

],

"homePhone": null,

"displayName": null,

"passwordNeverExpires": true

}

]

}</computeroutput></screen>

</step>

<step>

<para>

Test whether you are able to create a user on the Active Directory server

by sending a POST request with the <literal>create</literal> action.

</para>

<para>

The following request creates the user <literal>Jane Doe</literal> on the

Active Directory server.

</para>

<screen>$ <userinput>curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--header "Content-Type: application/json" \

--request POST \

--data '{

"distinguishedName" : "CN=Jane Doe,CN=Users,DC=example,DC=com",

"sn" : "Doe",

"cn" : "Jane Doe",

"sAMAccountName" : "sample",

"userPrincipalName" : "janedoe@example.com",

"__ENABLE__" : true,

"__PASSWORD__" : "Passw0rd",

"telephoneNumber" : "0052-611-091"

}' \

"https://localhost:8443/openidm/system/adpowershell/account?_action=create"</userinput>

<computeroutput>{

"_id": "42725210-8dce-4fdf-b0e0-393cf0377fdf",

"title": null,

"uSNCreated": "47244",

"pwdLastSet": "130615892934093041",

"cannotChangePassword": false,

"telephoneNumber": "0052-611-091",

"smartcardLogonRequired": false,

"badPwdCount": "0",

"department": null,

"distinguishedName": "CN=Jane Doe,CN=Users,DC=example,DC=com",

"badPasswordTime": "0",

"employeeID": null,

"cn": "Jane Doe",

"division": null,

"description": null,

"userPrincipalName": "janedoe@example.com",

"passwordNeverExpires": false,

"company": null,

"memberOf": [],

"givenName": null,

"streetAddress": null,

"sn": "Doe",

"initials": null,

"logonCount": "0",

"homeDirectory": null,

"employeeNumber": null,

"objectGUID": "42725210-8dce-4fdf-b0e0-393cf0377fdf",

"manager": null,

"lastLogon": "0",

"trustedForDelegation": false,

"scriptPath": null,

"allowReversiblePasswordEncryption": false,

"modifyTimeStamp": "11/27/2014 8:14:53 PM",

"whenCreated": "11/27/2014 8:14:52 PM",

"whenChanged": "11/27/2014 8:14:53 PM",

"accountExpirationDate": null,

"name": "Jane Doe",

"displayName": null,

"homeDrive": null,

"passwordNotRequired": false,

"createTimeStamp": "11/27/2014 8:14:52 PM",