Overview
At the heart of OpenIDM are managed objects. Out of the box three managed objects are configured:
User: User identities, effectively this is your central identity store.
Role: An object for modelling roles.
Assignment: An object for modelling assignments. Assignments are effectively ways of capturing sets of entitlements across mapping. Which can then be associated with roles.
In this blog we will examine the user managed object in detail, roles and assignments will be explored later in the series.
It is important to understand that objects can really be anything and you can create new objects very easily. This is an incredibly powerful way to model all sorts of different things:
Users
Organisations, divisions, teams or other parts of a business.
Devices and hardware.
Products and offerings.
Anything else you can think of! Managed objects are completely configurable.
Not only can you model things, but you can also model the relationships between things. For example:
Which organisations a user belongs to.
The devices that a user owns.
The products a user has.
The teams that belong to an organisation.
Anything else you can think of!
Objects
All objects have the following properties:
Details: The name and icon that represents the object in the UI.
Schema: Properties, their validation rules and their relationships.
Scripts: Different hooks for running scripts throughout the object lifecycle e.g. postCreate
Properties: Rules for special attribute behaviors e.g. passwords should be encrypted and private.
Lets look at each of this in detail.
Details
Not much to say here. Just the name of your object and you can select a funky icon that will be displayed throughout the interface wherever your object is used.
Schema
The properties that actually comprise your object. Lets take a look at the managed user schema.
On the left, under Schema Properties you can see each property that comprises a user. There are many properties available out of the box and you can easily add or remove properties as required.
Let’s look at a property in detail.
So what does a property comprise of:
Property Name: The internal name users within the OpenIDM platform to refer to the property, think of it like a variable name only used internally.
Readable Title: The name that will be used to refer to the property in the user interface.
Description: Simple description of the attribute that when populated is used throughout the interface as a tooltip.
Viewable: Can it be seen in the UI?
Searchable: Is it indexed and searchable in the UI?
End users allowed to edit: Used are allowed to update the value using self service.
Minimum Length: Minimum length of the attribute value.
Pattern: Any specific pattern to which the value of the property must adhere. e.g. date formats.
Validation Policies: Rules that can be used to define attribute behavior. We will look at these in detail in a moment.
Required: Must be populated with a value.
Return by Default: If true, will be returned when user details are requested via the API. If false, will only be returned if specifically asked for.
Type: Type of the attribute: String, Array, Boolean, Integer, Number. Object or Relationship. We will look at relationships in a moment.
Validation Policies
Validation policies are ways to validate the attribute. The example below checks that the mail attribute is a valid email address. This prevents the user from inputting an invalid email address during self registration or an administrator changing the email incorrectly.
Similarly for the password attribute validation policies allow you to enforce password rules, for example:
Relationships
Relationships are incredibly powerful and really at the heart of what OpenIDM does. If you have installed OpenIDM in part 1 then I recommend you take a look at the out of the box managed objects to really understand this, however we will briefly discuss it.
The out of the box managed user object defines a relationship between managers and reports.
manager:
reports:
What are we saying here?
User’s have a manager. This is a Relationship. It is in fact a reverse relationship. As manager A, has reports X,Y,Z and reports X,Y,Z have the manager A.
User’s can also have reports. They may have multiple reports. Note this is an Array of Relationships: A manages X, A manages Y, A manages Z. Likewise this is a reverse relationship.
Relationships let you model relationships between all sorts of types of objects, users, organisations, devices, products, anything.
Scripts
Objects also have events which can be used to trigger events.
Out of the box, the above scripts are configured:
onCreate: The script that runs when the object is created. In this case, a script used to set the default fields for a user.
onDelete: The script that runs when the object is deleted. In this case, a script is used to cleanup users after deletion.
These scripts are completely configurable and new scripts can easily be added.
If you try add a new script you will see there are three options:
Script – Inline Script: script defined within the UI.
Script – File Path: a script stored within the OpenIDM configuration directory. This is how out of the box scripts work. If you navigate to /openidm/bin/defaults/script/ui you can examine these out of the box scripts to see what they do.
Workflow – Event can be used to trigger a workflow.
Note: If you add new scripts, these should be placed somewhere else, usually: /usr/local/env/box/openidm/script
Scripting is a great way to do all sorts of things to help you manage objects.
Properties
Properties let you define additional behaviors for attributes.
Encrypted: The attribute value is encrypted. This means it can be decrypted and the value retrieved if required.
Private: Restricts HTTP access to sensitive data, if this is true the attribute is not returned when using the REST API.
Virtual: The attribute is calculated on the fly, usually from a script.
Hashed: The attribute is hashed. Hashing is a one way function and the usual way that passwords should be stored. You hash the password when a user registers for the first time. When they log in again subsequently you hash the password that they enter against the original password hash. If they match you know the passwords are the same. Crucially, it is impossible to take a hash and extract the original password from it.
A common use for this is calculating effective roles. Effective roles are dynamically calculated using an out of the box script:
You can examine the script here: /openidm/bin/defaults/script/roles/effectiveRoles.js.
Managed Objects and the REST API
For the final part of this blog I want to take a look at something I think is pretty cool. The OpenIDM REST API.
All managed objects ( including the ones you can create yourself ) are automatically made available using a REST API.
Using the API you can Create, Return, Update and Delete objects ( CRUD ) as well as search for and query objects. We will dive into the REST API in a later series but we can do a quick demo just to get a feel for how it works.
I recommend downloading Postman for this, Postman is a plug in for Chrome that lets you easiy invoke REST API’s. You can grab it here: https://www.getpostman.com/
Once you have Postman. Log into OpenIDM as administrator and go to Manage, then User and create a new user:
Press Save. Now look at the URL:
Note the long string of letters and numbers. This is the object id for our new user.
Now if we go to Postman, we can setup a new request:
Make sure you populate the headers as I have above. Set the request to a GET and enter a URL to return. In our case:
http://localhost.localdomain.com:8080/openidm/managed/user/9a372a83-1ec0-4036-9a02-6557e8eb4ed7
How does this break down:
Now, if you press Send, you should retrieve the user we just created:
This is just a small taster of what the REST API can do and we will explore it in much more detail in later blogs. You can also read all about the REST API here:
https://forgerock.org/openidm/doc/bootstrap/integrators-guide/index.html#appendix-rest
This blog post was first published @ http://identity-implementation.blogspot.no/, included here with permission from the author.