An introduction to Novell Roles Based Provisioning Manager Web Services and Java Examples

Author: Jason Rivard

Contents

1 Executive Summary
1.1 Introduction
1.2 Web Services Background
1.3 RBPM Web Service Functionality
1.4 RBPM Architecture
1.5 Security & Authentication
1.6 Sessions
1.7 About these Examples
1.8 Using Provisioning Workflows as General Purpose APIs
1.9 LDAP Background
2 SOAP Services
2.1 Provisioning Services
2.1.1 Start Workflow (Start)
2.1.2 Get Process Info (GetProcess)
2.1.3 Get Processes for a Workflow (GetProcessById)
2.2 VDX Services
2.2.1 Read Attribute Data (GetAttribute)
2.2.2 Write User Data (SetAttribute)
2.2.3 User Search (GlobalQuery)
2.3 Role Service
2.3.1 Read All Roles
2.3.2 Read Role Categories (GetRoleCategories)
2.3.3 Read Role Assignments (GetUser)
2.3.4 Add Role Assignment (RoleAssignment)
2.3.5 Revoke Role Assignment (RoleAssignment)
2.4 Resource Service
2.4.1 Read User Resources (GetResourceAssignmentsForUser)
2.4.2 Add Resource Assignment (RequestResourceGrant)
2.4.3 Remove Resource Assignment (RequestResourceGrant)
2.5 Forgotten Password
3 REST Services
3.1 Password Services
3.1.1 Change Password
3.1.2 Set Responses
3.1.3 Retrieve Challenge Policy
3.2 Identity Services
3.2.1 List All Identities
3.2.2 Read Identity
4 Glossary of Terms

Executive Summary

1.1 Introduction

This document is intended as a guide for developers to leverage the SOAP and REST web services available as part of the Novell Identity Manager Roles Based Provisioning Module (RBPM). This document is not a replacement for the RBPM product documentation. The reader will need to refer to the product documentation for a comprehensive list of available APIs. The product documentation can be found on the Novell documentation website at http://www.novell.com/documentation.

This document is oriented towards a Java developer with an understanding of identity management terms and concepts. Developers for other languages and platforms as well as system administrators may also find this document useful as the APIs and many of the concepts are the same regardless of client platform.

1.2 Web Services Background

The web service operations use standard SOAP and REST interfaces. These web services are documented by the RBPM v3.7 product documentation.

SOAP (sometimes called “Big Web services”) uses a standard XML data format and has a rich array of features, sometimes making it difficult for developers to learn. For each SOAP service there is a WSDL definition available. Most development environments will auto-generate so-called “stub” code for working with SOAP services by just supplying a WSDL document. This generally makes it much easier to work with the SOAP interface.

Novell does not provide generated stub files. Instead, the generation and maintenance of stub files used by a particular application or platform are the responsibility of the application or platform.

A discussion of stub generation is beyond the scope of this document, see your platform or environment documentation for information about how to generate stub files. Novell RBPM documentation describes how to create Java stubs using a Novell supplied library known as WSSDK. In general, this is probably not an ideal library to use for modern projects as the Novell WSSDK is out of date and is not in common use by the Java community.

REST interfaces are generally much simpler than SOAP interfaces to access. REST uses simple HTTP GET and POST methods. A complex definition (such as WSDL) or data format (XML) is not required. Not all methods are available with REST interfaces. All REST interfaces described in this document return data in JSON (JavaScript Object Notation) format.

General Reading

http://en.wikipedia.org/wiki/Web_service
http://en.wikipedia.org/wiki/SOAP
http://en.wikipedia.org/wiki/REST
http://en.wikipedia.org/wiki/JSON

Novell Documentation

• SOAP Interfaces for RBPM v3.7

• REST Interfaces for RBPM v3.7

1.3 RBPM Web Service Functionality

As of version 3.7 of the Novell Roles Based Provisioning Module (RBPM), the following functionality is available:

SOAP

• Provisioning (workflow)

• VXD (general purpose Create/Read/Update/Delete interface)

• Role Service

• Resource Service

• Forgotten Password (reset forgotten password using challenge/response)

REST

• Identity, Role and Resource Service (part of the RIS.war)

• Password Management

• Work Item (workflow)

This list includes the most commonly used services. An exhaustive list of services is available in the RBPM product documentation.

1.4 RBPM Architecture

Overview

The RBPM system is comprised of several different components. The primary component is the Java J2EE application generally referred to as the User Application or UserApp. Other components are the UserApp IDM Connector and The Role & Resource IDM Connector. The RBPM system is deployed on the Novell Identity Management platform which uses Novell eDirectory for event management and data storage.

The UserApp J2EE server is the component that provides the web service endpoints for RBPM. The SOAP and REST services are hosted by the UserApp.

 

The UserApp consists of several different server contexts, but the primary ones dealt with are the /IDM and /RIS application contexts. /IDM (sometimes renamed to /IDMProv) is the primary user interface for the UserApp server.

The RIS Context

RBPM ships with a RIS.war application that is not automatically deployed at the time of RBPM installation. In order to use RIS based REST services the RIS.war must be deployed and configured. The RBPM product documentation describes the process to deploy and configure the RIS context.

The RIS context provides the following REST web-services:

• Identity Service

• Role Service

• Resource Service

1.5 Security & Authentication

By default, RBPM installations allow operations over HTTP and HTTPS. However, it is recommended that production web services deployments disable HTTP and only allow HTTPS. The web services available in RBPM depend on the HTTPS transport layer for security.

SOAP services are authenticated using parameters of the SOAP method calls.

REST services are authenticated using the “RESTAuthorization” HTTP header with the value of standard HTTP Basic Authentication request of “username:password” which is then Base64 encoded. Username should be expressed as a distinguished name (DN) in LDAP format.

The REST services that are part of the RIS.war context support a token based authentication method that allows re-using authentication credentials without having to send the credentials on each request.

1.6 Sessions

The REST services do not maintain session state.

SOAP services can optionally maintain a session state. To avoid session invalidation issues, it is recommended that session state only be used for a short duration; such as multiple consecutive operations that are part of a single application API.

In the case of the Forgotten Password SOAP service, session state is required for the scope of a complete Forgotten Password activity. This is discussed in more detail later in this document.

1.7 About these Examples

These examples were developed against the Novell RBPM v3.7 system using Java 5 development environment. The RBPM server used is the Novell Demo Systems RBPM v3.7 (Picasso) December 2009 image.

The Demo Systems image is a standard product installation and the examples will work against any RBPM v3.7 or better installation. If you wish to use the examples against your own RBPM environment, you will need to change the connect URLs and user data as appropriate.

Apache Axis was used for stub generation and the SOAP API. The built-in Java HttpURLConnection class is used for REST examples.

1.8 Using Provisioning Workflows as General Purpose APIs

The traditional notion of a workflow typically invokes the concept of a user starting some process, a routing of that process among approvers and then some action being performed. This approach is used commonly with RBPM. Workflows can also be used as general purpose APIs to the identity management system. In this approach, "no-approval" workflows are implemented in which an action is immediately performed and the workflow is completed. This approach can be handy in cases where the product defined APIs do not meet your requirements.

Reasons to use a no-approval workflow as a SOAP API include:

• Combining several API calls into a single interface

• Performing data validation

• Invoking external libraries

• Implementing complex logic
  However, there can be challenges when using workflows this way. In particular:

• The start() workflow API is asynchronous
  Clients will need to continuously poll the system to learn the status of the workflow

• The amount of time until completion is not consistent
  When idle, workflow processing times are usually within a few seconds, but if the workflow queues are busy, processing times may be much longer.

1.9 LDAP Background

The foundational data repository of RBPM is Novell eDirectory. eDirectory is an X.500 based directory implementation. In many cases, the web services abstract the LDAP foundations of the system, but consumers of the web services should still be familiar with LDAP. In particular, many of the web services expose the LDAP DN (Distinguished Names) of users, roles and resources.

LDAP DNs can be thought of as a short-term unique identifier for a data object. In many cases, LDAP DNs are essentially permanent, but administrative and other changes may cause LDAP DNs to be modified over time.

For example, the LDAP DN of the user used in many of the examples for user KSmith is:

cn=ksmith,ou=users,o=utopia

Nearly all functions available through LDAP are available through the RBPM web services with the notable exception of Authentication. Authentication web services are available in the Novell Access Manager product in the form of federation protocols such as SAML.

This document assumes the reader is somewhat familiar with LDAP.

2 SOAP Services

2.1 Provisioning Services

The SOAP Provisioning Service is used to initiate a workflow within the RBPM system. Workflows are defined by the RBPM administrator and can be of arbitrary complexity. In Novell RBPM terms, workflows are referred to as Provisioning Request Definitions (PRD).

Workflows are invoked from within a queue managed by the RBPM system. The RBPM system manages the queue internally. Queue workload can be processed in parallel by a single server or a cluster of servers. RBPM does not offer guarantees about queue processing times or order of processing.

Workflows are composed of activities. Each activity within a workflow causes some processing or action to be performed. Many of the provisioning APIs deal with individual activities of workflow as opposed to the overall workflow.

Each time a workflow is initiated, the workflow is assigned a process ID that can be used to reference the particular instance of a workflow. Workflow instances persist in the RBPM for some time after the instance completes. By default, workflows are available for 120 days after completion.

SOAP interfaces to manage the RBPM workflow are available to:

• Start a workflow

• Read the status of a workflow process

• Read the status of a workflow activity

• Discover information about defined workflows in the system

The WSDL for the provisioning service can be found on the server at:
https://servername.example.com/IDM/provisioning/service?wsdl



2.1.1 Start Workflow (Start)

The start() workflow service is used to initiate a workflow process. The workflow (also known as the Provisioning Request Definition or PRD) must be previously defined by the RBPM administrator.

This method is an asynchronous call, meaning that when the API completes, the workflow has been submitted, but not yet processed.

Callers will typically retrieve the workflow processID from the response, and then use that processID with other APIs to read the status of the process.

Parameters

Aside from the service account DN and credentials used to authenticate the SOAP client, the parameters for the registration operation using SOAP provisioning start() service are as follows:

Parameter

Value

processId

The LDAP DN of the workflow. Defined by the workflow administrator. This example is using “cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=systems”

recipient

The LDAP DN of the user that receive the action. Even if the workflow does not act on the recipient, a valid LDAP DN must be supplied

dataItem

Mapping of the following data elements:The available data item keys are specified as part of the provisioning request definition's request form. Each parameter specified on the request form can be specified as a DataItem element. Key (Form name) Value

reason

User Requested Access

 

 

Example Java Code

The example java code for this SOAP service is as follows:

package client.soap.provisioning;
import org.apache.axis.client.Call;
import stubs.provisioning.*;
import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;
import java.util.*;
public class StartWorkflow {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/provisioning/service";
	public static final String PROVISIONING_DN = "cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig,
cn=UserApplication, cn=driverset, o=system";

public static void main(String[] args)
			throws ServiceException, MalformedURLException, RemoteException
	{
		ProvisioningServiceLocator locater = new ProvisioningServiceLocator();
		Provisioning service = locater.getProvisioningPort(new URL(SERVICE_URL));
		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);
		List<DataItem> startRequestDataItem = new ArrayList<DataItem>();
		startRequestDataItem.add(new DataItem("reason", new String[] {"User Requested Access”}));
		DataItem[] dataItemArray = startRequestDataItem.toArray(new DataItem[startRequestDataItem.size()]);
		StartRequest startRequest = new StartRequest();
		startRequest.setArg0(PROVISIONING_DN);
		startRequest.setArg1("cn=ksmith,ou=users,o=utopia");
		startRequest.setArg2(dataItemArray);
		StartResponse startResponse = service.start(startRequest);
		System.out.println("start workflow complete, processID="   startResponse.getResult());
	}
}

Example Java Code Output

start workflow complete, processID=0e2b563d3cf64e838dd671286ef277ad

API Notes

After the start() is initiated, the service will return a transaction ID that the client should retain. This transaction ID can be used to check the process status of the workflow request using several of the provisioning APIs, such as getProcess().

The start() command starts an asynchronous workflow process. The successful completion of this command means only that the workflow was accepted for processing at some point in the future.

Workflow processes may be executed concurrently. If it is important to execute workflows in a serial order, you must use the getProcess command to wait for a workflow to complete before submitting the next workflow.

Workflow processes may execute out of order. Due to the way the servers may be clustered, it is possible for workflows to be submitted to different servers with different calls to the start process. While this may be a rare event, you should avoid depending on ordered operations without using the getProcess command to wait for completed process prior to invoking the next start operation.



2.1.2 Get Process Info (GetProcess)

The provisioning API getProcess method is used to get the process information about a running or completed workflow process. By default, workflow processes are available for 120 days after they have completed. Other APIs allow you to retrieve more detailed status about the processes' activities.

Parameters

The parameters for the getProcess ProvisioningSOAP operation using are as follows:

Parameter

Value

arg0

The processID of the workflow process. This example is using “0e2b563d3cf64e838dd671286ef277ad”, a value returned as the result of a start() invocation.

 

 

Example Java Code

The example java code for this SOAP service is as follows:

package client.soap.provisioning;

import org.apache.axis.client.Call;
import org.apache.axis.client.Stub;
import stubs.provisioning.*;
import stubs.provisioning.Process;

import javax.xml.rpc.ServiceException;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class GetProcessInfo {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/provisioning/service";
	public static final String REQUEST_ID = "0e2b563d3cf64e838dd671286ef277ad";

	public static void main(String[] args)
			throws ServiceException, MalformedURLException, RemoteException
	{
		ProvisioningServiceLocator locater = new ProvisioningServiceLocator();
		Provisioning service = locater.getProvisioningPort(new URL(SERVICE_URL));
		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);
		GetProcessRequest getProcessesRequest = new GetProcessRequest();
		getProcessesRequest.setArg0(REQUEST_ID);
		GetProcessResponse response = service.getProcess(getProcessesRequest);
		Process process = response.getProcess();
		if (process == null) {
		System.out.println("process not found");
		System.exit(0);
		}
		System.out.println("requestID="   process.getRequestId());
		System.out.println("processID="   process.getProcessId());
		System.out.println("processName="   process.getProcessName());
		System.out.println("processStatus="   process.getProcessStatus());
		System.out.println("approvalStatus="   process.getApprovalStatus());
		System.out.println("recipient="   process.getRecipient());
	}
}

Example Java Code Output

requestID=0e2b563d3cf64e838dd671286ef277ad
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Completed
approvalStatus=Approved
recipient=cn=ksmith,ou=users,o=utopia

2.1.3 Get Processes for a Workflow (GetProcessById)

The getProcessesById command can be used to discover workflow processes invoked against a particular workflow provisioning request definition (PRD). This may be useful in cases where the processID returned during the start() method is unavailable.

Parameters

The parameters for the getProcessesById Provisioning SOAP operation are as follows:

Parameter

Value

arg0

The LDAP DN of the workflow. Defined by the workflow administrator. This example is using “cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=systems”

 

 

Example Java Code

The example java code for this Get Process By ID SOAP service is as follows:

package client.soap.provisioning;

import org.apache.axis.client.Call;
import org.apache.axis.client.Stub;
import stubs.provisioning.*;
import stubs.provisioning.Process;

import javax.xml.rpc.ServiceException;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class GetProcessesForWorkflow {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/provisioning/service";
	public static final String PROVISIONING_DN = "cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication,
cn=driverset, o=system";
	public static void main(String[] args)
			throws ServiceException, MalformedURLException, RemoteException
	{
		ProvisioningServiceLocator locater = new ProvisioningServiceLocator();
		Provisioning service = locater.getProvisioningPort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		GetProcessesByIdRequest getProcessesByIdRequest = new GetProcessesByIdRequest();
		getProcessesByIdRequest.setArg0(PROVISIONING_DN);

		GetProcessesByIdResponse response = service.getProcessesById(getProcessesByIdRequest);
		Process[] processes = response.getProcessArray();

		if (processes == null) {
			System.out.println("no processes found");
			System.exit(0);
		}

		for (Process process : processes) {
			System.out.println("requestID="   process.getRequestId());
			System.out.println("processID="   process.getProcessId());
			System.out.println("processName="   process.getProcessName());
			System.out.println("processStatus="   process.getProcessStatus());
			System.out.println("approvalStatus="   process.getApprovalStatus());
			System.out.println("recipient="   process.getRecipient());
			System.out.println("");
		}
	}
}

Example Java Code Output

requestID=bef116b378ea445aa0516ee6df3f6901
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Running
approvalStatus=Processing
recipient=cn=ksmith,ou=users,o=utopia

requestID=84fad168eb1c45c394fc1f783c180e52
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Running
approvalStatus=Processing
recipient=cn=ksmith,ou=users,o=utopia

requestID=490b4d80165e45cfa44f355606e28af8
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Running
approvalStatus=Processing
recipient=cn=ksmith,ou=users,o=utopia

requestID=6c7a1ffd73b24b5b905e791a332652a4
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Running
approvalStatus=Processing
recipient=cn=ksmith,ou=users,o=utopia

requestID=4d047d7ef6ca4114833f2ae34ab0a01a
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Terminated
approvalStatus=Error
recipient=cn=ksmith,ou=users,o=utopia

requestID=2b300f395ec04e51ace50d02426dec49
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Terminated
approvalStatus=Error
recipient=cn=ksmith,ou=users,o=utopia

requestID=0e2b563d3cf64e838dd671286ef277ad
processID=cn=RequestLinuxAccount, cn=RequestDefs, cn=AppConfig, cn=UserApplication, cn=driverset, o=system
processName=Request Linux Account
processStatus=Completed
approvalStatus=Approved
recipient=cn=ksmith,ou=users,o=utopia

2.2 VDX Services

The Novell Identity Manager Roles Based Provisioning Module (RBPM) provides a general purpose data accessor SOAP service knows as the VDX Web Service. The VDX Web Service provides access to the Directory Abstraction Layer (DAL) in RBPM, which in turn is backed by eDirectory data service.

Traditionally, data access to a directory is provided using the LDAP (Lightweight Directory Access Protocol). You can think of the VDX Web Services as Novell's web services based alternative to LDAP.

VDX Web Services are composed primarily of:

• Attribute Read Operations

• Attribute Write Operations

• Pre-Defined Query Operations

The query operations require that the administrator create a query-operation prior to the invocation of the web service. The client may specify parameters of the search terms.

VDX services are typically invoked using a service account with service level permissions. The data-level ACL permissions of the service account are applied to the results.

Data is accessed for a particular entry (LDAP DN), and requires specifying class and attribute. The class and attribute definitions are defined by the RBPM administrator by configuring the DAL.



2.2.1 Read Attribute Data (GetAttribute)

Reading data from the directory is the most common operation. This example shows reading a user's Title attribute. The class and attribute names are set by the RBPM administrator when configuring the DAL (Directory Abstract Layer).

Parameters

The parameters for the getAttribute operation using VDX web service are as follows:

Parameter

Value

arg0

User LDAP DN. “cn=ksmith,ou=users,o=utopia” in this example

arg1

“user” The class for users as defined in RBPM. Value is case sensitive.

arg2

“Title” The attribute for Title attributes as defined in the DAL. Value is case sensitive.

 

 

Example Java Code

The example java code for this VDX web service is as follows:

package client.soap.vdx;

import org.apache.axis.client.Call;
import org.apache.axis.client.Stub;
import stubs.vdx.*;

import javax.xml.rpc.ServiceException;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class ReadUserData {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/vdx/service";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static final String USER_ATTRIBUTE_NAME = "Title";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final VdxServiceLocator locater = new VdxServiceLocator();
		final IRemoteVdx service = locater.getIRemoteVdxPort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		GetAttributeRequest request = new GetAttributeRequest();
		request.setArg0(USER_DN);
		request.setArg1("user");
		request.setArg2(USER_ATTRIBUTE_NAME);

		GetAttributeResponse response = service.getAttribute(request);
		Attribute attribute = response.getResult();

		String[] strings = attribute.getStrings();
		if (strings.length > 0) {
			System.out.println("value="   strings[0]);
		} else {
			System.out.println("no value returned");
		}
	}
}

Example Java Code Output

value=Executive Sales Representative

2.2.2 Write User Data (SetAttribute)

This service can be used to update user attribute data into the system. This Update User Data service can be used to update the following attributes in the Directory through the DAL layer. The class and attribute names are set by the RBPM administrator when configuring the DAL (Directory Abstract Layer).

Parameters

The parameters for the User Search operation using VDX web service are as follows:

Parameter

Value

arg0

User LDAP DN. “cn=ksmith,ou=users,o=utopia” in this example

arg1

“user” The class for users as defined in RBPM. Value is case sensitive.

arg2

“Title” The attribute for Title attributes as defined in the DAL. Value is case sensitive.

arg3

Attribute data object with a String AttributeType

 

 

Example Java Code

The example java code for this VDX web service is as follows:

package client.soap.vdx;

import org.apache.axis.client.Call;
import stubs.vdx.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class WriteUserData {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/vdx/service";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static final String USER_ATTRIBUTE_NAME = "Title";
	public static final String USER_ATTRIBUTE_VALUE = "Executive Sales Representative";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final VdxServiceLocator locater = new VdxServiceLocator();
		final IRemoteVdx service = locater.getIRemoteVdxPort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		Attribute newPasswordValue = new Attribute();
		newPasswordValue.setType(AttributeType.String);
		newPasswordValue.setStrings(new String[] {USER_ATTRIBUTE_VALUE});

		SetAttributeRequest request = new SetAttributeRequest();
		request.setArg0(USER_DN);
		request.setArg1("user");
		request.setArg2(USER_ATTRIBUTE_NAME);
		request.setArg3(newPasswordValue);

		service.setAttribute(request);

		System.out.println("value set successfully");
		}
	}

Example Java Code Output

value set successfully

2.2.3 User Search (GlobalQuery)

This service is used to search the system for a user account. Queries are defined and configured by the RBPM administrator. In this example a query with a key of “loginid-query” is configured to search for login ID values.

Parameters

The parameters for the Set User Password operation using VDX web service are as follows:

Parameter

Value

Query Key

“user-by-id”

Entry

A StringMap containing the following StingEntry element: Key       Value userid       a*Each StringEntry element maps to a query parameter that is defined in the query definition configured by the RBPM administrator.

 

 

Example Java Code

The example java code for this VDX web service is as follows:

package client.soap.vdx;

import org.apache.axis.client.Call;
import stubs.vdx.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class UserSearch {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/vdx/service";

	public static final String QUERY_KEY = "user-by-id";
	public static final String QUERY_PARAMETER_1 = "userid";
	public static final String QUERY_PARAMETER_1_VALUE = "a*";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final VdxServiceLocator locater = new VdxServiceLocator();
		final IRemoteVdx service = locater.getIRemoteVdxPort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		StringMap stringMap = new StringMap();
		StringEntry stringEntry = new StringEntry();
		stringEntry.setKey(QUERY_PARAMETER_1);
		stringEntry.setValues(QUERY_PARAMETER_1_VALUE);
		stringMap.setEntries(new StringEntry[] { stringEntry });

		GlobalQueryRequest request = new GlobalQueryRequest();
		request.setArg0(QUERY_KEY);
		request.setArg1(stringMap);

		GlobalQueryResponse response = service.globalQuery(request);
		String[] entityAttributeMap = response.getResult();

		for (String entry : entityAttributeMap) {
			System.out.println(entry);
		}
	}
}

Example Java Code Output

cn=asmith,ou=users,o=utopia
cn=achung,ou=users,o=utopia
cn=ablake,ou=users,o=utopia
cn=apalani,ou=users,o=utopia
cn=aspencer,ou=users,o=utopia

2.3 Role Service

Role Service APIs can be used to search for roles, read role information, modify attributes of a role, and perhaps most importantly, add and remove users from a role.

RBPM roles can have parent and children roles which form a role hierarchy. Roles can be part of a category, can be related to RBPM resources and entitlements, and have their own approval processes defined. Role assignments also have effective and expiration dates. Additionally, roles can be part of Separation of Duties (SOD) definitions which prevent a user from being a member of conflicting roles. Understanding RBPM roles and their proper usage is beyond the scope of this document.

It's worth mentioning that strictly speaking there is no API to directly add or remove users to and from a role. In fact, the role assignment request APIs simply initiate a request to add or remove users from roles. Roles definitions include policy about how these activities actually get processed and may include approvals or other activities. In fact, for every role add or remove request a workflow process is initiated by RBPM to process the request. With good reason, the RBPM APIs do not offer a way to bypass these policies.



2.3.1 Read All Roles

The first role service described here will use the FindRoleByExampleWithOperator request to discover all of the roles defined. The Role API contains several search APIs to discover roles. In this case the API will be invoked with a wildcard search to return all defined roles.

Example Java Code

The example java code for this SOAP web service is as follows:

package client.soap.roles;

import org.apache.axis.client.Call;
import stubs.role.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class ReadAllRoles {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/role/service";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final RoleServiceLocator locater = new RoleServiceLocator();
		final IRemoteRole service = locater.getIRemoteRolePort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		Role exampleRole = new Role();
		exampleRole.setName("*");

		FindRoleByExampleWithOperatorRequest request = new FindRoleByExampleWithOperatorRequest();
		request.setRole(exampleRole);

		FindRoleByExampleWithOperatorResponse response = service.findRoleByExampleWithOperator(request);
		final Role[] roles = response.getResult();

		for(Role role : roles) {
			System.out.println("role name: "   role.getName());
			System.out.println("role key: "   role.getEntityKey());
			System.out.println("role description: "   role.getDescription());
			System.out.println("");
		}
	}
}

2.3.2 Read Role Categories (GetRoleCategories)

Roles are organized into categories to help users and administers find roles when browsing or searching for them. The GetRoleCategories service will return a list of all categories defined.

Categories can be used when searching for Roles to list roles for a particular category.

Example Java Code

The example java code for this SOAP web service is as follows:

package client.soap.roles;

import org.apache.axis.client.Call;
import stubs.role.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class ReadRoleCategories {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/role/service";

	public static void main(final String[] args)
			throws ServiceException, MalformedURLException, RemoteException
	{
		final RoleServiceLocator locater = new RoleServiceLocator();
		final IRemoteRole service = locater.getIRemoteRolePort(new URL(SERVICE_URL));
		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);
		GetRoleCategoriesRequest request = new GetRoleCategoriesRequest();
		GetRoleCategoriesResponse response = service.getRoleCategories(request);
		final Category[] roleCategories = response.getResult();
		for(Category category : roleCategories) {
			System.out.println("category key: "   category.getCategoryKey());
			System.out.println("category label: "   category.getCategoryLabel());
			System.out.println("");
		}
	}
}

Example Java Code Output

category key: hr
category label: Human Resources

category key: is
category label: Information Services

category key: system
category label: System Roles

category key: default
category label: Default

category key: marketing
category label: Marketing

category key: sales
category label: Sales

category key: global
category label: Global

category key: operations
category label: Operations

category key: accounting
category label: Accounting

2.3.3 Read Role Assignments (GetUser)

The role GetUser service can be used to read the role assignments of a user category.

Example Java Code

The example java code for the GetUser SOAP web service is as follows:

package client.soap.roles;

import org.apache.axis.client.Call;
import stubs.role.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class ReadRoleAssignments {

	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";
	public static final String SERVICE_URL ="http://172.17.2.91:8080/IDM/role/service";
	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final RoleServiceLocator locater = new RoleServiceLocator();
		final IRemoteRole service = locater.getIRemoteRolePort(new URL(SERVICE_URL));
		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);
		GetUserRequest request = new GetUserRequest();
		request.setUserDN(USER_DN);
		GetUserResponse response = service.getUser(request);
		User theUser = response.getResult();
		System.out.println("user: "   theUser.getEntityKey());
		RoleAssignment[] roleAssignments = theUser.getRoleAssignments();
		for (RoleAssignment roleAssignment : roleAssignments) {
			final Role role = service.getRole(new GetRoleRequest(roleAssignment.getRole())).getResult();
			System.out.println(" role name="   role.getName());
			System.out.println(" role key="   role.getEntityKey());
			System.out.println(" assignment type: "   roleAssignment.getAssignmentType() );

			System.out.println("");

		}
	}
}

Example Java Code Output

user: cn=ksmith,ou=users,o=utopia
 role name=Tokyo
 role
key=cn=Tokyo,cn=Locations,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=UserApplication,cn=driverset,o=system
 assignment type: USER_TO_ROLE

 role name=Operations
 role
key=cn=Operations,cn=Departments,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=UserApplication,cn=driverset,o=syst
em
 assignment type: USER_TO_ROLE

 role name=Sales
 role
key=cn=Sales,cn=Departments,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=UserApplication,cn=driverset,o=system
 assignment type: USER_TO_ROLE

2.3.4 Add Role Assignment (RoleAssignment)

The role RoleAssignment service can be used to request to add (or “grant”) a role assignment to a user. This service does not directly assign a role to user, it merely initiates the request process. Depending on the policy of the role, the assignment may be immediately processed or may require approval.

Example Java Code

The example java code for the RoleAssignment SOAP role web service is as follows:

package client.soap.roles;

import org.apache.axis.client.Call;
import stubs.role.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class AddRoleAssignment {

	public static String ROLE_DN = "cn=Accounts
Payable,cn=Departments,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=UserApplication,cn=driverset,o=system";
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";
	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/role/service";
	public static final String USER_DN = "cn=ablake,ou=users,o=utopia";

	public static void main(final String[] args)
			throws ServiceException, MalformedURLException, RemoteException
	{
		final RoleServiceLocator locater = new RoleServiceLocator();
		final IRemoteRole service = locater.getIRemoteRolePort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		RoleAssignmentRequest roleAssignmentRequest = new RoleAssignmentRequest();
		roleAssignmentRequest.setActionType(RoleAssignmentActionType.grant);
		roleAssignmentRequest.setAssignmentType(RoleAssignmentType.USER_TO_ROLE);
		roleAssignmentRequest.setIdentity(USER_DN);
		roleAssignmentRequest.setReason("the reason");
		roleAssignmentRequest.setRoles(new DNString[]{new DNString(ROLE_DN)});

		RequestRolesAssignmentRequest requestRolesAssignmentRequest = new RequestRolesAssignmentRequest();
		requestRolesAssignmentRequest.setAssignRequest(roleAssignmentRequest);

		service.requestRolesAssignment(requestRolesAssignmentRequest);

		System.out.println("grant role assignment successful");
	}
}

2.3.5 Revoke Role Assignment (RoleAssignment)

The role RoleAssignment service can also be used to request to remove (or “revoke”) a role assignment to a user. This service does not directly remove a role assignment from the user, it merely initiates the request process. Depending on the policy of the role, the removal may be immediately processed or may require approval.

Example Java Code

The example java code for the RoleAssignment SOAP role web service is as follows:

package client.soap.roles;

import org.apache.axis.client.Call;
import stubs.role.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class RevokeRoleAssignment {
	public static String ROLE_DN = "cn=Accounts Payable
Employee,cn=Departments,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=UserApplication,cn=driverset,o=system";

	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/role/service";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final RoleServiceLocator locater = new RoleServiceLocator();
		final IRemoteRole service = locater.getIRemoteRolePort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		RoleAssignmentRequest roleAssignmentRequest = new RoleAssignmentRequest();
		roleAssignmentRequest.setActionType(RoleAssignmentActionType.revoke);
		roleAssignmentRequest.setAssignmentType(RoleAssignmentType.USER_TO_ROLE);
		roleAssignmentRequest.setIdentity(USER_DN);
		roleAssignmentRequest.setReason("cuz!");
		roleAssignmentRequest.setRoles(new DNString[]{new DNString(ROLE_DN)});

		RequestRolesAssignmentRequest requestRolesAssignmentRequest = new RequestRolesAssignmentRequest();
		requestRolesAssignmentRequest.setAssignRequest(roleAssignmentRequest);

		service.requestRolesAssignment(requestRolesAssignmentRequest);

		System.out.println("role revoke assignment successful");
	}
}

2.4 Resource Service

Role Service APIs can be used to read resource information as well as to add and remove users from a role.

RBPM resources represent items that users can have access to. The resources may represent groups in an application, or physical access to a building or anything the RBPM administrator cares to define. Resources assignments are often inherited as a result of a role assignment, but they can also be assigned directly to a user without a role. Understanding RBPM roles and their proper usage is beyond the scope of this document.

Like the role assignments, it's worth mentioning that strictly speaking there is no API to directly add or remove users to and from a resource. The resource assignment request APIs simply initiate a request to add or remove users from resources. Resource definitions include policy about how these activities actually get processed and may include approvals or other activities. In fact, for every resource assignment add or remove request a workflow process is initiated by RBPM to process the request. With good reason, the RBPM APIs do not offer a way to bypass these policies.



2.4.1 Read User Resources (GetResourceAssignmentsForUser)

This service discovers all explicit resource assignments for a user and returns information about those assignments.

Example Java Code

The example java code for this SOAP web service is as follows:

package client.soap.resources;

import org.apache.axis.client.Call;
import org.apache.axis.client.Stub;
import stubs.resource.*;

import javax.xml.rpc.ServiceException;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class ReadUserResources {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/resource/service";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final ResourceServiceLocator locater = new ResourceServiceLocator();
		final IRemoteResource service = locater.getIRemoteResourcePort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		GetResourceAssignmentsForUserRequest request = new GetResourceAssignmentsForUserRequest();
		request.setUserDn(USER_DN);

		GetResourceAssignmentsForUserResponse response = service.getResourceAssignmentsForUser(request);

		ResourceAssignment[] assignment = response.getResult();

		for(ResourceAssignment resourceAssignment : assignment) {
			System.out.println("recipientDn: "   resourceAssignment.getRecipientDn());
			System.out.println("resourceDn: "   resourceAssignment.getResourceDn());
			System.out.println("reason: "   resourceAssignment.getReason());
			System.out.println("");
		}
	}
}

2.4.2 Add Resource Assignment (RequestResourceGrant)

Users can be assigned directly to a resource. This service initiates a request to assign a resource to a user. Depending on the policy of the resource, the request may be processed immediately or may require an approval.

Example Java Code

The example java code for this SOAP web service is as follows:

package client.soap.resources;

import org.apache.axis.client.Call;
import org.apache.axis.client.Stub;
import stubs.resource.*;

import javax.xml.rpc.ServiceException;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class AddResourceAssignment {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static final String RESOURCE_DN =
"cn=Linux,cn=ResourceDefs,cn=RoleConfig,cn=AppConfig,cn=UserApplication,cn=driverset,o=system";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/resource/service";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final ResourceServiceLocator locater = new ResourceServiceLocator();
		final IRemoteResource service = locater.getIRemoteResourcePort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		RequestResourceGrantRequest request = new RequestResourceGrantRequest();
		request.setResourceTarget(RESOURCE_DN);
		request.setUserTarget(USER_DN);

		RequestResourceGrantResponse response = service.requestResourceGrant(request);

		final String result = response.getResult();
		System.out.println("result="   result);
	}
}

2.4.3 Remove Resource Assignment (RequestResourceGrant)

Users that are assigned directly to a resource can be removed from that resource. This service initiates a request to remove a resource from a user. Depending on the policy of the resource, the request may be processed immediately or may require an approval.

Example Java Code

The example java code for this SOAP web service is as follows:

package client.soap.resources;

import org.apache.axis.client.Call;
import org.apache.axis.client.Stub;
import stubs.resource.*;

import javax.xml.rpc.ServiceException;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;

public class RevokeResourceAssignment {
	public static final String SERVICE_ACCOUNT_DN = "cn=padmin,ou=users,o=utopia";
	public static final String SERVICE_ACCOUNT_PW = "n0v3ll";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static final String RESOURCE_DN =
"cn=Linux,cn=ResourceDefs,cn=RoleConfig,cn=AppConfig,cn=UserApplication,cn=driverset,o=system";

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/resource/service";

	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		final ResourceServiceLocator locater = new ResourceServiceLocator();
		final IRemoteResource service = locater.getIRemoteResourcePort(new URL(SERVICE_URL));

		((Stub)service)._setProperty(Call.USERNAME_PROPERTY, SERVICE_ACCOUNT_DN);
		((Stub)service)._setProperty(Call.PASSWORD_PROPERTY, SERVICE_ACCOUNT_PW);

		RequestResourceRevokeRequest request = new RequestResourceRevokeRequest();
		request.setResourceTarget(RESOURCE_DN);
		request.setUserTarget(USER_DN);

		RequestResourceRevokeResponse response = service.requestResourceRevoke(request);

		final String result = response.getResult();
		System.out.println("result="   result);
	}
}

2.5 Forgotten Password

This service is used when a user forgets their password and wishes to reset their password using their pre-configured challenge/response questions. That is the only functionality available through the SOAP forgotten password service, all other password related functionality is found in the REST password service.

To complete a forgotten password reset, three successful method calls must be made using the forgotten password service:

#

Method

Purpose

1

processUser

Initiate the process for the user, and read the user’s challenge questions. If the user has any “random” password responses, a random selection of the minimum required randoms will be presented here.

2

processChaRes

Send the user’s response answers back and validate them. This method can be called repeatedly until it succeeds. However, each incorrect attempt counts as an invalid password authentication and will eventually trip the automatic Intruder Detection feature.

3

processChgPwd

Once the processChaRes method succeeds, this method is used to modify the user’s password using a user supplied parameter.

 

 

Unlike the other SOAP services available from RBPM, the forgotten password service requires that an HTTP session (using http cookies) be maintained throughout these calls. Consult your SOAP API documentation to learn how to maintain a session. For Apache AXIS which is used in these examples, the following parameter needs to be set:

((Stub)service)._setProperty(javax.xml.rpc.Stub.SESSION_MAINTAIN_PROPERTY, Boolean.TRUE);

The session must be maintained for the three subsequent calls to processUser, processChaRes and processChgPwd, however the session needs to be discarded once the operation is complete. That is, the session should be reused for multiple invocations of processUser.

Additionally, the ForgottenPassword stub cannot be serialized (or passivated in servlet terms). The instance of ForgottenPassword must remain in memory while it is being processed.

Example Java Code

The example java code for this SOAP service is as follows:

package client.soap.password;

import stubs.pwdmgmt.*;

import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class ForgottenPassword {
	final static String USER_DN = "cn=ksmith,ou=users,o=utopia";
	final static String SERVICE_URL = "http://172.17.2.91:8080/IDM/pwdmgt/service";
	final static String NEW_PASSWORD = "newPw1234";
	final static String NEW_PASSWORD_CONFIRM = "newPw1234";
	final static Map<String,String> USER_RESPONSES = new HashMap<String,String>();

	static {
		USER_RESPONSES.put("question0","response0");
		USER_RESPONSES.put("question1","response1");
		USER_RESPONSES.put("question2","response2");
		USER_RESPONSES.put("question3","response3");
		USER_RESPONSES.put("question4","response4");

	}
	public static void main(final String[] args) throws ServiceException, MalformedURLException, RemoteException {
		/* Setup Axis SOAP connection */
		final PasswordManagementServiceLocator locater = new PasswordManagementServiceLocator();
		final PasswordManagement service = locater.getPasswordManagementPort(new URL(SERVICE_URL));

		// make sure the HTTP session is maintained over the three iterative API calls. If the
		// HTTP session is not maintained, this api's "timeout" will be set to true and the action
		// will fail. The session (service instance) should be discarded once the operation
		// for a particular user is completed.
		((Stub)service)._setProperty(javax.xml.rpc.Stub.SESSION_MAINTAIN_PROPERTY, Boolean.TRUE);

		/* Begin the processUser() API call */
		System.out.println("--processUser--");
		ProcessUserRequest userRequest = new ProcessUserRequest(USER_DN);
		ForgotPasswordWSBean processUserResponse = service.processUser(userRequest);
		System.out.println("msg="   processUserResponse.getMessage());
		System.out.println("error="   processUserResponse.isError());
		System.out.println("timeout="   processUserResponse.isTimeout());
		System.out.println("action="   processUserResponse.getAction());
		System.out.println("getUsers.length="   processUserResponse.getUsers().length);
		if (processUserResponse.getChallengeQuestions() != null) {
			for (String c: processUserResponse.getChallengeQuestions()) {
				System.out.println("q="   c);
			}
		}

		if (processUserResponse.isError() || processUserResponse.isTimeout()) {
				System.out.println("exiting due to error or timeout");
				System.exit(-1);
		}

		/* Begin the processChaRes() API call */
		System.out.println("--processChaRes--");
		final String[] userResponses = makeResponsesArray(processUserResponse.getChallengeQuestions());
		ProcessChaResRequest chaResRequest = new ProcessChaResRequest(
			USER_DN,
			userResponses);
		chaResRequest.setUserDN(USER_DN);
		ForgotPasswordWSBean processChaResResponse = service.processChaRes(chaResRequest);
		System.out.println("msg="   processChaResResponse.getMessage());
		System.out.println("error="   processChaResResponse.isError());
		System.out.println("timeout="   processChaResResponse.isTimeout());
		System.out.println("locked="   processChaResResponse.getLocked());
		System.out.println("rules="   processChaResResponse.getRules());

		if (processChaResResponse.isError() || processChaResResponse.isTimeout()) {
			System.out.println("exiting due to error or timeout");
			System.exit(-1);
		}

		/* Begin the processChgPwd() API call */
		System.out.println("--processChgPwd--");
		ProcessChgPwdRequest chgPwdRequest = new ProcessChgPwdRequest(
				USER_DN,
				NEW_PASSWORD,
				NEW_PASSWORD_CONFIRM
		);
		ForgotPasswordWSBean processChgPwdResponse = service.processChgPwd(chgPwdRequest);
		System.out.println("msg="   processChgPwdResponse.getMessage());
		System.out.println("error="   processChgPwdResponse.isError());

		if (processChaResResponse.isError() || processChaResResponse.isTimeout()) {
			System.out.println("--operation failure due to error or timeout--");
		} else {
			System.out.println("--operation success--");
		}
	}

	static String[] makeResponsesArray(String[] questions) {
		List<String> responses = new ArrayList<String>();
		for (String question : questions) {
			if (USER_RESPONSES.containsKey(question)) {
				responses.add(USER_RESPONSES.get(question));
			}
		}
		return responses.toArray(new String[responses.size()]);
	}
}

Error Conditions

This API can return error states at each step. It is important to check the isError method after each method invocation. If isError is true, the error must be corrected before the next step will be able to succeed. A positive value for isError is usually because the user data or values are preventing the API from proceeding normally.

Additionally, isTimeout should be checked after each method invocation. A positive value for isTimeout could indicate any of the following:

• The overall API time has exceeded the maximum allowed.

• The API is not properly maintaining HTTP session state with server.

• The instance of RBPM has changed (check to be sure sticky sessions are configured for all load balancing, proxy and firewalls between the client and RBPM server.

• The ForgottenPassword stub has been serialized.

The following table lists some of the more common error messages that may be generated:

Method

Error Message

Description

processChaRes

Challenge response failed.

Incorrect Responses

processChaRes

Hint was not defined.

does not set isError()==true, can be ignored as hint is not being used

processChaRes

All fields are required.

Empty response array

processChgPwd

Passwords must match.

Different new/confirm passwords

processChgPwd

All fields are required.

Empty new/confirm passwords

processChgPwd

Password does not meet the minimum numeric character requirement.

If password does not meet AD complexity and has no numbers

processChgPwd

Password is too short.

new password is not long enough

processChgPwd

Password attribute violation has been detected.

If password is same as first, last, full, email or loginID

processChgPwd

Password is on the exclusion list.

If password == 'password' or other value explicitly excluded

processChgPwd

Password does not meet the uppercase character minimum requirement.

If password does not meet AD complexity and has no letters

processChgPwd

[remote NullPointerException ]

Password > 517 chars

processUser

Password is not unique.

if password used previously

processUser

Forgot password feature disabled.

If password policy has forgotten password disabled

processUser

Answers to challenge response questions have not been set, or cannot be read at this time.

Responses not saved

processUser

Account restrictions prevent you from logging in. See your administrator for more details.

loginDisabled=true or lockedByIntruder=true

 

 

3 REST Services

3.1 Password Services

The REST password services offer methods to change the password and configure challenge response questions for a user.



3.1.1 Change Password

The pwdmgmt /password REST endpoint allows a user to change a password.

Parameters

Field Name

Field Value

oldPassword

novell

newPassword

newPw1234

retypeNewPassword

newPw1234

 

 

Example Java Code

The example java code for this REST service is as follows:

package client.rest.password;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class ChangePassword {

	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/roa/v1/pwdmgt/user/";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static final String CURRENT_PASSWORD = "novell";
	public static final String NEW_PASSWORD = "newPw1234";

	public static void main(String[] args) throws IOException {
		String authString = USER_DN   ":"   CURRENT_PASSWORD;
		String b64encodedAuthString = new sun.misc.BASE64Encoder().encode(authString.getBytes());
		URL restURL = new URL(SERVICE_URL   USER_DN   "/password");

		HttpURLConnection passwordURL = (HttpURLConnection) restURL.openConnection();
		passwordURL.setRequestMethod("POST");
		passwordURL.setRequestProperty("RESTAuthorization", b64encodedAuthString);
		passwordURL.setDoOutput(true);
		passwordURL.connect();

		StringBuilder postBody = new StringBuilder();

		postBody.append("oldPassword="   CURRENT_PASSWORD);
		postBody.append("&");
		postBody.append("newPassword="   NEW_PASSWORD);
		postBody.append("&");
		postBody.append("retypeNewPassword="   NEW_PASSWORD);

		OutputStream postOutputStream = passwordURL.getOutputStream();
		postOutputStream.write(postBody.toString().getBytes());
		postOutputStream.close();

		InputStream in = passwordURL.getInputStream();
		BufferedReader reader = new BufferedReader(new InputStreamReader(in));
		String text = reader.readLine();
		System.out.println(text);

		passwordURL.disconnect();
	}
}

Example Results

[{"pwdChgRtnPage":"","accessMgr":"false","pwd_chg_rtn_page":"Password Change Return Page","success_message":"Your
password has been changed successfully."}]

The returned results are JSON encoded. Of particular interest is either the success_message or error_message keys. The presence of these keys indicates success or failure of the operation, and the value is a user presentable message showing the result of the operation.

Password Set

The RBPM services do not offer a way to administratively set the user's password if the current password is not available. However, there are at least two ways to set the password without the current password.

One approach is to use the SOAP forgotten password service.

An alternative is to use the VDX SetAttribute service to write to the pseudo-attribute “userPassword”. For this to be possible, the RBPM administrator must do the following:

1. Add the “userPassword” attribute as a case-ignore-string to the Identity Vault schema in Designer and assign it to the User class.

• Add the userPassword attribute to the DAL entry for user, making it writable.

• Grant the service account used by the client API “Password Management” permissions within eDirectory.

3.1.2 Set Responses

The pwdmgmt /chares REST endpoint allows a user to set responses Example Java Code

The example java code for this REST service is as follows:

package client.rest.password;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class SetResponses {
	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/roa/v1/pwdmgt/user/";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static final String CURRENT_PASSWORD = "novell";

	public static void main(String[] args) throws IOException {
		String authString = USER_DN   ":"   CURRENT_PASSWORD;
		String b64encodedAuthString = new sun.misc.BASE64Encoder().encode(authString.getBytes());
		URL restURL = new URL(SERVICE_URL   USER_DN   "/chares");

		HttpURLConnection passwordURL = (HttpURLConnection) restURL.openConnection();
		passwordURL.setRequestMethod("POST");
		passwordURL.setRequestProperty("RESTAuthorization", b64encodedAuthString);
		passwordURL.setDoOutput(true);
		passwordURL.connect();

		StringBuilder postBody = new StringBuilder();

		postBody.append("_question0="   "question0");
		postBody.append("&");
		postBody.append("_question1="   "question1");
		postBody.append("&");
		postBody.append("_question2="   "question2");
		postBody.append("&");
		postBody.append("_answer0="   "response0");
		postBody.append("&");
		postBody.append("_answer1="   "response1");
		postBody.append("&");
		postBody.append("_answer2="   "response2");

		OutputStream postOutputStream = passwordURL.getOutputStream();
		postOutputStream.write(postBody.toString().getBytes());
		postOutputStream.close();

		InputStream in = passwordURL.getInputStream();
		BufferedReader reader = new BufferedReader(new InputStreamReader(in));
		String text = reader.readLine();
		System.out.println(text);

		passwordURL.disconnect();
	}
}

Example Results

[{"success_message":"Challenge responses were saved successfully"}]

3.1.3 Retrieve Challenge Policy

This service allows retrieval of the administratively defined challenge response questions.

Example Code

The example java code for this REST service is as follows:

package client.rest.password;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class RetrieveChallenges {
	public static final String SERVICE_URL = "http://172.17.2.91:8080/IDM/roa/v1/pwdmgt/user/";

	public static final String USER_DN = "cn=ksmith,ou=users,o=utopia";
	public static final String USER_PASSWORD = "novell";

	public static void main(String[] args) throws IOException {
		String authString = USER_DN   ":"   USER_PASSWORD;
		String b64encodedAuthString = new sun.misc.BASE64Encoder().encode(authString.getBytes());
		URL restURL = new URL(SERVICE_URL   USER_DN   "/chares");

		HttpURLConnection passwordURL = (HttpURLConnection) restURL.openConnection();
		passwordURL.setRequestMethod("GET");
		passwordURL.setRequestProperty("RESTAuthorization", b64encodedAuthString);
		passwordURL.setDoOutput(true);
		passwordURL.connect();

		InputStream in = passwordURL.getInputStream();
		BufferedReader reader = new BufferedReader(new InputStreamReader(in));
		String text = reader.readLine();
		System.out.println(text);

		passwordURL.disconnect();
	}
}

Example Results

[{},{"have_stored_challenges":"true","use_mask":"false"},{"0":"question0","1":"question1","2":"question2"},{},
{"use_grace_login":"true","grace_login_remaining":"4"}]

3.2 Identity Services

The REST RIS identity endpoint allows for accessing user information via REST. A single identity service is demonstrated here:



3.2.1 List All Identities

The RIS /identities REST endpoint allows listing users and user information.

Example Java Code

The example java code for this REST service is as follows:

package client.rest.identities;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ReadAllIdentities {
	public static final String SERVICE_URL = "http://172.17.2.91:8080/RIS/v1/identities";

	public static final String ADMIN_DN = "cn=padmin,ou=users,o=utopia";
	public static final String ADMIN_PW = "n0v3ll";

	public static void main(String[] args) throws IOException {
		String authString = ADMIN_DN   ":"   ADMIN_PW;
		String b64encodedAuthString = new sun.misc.BASE64Encoder().encode(authString.getBytes());
		URL restURL = new URL(SERVICE_URL );

		System.out.println("calling url: "   restURL.toString());
		HttpURLConnection identitiesURL = (HttpURLConnection) restURL.openConnection();
		identitiesURL.setRequestMethod("GET");
		identitiesURL.setRequestProperty("RESTAuthorization", b64encodedAuthString);
		identitiesURL.connect();
		System.out.println("response code: "   identitiesURL.getResponseCode());

		if (identitiesURL.getResponseCode() == 200) {
			identitiesURL.getContentLength();
			InputStream in = identitiesURL.getInputStream();
			BufferedReader reader = new BufferedReader(new InputStreamReader(in));
			String text = reader.readLine();
			System.out.println(text);
		}
	identitiesURL.disconnect();
	}
}

Example Results

[{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=zz,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"003c080378ae7e4341af003c080378ae","Link":"/RIS/v1/identities/003c080378ae7e4341af003c080378ae","DN"
:"cn=zz,ou=users,o=utopia","FirstName":["zz"],"LastName":["zz"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entitydefinition-
key=user&entity-key=cn=zz,ou=users,o=utopia&attribute-key=UserPhoto","Title":[""],"TelephoneNumber":
[],"Department":[""],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=zort,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"0ebb55f07f0e9f4a8c920ebb55f07f0e","Link":"/RIS/v1/identities/0ebb55f07f0e9f4a8c920ebb55f07f0e","DN"
:"cn=zort,ou=users,o=utopia","FirstName":["jason"],"LastName":
["jason"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=zort,ou=users,o=utopia&attribute-key=UserPhoto","Title":[""],"TelephoneNumber":[],"Department":[""],"Location":
[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=cnano,ou
=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"afa0c14227d675406f87afa0c14227d6","Link":"/RIS/v1/identities/afa0c14227d675406f87afa0c14227d6","DN"
:"cn=cnano,ou=users,o=utopia","FirstName":["Chip"],"LastName":["Nano"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?
entity-definition-key=user&entity-key=cn=cnano,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Chief Information
Officer"],"TelephoneNumber":[],"Department":["Information Services"],"Location":[],"Email":[]},{"Managers":[],"Groups":
[],"Links":[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=rogueadmin,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"49a5f16b65bbf1442cb649a5f16b65bb","Link":"/RIS/v1/identities/49a5f16b65bbf1442cb649a5f16b65bb","DN"
:"cn=rogueadmin,ou=users,o=utopia","FirstName":["rogue"],"LastName":
["admin"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=rogueadmin,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Rogue Administrator"],"TelephoneNumber":
[],"Department":[""],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=tina,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"30373f5f521fdc0180b0ba0003000000","Link":"/RIS/v1/identities/30373f5f521fdc0180b0ba0003000000","DN"
:"cn=tina,ou=users,o=utopia","FirstName":["Tina"],"LastName":
["Novell"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=tina,ou=users,o=utopia&attribute-key=UserPhoto","Title":[""],"TelephoneNumber":[],"Department":[""],"Location":
[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=bob,ou
=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"70d12855521fdc0180e07a0003000000","Link":"/RIS/v1/identities/70d12855521fdc0180e07a0003000000","DN"
:"cn=bob,ou=users,o=utopia","FirstName":["Bob"],"LastName":["Novell"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?
entity-definition-key=user&entity-key=cn=bob,ou=users,o=utopia&attribute-key=UserPhoto","Title":[""],"TelephoneNumber":
[],"Department":[""],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=cblack,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"a0fd234371f2db0180819c0003000000","Link":"/RIS/v1/identities/a0fd234371f2db0180819c0003000000","DN"
:"cn=cblack,ou=users,o=utopia","FirstName":["Chris"],"LastName":
["Black"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=cblack,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Sales Director, Black"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=jwest,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"e0d1744271f2db0180819c0003000000","Link":"/RIS/v1/identities/e0d1744271f2db0180819c0003000000","DN"
:"cn=jwest,ou=users,o=utopia","FirstName":["Jay"],"LastName":["West"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?
entity-definition-key=user&entity-key=cn=jwest,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Sales Director,
West"],"TelephoneNumber":[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=bbender,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"50eda34171f2db0180819c0003000000","Link":"/RIS/v1/identities/50eda34171f2db0180819c0003000000","DN"
:"cn=bbender,ou=users,o=utopia","FirstName":["Bill"],"LastName":
["Bender"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=bbender,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Technical Account Manager"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=asmith,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"7055f94071f2db0180819c0003000000","Link":"/RIS/v1/identities/7055f94071f2db0180819c0003000000","DN"
:"cn=asmith,ou=users,o=utopia","FirstName":["April"],"LastName":
["Smith"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=asmith,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Account Exectuive"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=ksmith,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"10aa324071f2db0180819c0003000000","Link":"/RIS/v1/identities/10aa324071f2db0180819c0003000000","DN"
:"cn=ksmith,ou=users,o=utopia","FirstName":["Kate"],"LastName":
["Smith"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=ksmith,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Executive Sales Representative"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=ssouth,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"60ff743f71f2db0180819c0003000000","Link":"/RIS/v1/identities/60ff743f71f2db0180819c0003000000","DN"
:"cn=ssouth,ou=users,o=utopia","FirstName":["Sally"],"LastName":
["South"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=ssouth,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Sales Director, Southeast"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=jbrown,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"602c353e71f2db0180819c0003000000","Link":"/RIS/v1/identities/602c353e71f2db0180819c0003000000","DN"
:"cn=jbrown,ou=users,o=utopia","FirstName":["Jane"],"LastName":
["Brown"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=jbrown,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Technical Account Manager"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=kcarson,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"10b6423d71f2db0180819c0003000000","Link":"/RIS/v1/identities/10b6423d71f2db0180819c0003000000","DN"
:"cn=kcarson,ou=users,o=utopia","FirstName":["Ken"],"LastName":
["Carson"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=kcarson,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Account Executive"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=bjenner,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"f05a5f3c71f2db0180819c0003000000","Link":"/RIS/v1/identities/f05a5f3c71f2db0180819c0003000000","DN"
:"cn=bjenner,ou=users,o=utopia","FirstName":["Bob"],"LastName":
["Jenner"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=bjenner,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Account Executive"],"TelephoneNumber":
[],"Department":["Marketing"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=bjones,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"90209b3b71f2db0180819c0003000000","Link":"/RIS/v1/identities/90209b3b71f2db0180819c0003000000","DN"
:"cn=bjones,ou=users,o=utopia","FirstName":["Brad"],"LastName":
["Jones"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=bjones,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Account Executive"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=kchang,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"e0b8bd3a71f2db0180819c0003000000","Link":"/RIS/v1/identities/e0b8bd3a71f2db0180819c0003000000","DN"
:"cn=kchang,ou=users,o=utopia","FirstName":["Kevin"],"LastName":
["Chang"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=kchang,ou=users,o=utopia&attribute-ke
y=UserPhoto","Title":["Account Executive"],"TelephoneNumber":[],"Department":["Sales"],"Location":[],"Email":[]},
{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=nnorth,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"40982e3a71f2db0180819c0003000000","Link":"/RIS/v1/identities/40982e3a71f2db0180819c0003000000","DN"
:"cn=nnorth,ou=users,o=utopia","FirstName":["Ned"],"LastName":
["North"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=nnorth,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Director, Northeast Sales"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=bburke,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"d0be7d3971f2db0180819c0003000000","Link":"/RIS/v1/identities/d0be7d3971f2db0180819c0003000000","DN"
:"cn=bburke,ou=users,o=utopia","FirstName":["Bill"],"LastName":
["Burke"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=bburke,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Sales Manager, Central"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=ccentral,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"9096c33871f2db0180819c0003000000","Link":"/RIS/v1/identities/9096c33871f2db0180819c0003000000","DN"
:"cn=ccentral,ou=users,o=utopia","FirstName":["Cal"],"LastName":
["Central"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=ccentral,ou=users,o=utopia&attribute-key=UserPhoto","Title":["VP, North American Sales"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=kkeller,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"4083ff3771f2db0180819c0003000000","Link":"/RIS/v1/identities/4083ff3771f2db0180819c0003000000","DN"
:"cn=kkeller,ou=users,o=utopia","FirstName":["Kip"],"LastName":
["Keller"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=kkeller,ou=users,o=utopia&attribute-key=UserPhoto","Title":["VP, North American Sales"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=achung,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"e023563771f2db0180819c0003000000","Link":"/RIS/v1/identities/e023563771f2db0180819c0003000000","DN"
:"cn=achung,ou=users,o=utopia","FirstName":["Angie"],"LastName":
["Chung"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=achung,ou=users,o=utopia&attribute-key=UserPhoto","Title":["VP, AsiaPAC Sales"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=eeuro,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"a0986d3671f2db0180819c0003000000","Link":"/RIS/v1/identities/a0986d3671f2db0180819c0003000000","DN"
:"cn=eeuro,ou=users,o=utopia","FirstName":["Ernie"],"LastName":
["Euro"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=eeuro,ou=users,o=utopia&attribute-key=UserPhoto","Title":["VP, European Sales"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=rcastro,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"905da03571f2db0180819c0003000000","Link":"/RIS/v1/identities/905da03571f2db0180819c0003000000","DN"
:"cn=rcastro,ou=users,o=utopia","FirstName":["Ricardo"],"LastName":
["Castro"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=rcastro,ou=users,o=utopia&attribute-key=UserPhoto","Title":["VP, Latin American Sales"],"TelephoneNumber":
[],"Department":["Sales"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=kkilpatrick,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"302c193571f2db0180819c0003000000","Link":"/RIS/v1/identities/302c193571f2db0180819c0003000000","DN"
:"cn=kkilpatrick,ou=users,o=utopia","FirstName":["Kelly"],"LastName":
["Kilpatrick"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=kkilpatrick,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Sr. VP, Worldwide Sales"],"TelephoneNumber":
[],"Department":["Management"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=ablake,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"f099463471f2db0180819c0003000000","Link":"/RIS/v1/identities/f099463471f2db0180819c0003000000","DN"
:"cn=ablake,ou=users,o=utopia","FirstName":["Allison"],"LastName":
["Blake"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=ablake,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Creative Assistant"],"TelephoneNumber":
[],"Department":["Marketing"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=kchester,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"c04c6f3371f2db0180819c0003000000","Link":"/RIS/v1/identities/c04c6f3371f2db0180819c0003000000","DN"
:"cn=kchester,ou=users,o=utopia","FirstName":["Kevin"],"LastName":
["Chester"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=kchester,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Marketing Assistant"],"TelephoneNumber":
[],"Department":["Marketing"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=mmackenzie,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"9049623271f2db0180819c0003000000","Link":"/RIS/v1/identities/9049623271f2db0180819c0003000000","DN"
:"cn=mmackenzie,ou=users,o=utopia","FirstName":["Margo"],"LastName":
["MacKenzie"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=mmackenzie,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Director, Marketing"],"TelephoneNumber":
[],"Department":["Marketing"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=tswan,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"e0df313171f2db0180819c0003000000","Link":"/RIS/v1/identities/e0df313171f2db0180819c0003000000","DN"
:"cn=tswan,ou=users,o=utopia","FirstName":["Timothy"],"LastName":
["Swan"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=tswan,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Director, Marketing, Vice
President"],"TelephoneNumber":[],"Department":["Management"],"Location":[],"Email":[]},{"Managers":[],"Groups":
[],"Links":[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=jkelley,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"e0a67f3071f2db0180819c0003000000","Link":"/RIS/v1/identities/e0a67f3071f2db0180819c0003000000","DN"
:"cn=jkelley,ou=users,o=utopia","FirstName":["Josh"],"LastName":
["Kelley"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=jkelley,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Controller"],"TelephoneNumber":[],"Department":
["Accounting"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=fstats,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"0044e12f71f2db0180819c0003000000","Link":"/RIS/v1/identities/0044e12f71f2db0180819c0003000000","DN"
:"cn=fstats,ou=users,o=utopia","FirstName":["Fred"],"LastName":
["Stats"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=fstats,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Controller"],"TelephoneNumber":[],"Department":
["Accounting"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=jsmith,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"f02df92e71f2db0180819c0003000000","Link":"/RIS/v1/identities/f02df92e71f2db0180819c0003000000","DN"
:"cn=jsmith,ou=users,o=utopia","FirstName":["Jane"],"LastName":
["Smith"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=jsmith,ou=users,o=utopia&attribute-key=UserPhoto","Title":["HR, Representative"],"TelephoneNumber":
[],"Department":["Human Resources"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=rresource,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"00b7c52d71f2db0180819c0003000000","Link":"/RIS/v1/identities/00b7c52d71f2db0180819c0003000000","DN"
:"cn=rresource,ou=users,o=utopia","FirstName":["Renee"],"LastName":
["Resource"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=rresource,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Director, Human Resource"],"TelephoneNumber":
[],"Department":["Management"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=apalani,ou=users,o=utopia","Type":"wf/workitems","V
alue":"Workflow
Workitems"}],"GUID":"101b3c2a71f2db0180819c0003000000","Link":"/RIS/v1/identities/101b3c2a71f2db0180819c0003000000","DN"
:"cn=apalani,ou=users,o=utopia","FirstName":["Anthony"],"LastName":
["Palani"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=apalani,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Chief Operating Officer"],"TelephoneNumber":
[],"Department":["Management"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=bbrown,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"c0c8cc2771f2db0180819c0003000000","Link":"/RIS/v1/identities/c0c8cc2771f2db0180819c0003000000","DN"
:"cn=bbrown,ou=users,o=utopia","FirstName":["Bill"],"LastName":
["Brown"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=bbrown,ou=users,o=utopia&attribute-key=UserPhoto","Title":["System Administrator"],"TelephoneNumber":
[],"Department":["Information Services"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=aspencer,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"8052a22671f2db0180819c0003000000","Link":"/RIS/v1/identities/8052a22671f2db0180819c0003000000","DN"
:"cn=aspencer,ou=users,o=utopia","FirstName":["Abby"],"LastName":
["Spencer"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=aspencer,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Sr. System Administrator"],"TelephoneNumber":
[],"Department":["Information Services"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=tmellon,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"d0c38c2571f2db0180819c0003000000","Link":"/RIS/v1/identities/d0c38c2571f2db0180819c0003000000","DN"
:"cn=tmellon,ou=users,o=utopia","FirstName":["Terry"],"LastName":
["Mellon"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=tmellon,ou=users,o=utopia&attribute-key=UserPhoto","Title":["VP, Information Systems"],"TelephoneNumber":
[],"Department":["Information Services"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=jmiller,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"103bc62071f2db0180819c0003000000","Link":"/RIS/v1/identities/103bc62071f2db0180819c0003000000","DN"
:"cn=jmiller,ou=users,o=utopia","FirstName":["Jack"],"LastName":
["Miller"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=jmiller,ou=users,o=utopia&attribute-key=UserPhoto","Title":["President, CEO"],"TelephoneNumber":[],"Department":
["Management"],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?
filter=Addressee=cn=pldapguest,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"20541152aadcdb018020a40003000000","Link":"/RIS/v1/identities/20541152aadcdb018020a40003000000","DN"
:"cn=pldapguest,ou=users,o=utopia","FirstName":["LDAP"],"LastName":
["Guest"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=pldapguest,ou=users,o=utopia&attribute-key=UserPhoto","Title":[""],"TelephoneNumber":[],"Department":
[""],"Location":[],"Email":[]},{"Managers":[],"Groups":[],"Links":[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn
=padmin,ou=users,o=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"604faf0faadcdb0180c0440003000000","Link":"/RIS/v1/identities/604faf0faadcdb0180c0440003000000","DN"
:"cn=padmin,ou=users,o=utopia","FirstName":["Portal"],"LastName":
["Admin"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=padmin,ou=users,o=utopia&attribute-key=UserPhoto","Title":[""],"TelephoneNumber":[],"Department":[""],"Location":
[],"Email":[]}]

3.2.2 Read Identity

The RIS /identities REST endpoint also allows listing an individual user's information. This example uses the GUID and URL information discovered in the previous API.

Example Java Code

The example java code for this REST service is as follows:

package client.rest.identities;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class ReadIdentity {
	public static final String SERVICE_URL = "http://172.17.2.91:8080/RIS/v1/identities";

	public static final String ADMIN_DN = "cn=padmin,ou=users,o=utopia";
	public static final String ADMIN_PW = "n0v3ll";

	public static final String IDENTITY_GUID = "00b7c52d71f2db0180819c0003000000";

	public static void main(String[] args) throws IOException {
		String authString = ADMIN_DN   ":"   ADMIN_PW;
		String b64encodedAuthString = new sun.misc.BASE64Encoder().encode(authString.getBytes());
		URL restURL = new URL(SERVICE_URL   "/"   IDENTITY_GUID);

		System.out.println("calling url: "   restURL.toString());
		HttpURLConnection identitiesURL = (HttpURLConnection) restURL.openConnection();
		identitiesURL.setRequestMethod("GET");
		identitiesURL.setRequestProperty("RESTAuthorization", b64encodedAuthString);
		identitiesURL.connect();

		System.out.println("response code: "   identitiesURL.getResponseCode());

		if (identitiesURL.getResponseCode() == 200) {
			identitiesURL.getContentLength();
			InputStream in = identitiesURL.getInputStream();
			BufferedReader reader = new BufferedReader(new InputStreamReader(in));
			String text = reader.readLine();
			System.out.println(text);
		}
		identitiesURL.disconnect();
	}
}

Example Results

{"Managers":
[{"DN":"cn=apalani,ou=users,o=utopia","GUID":"101b3c2a71f2db0180819c0003000000","Link":"/RIS/v1/identities/101b3c2a71f2d
b0180819c0003000000","Value":"cn=apalani,ou=users,o=utopia"}],"Groups":[{"DN":"","Link":"","Value":""}],"Links":
[{"Link":"/RIS/v1/wf/workitems?filter=Addressee=cn=rresource,ou=users,o
=utopia","Type":"wf/workitems","Value":"Workflow
Workitems"}],"GUID":"00b7c52d71f2db0180819c0003000000","Link":"/RIS/v1/identities/00b7c52d71f2db0180819c0003000000","DN"
:"cn=rresource,ou=users,o=utopia","FirstName":["Renee"],"LastName":
["Resource"],"Photo":"http://172.17.2.91:8080/IDM/vdataImages?entity-definition-key=user&entitykey=
cn=rresource,ou=users,o=utopia&attribute-key=UserPhoto","Title":["Director, Human Resource"],"TelephoneNumber":
["801-802-0007"],"Department":["Management"],"Location":["NYC"],"Email":["rresource@ad.ism.utopia.novell.com"]}

The returned results are JSON encoded.

4 Glossary of Terms

Term

Meaning

DN

Distinguished Name. The fully qualified name of an LDAP entry

LDAP

Lightweight Directory Access Protocol. A communication protocol for accessing eDirectory.

PRD

Provisioning Request Definition - A workflow process

RBPM

Novell Role s Based Provisioning Module