26.1 About the Provisioning Web Service

The identity applications includes a workflow system that executes approval flows. A workflow process is based on a provisioning request definition, which is an XML document stored in the Identity Vault. The provisioning request definition describes an arbitrary topology using activities and links. For example, a provisioning request to grant an entitlement might have a workflow that collects approvals from relevant users and writes the entitlement to the directory.

To support access by third-party software applications, the provisioning workflow system includes a Web service endpoint. The endpoint offers all provisioning functionality (for example, allowing SOAP clients to start a new approval flow, or list currently executing flows). The Web service is built using the NetIQ Web Service SDK (WSSDK), which supports the WS-I Basic Profile, thus guaranteeing interoperability with other standards based SOAP implementations.

This Appendix describes the provisioning Web service in detail and shows how to access it using the Web or by writing a Java or C# client. We provide an overview of the operations in the SOAP endpoint and describe how to use the Web interface. We show how to develop a Java client using the SOAP toolkit included with Identity Manager provisioning, followed by how to write a C# client using Mono. The sample source code a the Java client and associated ANT build file is provided.

26.1.1 Provisioning Web Service Overview

Identity Manager is composed of two main systems: the Identity Vault and the workflow application. The Identity Vault is capable of connecting to a large number of different systems such as databases, financial systems, and other enterprise applications, and keep these systems synchronized. The rules for synchronizing the remote systems can be very complex and the Identity Vault engine supports a sophisticated scripting language for expressing the rules.

The workflow application is composed of several subsystems. The identity applications provides a user-interface for workflows. The identity applications is a Web application for requesting and managing approval flows. The Web application runs in a portal, which also includes administration portlets. The workflow application contains a security layer, a directory abstraction layer and a logging subsystem, which can send log events to NetIQ Sentinel. The workflow subsystem is responsible for executing approval flows. The identity applications runs on a Tomcat application server and uses a database (for example, Oracle) for persistence.

The Web service for the workflow system is only used by the User Application driver, which is capable of listening to certain events emitted by the Identity Vault engine and convert these events into an appropriate SOAP message. For example, when a specific attribute in the Identity Vault changes, the Identity Vault engine emits an event, which the identity applications picks up from the subscriber channel. The User Application driver then sends a SOAP message to the provisioning Web service to start a new approval flow.

26.1.2 Removing Administrator Credential Restrictions

By default, the requirement for invoking the public interfaces for the SOAP services is that the HTTP session logged in user must have administrator credentials. The Provisioning and Directory Services require Provisioning Administrator credentials. The Role Service and Resource Service require Role Administrator and Resource Administrator credentials respectively. The restrictions can be removed to allow a session with a logged in user who does not have administrator credentials to invoke the methods for the services by changing the configuration settings for the service. The details for changing the Provisioning Service follow. Instructions for the other SOAP services are provided with the documentation for these services.

To remove the administrator credential restriction for the Provisioning Service:

  1. Open the ism-configuration.properties file, located by default in the /netiq/idm/apps/tomcat/conf directory.

  2. Change WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly to false.

  3. Save and close the file.

These are the methods that can be invoked by users without Provisioning Administrator credentials if the WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly property is set to false:

  • getAllProvisioningRequests(String)

  • getDataItems(String workId)

  • getDefinitionByID(String definitionID, String recipient)

  • getProvisioningCategories()

  • getProvisioningRequests(String recipient, String category, String operation)

  • getWork(String workId)

  • getWorkEntries(T_WorkEntryQuery query, int maxRecords)

  • start(String processId, String recipient, DataItemArray items)

  • startAsProxy(String processId, String recipient, DataItemArray items, String proxyUser)

  • startAsProxyWithDigitalSignature(String processId, String recipient, DataItemArray items, String digitalSignature, SignaturePropertyArray digitalSignaturePropertyArray, String proxyUser)

  • startWithCorrelationId(String processId, String recipient, DataItemArray items, String digitalSignature, SignaturePropertyArray digitalSignaturePropertyArray, String proxyUser, String correlationId)

  • startWithDigitalSignature(String processId, String recipient, DataItemArray items, String digitalSignature, SignaturePropertyArray digitalSignaturePropertyArray)

All other methods for this service always require Provisioning Administrator credentials independent of whether the WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly property is set to false.

26.1.3 Provisioning Web Service Method Categories

The methods provided by the provisioning Web service endpoint are divided into six categories:

Table 26-1 Provisioning Web Service Operation Categories

Category

Description

Comments

Methods for retrieving comments and for adding a comment to a pending user activity

Configuration

Methods for getting and setting configuration parameters for the workflow system (for example, timeouts, thread pool settings).

Miscellaneous

Several unrelated methods (for example, for getting a JPG with a provisioning request's topology, for getting the XML definition of a provisioning request, and for getting the XML for the request form).

Processes

Methods for getting information about running and completed workflow processes.

Provisioning Requests

Methods for working with provisioning requests (for example, listing available provisioning requests, listing provisioning categories)

Work Entries

Methods for retrieving and manipulating work entries (items awaiting approval).

The methods provided by the provisioning Web service are described in detail in Section 26.0, Provisioning Web Service.