Overview of the OpenIDM Samples

This chapter lists all the samples provided with OpenIDM and gives a high-level overview of the purpose of each sample. This chapter also provides information that is required for all of the samples. Read this chapter, specifically "Installing the Samples" and "Preparing OpenIDM" before you try any of the samples provided with OpenIDM.

Overview of the Samples Provided With OpenIDM

OpenIDM provides a number of samples in the openidm/samples directory. This section describes the purpose of each sample:

"XML Samples - Reconciling Data Between OpenIDM and an XML File"

The XML samples all use the XML file connector to interact with an XML file resource. The samples demonstrate the following OpenIDM functionality:

"LDAP Samples - Reconciling Data Between OpenIDM and One or More LDAP Directories"

The LDAP samples all assume a connection to an LDAP directory, usually OpenDJ, or Active Directory. Samples 5 and 5b simulate an LDAP directory with an XML file, and use the XML connector. These samples demonstrate a wide variety of OpenIDM functionality and are broken down as follows:

  • "Sample 2 - LDAP One Way"

    This sample uses the generic LDAP connector to connect to an LDAP directory. The sample includes one mapping from the LDAP directory to the managed user repository, and demonstrates reconciliation from the external resource to the repository.

  • "Sample 2b - LDAP Two Way"

    This sample uses the generic LDAP connector to connect to an LDAP directory. The sample includes two mappings, one from the LDAP directory to the managed user repository, and one from the repository to the LDAP directory. The sample demonstrates reconciliation in both directions.

  • "Sample 2c - Synchronizing LDAP Group Membership"

    This sample uses the generic LDAP connector to connect to an LDAP directory. The sample includes two mappings, one from the LDAP directory to the managed user repository, and one from the repository to the LDAP directory. The sample demonstrates synchronization of group membership, that is, how the value of the ldapGroups property in a managed user object is mapped to the corresponding user object in LDAP.

  • "Sample 2d - Synchronizing LDAP Groups"

    This sample uses the generic LDAP connector to connect to an LDAP directory. The sample builds on the previous sample by providing an additional mapping, from the LDAP groups object, to the managed groups object. The sample illustrates a new managed object type (groups) and shows how this object type is synchronized with group containers in LDAP.

  • "Sample 5 - Synchronization of Two LDAP Resources"

    Although this sample is grouped with the LDAP samples, it actually simulates two LDAP directories with XML files, and uses the XML file connector to connect the two. The purpose of this sample is to demonstrate reconciliation directly between two external resources, without the data passing through the OpenIDM repository. The sample also demonstrates the configuration of an outbound email service to send reconciliation summaries by mail.

  • "Sample 5b - Failure Compensation With Multiple Resources"

    This sample builds on the previous sample to demonstrate a failure compensation mechanism that relies on script event hooks. The failure compensation mechanism ensures that reconciliation changes are propagated throughout a multiple-resource deployment, or rolled back in the case of error. The purpose of this mechanism is to keep the data consistent across multiple resources.

  • "Sample 6 - LiveSync With an AD Server"

    This sample illustrates the LiveSync mechanism that pushes changes from an external resource to the OpenIDM repository. The sample uses an LDAP connector to connect to an LDAP directory, either OpenDJ or Active Directory.

  • "Linking Historical Accounts"

    This sample demonstrates the retention of inactive (historical) LDAP accounts that have been linked to a corresponding managed user account. The sample builds on sample 2b and uses the LDAP connector to connect to an OpenDJ instance. You can use any LDAP-v3 compliant directory server.

  • "Storing Multiple Passwords For Managed Users"

    This sample demonstrates how to set up multiple passwords for managed users and how to synchronize separate passwords to different external resources. The sample includes two target LDAP servers, each with different password policy and encryption requirements. The sample also shows how to extend the password history policy to apply to multiple password fields.

"Samples That Use the Groovy Connector Toolkit to Create Scripted Connectors"

The samples in this section use the Groovy Connector Toolkit to create a scripted connector. Because you can use scripted Groovy connectors to connect to a large variety of systems, the samples in this section show connections to several different external resources. The samples are broken down as follows:

"Samples That Use the PowerShell Connector Toolkit to Create Scripted Connectors"

This sample uses the PowerShell Connector Toolkit to create a PowerShell connector, and 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.

"Scripted Kerberos Connector Sample"

This sample demonstrates how to use the scripted Kerberos connector to manage Kerberos user principals and to reconcile user principals with OpenIDM managed user objects.

"Audit Samples"

This sample uses a ScriptedSQL implementation of the Groovy Connector Toolkit to direct audit information to a MySQL database.

"Roles Samples - Demonstrating the OpenIDM Roles Implementation"

This sample builds on "Sample 2 - LDAP One Way", and extends that sample to demonstrate how roles are implemented in OpenIDM.

"The Multi-Account Linking Sample"

This sample illustrates how OpenIDM addresses links from multiple accounts to one identity.

"The Trusted Servlet Filter Sample"

This sample demonstrates how to use a custom servlet filter and the Trusted Request Attribute Authentication Module in OpenIDM. Once configured, OpenIDM can use the servlet filter to authenticate through another service.

"Full Stack Sample - Using OpenIDM in the ForgeRock Identity Platform"

This sample demonstrates the integration of three ForgeRock products: OpenIDM, OpenDJ, and OpenAM. With this sample, you can see how you can use OpenAM for authentication, for user identities that are maintained with OpenIDM, based on a data store of users in OpenDJ.

"Workflow Samples"

The workflow sample and use cases demonstrate how OpenIDM uses workflows to provision user accounts. The samples demonstrate the use of the Self-Service UI to enable user self-registration,

  • "Sample Workflow - Provisioning User Accounts"

    The provisioning workflow sample demonstrates a typical use case of a workflow — provisioning new users. The sample demonstrates the use of the Admin UI, to configure user self-service and the Self-Service UI that enables users to complete their registration process.

  • "Workflow Use Cases"

    The workflow use cases work together to provide a complete business story, with the same set of sample data. Each of the use cases is integrated with the Self-Service UI.

"Google Sample - Connecting to Google With the Google Apps Connector"

This sample uses the Google Apps Connector to manage the creation of users and groups on an external Google system, using OpenIDM’s REST interface.

"Salesforce Sample - Salesforce With the Salesforce Connector"

This sample uses the Salesforce Connector demonstrate reconciliation of user accounts from the OpenIDM repository to Salesforce, and from Salesforce to the OpenIDM repository.

"Custom Endpoint Sample"

OpenIDM supports scriptable custom endpoints that enable you to launch arbitrary scripts through an OpenIDM REST URI. This sample shows how custom endpoints are configured and returns a list of variables available to each method used in a custom endpoint script.

Installing the Samples

Each sample directory in openidm/samples/ contains a number of subdirectories, such as conf/ and script/. To start OpenIDM 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, but not all samples require additional software, such as an external LDAP server or database.

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

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 "Changing the Default Configuration" in the Integrator’s Guide.

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 "First OpenIDM Sample - Reconciling an XML File Resource".

Preparing OpenIDM

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.

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 openidm/db/openidm directory.

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

OpenIDM should then be ready to start with a new sample. For a number of the samples in this guide, users are created either with the UI or directly with a commons REST call. Users that have been created in the repository (managed users) should be able to log into the Self-Service UI.