Life as a Master Principal Systems Engineer @ Oracle (formerly known as Sun)

Thursday Jul 12, 2012

Overview

Organization's are leveraging RESTful Web Services to integrate multiple client interfaces and devices with Internet-centric data services. We will cover how RESTful Web Services can be added to Oracle Identity Manager (OIM) 11g using the Jersey (JAX-RS) framework and Project OpenPTK.

RESTful Web Services

RESTful Web Services have become a "defacto" Application Programming Interface (API) for the Internet. A typical RESTful Web Service architecture leverages HTTP to implement basic Create, Read, Update and Delete (CRUD) operations. The following table shows how RESTful Web Services use the combination of HTTP Operations and URIs to support these CRUD operations.

Resource - URI

CRUD

HTTPOperation

Collectionhttp://acme.com/users

Elementhttp://acme.com/users/abc123

Create

POST

Create an entry in the collection. Entry's Id is usually assigned and returned

Treat the member as a Collection, Create a sub-collection

Read

GET

List the collection members

Retrieve a representation of the member. Using the MIME-type

Update

PUT

Replace the entire collection with another collection

Update the member of the collection. Maybe create if it does not exist

Delete

DELETE

Delete the entire collection

Delete the member of the collection

RESTful Web Services enable the developer to create user interfaces using their choice of design tools and frameworks. RESTful Web Services can be consumed by a traditional Browser interface (leveraging AJAX-type techniques) as well as by mobile and tablet devices leveraging platform specific RESTful client frameworks.

Oracle Identity Manager 11g and Jersey (JAX-RS)

The Oracle Identity Manager (OIM) 11g provides a powerful Java API that can be used to programmatically manage user identities. Here's a blog entry detailing the use of the OIM 11g Java APIs.

RESTful Web Services are easy to create using the Jersey framework. The Jersey framework implements the JAX-RS specification and works with most Java development tools and Java Servlet Containers. Jersey provides a set of Java Annotations to provide RESTful Web Services. The following table highlights some of the Jersey Annotations:

Annotation

Description

@Path("/users")

Name of a relative URI path

@POST

Designates method for HTTP POST Operation (Create)

@GET

Designates method for HTTP GET Operation (Read)

@PUT

Designates method for HTTP PUT Operation (Update)

@DELETE

Designates method for HTTP DELETE Operation (Delete)

@Produces("text/plain")

Specify the MIME-types to send back to the client

@Consumes("application/json")

Specify the MIME-types, the resource can consume, sent by the client

Project OpenPTK

Project OpenPTK is an open source provisioning toolkit that extends the capabilities of a provisioning solution. Project OpenPTK leverges the Jersey framework to expose RESTful Web Services and it can leverage Oracle Identity Manager (OIM) 11g using its Java APIs. Project OpenPTK supports both JSON and XML RESTful Web Service data payloads, to and from the Client.

Configuration

The RESTful Web Service demonstration environment was configured using Project OpenPTK (v2.1) deployed to the same Weblogic domain that is hosting Oracle Identity Manager (OIM) 11g. Project OpenPTK has a set of documentation which covers configuration / installation procedures in more detail.

Prerequisites

Project OpenPTK is available from a Subversion (svn) on-line source code control system at http://java.net/projects/openptk. You will need svn to download the project. The download page contains more information on how to access the source code. Create a new directory to store the project's source code.

Procedure

Project OpenPTK uses Service modules to interface with identity repositories. A Service module was create using the Oracle Identity Manager (OIM) 11g OIMClient Java API. The following steps highlight how to integrate, build, and deploy Project OpenPTK to support Oracle Identity Manager 11g.

Obtain the Oracle Identity Manager 11g oimclient.jar file.

Install the oimclient.jar file into a local maven repository

Build the OpenPTK Server using the oim11g Service module

Copy the generated war file to the Weblogic server where Oracle Identity Manager 11g is installed

Demonstration

Log into the OpenPTK Admin Interface and confirm that the Oracle Identity Manager 11g Context is working correctly. After logging in (http://localhost:7001/openptk-server):

Select the Contexts menu

Select the User-Oracle-OIMClient uri.

To list the Users, select the uri for the subjects

The curl command-line utility will be used to demonstrate the RESTful Web Services.

Authenticate

Project OpenPTK has an authentication mechanism. When the user is authenticated a Session is created within the OpenPTK Server and a HTTP Cookie is created for the user. Normally the web-browser would manage the HTTP Cookie. Since curl is being used, the Cookie returned from the authentication process will be saved in a text file called cookies.txt. The Cookie text file will be used on all the other curl commands.

Search

Search for existing OIM11g users that have a firstname or lastname that contains "Jack". The OpenPTK Server supports encoding the response data in a number of different formats. To specify what encoding type to use, set the Accept HTTP Header variable to one of these MIME-type values:

application/json

application/xml

text/plain

text/html

We use the HTTP GET method (on the User-Oracle-OIMClient/subjects collection) to search for the users. The HTTP query parameter search is used to specify the search string.

Create

We use the HTTP POST method (on the User-Oracle-OIMClient/subjects collection) to create a new user, in the collection. The curl -v option is used to show data being passed in and to show the Location value that is returned with the full URI of the created element (subject). Because we are sending in data that is "json" encoded, the HTTP Header variable Content-Type needs to be set to the application/json MIME-type. The successful operation returns a HTTP response code of 201 Created

Read

We use the HTTP GET method (on the User-Oracle-OIMClient/subjects/jbauer1 element) to read the user. We can retrieve the data using a number of different encoding formats: json, xml, plain, html. The examples below demonstrate how the HTTP Header variable Accept is used to "tell" the server what MIME-type we (the client) want to "accept".

Update

We use the HTTP PUT method (on the User-Oracle-OIMClient/subjects/jbauer1 element) to update an existing user, in the collection. The curl -v option is used to show data being passed in and to show the details of the update operation. Because we are sending in data that is "json" encoded, the HTTP Header variable Content-Type needs to be set to the application/json MIME-type. The successful operation returns a HTTP response code of 204 No Content

Delete

We use the HTTP DELETE method (on the User-Oracle-OIMClient/subjects/jbauer1 element) to delete the user, in the collection. The curl -v option is used to show data being passed in and to show the details of the delete operation. The successful operation returns a HTTP response code of 204 No Content

Even more ...

We have covered how to use Jersey (JAX-RS), via Project OpenPTK, to implement RESTful Web Services for Oracle Identity Manager 11g. We focused on basic Create, Read, Update, Delete and Search operations related to Users. The OpenPTK project also includes RESTful Web Service examples for other tasks such as Self-Service Registration which leverages the Oracle Identity Manager 11g registration feature. Take a look at the CAPTCHA and Identity Manager blog entry that uses the registration feature.