Novell Doc: Identity Manager Roles Based Provisioning Module 3.7 User Application: Administration Guide

25.1 About RIS

This section describes the Resource Information Services (RIS) facility, which is a standalone component that interacts with the Identity Manager User Application. RIS is built on a Rest Oriented Architecture (ROA). The RIS implementation resides in a WAR file called RIS.WAR, where RIS refers to Resource Information Services. The REST resources exposed through RIS make SOAP calls to gather information from the Workflow system.

The methodology used to define these ROA services is based on the steps described by Leonard Richardson & Sam Ruby in the RESTful Web Services by O'Reilly.

25.1.1 How it Works

The code for RIS is contained in a WAR outside of the User Application. This is a standalone WAR (RIS.war) that uses SOAP calls to extract the necessary work item data.

Language support is determined by the “Accept-Language” header parameter.

The media type is determined by the “Accept” header parameter and must be equal to “application/json”.

The implementation does not support the use of extensions. It does not support the ability to enter a language or media extension at the end of a URI.

This implementation is based on the JSR-311 specification implemented by Sun's Jersey product.

You may see this error on the console:

09:52:52,684 ERROR [STDERR] Sep 30, 2008 9:52:52 AM
com.sun.jersey.api.core.ClasspathResourceConfig init
INFO: Root resource classes found:
  class com.novell.ris.spi.impl.Root

This is a Jersey message that is simply informational. The application should function normally. You can ignore the message.

NOTE:During the deployment of the RIS.war on WebSphere, you might see the following error message in the server log:

WebApp        W   Error while adding servlet mapping --> /* Please set
fileServingEnabled=false in the ibm-web-ext.xmi file which is under WEB-INF
folder.

This message does not affect the functions of RIS.

Caching the SOAP stubs The web.xml file in the RIS.war includes an element that allows you to control the size of the stub connection pool.

<init-param>
   <param-name>STUB_CONNECTION_POOL</param-name>
   <param-value>100</param-value>
</init-param>

The STUB_CONNECTION_POOL element defines the size of a pool for caching the SOAP stubs created by each user. The cache uses a Least Recently Used (LRU) eviction policy and defaults to a size of 10 if the element is not defined in web.xml.

Removing the administrator credential restrictions By default, the requirement for invoking the REST and SOAP services is that the HTTP session logged in user must have administrator credentials. The Provisioning and Directory Web Services require Provisioning Administrator credentials. The Roles Web Service requires Role Administrator credentials. The restrictions can be removed to allow a session with a logged in user who does not have administrator credentials to invoke the methods for the services by changing the configuration settings for the service. In order to do this, you must extract the configuration files from the User Application war, make the appropriate changes, and import the files back into the User Application WAR. The details for removing the restrictions is included with the documentation for each of the underlying SOAP services. For example, to remove the credential restriction for the Role Service, see Section 22.1.4, Removing Administrator Credential Restrictions.

Media Type Supported

The only media type supported is JSON (application/json). The service uses a JSON Array format for list of items and a single JSON object for detail information. The media type is determined by the “Accept” header parameter. The implementation uses the Jettison JSON APIs to create the JSON structures.

Digital Signature Not Supported

The REST interfaces do not support digital signatures. If you attempt to process a digital signature workflow through REST, an internal server error message will appear.

25.1.2 Configuring the RIS WAR

This section provides instructions for setting up the RIS WAR on JBoss, WebSphere, and WebLogic.

JBoss Configuration

To configure the RIS WAR on JBoss:

Modify the host, port, and WAR context information for the RBPM deployment on JBoss in the web.xml of the RIS WAR.
1. Copy the RIS.war file to a test folder.
  
  For example: /home/lab/RIS
2. Extract the web.xml from the RIS war, maintaining the folder structure.
  
  This will create the following structure: /home/lab/RIS/WEB-INF/web.xml
  1. Open the web.xml in a text editor.
  2. Locate the following entry:
    <init-param> <param-name>USER_APP_URL</param-name> <param-value>http://localhost:8080/IDMProv</param-value> </init-param>
  3. Modify the param-value as necessary. You need to use either the DNS name or the IP address of the server on which the RBPM war is deployed.
    
    IMPORTANT:Do not use localhost if you plan to use the REST identity services to access user photos. The photo URL is dependent on this entry. The photo URL must point to the User Application to retrieve the photo. The REST identity service does not provide the binaries for the photo, but does provide a link, which is based on this entry.
  4. Save the file.
3. Add the web.xml file back to the RIS war using the jar command from the SUN JDK.
  
  For example: /home/lab/jdk1.6.0_11/bin/jar -uf RIS.war WEB-INF/web.xml
Copy the RIS war to the deployment directory of the JBoss server.
Extract the commons-codec-1.3.jar from the RBPM war into the %context%/lib directory of the JBoss server where the RIS WAR will be deployed. Make sure to not maintain folder structure when extracting the file.

For example: /home/lab/IDM370/idm/jboss/server/IDMProv/lib
Start JBoss.

WebSphere Configuration

To configure the RIS WAR on WebSphere:

Modify the host, port, and war context information for the RBPM deployment on WebSphere in the web.xml of the RIS WAR.
1. Copy the RIS war to a test folder.
  
  For example: /home/lab/RIS
2. Extract the web.xml from the RIS war, maintaining the folder structure.
  
  This will create the following structure: /home/lab/RIS/WEB-INF/web.xml
  1. Open the web.xml in a text editor.
  2. Locate the following entry:
    <init-param> <param-name>USER_APP_URL</param-name> <param-value>http://localhost:8080/IDMProv</param-value> </init-param>
  3. Modify the param-value as necessary. You need to use either the DNS name or the IP address of the server on which the RBPM war is deployed.
    
    IMPORTANT:Do not use localhost if you plan to use the REST identity services to access user photos. The photo URL is dependent on this entry. The photo URL must point to the User Application to retrieve the photo. The REST identity service does not provide the binaries for the photo, but does provide a link, which is based on this entry.
  4. Save the file.
3. Add the web.xml file back to the RIS war using the jar command from the IBM JDK.
  
  For example: /home/lab/WAS61/IBM/WebSphere/AppServer/java/bin/jar -uf RIS.war WEB-INF/web.xml
Extract the commons-httpclient.jar and log4j.jar from the RBPM war that was created for WebSphere into your test folder/WEB-INF/lib directory.

For example: /home/lab/RIS/WEB-INF/lib

Add the two jars to the RIS war using the jar command from the IBM JDK.

For example:

/home/lab/WAS61/IBM/WebSphere/AppServer/java/bin/jar -uf RIS.war WEB-INF/lib/commons-httpclient.jar
/home/lab/WAS61/IBM/WebSphere/AppServer/java/bin/jar -uf RIS.war WEB-INF/lib/log4j.jar

Deploy the RIS WAR to WebSphere.
NOTE:You may see a warning message in the WebSphere logs when deploying the RIS.war. However, the deployment should complete successfully.
```
Error while adding servlet mapping --> /* Please set fileServingEnabled=false in the ibm-web-ext.xmi file which is under WEB-INF folder.
```

WebLogic Configuration

To configure the RIS WAR on WebLogic:

Modify the host, port, and war context information for the RBPM deployment on WebLogic in the web.xml of the RIS WAR.
1. Copy the RIS war to a test folder.
  
  For example: /home/lab/RIS
2. Extract the web.xml from the RIS war, maintaining the folder structure.
  
  This will create the following structure: /home/lab/RIS/WEB-INF/web.xml
  1. Open the web.xml in a text editor.
  2. Locate the following entry:
    <init-param> <param-name>USER_APP_URL</param-name> <param-value>http://localhost:8080/IDMProv</param-value> </init-param>
  3. Modify the param-value as necessary. You need to use either the DNS name or the IP address of the server on which the RBPM war is deployed.
    
    IMPORTANT:Do not use localhost if you plan to use the REST identity services to access user photos. The photo URL is dependent on this entry. The photo URL must point to the User Application to retrieve the photo. The REST identity service does not provide the binaries for the photo, but does provide a link, which is based on this entry.
  4. Save the file.
3. Add the web.xml file back to the RIS war using the jar command from the JRocket JDK.
  
  For example: /home/lab/WL103/bea/jrockit_160_05/bin/jar -uf RIS.war WEB-INF/web.xml
Extract the commons-httpclient.jar from the RBPM war that was created for WebLogic into your test folder/WEB-INF/lib directory.

For example: /home/lab/RIS/WEB-INF/lib

Add the jar to the RIS war using the jar command from the JRocket JDK.

For example:

home/lab/WL103/bea/jrockit_160_05/bin/jar -uf RIS.war WEB-INF/lib/commons-httpclient.jar

Deploy the RIS WAR to WebLogic.