Monday, 27 June 2016

A Beginners Guide to OpenIDM - Part 1

This is the first in a series of blogs aiming to demystify OpenIDM, the Identity Management component of the ForgeRock platform.

I have actually been really impressed with OpenIDM and how much you can accomplish with it in a short time. It is fair to say though that if you are used to more traditional IDM technologies such as Oracle Identity Manager then it can take a bit of time to get your head around how OpenIDM works and how to get things done.

In the first of this series of tutorials I want to walkthrough a basic installation of OpenIDM, look at the architecture of the product and how everything fits together.

This blog continues my OpenIDM Beginners series, catch up with the links below:

A Beginners Guide to OpenIDM - Part 1
A Beginners Guide to OpenIDM - Part 2 - Objects
A Beginners Guide to OpenIDM - Part 3 - Connectors
A Beginners Guide to OpenIDM - Part 4 - Mappings
A Beginners Guide to OpenIDM - Part 5 - User Registration
A Beginners Guide to OpenIDM - Part 6 - Provisioning to Active Directory


OpenIDM is primarily concerned with the following functionality:
  • Objects and relationships: Quickly modelling complex objects, schemas and the relationships between them, e.g. for users, devices and things and exposing them as RESTful resources.
  • Data Synchronization: Moving data to and from systems such as Active Directory, databases, webservices and others, makes use of connectors and mappings to:
    • Create and update users and accounts in target systems i.e. pushing data to target systems from OpenIDM.
    • Reconcile users and accounts from target systems i.e. pulling data into OpenIDM from target systems.
    • Move data about users, devices and things to and from any other system.
  • Workflow Engine: processes such as request and approval of access to resources and much more.
  • Self Service: Enabling end users to easily and securely register accounts, retrieve forgotten passwords and manage their profiles.
  • Task Scheduling: Automating certain processes to run periodically.
All of this is built upon a consistent set of REST APIs with numerous hooks throughout the platform for scripting behaviors using Groovy or javascript.

OpenIDM also makes use of a data store into which it reads and writes:

  • Data for users, devices and things: e.g. actual user account data such as first_name=Wayne, last_name=Blacklock for all objects that OpenIDM is managing.
  • Linked account data: "Mirrored data" for the systems that OpenIDM has been integrated with. This enables you to view and manipulate all of a users account data across all systems from OpenIDM.
  • Various pieces of state relating to workflow, scheduling and other functionality
Finally, all of the OpenIDM's config is stored as .json files locally per deployment.

Logical Architecture

The diagram below aims to give you a bit of an overview of how OpenIDM fits together. We will explore each major component in detail with worked examples over the next few months.

Getting Started

This blog series is intended to be a practical introduction to OpenIDM so the first thing we need to do is download and install it.

If you already have a ForgeRock Backstage subscription you can download IDM from there. Otherwise you need to register for the evaluation version:

Note: For now we are going to use the embedded OpenIDM OrientDB database, rather than install an external database. The OrientDB database ships with OpenIDM and is ready to go right from the start however please note it is not suitable for production deployments. We will cover the usage of another database for enterprise deployments later in the series.

Download and unzip OpenIDM to a directory. Make sure you have Java installed, configured and available from the command line.

To start up OpenIDM simply type:

Linux: ./
Windows: startup.bat

That's it! By default OpenIDM runs on port 8080. You can them navigate to the interfaces at:

You'll note both pages look similar, but one is for users and one is for admins.

The default username and password for the administrator is openidm-admin / openidm-admin.

Log into the administrator interface, once you have logged in you should see the dashboard:

Over the rest of this series we will explore the functionality of OpenIDM in detail.

Friday, 10 June 2016

A Quick & Easy Way to Create Test Users in OpenAM

More often then not we need ways to create test users and this isn't something that we want to spend large amounts of time doing. Helpfully OpenAM comes bundled with a script which can quickly let you do this.

There is a script named make-ldif that can be found here: openam/opends/bin

This script generates an ldif file that contains a set of test users which randomly generate names, email addresses and other attributes. An example of this output is below:

 dn: uid=user.41,ou=People,dc=example,dc=com  
 objectClass: top  
 objectClass: person  
 objectClass: organizationalperson  
 objectClass: inetorgperson  
 givenName: Addie  
 sn: Achille  
 cn: Addie Achille  
 initials: AJA  
 employeeNumber: 41  
 uid: user.41  
 userPassword: password  
 telephoneNumber: +1 892 829 0033  
 homePhone: +1 307 295 8896  
 pager: +1 397 006 1503  
 mobile: +1 168 140 0201  
 street: 86587 Hillcrest Street  
 l: Santa Fe  
 st: NJ  
 postalCode: 76090  
 postalAddress: Addie Achille$86587 Hillcrest Street$Santa Fe, NJ 76090  
 description: This is the description for Addie Achille.  
To run the script, you need to configure the example.template file to match your environment and user attributes.
 define suffix=dc=example,dc=com  
 define numusers=10001  
 branch: [suffix]  
 branch: ou=People,[suffix]  
 subordinateTemplate: person:[numusers]  
 template: person  
 rdnAttr: uid  
 objectClass: top  
 objectClass: person  
 objectClass: organizationalPerson  
 objectClass: inetOrgPerson  
 givenName: <first>  
 sn: <last>  
 cn: {givenName} {sn}  
 initials: {givenName:1}<random:chars:ABCDEFGHIJKLMNOPQRSTUVWXYZ:1>{sn:1}  
 employeeNumber: <sequential:0>  
 uid: user.{employeeNumber}  
 mail: {uid}@[maildomain]  
 userPassword: password  
 telephoneNumber: <random:telephone>  
 homePhone: <random:telephone>  
 pager: <random:telephone>  
 mobile: <random:telephone>  
 street: <random:numeric:5> <file:streets> Street  
 l: <file:cities>  
 st: <file:states>  
 postalCode: <random:numeric:5>  
 postalAddress: {cn}${street}${l}, {st} {postalCode}  
 description: This is the description for {cn}.  
The key attributes to change are:
define suffix=dc=example,dc=com  
define numusers=10001  
Set the suffix and maildomain to match the installation of your OpenAM instance. 
Set numusers to the number of test users you want to generate. I usually use about 500.

You will also need to add any attributes that you need users in the schema to have by default. 

To save time, I have attached an example.template that will work perfectly with a clean installation of OpenAM that has the default out of the box domain suffix and attribute schema. Download it from here.

Once you have an example.template. You can run the make-ldif script using the command below, users.ldif is the desired output file:

 ./make-ldif -t ../config/MakeLDIF/example.template -o /usr/local/tools/users.ldif  
Finally, you can use the ldapadd tool to process users.ldif and create the users:
 ldapadd -h localhost -p 50389 -D "cn=Directory Manager" -w cangetinam -f /usr/local/tools/users.ldif -c  
The ldapadd tool will connect to the embedded DJ directory, ensure you update the host (-h), port (-p), bindDN (-D) and password (-w) to match your installation.

This should result with an OpenAM instance fully populated with users.