24.1 About the Role Web Service

To support access by third-party software applications, the Role subsystem includes a Web service endpoint called the Role Web Service. It supports a wide range of role management and SoD management functions.

This Appendix describes the programming interface for the Role Web Service.

24.1.1 Accessing the Test Page

You can access the Role Web Service endpoint using a URL similar to the following:

http://server:port/warcontext/role/service?test

For example, if your server is named “myserver”, your User Application is listening on port 8080, and your User Application war file is named “IDMPROV”, the URL would be:

http://myserver:8080/IDMPROV/role/service?test

You can also access the SOAP endpoint by going to the Administration tab within the User Application. To do this, you need to select the Application Configuration tab, then select Web Services from the left-navigation menu. After selecting Web Services, pick the Web Service endpoint you want from the list.

WARNING:The test page is disabled by default. Since some of the methods allow data to be updated, the test page presents a potential security vulnerability and should not be allowed in a production environment.

Servlet Declaration for the Test Page

A SOAP service using WSSDK is deployed by adding the following declarations in the deployment descriptor (i.e. WEB-INF/web.xml):

<servlet>
  <servlet-name>Role</servlet-name>
  <servlet-class>com.novell.idm.nrf.soap.ws.role.impl.RoleServiceSkeletonImpl</servlet-class>

<servlet-mapping>
  <servlet-name>Role</servlet-name>
  <url-pattern>/role/service</url-pattern>
</servlet-mapping>
</servlet>

This follows the normal servlet declaration pattern. It indicates that the servlet com.novell.idm.nrf.soap.ws.role.impl.RoleServiceSkeletonImpl is deployed at /role/service.

When a user reaches this servlet using a HTTP GET by entering http://server-name/context/role/service (for example, http://localhost:8080/IDMProv/role/service) in their browser, the WSSDK provides a page that exposes some information about the deployed service. By default the page looks like this:

Figure 24-1 SOAP Service with Test Page Disabled

After you enable the test page, the Test Service link is available:

Figure 24-2 SOAP Servlet with Test Page Enabled

On the test page, the user can retrieve the WSDL document that describes the Web Service, see the Java Remote Interface that represents the service, and also see the type mappings from XML to Java. In addition, the user can test the service by invoking individual methods.

Enabling the Test Page

WARNING:The test page is disabled by default. Since some of the methods allow data to be updated, the test page presents a potential security vulnerability and should not be allowed in a production environment.

To enable the test page, you need to update the web.xml file. Before you make your changes, the web.xml should look like this:

<servlet>
  <servlet-name>Role</servlet-name>
  <servlet-class>com.novell.idm.nrf.soap.ws.role.impl.RoleServiceSkeletonImpl</servlet-class>
  <init-param>
    <param-name>com.novell.soa.ws.test.disable</param-name>
    <param-value>true</param-value>
  </init-param>
</servlet>

Change the servlet declaration, as follows:

<servlet>
  <servlet-name>Role</servlet-name>
  <servlet-class>com.novell.idm.nrf.soap.ws.role.impl.RoleServiceSkeletonImpl</servlet-class>
</servlet>

24.1.2 Accessing the WSDL

You can access the WSDL for the Role Web Service using a URL similar to the following:

http://server:port/warcontext/role/service?wsdl

For example, if your server is named “myserver”, your User Application is listening on port 8080, and your User Application war file is named “IDMPROV”, the URL would be:

http://myserver:8080/IDMPROV/role/service?wsdl

24.1.3 Generating the Stub Classes

Before using the Web Service, you need to use the WSSDK tool or another SOAP tool kit to generate the stub classes. To allow your code to find the stub classes, you also need to add the JAR that contains the stub classes to your classpath.

If you want to use the Novell WSSDK tool, you can generate the client stubs by extracting the WSDL and running the wsdl2java utility. For example, you could run this command to generate the stubs in a package called com.novell.soa.af.role.soap.impl:

"C:\Program Files\Java\jdk1.5.0_14\bin\java" -cp "../lib/wssdk.jar;../lib/jaxrpc-api.jar";"../lib/mail.jar";"../lib/activation.jar";"c:\Program Files\Java\jdk1.5.0_14\lib\tools.jar"; com.novell.soa.ws.impl.tools.wsdl2java.Main -verbose -ds gensrc -d C:\ -noskel -notie -genclient -keep -package com.novell.soa.af.role.soap.impl -javadoc role.wsdl

You can change the wsdl2java parameters to suit your requirements.