Start Here

Before you try any of the samples read "Run the Samples" and "Prepare IDM".

Read "LDAP Server Configuration" for any samples that require an LDAP server.

Run the Samples

Each sample directory in openidm/samples/ contains a number of subdirectories, such as conf/ and script/. To start IDM with a sample configuration, navigate to the /path/to/openidm directory and use the -p option of the startup command to point to the sample whose configuration you want to use. Some samples require additional software, such as an external LDAP server or database.

Many of the procedures in this guide refer to paths such as samples/sample-name. In each of these cases, the complete path is assumed to be /path/to/openidm/samples/sample-name.

When you move from one sample to the next, you are changing the IDM configuration. For more information, see "Configuration Changes".

The command-line examples in the IDM documentation assume a UNIX shell. To run the samples on Windows, adjust the commands, as necessary.

Prepare IDM

Install an instance of IDM specifically to experiment with the samples and easily discard the result when you finish.

If you are using the same IDM instance for multiple samples, clear the repository between samples. To do so, shut down IDM and delete the openidm/db/openidm directory: 

rm -rf /path/to/openidm/db/openidm

LDAP Server Configuration

For samples in this guide that require an LDAP server, ForgeRock recommends using ForgeRock Directory Services (DS).

  • The LDAP server runs on the local host.

  • The LDAP server listens on port 1389.

  • The replication port is 8989.

    Servers with replication ports maintain a changelog for their own use. The changelog is exposed over LDAP under the base DN, cn=changelog. For samples that demonstrate liveSync with an LDAP server, you must configure a replication port when you set up DS. For ease of use, all the LDAP samples assume that you have configured a replication port, even if you don't use liveSync.

  • A user with DN uid=admin and password password has read access to the LDAP server.

  • Directory data for that server is stored under base DN dc=com.

  • User objects for that server are stored under base DN ou=People,dc=example,dc=com.

  • User objects have the object class inetOrgPerson.

  • User objects have the following attributes:

    • cn

    • description

    • givenName

    • mail

    • sn

    • telephoneNumber

    • uid

    • userPassword 

    dn: uid=bjensen,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: Barbara
uid: bjensen
cn: Barbara Jensen
telephoneNumber: 1-360-229-7105
sn: Jensen
mail: bjensen@example.com
description: Created for OpenIDM
userPassword: password

Note

If you are using the same DS instance for multiple samples, delete the DS configuration between samples:

  1. Shutdown DS:

    /path/to/opendj/bin/stop-ds --quiet

  2. Delete the opendj/db directory:

    rm -rf /path/to/opendj/db

  3. Delete the opendj/config directory:

    rm -rf /path/to/opendj/config
Start DS Using Sample LDIF data

Samples that use an LDAP server require existing user data. The example procedure below corresponds to the sync-with-ldap sample and imports user data (openidm/samples/sync-with-ldap/data/Example.ldif) during DS setup. For other samples, replace the path to the sample data, as necessary.

Note

The following procedure provides setup instructions for DS 7.1. For older versions of DS, or an alternative LDAP server, modify the instructions, as necessary.

  1. Download the DS and IDM .zip archives.

  2. Extract the .zip archives.

  3. Start DS: 

    /path/to/opendj/setup \
--serverId evaluation-only \
--deploymentKeyPassword password \
--rootUserDN uid=admin \
--rootUserPassword password \
--hostname localhost \
--adminConnectorPort 4444 \
--ldapPort 1389 \
--enableStartTls \
--ldapsPort 1636 \
--replicationPort 8989 \
--httpPort 8090 \
--profile ds-user-data:7.0.0 \
--set ds-user-data/baseDn:dc=com \
--set ds-user-data/ldifFile:/path/to/openidm/samples/sync-with-ldap/data/Example.ldif \
--acceptLicense \
--start

Validating parameters..... Done
Configuring certificates....... Done

Store the following deployment key in a safe place and re-use it when
configuring other servers in the topology:

your-deployment-key

Configuring server..... Done
Configuring profile DS application data store....... Done
Starting directory server.............. Done

To see basic server status and configuration, you can launch
/path/to/opendj/bin/status

    Note

    Every DS deployment requires a deployment key and a deployment key password to secure network connections. The deployment key is a random string generated by DS software. The deployment key password is a secret string that you choose. It must be at least 8 characters long. The deployment key and password automate key pair generation and signing without storing the CA private key. For more information, see Deployment Keys in the DS Security Guide.

  4. Import the DS CA certificate into the IDM truststore:

    /path/to/opendj/bin/dskeymgr \
export-ca-cert \
--deploymentKey your-deployment-key \
--deploymentKeyPassword password \
--alias dscert \
--keyStoreFile /path/to/openidm/security/truststore \
--keyStorePasswordFile /path/to/openidm/security/storepass

    Note

    Because each new deployment of DS has a unique deployment key, the same certificate does not work from one sample to the next. To handle this scenario, do one of the following:

    • Give each subsequent sample certificate a unique alias. For example:

      • --alias dscert1

      • --alias dscert2

      • --alias dscert3

    • Delete the old certificate from the trust store:

      keytool \
-delete \
-keystore /path/to/openidm/security/truststore \
-alias dscert
Read a different version of :