OIM 11.1.2.0.0 (11gR2) API - UserManager

OIM 11.1.2.0.0 (11gR2) API - UserManager

In this post, I will explain UserManager service API provided by Oracle Identity Manager 11.1.2.0.0 (11gR2). OIM API can be used to develop clients which can communicate with OIM to perform various operations on OIM objects.

OIM supports two ways by which clients can be developed. They are :
1.    oracle.iam.platform.OIMClient
2.    Thor.API.tcUtilityFactory

Thor.API.tcUtilityFactory API was supported in the previous versions of OIM and it is still provided in the latest releases. But oracle.iam.platform.OIMClient is recommneded by Oracle and it should be preferred over tcUtilityFactory as it provides more robust way to build clients.
Here I will give you a few code snippets which are used to connect to OIM server and perform operations on OIM objects.

1. Setup
• Copy <IDM_HOME>/server/client/oimclient.zip on local machine. Extract the zip file. The extracted folder contains conf, lib and oimclient.jar.
• Add oimclient.jar and libraries from lib folder to the classpath of the client project. The project should have following jars in the classpath :
• commons-logging.jar
• spring.jar
• oimclient.jar
• jrf-api.jar
• wlfullclient.jar

                              Generation of wlfullclient.jar is explained at this location :http://docs.oracle.com/cd/E12840_01/wls/docs103/client/jarbuilder.html

• Make sure JDK 1.6 and ANT 1.7 are present in the classpath


1. Initialize
• Create OIMClient instance by preparing the environment:


        Hashtable<Object, Object> env = new Hashtable<Object, Object>();
        env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL, "weblogic.jndi.WLInitialContextFactory");
        env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, "t3://localhost:14000");
        System.setProperty("java.security.auth.login.config", "/home/ganesh/com.gsk.oim/config/authwl.conf");
        System.setProperty("OIM.AppServerType", "wls");
        System.setProperty("APPSERVER_TYPE", "wls");
        OIMClient oimClient = new OIMClient(env);
 
2. Login
• Once OIMClient is instantiated, the instance is used to login by providing correct username and password. login() method throws LoginException if login is unsuccessful:


        oimClient.login("xelsysadm", "Welcome1".toCharArray(), env);
       
 
3. Lookup UserManager Service
• UserManager is the Service class which is mainly used to perform various User operations. It can be instantiated in the following manner:


        UserManager userManager = oimClient.getService(UserManager.class);

On creation of userManager instance, we have an object which can connect and perform changes in OIM server. I will discuss a few basic scenarios which are widely used by OIM clients:

• User Creation 

As I said earlier, UserManager is the instance which is used to perform ,as the name suggests, User specific actions. To create a User, we must pass a oracle.iam.identity.usermgmt.vo.User object to UserManager's create method. It takes UserId and a HashMap of user attributes as input. Following code snippet shows User Creation:
   
      HashMap<String, Object> userAttributeValueMap = new HashMap<String, Object>();
        userAttributeValueMap.put("act_key", new Long(1));
        userAttributeValueMap.put("User Login", userId);
        userAttributeValueMap.put("First Name", "Ganesh");
        userAttributeValueMap.put("Last Name", "Kamble");
        userAttributeValueMap.put("Email", "ganesh.kamble@abc.com");
        userAttributeValueMap.put("usr_password", "P1ssword");
        userAttributeValueMap.put("Role", "OTHER");
        User user = new User("Ganesh", userAttributeValueMap);
        userManager.create(user);
   
    Here we have created a userAttributeValueMap which stores mandatory attributes required for User Creation through OIM API. User object is created using an Unique Id and the HashMap. We pass this User object to UserManager.create(user) method. It returns UserManagerResult. We can verify the status by using UserManagerResult.getStatus() method. 

• User Retrieval

    To retrieve the details of a user, UserManager provides several methods named getDetails() distinguished by the input parameters. I will take a method which takes input as userid, a set of attributes which are to be returned for each user and a boolean flag specifying whether the userid is the user login. If blank Set is given in the input, the method returns all the attributes of the User.

        Set<String> resAttrs = new HashSet<String>();
        User user = userManager.getDetails("Ganesh", resAttrs, true); 

• User Update

     UserManager provides methods named modify to update User details in OIM. I will talk about the method which takes User Object as input. In the following code snippet, I have retrieved a User with the loginId "Ganesh" and updated it with the changed user attributes
   
       Set<String> resAttrs = new HashSet<String>();
        User retrievedUser = userManager.getDetails("Ganesh", resAttrs, true);

        HashMap<String, Object> userAttributeValueMap = new HashMap<String, Object>();
        userAttributeValueMap.put("act_key", new Long(1));
        userAttributeValueMap.put("User Login", userId);
        userAttributeValueMap.put("First Name", "Ganesh");
        userAttributeValueMap.put("Last Name", "Kamble");
        userAttributeValueMap.put("Email", "ganesh.kamble@xyz.com");
        userAttributeValueMap.put("usr_password", "P@ssword");
        userAttributeValueMap.put("Role", "Other");

        User user = new User((String) retrievedUser.getAttribute("User Login"), userAttributeValueMap);
        userManager.modify(user); 

• User Search

OIM provides the support to search Users based on a particular criteria. We build a SearchCriteria based on which the Users need to be inquired, pass the SearchCriteria instance to UserManager.search() method as shown below:
   
       SearchCriteria searchCriteria = new SearchCriteria("Email", "ganesh.kamble@xyz.com", SearchCriteria.Operator.EQUAL);
        Set<String> attrNames = null;
        HashMap<String, Object> mapParams = new HashMap<String, Object>();
        mapParams.put("STARTROW", 0);
        mapParams.put("ENDROW", 1);
        List<User> users = null;
        users = userManager.search(searchCriteria, attrNames, mapParams);
   
     Here I have prepared a SearchCriteria which indicates the Email of the User should be EQUAL to ganesh.kamble@xyz.com. mapParams are the ConfigurationParameters which provides the functionality of more granular search. They can be STARTROW, ENDROW, SORTEDBY and SORTORDER. Here I have used STARTROW and ENDROW which indicates which subset of the complete result should be fetched. SORTEDBY sorts the result by User Login by default. It can be changed to the desired attribute. SORTEDORDER can be SortOrder.DESCENDING or SortOrder.ASCENDING latter being the default.

• Lock/Unlock User Account

The following methods locks/unlocks a particular user account.
                 userManager.lock(userId, true, true);

                    Here first parameter is the id of the user to be locked. Second parameter indicates whether its a manual lock (true) or system lock (false). And third parameter indicates whether the userId is the UserLogin Id.

                userManager.unlock(userId, true);

                    Here first parameter is the id of the user to be locked. Second parameter is true if the userId is the UserLogin id.



    In this post, I have tried to cover some basic user operations on User entity. Each of the above operation comes in different flavours. You can find the entire set of OIM API at location : http://docs.oracle.com/cd/E27559_01/apirefs.1112/e28159/toc.htm . The detailed information on how to use the API is explained at this location : http://docs.oracle.com/cd/E27559_01/dev.1112/e27150/apis.htm#BCFGCGHI .

    The set of attributes which OIM understands is given below. These attributes can be passed in the HashMap as an input. Also when you inquire the user, these attributes will be returned.

    [ FA Territory, Employee Number, Middle Name, Manually Locked, usr_disabled, Display Name, LDAP Organization, usr_locked, Currency, Time Format, usr_created, usr_deprovisioning_date, Full Name, Country, Accessibility Mode, usr_pwd_expire_date, usr_pwd_cant_change, Email, usr_data_level, Automatically Delete On, Locked On, usr_login_attempts_ctr, Last Name, First Name, Locality Name, usr_policy_update, Street, Embedded Help, Department Number, usr_createby, usr_pwd_warned, Manager Login, Telephone Number, Manager First Name, usr_updateby, Home Phone, LDAP Organization Unit, usr_pwd_min_age_date, User Login, Title, Role, FA Language, Password Generated, usr_provisioning_date, usr_pwd_warn_date, Organization Name, usr_locale, usr_update, Date Format, usr_timezone, Mobile, usr_pwd_reset_attempts_ctr, End Date, Pager, usr_deprovisioned_date, Color Contrast, PO Box, usr_create, LDAP GUID, Xellerate Type, usr_change_pwd_at_next_logon, usr_provisioned_date, Common Name, Start Date, usr_manager_key, Number Format, usr_pwd_expired, Hire Date, User Name Preferred Language, Home Postal Address, Font Size, Manager Last Name, Description, Fax, Postal Code, act_key, usr_key, Common Name Generated, Status, Generation Qualifier, Postal Address, State, Manager Display Name, usr_pwd_never_expires, Initials, usr_pwd_must_change, LDAP DN ]