How to introduce a custom object class to embedded LDAP of Identity Server

WSO2 Identity Server (IS) 3.2.0 comes with an embedded-apacheds ldap as the default user store. We can introduce new attributes to embedded-ldap through custom object classes, in order to use them when persisting user information in  IS.

I have described how to write a custom object class and introduce it to a stand alone LDAP server in my previous post.

In this post I intend to describe how to import a custom object class to Identity Server's default user store and how to use it when adding users to IS.

Step 1: Write your custom object class with the required additional attributes and save it with .ldif extension. 

Before defining attributes in your custom object class, make sure to check what are the attributes that are already supportted  by LDAP  for creating user entries, so that you can use them without defining new attributes and also can avoid conflicts with existing attribute names.

Following is the custom object class that we will import into embedded-apacheds of IS.

dn: cn=schema
changetype: modify
add: attributeTypes
attributeTypes: ( 2.25.128424792425578037463837247958458780603.6
        NAME 'nicNumber'
        EQUALITY caseIgnoreMatch
        SUBSTR caseIgnoreSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
attributeTypes: ( 2.25.128424792425578037463837247958458780603.7
        NAME 'passportNumber'
        EQUALITY caseIgnoreMatch
        SUBSTR caseIgnoreSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} )
-
add: objectClasses
objectClasses: ( 2.25.128424792425578037463837247958458780603.8
    NAME 'samplePerson'
    DESC 'samplePerson'
    SUP wso2Person
    STRUCTURAL
    MAY  ( nicNumber $ passportNumber)
 )

This object class named: 'samplePerson' defines two new attributes to store NIC No. and Passport No. of a user. 

Note the line 19 which implies that 'samplePerson' inherits the 'wso2Person' which is once again a custom object class that we have already introduced to embedded-ldap of IS.

Step 2: Download the latest IS build from here. [IS 3.2.0 is not released yet and a latest build from trunk is hosted in this location.]

Step 3: Start Identity Server and connect to its embedded-ldap through Apache Directory Studio. If you are not familiar with Apache Directory Studio before, this post describes how to perform this step.

Step 4: Import the ldif file containing the new object class definition into the LDAP instance of IS.
You can do it as follows:
i). Locate the 'LDAP Browser' window in Apache Directory Studio as shown below.

                                                                      figure 1
ii). Right click on the 'ou=schema' context entry, select 'import->LDIF import' and point to the samplePerson ldif file and import it.
If you do not see any errors, that means ldif is successfully imported.

Step 6: Use the new object class for creating users in Identity Server.

To reflect the effect of the new object class in embedded-ldap, we need to restart the the Identity Server and also need to do some configuration level changes.

i).  Shutdown the IS.
ii). Locate 'embedded-ldap.xml' and 'user-mgt.xml' config files in [IS_HOME]/repository/conf folder and do the following changes.

• Find the 'EmbeddedLDAP' element in embedded-ldap.xml and change its 'AdminEntryObjectClass' property value to 'samplePerson'.

samplePerson

• Find 'UserStoreManager' element in 'user-mgt.xml' and change its 'UserEntryObjectClass' property to 'samplePerson' so that when adding users in IS, user entries will be created with new objectClass.

samplePerson 

iii). Delete the directory named: 'root' located in the path: [IS_HOME]/repository/data/org.wso2.carbon.directory. - so that default partition will be created again at the restart with admin user entry constructed with new objectClass.

iv). Start Identity Server.

v). Login to the management console with admin, admin credentials and add a new user through 'Users and Roles' tab in left hand panel.

vi). Now view the ldap user entry of the newly added user through 'LDAP Browser' window of Apache Directoy Studio.

                                                          figure 2
As you can see in the above figure 2, new user entry is constructed with the objecClass 'samplePerson'.

Step 7: You can use newly introduced attributes in user's profile of IS through 'Claim Management', which you will find in the left hand panel of  the management console.

Voilà, we are done.. :)