1 Using the Oracle Identity Manager API

Oracle provides a network-aware, Java-based application programming interface (API) that exposes commonly used functionality within Oracle Identity Manager. This API is beneficial for building clients for Oracle Identity Manager and for integrating third-party products with the Oracle Identity Manager platform.

This chapter discusses the following topics:

• Requirements of the Oracle Identity Manager API

• Factory Class

• Utility Classes

• Result Set Interface

• Administrative Queues

• API Usage

• Code Samples

• Using the Custom API ZIP File

• Creating a Custom Proxy Plug-in

1.1 Requirements of the Oracle Identity Manager API

The following table lists the primary API features.

Requirement	Solution
Common, easy to understand language	Java
Network-aware	Built around the Java 2 Platform, Enterprise Edition (J2EE) distributed computing
Easy to use	The task of session initialization and maintenance is hidden from the API user. The underlying work necessary for the creation of utility classes is hidden through the use of the Oracle Identity Manager API. A uniform approach to the creation and use of the utility classes is provided.

1.2 Factory Class

The Thor.API.tcUtilityFactory class supports a uniform approach for creating and using utility classes. This class minimizes and hides complexity when using Oracle Identity Manager functionality exposed through the APIs. This is done through the following:

• Providing uniform functionality for APIs that are called from any source, including Web clients, adapters, and custom code.

• Creating and maintaining session information about instantiation.

  This information is used to manage resources obtained through the Utility Factory.

• Identifying when the API is working in the context of an existing session.

  This enables utility methods to be used for retrieving utility classes, for example, using static methods if a database connection exists.

The following are scenarios for the use of this class:

• A session and database connection already exists.

  In this case, the class can be employed as a utility class through the use of static methods, for example, adapters that are created through the Adapter Factory.

• A session and database connection has not been created.

  In this case, the class can be instantiated and provided with the necessary information to connect to the database. When connecting to the database, it creates and manages session and database objects. This scenario arises only when the API is instantiated on the client side, typically by third parties that use the API to integrate with Oracle Identity Manager.

For a list of the methods available in this class, see the Java API Reference provided for the APIs. For an explanation on how to use the class, see "API Usage".

1.3 Utility Classes

The Oracle Identity Manager API exposes commonly used Oracle Identity Manager functionality through the utility classes and interfaces defined in the Thor.API.Operations package. These classes and interfaces group methods by their functional areas.

Table 1-1 provides a partial listing of the interfaces available in the API.

Table 1-1 Partial Listing of Utility Interfaces Available in the API

Interfaces	Description
tcUserOperationsIntf	Exposes common user operations, such as searching for users, creating users, and disabling and enabling users.
tcGroupOperationsIntf	Exposes common group operations. For example, searching for groups, creating groups, and adding and removing users from groups.
tcRequestOperationsIntf	Exposes common request operations. For example, creating a request and adding comments to a request.

See Also:

For a full listing of the classes and interfaces, including an explanation of all the methods available in them, see the API JavaDoc documentation.

All classes in the Thor.API.Operations package extend the base utility class, Thor.API.Base.tcBaseUtility, and implement the Thor.API.Base.tcUtilityOperationsIntf interface.

The base utility class provides a basic functionality common to all utility classes. It is an abstract class that provides common functionality inherited by all other utility classes. The inherited functionality focuses on the interaction between the factory class and the utility classes. All utility classes implement the interface tcUtilityOperationsIntf that labels the class as a utility class.

1.4 Result Set Interface

The Thor.API.tcResultSet interface is a data structure that stores records retrieved from the database. Methods in the Oracle Identity Manager API that must return a set of data use a result set. This is a two-dimensional data structure in which the columns correspond to the attributes and rows correspond to the entities. For example, a result set that is returned by the method that searches for users, each row would represent data pertaining to one user, and each column in the row would be an attribute for that user.

You can scroll through the result set and retrieve individual entries corresponding to particular attributes by using the various methods provided. To locate a particular row in the result set, use the goToRow() method with the row number as a parameter. To retrieve the values for the columns from a row, use appropriate accessor methods, such as getStringValue(). To obtain the value from a specific column, pass the column name as a parameter to the accessor method. The column name is the descriptive code defined in the Oracle Identity Manager Meta-Data system.

The following table shows some sample metadata values. This mapping is based on lookup codes and can be looked up in the Administrative and User Console by using the Lookup Definition Form.

Column Code	Explanation
Users.First Name	The first name of the user.
Groups.Group Name	The name of a group.

Note:

Keep track of the result set objects that are retrieved, because they will be required when updating an existing record.

1.5 Administrative Queues

You assign groups of users to manage a provisioning request by using an entity called a queue. A queue is a collection of group definitions. Queues can be nested within other queues.

Administrative queues increase the efficiency and manageability of requests. A queue that you assign to one request can be reused for other requests.

A request can specify different administrative privileges for each group in the queue. For example, suppose that you assign a queue with three user groups to a request. The members of the three groups can each have different administrative privileges for the request. The first user group can be allowed to read, modify, and delete the request. The second user group can be allowed to read and modify only, while the third user group can only be able to read and delete the request.

Note:

The Administrative Queues form in the Design Console is defunct. However, you can still view this form in the Design Console.

You can work with administrative queues by using the Thor.API.tcQueueOperationsIntf interface. The following are some of the tasks that you can perform by implementing the methods of this interface:

• Create, modify, and edit queues.

• Add and remove administrative groups from queues.

• Add and remove member groups.

See the Javadocs for more information about this interface.

1.6 API Usage

This section includes the following topics:

• Setup and Configuration

• Initializing the Factory Class with a Digital Signature

• Obtaining an Instance of a Utility Class

• Using a Result Set Object

• Handling Oracle Identity Manager Exceptions

• Cleaning Up

1.6.1 Setup and Configuration

To install the API:

1. Create the following directory structure:

   Custom Client\config\lib\ext

2. Copy the files from the config, lib, and ext folders of a standard Oracle Identity Manager desktop client installation to the config, lib, and ext folders, respectively, of your custom client installation.

3. Copy the basecp.bat and classpath.bat files to the Custom Client directory.

4. Open the classpath.bat file in a text editor and append the following line to the end of the file:

   ;.\ext\javagroups-all.jar;.\ext\oscache.jar;.\ext\commons-logging.jar
   

5. Append the following in the classpath.bat file:

For JBoss Application Server

Create a batch file with the following commands:

call classpath
set CLIENT_CLASS=fully qualified name of your custom API client class
java -Djava.security.manager -DXL.HomeDir=.  
-Djava.security.policy=config\xl.policy 
-Djava.security.auth.login.config=config\auth.conf 
-Djava.naming.provider.url=jnp://host_name:port CLIENT_CLASS

For Oracle WebLogic Server

Create a batch file with the following commands:

call classpath
set CLIENT_CLASS=fully qualified name of your custom API client class
java -Djava.security.manager -DXL.HomeDir=.  
-Djava.security.policy=config\xl.policy 
-Djava.security.auth.login.config=config\authwl.conf 
-Djava.naming.provider.url=t3://host_name:port CLIENT_CLASS

For IBM WebSphere Application Server

For IBM WebSphere Application Server, perform the following steps:

1. Install WebSphere Application Client.

2. Extract the XLCustomClient.ear file by unzipping the OIM_DC_HOME\xlclient\CustomClient.zip file.

3. Create a batch file with the following commands:

   call basecp.bat
   set WS_HOME=c:\Websphere
   "%WS_HOME%\bin\launchclient" XLCustomClient.ear -CCclasspath=%CLASSPATH% 
   -CCsecurityMgrPolicy=./config/xl.policy -CCDXL.HomeDir=. 
   -CCDjava.security.auth.login.config=./config/authws.conf 
   -CCDwas.home="%WS_HOME%"
   -CCDXL.ClientClassName name_of_class_file
   

   Note:

   The name_of_class_file argument should be contained within a JAR file that is in the class path.

For Oracle Application Server

Create a batch file with the following commands:

call classpath
set CLIENT_CLASS=<fully qualified name of your custom API client class>
java -Djava.security.manager -DXL.HomeDir=.
-Djava.security.policy=config\xl.policy
-Djava.security.auth.login.config=config\authoc4j.conf
-Djava.naming.provider.url=ormi://hostname:rmi_port/Xellerate CLIENT_CLASS

1.6.2 Initializing the Factory Class with a Digital Signature

When using the APIs with your own application, for example, a Web application, a client might be unable to obtain the Oracle Identity Manager password from the user. For example, in a Single Sign-On environment, the authentication application might not be available to Oracle Identity Manager for checking the user ID. In situations like this, you must establish a trust between Oracle Identity Manager and the entity providing only the user ID to Oracle Identity Manager.

You establish trust by using digital signatures. See the init() method in Example 1-2.

tcUtilityFactory moFactory = new tcUtilityFactory("development",signedMessage);

The tcSignatureMessage object contains the Oracle Identity Manager user ID, a signed version of the user ID, and an X.509 certificate that establishes the identity of the entity that is connecting to Oracle Identity Manager.

To create the object, use the static utility method sign in the utility class tcCryptoUtil, as follows:

tcSignatureMessage moSignature = tcCryptoUtil.sign("xelsysadm","PrivateKey");

The entity using the APIs must maintain security of the private key for the signature. The private key is the basis for establishing trust between the two systems.

Oracle Identity Manager must also know what certificates to trust. To trust a certificate, the signer of the certificate must be added as a trusted CA in .xlkeystore or in the keystore configured in the security section in the xlconfig.xml file on the server.

1.6.3 Obtaining an Instance of a Utility Class

After you have created an instance of the factory class, you can use this to obtain instances of utility classes by calling the getUtility() method. The getUtility() method returns instances of tcUtilityOperationsIntf. The return object must be cast to the particular utility class that was requested.

tcUserOperationsIntf moUserUtility = (tcUserOperationsIntf) moFactory.getUtility("Thor.API.Operations.tcUserOperationsIntf");

Note:

For a Scheduled Task, these instructions are different. For an installation earlier than release 9.0.2, see the Oracle Identity Manager upgrade document for the application server that you are using.

For Oracle Identity Manager installations later than release 9.0.2, see the following:

• Oracle Identity Manager Installation and Configuration Guide for JBoss Application Server

• Oracle Identity Manager Installation and Configuration Guide for Oracle WebLogic Server

• Oracle Identity Manager Installation and Configuration Guide for IBM WebSphere Application Server

• Oracle Identity Manager Installation and Configuration Guide for Oracle Application Server

1.6.4 Using a Result Set Object

The following is an example of how to use a result set. This example obtains a result set by calling the findAllUsers() method. This method searches for all users matching certain criteria:

tcResultSet moResultSet = moUserUtility.findAllUsers(mhAttribs);

To check if the findAllUsers() method returned any records, use the isEmpty() method, for example:

boolean mbEmpty = moResultSet.isEmpty();

To retrieve the number of records found, use the getRowCount() method. If no records are found, then the method returns 0. The following is an example:

int mnNumRec = moResultSet.getRowCount();

To select a particular record in the system, use the goToRow() method:

moResultSet.goToRow(5);

To retrieve the values of attributes from the current row, use the appropriate accessor method, for example:

String msUserLastName = moResultSet.getStringValue("Users.Last Name");

1.6.5 Handling Oracle Identity Manager Exceptions

The API methods throw Oracle-defined Java exceptions. Instead of using the getMessage() method on the exception object received, you can access the isMessage internal variable to retrieve the exception message.

1.6.6 Cleaning Up

The tcUtilityFactory class manages all resources used by a utility or factory instance and provides a means to release these resources after they are used.

If you instantiate and use tcUtilityFactory to obtain utility class instances, to release the resources that are associated with the utility class, call the close(utility Object) method on the factory class. If the session has ended, call the close() method on the factory instance to release all the utility classes, the session objects, and the database objects.

If you obtain a utility class directly by using static calls, after the utility object is no longer needed, call the close(object) method on the utility object.

1.7 Code Samples

Example 1-1 illustrates how to retrieve Oracle Identity Manager information. This example creates an instance of the utility factory. This instance is then employed several times to retrieve individual utility classes and use them to retrieve Oracle Identity Manager information.

Example 1-1 Retrieving Oracle Identity Manager Information

/** The utility factory instance. */
tcUtilityFactory ioUtilityFactory

public void init(){
  ConfigurationClient.ComplexSetting config = 
     ConfigurationClient.getComplexSettingByPath("Discovery.CoreServer");
  final Hashtable  env = config.getAllSettings();
  tcUtilityFactory ioUtilityFactory =  new tcUtilityFactory(env, "xelsysadm",
  "xelsysadm");

}

/** Retrieves user login based on the first name. */
public List getUserLogin(String psFirstName){
  Vector mvUsers=new Vector();
  tcUserOperationsIntf moUserUtility = 
(tcUserOperationsIntf)ioUtilityFactory.getUtility("Thor.API.Operations.tcUserOperationsIntf"); 
  Hashtable mhSearchCriteria = new Hashtable();
  mhSearchCriteria.put("Users.First Name", psFirstName);
  tcResultSet moResultSet = moUserUtility.findUsers(mhSearchCriteria);
  for (int i=0; i<moResultSet.getRowCount(); i++){
    moResultSet.goToRow(i);
    mvUsers.add(moResultSet.getStringValue("Users.User ID"));
  }
}

/** Retrieves the administrators of an organization based on the organization name. */
public List getAdministratorsOfOrganization(String psOrganizationName){
  Vector mvOrganizations=new Vector();
  tcOrganizationOperationsIntf moOrganizationUtility = 
(tcOrganizationOperationsIntf)ioUtilityFactory.getUtility("Thor.API.Operations.tcOrganizationOperationsIntf"); 
  Hashtable mhSearchCriteria = new Hashtable();
  mhSearchCriteria.put("Organizations.Organization Name", psOrganizationName);
  tcResultSet moResultSet = 
     moOrganizationUtility.findOrganizations(mhSearchCriteria);
  tcResultSet moAdmins;
  for (int i=0; i<moResultSet.getRowCount(); i++){
    moResultSet.goToRow(i);
    moAdmins=moOrganizationUtility.getAdministrators(moResultSet.getLongValue("Organizations.Key"));
mvOrganizations.add(moAdmins.getStringValue("Groups.Group Name"));
  }
}
public void example(){
  List moList;
  // initialize resources  
  init();  
  // retrieve user logins with first name 'Joe'
  moList=getUserLogin("Joe");
  // retrieve user logins with first names starting with 'D'
  moList=getUserLogin("D*");
  // retrieve the administrators of an organization with name 'Example Organization'
  moList=getAdministratorsOfOrganization("Example Organization");
  // release resources
  ioUtilityFactory.close();
}

Example 1-2 demonstrates how to create an instance of the utility factory by using a digital signature-based method.

Example 1-2 Using the Digital Signature-Based Method

/** The utility factory instance. */
public void init() {
  try {
    ConfigurationClient.ComplexSetting config =      
      ConfigurationClient.getComplexSettingByPath("Discovery.CoreServer");
    final Hashtable  env = config.getAllSettings();
    tcSignatureMessage moSignature = tcCryptoUtil.sign("xelsysadm",
                                             "PrivateKey");
    tcUtilityFactory m_utilFactory = new tcUtilityFactory(env, moSignature);
  }
  catch(Exception ex) {
    ex.printStackTrace();
  }
}

1.8 Using the Custom API ZIP File

As of Oracle Identity Manager 8.0.2, a custom API ZIP file is installed with the Oracle Identity Manager desktop client. The purpose of this ZIP file is to ease the API development cycle. This ZIP file is located at:

XL_installation_directory/xlclient/CustomClient.zip

Configure the custom API ZIP file as follows:

1. Extract the custom API ZIP file.

2. For Oracle Application Server, JBoss Application Server, and Oracle WebLogic Server, modify and run xlCustomClient.

   For IBM WebSphere Application Server, modify and run wsCustomClient.

   Information about configuring these scripts is provided in the following sections.

JBoss Application Server Configuration

Modify classpath.bat by adding JARs associated with the custom client installation to the CLASSPATH.

Modify xlCustomClient.bat as follows:

1. Set the CLIENT_CLASS variable to the custom client main class name.

2. Add the following properties after -Dlog4j.configuration=config/log.properties:

   -Djava.naming.provider.url=t3://hostname:port
   

Modify Custom Client/config/xlconfig.xml as follows:

1. Modify the application server name.

   <appServerName>jboss</appServerName>
   

2. Modify the application URL as follows:

   <ApplicationURL>http://hostname:port/xlWebApp/loginWorkflowRenderer.do</ApplicationURL>
   

3. Modify the Discovery setting for JBoss-specific values.

   <Discovery>
   <CoreServer>
   <java.naming.provider.url>jnp://hostname:port</java.naming.provider.url> </java.naming.provider.url>
   <java.naming.factory.initial>org.jnp.interfaces.NamingContextFactory</java.naming.factory.initial>
   </CoreServer>
   </Discovery>
   

Oracle WebLogic Server Configuration

Modify classpath.bat by adding JARs associated with the custom client installation to the CLASSPATH.

Modify xlCustomClient.bat as follows:

1. Set CLIENT_CLASS to the custom client main class name.

2. Modify the following property:

   -Djava.security.auth.login.config=config\auth.conf
   

   To:

   -Djava.security.auth.login.config=config\authwl.conf
   

3. After -Dlog4j.configuration=config/log.properties, add the following property:

   -Djava.naming.provider.url=t3://hostname:port
   

Modify Custom Client/config/xlconfig.xml as follows:

1. Modify the application server name.

   <appServerName>weblogic</appServerName>
   

2. Modify the application URL:

   <ApplicationURL>http://hostname:port/xlWebApp/loginWorkflowRenderer.do</ApplicationURL>
   

3. Modify the Discovery setting for WebLogic-specific values.

   <Discovery>
   <CoreServer>
   <java.naming.provider.url>t3://hostname:port</java.naming.provider.url>
   <java.naming.factory.initial>weblogic.jndi.WLInitialContextFactory</java.naming.factory.initial>
   </CoreServer>
   </Discovery>
   

IBM WebSphere Configuration

Modify the CLASSPATH to add JARs associated with the custom client installation.

Modify wsCustomClient.bat as follows:

1. Set CLIENT_CLASS to the custom client main class name.

2. Set WS_HOME to the WebSphere home directory.

Modify Custom Client/config/xlconfig.xml as follows:

1. Modify the application server name.

   <appServerName>websphere</appServerName>
   

2. Modify the Discovery setting for WebSphere-specific values.

   <Discovery>
     <CoreServer>
   <java.naming.provider.url>corbaloc:iiop:hostname:port</java.naming.provider.url>
   <java.naming.factory.initial>com.ibm.websphere.naming.WsnInitialContextFactory</java.naming.factory.initial>
     </CoreServer>
   </Discovery>
   

Oracle Application Server Configuration

Modify classpath.bat by adding JARs associated with the custom client installation to the CLASSPATH.

Modify xlCustomClient.bat as follows:

1. Set the CLIENT_CLASS variable to the custom client main class name.

2. Modify the following properties:

   Change:

   -Djava.security.auth.login.config=config\auth.conf
   

   To:

   -Djava.security.auth.login.config=config\authoc4j.conf
   

3. After -Dlog4j.configuration=config/log.properties, add the following property:

   -Djava.naming.provider.url=ormi://hostname:rmi_port/Xellerate
   

Modify Custom Client/config/xlconfig.xml as follows:

1. Modify the application server name:

   <appServerName>oracle</appServerName>
   

2. Modify the Discovery setting for Oracle Application Server-specific values.

   <Discovery>
   <CoreServer>
   <java.naming.provider.url>ormi://hostname:rmi_port/Xellerate
   </java.naming.provider.url>
   <java.naming.factory.initial>oracle.j2ee.rmi.RMIInitialContextFactory
   </java.naming.factory.initial>
   <CoreServer>
   <Discovery>
   

1.9 Creating a Custom Proxy Plug-in

By default, when a user selects a proxy with the Administrative and User Console, the user is presented with a list of all Oracle Identity Manager users in the current environment. To restrict the users that can be selected as a proxy, you can create a custom proxy plug-in by customizing the following API:

tcResultSet tcUserOperationsIntf->getProxyList(Map, String[])

The preceding API first determines whether the XL.CustomProxyClassName system property is defined. By default, the XL.CustomProxyClassName system property is not defined and the API uses criteria that were passed with the Map parameter to filter the list of users. However, if the XL.CustomProxyClassName system property is defined, then its value is used as the custom proxy class name. The API then loads the custom proxy class, executes the getProxyList() method, and returns a result set containing the proxy list.

The data object layer in the custom proxy plug-in API is configured with the following two classes:

• com.thortech.xl.dataobj.plugins.AbstractBasePlugin.java—Abstract base class that contains various utility methods and other code for accessing the Oracle Identity Manager API interfaces.

• com.thortech.xl.dataobj.plugins.CustomUserProxyPlugin.java—Baseclass from which a custom proxy plug-in class should derive. This class contains various utility methods and an abstract getProxyList() method that you can use to implement your own functionality for returning a list of proxy users.

Perform the following steps to implement a custom proxy plug-in:

1. Define a class that derives from the CustomUserProxyPlugin.java class and provide an implementation for the abstract getProxyList() method. The abstract getProxyList() method must return an array containing user keys for each user who can be selected as a proxy. You can use any of the Oracle Identity Manager APIs to identify and filter the user keys that are returned in the array.

2. Compile your custom proxy plug-in class, store it in a JAR file, and then copy the JAR file to the OIM_HOME\JavaTasks directory.

3. Log in to the Design Console as an administrative user and open the System Configuration form.

4. Click New to create a new entry, and then enter the following values in the Name, Keyword, and Value fields:

   Name—custom proxy class name

   Keyword—XL.CustomProxyClassName

   Value—fully qualified class name of your custom proxy class

5. Click Save to create the new property definition.

6. Restart the server.