| Oracle® Identity Manager API Usage Guide Release 9.0.3 Part Number B32449-01 |
|
|
View PDF |
| Oracle® Identity Manager API Usage Guide Release 9.0.3 Part Number B32449-01 |
|
|
View PDF |
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:
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. |
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. It does this by doing 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 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 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, 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, 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 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 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, 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 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. |
Note:
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 with your own application, for example, a Web application, a client may be unable to obtain the Oracle Identity Manager password from the user. For example, in a single sign-on environment, the authentication application may not be available to Oracle Identity Manager for checking the user ID. In situations like this, you must establish trust between Oracle Identity Manager and the entity providing only the user ID to Oracle Identity Manager.
You establish trust 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.
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 installation prior to version 9.0.2, see the Oracle Identity Manager Installation and Upgrade Guide for the application server that you are using.For later versions, see the following:
Oracle Identity Manager Installation Guide for JBoss
Oracle Identity Manager Installation Guide for Oracle Containers for J2EE
Oracle Identity Manager Installation Guide for WebLogic
Oracle Identity Manager Installation Guide for WebSphere
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, by use the appropriate accessor method, for example:
String msUserLastName = moResultSet.getStringValue("Users.Last Name");
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.
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 using static calls, after the utility object is no longer needed, call the close(object) method on the utility object.
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();
}
}
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:
Extract the custom API ZIP file.
For JBoss and WebLogic, modify and run xlCustomClient.
For WebSphere, modify and run wsCustomClient.
Information on configuring these scripts is provided in the following sections.
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>
