Using Oracle Identity Analytics 11g Web Services

Introduction

The purpose of this document is to illustrate and provide a starting point to use web services exposed by Oracle Identity Analytics 11g. Apache CXF 2.6.1 is used to generate the wrapper libraries.

Build Library Setup

We also need a few jars to get everything compiled

Samples

To run the samples you need to configure the file settings.properties with the following

Property Name	Description
user	Username for connecting to OIA
password	Password for OIA user
wsdlurl	Address for WSDL file

userService

roleService

businessService

auditService 

Enabling Web Services in Oracle Identity Analytics (OIA)

                Edit web.xml with the following changes.

a.       Add classpath:org/codehaus/xfire/spring/xfire.xml

b.      Uncomment the servlet definition and mapping for webservice

c.       Restart OIA.

Webservice Endpoints

For a server that is running on localhost with port 7001 we have four web service endpoints available. These four endpoints are

http://localhost:7001/rbacx/ws/userService?wsdl

http://localhost:7001/rbacx/ws/roleService?wsdl

http://localhost:7001/rbacx/ws/auditService?wsdl

http://localhost:7001/rbacx/ws/businessUnitService?wsdl

Creating Java client

We can easily call the web services by creating a java client for the above 4 endpoints. We will be using Apache CXF to build our client application. However there are other ways also like using Apache Axis 1.x and Apache Axis 2.x. Every framework has its own way to wrap the web service operations, which we will not be covering here.

With Apache CXF we have a neat little command line client wsdl2java which creates the java client classes for us. We created the clients for the above four web services as shown below

I first saved the WSDL document from the above URLs. Also since the default generation logic creates a rather weird data structure to use I have put in some customization in javabindings.xml which is specified during client generation.

Role Service

User Service

Business Unit Service
 

 

Audit Service

Javabindings.xml

Once this is done classes are created in the generated folder. Please note that I created separate java projects for each of the web service. If you do all of them in one project you would need to do some manual class changes.

I added some test code also, which I’ll explain below. The projects structure in my eclipse looks like:

Calling the webservice

Any operation that is to be requested needs authentication. The web service client classes do not have any in-built authentication wrappers built. Rather this functionality is present in Apache CXF’s classes. We will go step by step on how the client is created now.

Step 1: Getting the client instance

We have four endpoints, each of which has a different client class to start off with. Below is what we need to get started for User Service.

It will be similar for the other services, for audit we will get the AuditService and so on for the others.

Step 2: Setting up the authentication

As mentioned earlier we need to take help from Apache CXF’s classes to get the authentication working.  We wrapped all this up in one method in the class Common.

Here we are doing two things:
1.  Add logging by adding LoggingInInterceptor and LoggingOutInterceptor in the interceptor queue.
2.  Add username/password for authentication by inserting a WSS4JInterceptor

The above code is how Apache CXF wants it, so more details on why and how on this can be found on Apache CXF’s website.

Step 3: Calling the webservice

Each webservice has different operations available. However the way of operating is similar. Shown below is the easiest method to call getVersion() which is present in all the webservices.

Active Roles Server and OIM

Why do companies love web service? Active Directory follows the LDAP v3 protocol to communicate, but no some people are hell bent on getting web service over this neat little bundle wrapped in LDAP. So here comes ARS or Active Roles Server. The server itself provides a web based console to access the users contained inside Active Directory. It has a add-on component that one has to add to enable a web service interface (follows SPMLv2), which allows us to create users via a web service. This web service follows the SPML v2 standard, but so much for just following a new standard, when a already established standard is being used and that too being light weight!

When we first started developing the Active Directory Connector, fitting in the requirements, the default OOTB connector for Active Directory 9.x was being used. I wish it was used all the way, but the client wanted us to use the Active Roles Server web service.  I never had development experience with web services so I tried experimenting with OIM11’s SPML web service. I created a client using Axis 1.x for it and it worked perfectly. But when it came to ARS (Active Roles Server), it turned out ugly.

I started with Axis 1.x , created a client but had to spend a very long time to get my head around how to send the username/password for the request. It seemed like a crazy jungle where I have no help. But I finally had some help from a few YouTube videos and I was able to get it working. My idea was to use similar steps to complete the web service client for the ARS web service, but it all turned out into waste. I tried Axis 1.x / Axis 2.x. / Apache CXF / wsimport, but ended up with new problems every time. Axis 1.x created me a request class with Object[][] data type for a tag which was like – “<attr> <data><value></value></data><data><value></value></data> </attr>”. I had no clue how to get it from a Object[][]. Axis 2.x gave me the request class correctly but the response was not getting parsed and it used to throw an error when I got the response. Finally I went to the basics to solve all this mess.

A web service is a HTTP request. Why not hand craft the XML and send it. “Sound simple enough” is what I thought. I did not want to write all the code to create XML, so after looking for some time I found a neat little library called “Simple”.  It is available from http://simple.sourceforge.net/ . It has an easy to learn Java annotation based framework which allows to generate XML is pretty easy way. An example is like this

This class when converted to XML gives us something like this

Note: the formatting was slightly modified to make the XML fit

Once we are done with the XML conversion we create a HTTP request to the web service and send the XML. Here is how we send the request:

Here are the steps in plain English:

1. We need to create a request that is of type POST. So create a instance of class HttpPost
2. We also need to set header value “SOAPAction”. This will tell the web service what method we are calling. This can be inferred by testing your webservice from SOAPUI. Alternatively you can refer to the web service WSDL and get the values.  
3.The response is again a XML formatted document which we can parse using the standard Java DOM APIs.

To complete this post with an example, I have put in a few classes which will give an idea on how to put a web service client in place. The method is a rather low tech method, and it is up to the designer/developer to choose.

Sample Code