| Oracle® Identity Manager API Usage Guide Release 9.0 B25942-01 |
|
 Previous |
 Next |
Oracle provides a network-aware, Java-based application programming interface (API) that exposes commonly used functionality within Oracle Identity Manager. This is beneficial for both customers building their own clients for Oracle Identity Manager as well as any third party that needs to integrate with the Oracle Identity Manager platform.
This chapter contains the following sections:
The following table lists the API features required for any system that is integrated with the Oracle Identity Manager platform.
| 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. |
The Thor.API.tcUtilityFactory class supports a uniform approach to the creation and usage of utility classes. It also attempts to minimize and hide unnecessary complexity when using Oracle Identity Manager functionality exposed through the APIs. It does this by:
Providing uniform functionality, regardless of whether the APIs are being called from Web clients, adapters, or custom code.
Creating and maintaining session information on 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 the retrieval of utility classes. For example, using the static methods if a database connection exists.
There are two 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. In the process of connecting to the database, it will create and manage the necessary session and database objects. This scenario arises only when the API is instantiated on the client side, typically by third parties using the API to integrate with Oracle Identity Manager.
For a list of the methods available in this class, refer to the Java API Reference provided for the APIs. For an explanation on how to use the class, refer to "API Usage".
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 functional area. 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 |
|---|---|
|
|
Exposes common user operations, such as searching for users, creating users, and disabling and enabling users. |
|
|
Exposes common group operations. For example, searching for groups, creating groups, and adding and removing users from groups. |
|
|
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, refer to the API JavaDoc documentation. |
All the 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 basic functionality common to all utility classes. It is an abstract class, which provides common functionality inherited by all other utility classes. This inherited functionality focuses mainly 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.
The Thor.API.tcResultSet interface is a data structure that stores records retrieved from the database. Methods in the Oracle Identity Manager API that need to 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, in the case of the result set returned by the method that searches for users, each row would represent data pertaining to one user, while 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 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 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. |
It is particularly important to keep track of the result set objects that are retrieved, because they will be required when updating an existing record.
This section covers the following topics:
To install the API:
Create the following directory structure:
<Custom Client>\config\lib\ext
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.
Copy the basecp.bat and classpath.bat files to the <Custom Client> directory.
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 WebLogic 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\authwl.conf -Djava.naming.provider.url=t3://<host_name>:<port>/ <CLIENT_CLASS>
For WebSphere Application Server
For WebSphere Application Server, perform the following steps:
Install WebSphere Application Client.
Create an Enterprise Archive (EAR) file, XLCustomClient.ear. The EAR file must have a Java Archive (JAR) file containing the main class of custom client. The manifest file must have an entry of the main class name. Following is a sample Ant target to build the EAR file:
<target name="makeXLAPICustomClient" depends="init" description="create a jar for the client side code">
<jar jarfile="<dir>/xlWSCustomClient.jar">
<fileset dir="<dir>">
<include name="<fully qualified classes directory>"/>
</fileset>
<fileset dir="<dir>">
<include name="application-client.xml"/>
</fileset>
<manifest>
<attribute name="Main-Class" value="<fully qualified main class name>"/>
</manifest>
</jar>
<ear appxml="<dir>/application.xml" earfile="<dir>/XLCustomClient.ear">
<fileset file="<dir>/xlWSCustomClient.jar"/>
</ear>
</target>
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%"
When using the APIs in the context of your own application, for example, a Web application, the client may not be able to obtain the Oracle Identity Manager password from the user. Such a scenario typically arises in a single sign-on environment where the authentication application is not available to Oracle Identity Manager to check the user identification (ID). In such a situation, it is imperative to establish some kind of trust between Oracle Identity Manager and the entity providing the user ID (and nothing else) to Oracle Identity Manager. This is accomplished 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 same, and a certificate (X.509 based) establishing the identity of the entity that is connecting to Oracle Identity Manager. Creation of the object is accomplished by using the static utility method sign in the utility class tcCryptoUtil, as follows:
tcSignatureMessage moSignature = tcCryptoUtil.sign("xelsysadm","PrivateKey");
It is the responsibility of the entity using the APIs to maintain security of the private key used in the signature process, because that is the basis for establishing trust between the two systems.
Oracle Identity Manager must also be provided with information regarding the certificates it has to trust. To trust a certificate, the signer of the certificate must be added as a trusted CA in .xlkeystore or the keystore configured in the security section in the xlconfig.xml file on the server.
Once you have an instance of the factory class, you can use this to obtain instances of utility classes by calling the getUtility() method. Given that 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 Scheduled Task, these instructions are different. For detailed instructions, refer to Oracle Identity Manager Installation and Upgrade Guide for the application server that you are using. |
The following is an example of how to use a result set, which is obtained by calling the findAllUsers() method, to search for all users matching certain criteria:
tcResultSet moResultSet = moUserUtility.findAllUsers(mhAttribs);
To check if any records were returned by the findAllUsers() method, use the isEmpty() method:
boolean mbEmpty = moResultSet.isEmpty();
The actual number of records found can be retrieved by using the getRowCount() method. If no records are found, then the method will return 0.
int mnNumRec = moResultSet.getRowCount();
You can then select a particular record in the system by using the goToRow() method:
moResultSet.goToRow(5);
From the current row, you can then retrieve the values of various attributes by using the appropriate accessor method:
String msUserLastName = moResultSet.getStringValue("Users.Last Name");
The methods provided by the APIs 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.
The tcUtilityFactory class manages all the resources used by a utility or factory instance and provides a means to release these resources after they are used.
In cases where tcUtilityFactory was instantiated and used to obtain utility class instances, call the close(utility Object) method on the factory class to release the resources associated with that utility class. If the session has ended, then call the close() method on the factory instance to release all the utility classes as well as the session and database objects.
If a utility class was obtained directly through the static calls, then call the close(object) method on the utility object after it has been used and is no longer needed.
Example 1-1 illustrates how to retrieve Oracle Identity Manager information.
Example 1-1 Retrieving 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.
/** 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 illustrates the use of digital signature-based method.
Example 1-2 Using the Digital Signature-Based Method
This example demonstrates how to create an instance of the utility factory by 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();
}
}
From release 8.0.2 onward, the 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>/xlclient/CustomClient.zip
Configure the custom API ZIP file as follows:
Extract the custom API ZIP file.
For JBoss and WebLogic, run xlCustomClient.
For WebSphere, run wsCustomClient.
JBoss Configuration
Modify xlCustomClient.bat as follows:
Modify CLASSPATH to add JARs associated with the custom client.
Set the CLIENT_CLASS variable to the custom client main class name.
Modify the following properties:
-Djava.security.auth.login.config=config\auth.conf -Djava.naming.provider.url=jnp://<machinename>:<portno>/
WebLogic Configuration
Modify xlCustomClient.bat as follows:
Modify the CLASSPATH to JARs associated with the custom client installation.
Set CLIENT_CLASS to the custom client main class name.
Modify the following properties:
-Djava.security.auth.login.config=config\authwl.conf -Djava.naming.provider.url=t3://<machinename>:<portno>/
Modify <Custom Client>/config/xlconfig.xml as follows:
Modify the application server name.
<appServerName>weblogic</appServerName>
Modify the Discovery setting for WebLogic-specific values.
<Discovery>
<CoreServer>
<java.naming.provider.url>
t3://10.1.1.54:7001
</java.naming.provider.url>
<java.naming.factory.initial>
weblogic.jndi.WLInitialContextFactory
</java.naming.factory.initial>
</CoreServer>
</Discovery>
WebSphere Configuration
Modify wsCustomClient.bat as follows:
Modify the CLASSPATH to add JARs associated with the custom client installation.
Set CLIENT_CLASS to the custom client main class name.
Set WS_HOME to WebSphere home.
Modify <Custom Client>/config/xlconfig.xml as follows:
Modify the application server name.
<appServerName>websphere</appServerName>
Modify the Discovery setting for WebSphere-specific values.
<Discovery>
<CoreServer>
<java.naming.provider.url>
corbaloc:iiop:host:2809
</java.naming.provider.url>
<java.naming.factory.initial>
com.ibm.websphere.naming.WsnInitialContextFactory
</java.naming.factory.initial>
</CoreServer>
</Discovery>
