Programmatically Provisioning Users via Oracle Identity Manager's Java API

Ultimate control over your identities

Oracle Identity Manager (OIM) 11gR1 provides complete life-cycle management of user identities. Identity life-cycle management includes the creation, modification and termination of user access to provisioned resources. Organizations have specific requirements for how they need to manage both internal users and external users (citizens, customers, students, etc.). A provisioning solution needs to be flexible so that it can integrate into the various parts of an organization. OIM 11gR1 provides a range of options for how it can be customized. One of the most powerful and flexible ways of extending a solution is through the use of a Application Programming Interface (API). OIM 11gR1 provides a Java API which can be used to interface with multiple aspects of identity life-cycle management.

The examples covered, in these procedures, only demonstrate a select set of capabilities (basic User management) from a larger collection of interfaces and methods provided by the OIM 11gR1 Client Java API.  Organizations have used these OIM 11gR1 Java APIs for unique integration with their processes, and to support specialized user interface requirements.

User Management

The OIM 11gR1 Java APIs support searching, creating, reading, updating and deleting of Users. This procedure will cover how to use the OIM 11gR1 Java APIs to perform these operations.

Reference

Getting Started

OIM 11gR1 leverages a new Java API. The previous API (Thor) is still available. But, it is recommended that new projects use the OIM 11gR1 Client API.

Create a directory for downloading the required OIM files and sample source files. This procedure will use a directory/folder called examples.

Required server files

You will need to obtain the following files from the OIM 11gR1 server:

oimclient.zip
  • The OIM 11gR1 Java API classes are packaged as a jar file called oimclient.jar. This jar file is packaged within the oimclient.zip file. The oimclient.zip file is located in the OIM_ORACLE_HOME/server/client folder, on the OIM 11gR1 server.
  • Copy oimclient.zip from the OIM 11gR1 server:
    scp user@oimserver:/OIM_ORACLE_HOME/server/client/oimclient.zip .
  • Expand the oimclient.zip file:
    unzip oimclient.zip
  • The oimclient.zip file contains the following items:

    README text file containing information on using the bundled sample program
    oimclient.jar JAR file containing the OIM 11gR1 classes
    conf Sub-folder containing auth files
    lib Sub-folder containing jar files required by the OIM 11gR1 API
    sample Sub-folder containing bundled sample source code (not used)
wlfullclient.jar
  • Access the Weblogic Server system
    ssh user@wlserver
  • Change directories to the server/lib directory.
    cd WL_HOME/server/lib
  • Use the following command to create the wlfullclient.jar file in the server/lib directory:
    java -jar wljarbuilder.jar
  • Copy the wlfullclient.jar file.

Get the samples

This procedure will use a collection of samples that can be downloaded from a svn (subversion) repository, associated with Project OpenPTK. The following command will download the sample source code into a directory structure named oim:

svn export https://svn.java.net/svn/openptk~svn/branches/Oracle/OIM11gR1/examples/java/OIMClient/src/oim oim --username guest

Note: If you do not have svn (or a similar client subversion tool) you can get a "snap shot" of the source files as a downloadable zip file.

When the required jar files and the example code have been downloaded, the folder/directory structure should look like the following diagram.

folder structure

Review the samples

The sample source code leverages a Java packaging name-space starting with oim.client. At this level, you will find the following items:

Client.java Abstract class that contains OIM 11gR1 Server connection information. This class is used by all of the sample programs.
You will need to edit this file and change the OIM 11gR1 Server connection information.
organization Sub-folder for the package oim.client.organization which contains sample Java code that leverages some of the organization related capabilities of the OIM 11gR1 Client API. This folder and its samples are not used as part of this procedure.
request Sub-folder for the package oim.client.request which contains sample Java code that leverages some of the request related capabilities of the OIM 11gR1 Client API. This folder and its samples are not used as part of this procedure.
role Sub-folder for the package oim.client.role which contains sample Java code that leverages some of the role related capabilities of the OIM 11gR1 Client API. This folder and its samples are not used as part of this procedure.
user Sub-folder for the package oim.client.user which contains sample Java code that leverages some of the user related capabilities of the OIM 11gR1 Client API. We will be using some of these files to demonstrate basic operations related to a user:

ClientUser.java Abstract class, extends Client. It provides "User" specific capabilities.
UserChangePassword.java Not used as part of this procedure
UserCreate.java Demonstrates the creating of a user. Extends ClientUser
UserDelete.java Demonstrates the deleting of a user. Extends ClientUser
UserRead.java Demonstrates the reading of a user. Extends ClientUser
UserRegister.java Not used as part of this procedure
UserSearch.java Demonstrates the searching of users. Extends ClientUser
UserUnauthChallenge.java Not used as part of this procedure
UserUnauthSelfService.java Not used as part of this procedure
UserUpdate.java Demonstrates the updating of a user. Extends ClientUser

Class structure

The following diagram illustrates the class structure used by the samples. This procedure will cover many of the classes in the user package.

class structure

Source code

Client.java

This is an abstract class. It provides common methods that are used by all of the sub-categories; organization, request, role and user. For this procedure, we will focus on the user sub-category. This class establishes the connection to the OIM 11gR1 Server. It performs the following tasks:

  1. Creates a HashTable containing connection data
  2. Creates a OIMClient object using the HashTable
  3. Executes the OIMClinet.login(...) method to login as the proxy (admin) user

You will need to edit this file and set the OIM 11gR1 Server connection information. The URL, Admin UserId, and Admin Password will need to be set.

   private static final String OIM_URL = "t3://localhost:14000"; // OIM 11g deployment
   ...
   protected static final String OIM_USERNAME = "xelsysadm";
   protected static final String OIM_PASSWORD = "Passw0rd"; // "Passw0rd"
OIM_URL t3://hostname:port The url for connecting to the OIM 11gR1 server
OIM_USERNAME xelsysadm The login id of a user that has admin privileges to manage user accounts
OIM_PASSWORD password The password for the admin user

Note: The above example "hard codes" the proxy user's id and password.  The "hard coding" of these values is NOT recommended and is NOT secure.  The source code and techniques covered in these procedures are for demonstration purposes only and should NOT be used in a production environment.  The proxy user id and password should be accessible to the program at runtime and securely controlled.

ClientUser.java

This is an abstract class that extends Client and provides methods that can be used by sub-classes which need to leverage the User APIs. For example, The User APIs need the UserManager class to execute operations. This class performs the following tasks:

  1. Gets a UserManager object via the OIMClient.getService(UserManager.class) method.
  2. Gets a UnauthenticatedSelfService object via the OIMClient.getService(UnauthenticatedSelfService.class) method.(not used in this procedure)

UserCreate.java

This class extends ClientUser and demonstrates how a user can be "directly" created in the OIM 11gR1 user repository. Note: OIM 11gR1 also provides a "registration" facility for creating users. This procedure does not cover the registration mechanism (topic for another blog). This class performs the following tasks:

  1. Gets the UserManager
  2. Creates a HashMap, to hold attributes
  3. Adds attributes (name/value) to the HashMap
  4. Creates a User object using an accountId and adds the HashMap of attributes.
  5. Calls the UserManager create() method to create the new user.
  6. A UserManagerResult object is returned. It is evaluated.

NOTICE: If you plan on running this sample, you may need to update some of the variables. Check the following variables and make sure the values will work in your environment:
      String accountId = "jhomer";
      String first = "John";
      String last = "Homer";

UserSearch.java

This class extends ClientUser and demonstrates how to search for users in the OIM 11gR1 user repository. This class performs the following tasks:

  1. Gets the UserManager
  2. Creates a "simple" SearchCriteria object using an attribute name, attribute value and a SearchCriteria.Operator.
  3. Creates a HashSet of attribute names (what attributes to return in the search results).
  4. Creates a HashMap for search parameters. Parameters can include how to sort the search results and how many (rows) to return. This example uses a NULL HashMap which means that default parameters will be used.
  5. Calls the UserManager search() method. The method uses the Search Criteria, Attribute Names, and Parameters to perform the search.
  6. A List of User objects is return.
    For each user, its Attributes name and value are obtained. The user data is displayed.

NOTICE: If you plan on running this sample, you may need to update the source file. Uncomment and/or update one of the SearchCriteria items:
      criteria = new SearchCriteria("First Name", "John", SearchCriteria.Operator.EQUAL);
//      criteria = new SearchCriteria("Email", "John.Wayne@openptk.org", SearchCriteria.Operator.EQUAL);
//      criteria = new SearchCriteria("First Name", "scott", SearchCriteria.Operator.EQUAL);
//      criteria = new SearchCriteria("User Login", "*", SearchCriteria.Operator.EQUAL);
//      criteria = new SearchCriteria("usr_key", "*", SearchCriteria.Operator.EQUAL);

UserUpdate.java

This class extends ClientUser and demonstrates how to update a user in the OIM 11gR1 user repository. This class performs the following tasks:

  1. Gets the UserManager
  2. Creates a HashMap, to hold attributes (that will be updated)
  3. The attributes to be modified (name and value), are added to the HashMap
  4. Creates a User object using an accountId and adds the HashMap of attributes.
  5. Calls the UserManager modify() method to update the existing user.
  6. A UserManagerResult object is returned. It is evaluated.

NOTICE: If you plan on running this sample, you may need to update the "login id" to match the "login id" that was used to create the user. Check the following lines of code and make sure the values will work in your environment:
      user = new User("jhomer", mapAttrs);
      result = umgr.modify("User Login", "jhomer", user);

UserRead.java

This class extends ClientUser and demonstrates how to read a user in the OIM 11gR1 user repository. This class performs the following tasks:

  1. Gets the UserManager
  2. Creates a HashMap, to hold attributes (which ones to return)
  3. The attributes to be returned (name and value), are added to the HashMap
  4. Creates a User object using an accountId and adds the HashMap of attributes. In this example, the HashMap is null, all of the available/allowed attributes will be returned.
  5. Calls the UserManager getDetails() method to read the existing user.
  6. A User object is returned.
  7. The attributes can be obtained by calling the "getter" methods or by obtaining a HashMap of the attributes and iterating through it. Both techniques are used.

NOTICE: If you plan on running this sample, you may need to update the "login id" to match the "login id" that was used to create the user. Check the following lines of code and make sure the values will work in your environment:
      user = umgr.getDetails("jhomer", attrNames, true);

UserDelete.java

This class extends ClientUser and demonstrates how to delete a user in the OIM 11gR1 user repository. This class performs the following tasks:

  1. Gets the UserManager
  2. Calls the UserManager delete() method to delete the existing user.
  3. A UserManagerResult object is returned. It is evaluated.

NOTICE: If you plan on running this sample, you may need to update the "login id" to match the "login id" that was used to create the user. Check the following lines of code and make sure the values will work in your environment:
      result = umgr.delete("User Login", "jhomer");

Compile samples

Compile the Java code from the directory where the jar files and source files where downloaded. Set the CLASSPATH and run javac

export CLASSPATH=.:oimclient.jar:wlfullclient.jar
javac oim/client/*/*

Run samples

Create

A new user will be created with the login id of "jhomer".

java oim/client/user/UserCreate

LOG: __BEGIN__
LOG: UserManager ready
LOG: User object created: 'jhomer'
LOG: Creation status: 'COMPLETED'
LOG: __END__

Search

The new user is in the search output, lastname="John".

java oim/client/user/UserSearch

LOG: __BEGIN__
LOG: UserManager ready
LOG: search results, quantity=8
LOG: EntityId: 214, Id: 214, Attributes: Email='John.Homer@oracle.com', usr_key='214', User Login='JHOMER', Last Name='Homer', First Name='John', 
LOG: EntityId: 8, Id: 8, Attributes: Email='John.Smith@oracle.com', usr_key='8', User Login='JSMITH1', Last Name='Smith', First Name='John', 
LOG: EntityId: 27, Id: 27, Attributes: Email='John.Wayne@openptk.org', usr_key='27', User Login='JWAYNE', Last Name='Wayne', First Name='John', 
LOG: EntityId: 12, Id: 12, Attributes: Email='john.thompson@email.com', usr_key='12', User Login='JTHOMPSON', Last Name='Thompson', First Name='John', 
LOG: EntityId: 83, Id: 83, Attributes: Email='John.Simpson@openptk.org', usr_key='83', User Login='JSIMPSON', Last Name='Simpson', First Name='John', 
LOG: EntityId: 10, Id: 10, Attributes: Email='John.Smith3@oracle.com', usr_key='10', User Login='JSMITH3', Last Name='Smith', First Name='John', 
LOG: EntityId: 14, Id: 14, Attributes: Email='John.Hope@openptk.org', usr_key='14', User Login='JHOPE', Last Name='Hope', First Name='John', 
LOG: EntityId: 17, Id: 17, Attributes: Email='test@test.com', usr_key='17', User Login='JHENRY2', Last Name='Henry', First Name='John', 
LOG: __END__

Read

The new user, "jhomer" has the following details.

java oim/client/user/UserRead

LOG: __BEGIN__
LOG: UserManager ready
LOG: Got user detail
LOG: 
Id                            : 214
Entity Id                     : 214
Login                         : JHOMER
First Name                    : John
Middle Name                   : (null)
Last Name                     : Homer
Common Name                   : JHOMER
Display Name                  : John Homer
Employee Number               : (null)
Employee Type                 : Full-Time
Email                         : John.Homer@oracle.com
User Type                     : End-User
Country                       : (null)
Description                   : (null)
Status                        : Active
Generation Qualifier          : (null)
Account Status                : 0
Manager Key                   : (null)
Manually Locked               : (null)
User Disabled                 : 0
Policy Update Enabled         : (null)
Change Password At Next login : 1
Password Cant Change          : (null)
Password Expired              : (null)
Password Generated            : (null)
Password Must Change          : (null)
Password Never Expires        : (null)
Password Warned               : (null)
Attributes                    : 
FA Territory=
usr_pwd_warn_date='Tue Aug 07 22:23:17 CDT 2012
Employee Number=
usr_locale=
Middle Name=
Manually Locked=
usr_disabled='0
usr_update='Mon Apr 16 22:23:17 CDT 2012
Date Format=
Display Name='{base=John Homer}
Mobile=
usr_timezone=
LDAP Organization=
usr_locked='0
usr_pwd_reset_attempts_ctr='0
Currency=
End Date=
Pager=
usr_deprovisioned_date=
Time Format=
usr_created=
usr_deprovisioning_date=
Color Contrast=
PO Box=
usr_create='Mon Apr 16 22:23:17 CDT 2012
LDAP GUID=
Full Name='{base=null}
Accessibility Mode=
Country=
Xellerate Type='End-User
usr_change_pwd_at_next_logon='1
usr_pwd_expire_date='Tue Aug 14 22:23:17 CDT 2012
usr_pwd_cant_change=
Email='John.Homer@oracle.com
usr_provisioned_date='Mon Apr 16 22:23:16 CDT 2012
usr_data_level=
Common Name='JHOMER
Automatically Delete On=
Locked On=
Start Date=
Last Name='Homer
usr_login_attempts_ctr='0
First Name='John
Locality Name=
usr_manager_key=
Number Format=
usr_policy_update=
Street=
Embedded Help=
usr_pwd_expired=
Department Number=
Hire Date=
usr_createby='1
usr_pwd_warned=
Telephone Number=
Home Postal Address=
Font Size=
usr_updateby='1
Description=
Home Phone=
LDAP Organization Unit=
usr_pwd_min_age_date=
Assurance Level='1
Fax=
Postal Code=
act_key='1
usr_key='214
User Login='JHOMER
Title=
Status='Active
Generation Qualifier=
State=
Postal Address=
Initials=
usr_pwd_never_expires=
usr_pwd_must_change=
LDAP DN=
Role='Full-Time
FA Language=
Password Generated=
usr_provisioning_date=

LOG: __END__

Update

The new user, "jhomer" will be updated. You can see the modified email address in the Search output and the updated title in the Read output.

java oim/client/user/UserUpdate

LOG: __BEGIN__
LOG: UserManager ready
LOG: User object created
LOG: Modification status: 'COMPLETED'
LOG: __END__
java oim/client/user/UserSearch

LOG: __BEGIN__
LOG: UserManager ready
LOG: search results, quantity=8
LOG: EntityId: 214, Id: 214, Attributes: Email='jhomer@oracle.com', usr_key='214', User Login='JHOMER', Last Name='Homer', First Name='John', 
LOG: EntityId: 8, Id: 8, Attributes: Email='John.Smith@oracle.com', usr_key='8', User Login='JSMITH1', Last Name='Smith', First Name='John', 
LOG: EntityId: 27, Id: 27, Attributes: Email='John.Wayne@openptk.org', usr_key='27', User Login='JWAYNE', Last Name='Wayne', First Name='John', 
LOG: EntityId: 12, Id: 12, Attributes: Email='john.thompson@email.com', usr_key='12', User Login='JTHOMPSON', Last Name='Thompson', First Name='John', 
LOG: EntityId: 83, Id: 83, Attributes: Email='John.Simpson@openptk.org', usr_key='83', User Login='JSIMPSON', Last Name='Simpson', First Name='John', 
LOG: EntityId: 10, Id: 10, Attributes: Email='John.Smith3@oracle.com', usr_key='10', User Login='JSMITH3', Last Name='Smith', First Name='John', 
LOG: EntityId: 14, Id: 14, Attributes: Email='John.Hope@openptk.org', usr_key='14', User Login='JHOPE', Last Name='Hope', First Name='John', 
LOG: EntityId: 17, Id: 17, Attributes: Email='test@test.com', usr_key='17', User Login='JHENRY2', Last Name='Henry', First Name='John', 
LOG: __END__


java oim/client/user/UserRead

LOG: __BEGIN__
LOG: UserManager ready
LOG: Got user detail
LOG: 
Id                            : 214
Entity Id                     : 214
Login                         : JHOMER
First Name                    : John
Middle Name                   : (null)
Last Name                     : Homer
Common Name                   : JHOMER
Display Name                  : John Homer
Employee Number               : (null)
Employee Type                 : Full-Time
Email                         : jhomer@oracle.com
User Type                     : End-User
Country                       : (null)
Description                   : (null)
Status                        : Active
Generation Qualifier          : (null)
Account Status                : 0
Manager Key                   : (null)
Manually Locked               : (null)
User Disabled                 : 0
Policy Update Enabled         : (null)
Change Password At Next login : 1
Password Cant Change          : (null)
Password Expired              : (null)
Password Generated            : (null)
Password Must Change          : (null)
Password Never Expires        : (null)
Password Warned               : (null)
Attributes                    : 
FA Territory=
usr_pwd_warn_date='Tue Aug 07 22:23:17 CDT 2012
Employee Number=
usr_locale=
Middle Name=
Manually Locked=
usr_disabled='0
usr_update='Mon Apr 16 22:24:19 CDT 2012
Date Format=
Display Name='{base=John Homer}
Mobile=
usr_timezone=
LDAP Organization=
usr_locked='0
usr_pwd_reset_attempts_ctr='0
Currency=
End Date=
Pager=
usr_deprovisioned_date=
Time Format=
usr_created=
usr_deprovisioning_date=
Color Contrast=
PO Box=
usr_create='Mon Apr 16 22:23:17 CDT 2012
LDAP GUID=
Full Name='{base=null}
Accessibility Mode=
Country=
Xellerate Type='End-User
usr_change_pwd_at_next_logon='1
usr_pwd_expire_date='Tue Aug 14 22:23:17 CDT 2012
usr_pwd_cant_change=
Email='jhomer@oracle.com
usr_provisioned_date='Mon Apr 16 22:23:16 CDT 2012
usr_data_level=
Common Name='JHOMER
Automatically Delete On=
Locked On=
Start Date=
Last Name='Homer
usr_login_attempts_ctr='0
First Name='John
Locality Name=
usr_manager_key=
Number Format=
usr_policy_update=
Street=
Embedded Help=
usr_pwd_expired=
Department Number=
Hire Date=
usr_createby='1
usr_pwd_warned=
Telephone Number=
Home Postal Address=
Font Size=
usr_updateby='1
Description=
Home Phone=
LDAP Organization Unit=
usr_pwd_min_age_date=
Assurance Level='1
Fax=
Postal Code=
act_key='1
usr_key='214
User Login='JHOMER
Title='Engineer
Status='Active
Generation Qualifier=
State=
Postal Address=
Initials=
usr_pwd_never_expires=
usr_pwd_must_change=
LDAP DN=
Role='Full-Time
FA Language=
Password Generated=
usr_provisioning_date=

LOG: __END__

Delete

The new user, "jhomer" will be deleted. The search output no longer contains the user.

java oim/client/user/UserDelete

LOG: __BEGIN__
LOG: UserManager ready
LOG: Delete status: 'COMPLETED'
LOG: __END__


java oim/client/user/UserSearch

LOG: __BEGIN__
LOG: UserManager ready
LOG: search results, quantity=7
LOG: EntityId: 8, Id: 8, Attributes: Email='John.Smith@oracle.com', usr_key='8', User Login='JSMITH1', Last Name='Smith', First Name='John', 
LOG: EntityId: 27, Id: 27, Attributes: Email='John.Wayne@openptk.org', usr_key='27', User Login='JWAYNE', Last Name='Wayne', First Name='John', 
LOG: EntityId: 12, Id: 12, Attributes: Email='john.thompson@email.com', usr_key='12', User Login='JTHOMPSON', Last Name='Thompson', First Name='John', 
LOG: EntityId: 83, Id: 83, Attributes: Email='John.Simpson@openptk.org', usr_key='83', User Login='JSIMPSON', Last Name='Simpson', First Name='John', 
LOG: EntityId: 10, Id: 10, Attributes: Email='John.Smith3@oracle.com', usr_key='10', User Login='JSMITH3', Last Name='Smith', First Name='John', 
LOG: EntityId: 14, Id: 14, Attributes: Email='John.Hope@openptk.org', usr_key='14', User Login='JHOPE', Last Name='Hope', First Name='John', 
LOG: EntityId: 17, Id: 17, Attributes: Email='test@test.com', usr_key='17', User Login='JHENRY2', Last Name='Henry', First Name='John', 
LOG: __END__

YouTube Video

Summary

These procedures used a collection of Java sample programs to demonstrate some of the "User" capabilities of the OIM 11gR1 Java API. These samples merely provide an introduction into how Oracle Identity 11gR1 can be extended.
Comments:

Post a Comment:
Comments are closed for this entry.
About

Scott Fehrman

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today
News

No bookmarks in folder

Projects

No bookmarks in folder

Ref. Material

No bookmarks in folder