Sun Identity Manager 8.1 Web Services

Developing SPML Applications

After configuring the server, your SPML application requires a mechanism for sending SPML messages and receiving SPML responses. For JavaTM applications, use the OpenSPML Toolkit to configure this mechanism.


Note –

For optimal performance when you are working with the Identity Manager Web Service Interfaces, use the OpenSPML Toolkit that is co-packaged with Identity Manager.

Using the openspml.jar file from the http://www.openspml.org/ web site might cause memory leaks.


The OpenSPML Toolkit provides the following components:

The following table describes the most important classes provided by the toolkit. Each request type has a corresponding class. Consult the JavadocTM tool distributed with the toolkit for complete information.

Table 1–3 Classes Provided by the OpenSPML Toolkit

Class 

Description  

AddRequest

Constructs a message to request creation of a new object. You define the object type by passing an objectclass attribute. Other passed attributes must adhere to the schema associated with the object class. SPML does not yet define standard schemas, but you can configure Identity Manager to support almost all schemas.

BatchRequest

Constructs a message that can contain more than one SPML request. 

CancelRequest

Constructs a message to cancel a request that was formerly executed asynchronously. 

DeleteRequest

Constructs a message to request the deletion of an object. 

ModifyRequest

Constructs a message to request modification of an object. Include only those attributes that you want to modify in the request. Attributes omitted from the request will retain their current values. 

SchemaRequest

Constructs a message to request information about SPML object classes supported by the server. 

SearchRequest

Constructs a message to request object attributes that match certain criteria. 

SpmlClient

Presents a simple interface for sending and receiving SPML messages. 

SpmlResponse

Includes the base class for objects representing response messages sent back from the server. Each request class has a corresponding response class, for example, AddResponse and ModifyResponse.

StatusRequest

Constructs a message to request the status of a request that was formerly executed asynchronously. 

The Service Provider REF Kit contains an SpmlUsage.java file that demonstrates how to use the Service Provider SPML interface. This REF Kit also contains an ant script that compiles the SpmlUsage class.

Usage:

java [ -Dtrace=true ] com.sun.idm.idmx.example.SpmlUsage [ URL ]

where URL points to the Service Provider SPML interface. The URL defaults to

http://host:port/idm/spespml

where

You can enable trace for Service Provider to print Service Provider SPML messages to standard output.

ExtendedRequest Examples

The following table describes the different ExtendedRequest classes that you can use to send messages to and receive messages from the client.

Table 1–4 ExtendedRequest Classes for Sending and Receiving Messages

ExtendedRequest Class

Description 

changeUserPassword

Constructs a message to request a user password change. 

deleteUser

Constructs a message to request a user deletion. 

disableUser

Constructs a message to request the disabling of a user. 

enableUser

Constructs a message to request the enabling of a user. 

launchProcess

Constructs a message to request the launch of a process. 

listResourceobjects

Constructs a message to request the name of a resource object in the Identity Manager repository, and the type of object supported by that resource. The request returns a list of names. 

resetUserPassword

Constructs a message to request the reset of a user password. 

runForm

Allows you to create custom SPML requests that return information obtained by calling the Identity Manager Session API. 

The server code converts each ExtendedRequest into a view operation.

The following examples illustrate the typical formats for an ExtendedRequest and its classes:

ExtendedRequest Example

The following example shows the typical format for an ExtendedRequest.


Example 1–5 ExtendedRequest Format


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("changeUserPassword");
req.setAttribute("accountId", "exampleuser");
req.setAttribute("password", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);

Most SPML ExtendedRequest requests accept the following arguments:

deleteUser Example

The following example shows the typical format for a deleteUser request (View -> Deprovision view).


Note –

If you customize this request, there might be side effects.



Example 1–6 deleteUser Request


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("deleteUser");
req.setAttribute("accountId","exampleuser");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);

disableUser Example

The following example shows the typical format for a disableUser request (View -> Disable view).


Example 1–7 disableUser Request


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("disableUser");
req.setAttribute("accountId","exampleuser");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);

enableUser Example

The following example shows the typical format for an enableUser request (View -> Enable view).


Example 1–8 enableUser Request


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("enableUser");
req.setAttribute("accountId","exampleuser");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);

launchProcess Example

The following example shows the typical format for a launchProcess request (View -> Process view).


Example 1–9 launchProcess Request


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("launchProcess");
req.setAttribute("process", "my custom process");
req.setAttribute("taskName", "my task instance");
ExtendedResponse res = (ExtendedResponse) client.send(req);

where:

The remaining attributes are arbitrary and they are passed into the task.

listResourceObjects Example

The following example shows the typical format for a listResourceObjects request.


Example 1–10 listResourceObjects Request


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("listResourceObjects");
req.setAttribute("resource", "LDAP");
req.setAttribute("type", "group");
ExtendedResponse res = (ExtendedResponse) client.send(req);

where:

resetUserPassword Example

The following example shows the typical format for a resetUserPassword request (View -> Reset User Password view).


Example 1–11 resetUserPassword Request


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("resetUserPassword");
req.setAttribute("accountId","exampleuser");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);

runForm Example

The following example shows the typical format for a runForm request.


Example 1–12 runForm Request


ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("runForm");
req.setAttribute("form", "SPML Get Object Names");
ExtendedResponse res = (ExtendedResponse) client.send(req);

where form is the name of a configuration object containing a form.

Example Query Form

The following example shows a form that is used to run queries and return a list of the Role, Resource, and Organization names accessible to the current user.


Example 1–13 Query Form

<Configuration name='SPML Get Object Names'>
  <Extension>
    <Form>
      <Field name='roles'>
        <Derivation>
          <invoke class='com.waveset.ui.FormUtil'>
            <ref>display.session</ref>
            <s>Role</s>
          </invoke>
        </Derivation>
      </Field>
      <Field name='resources'>
        <Derivation>
          <invoke class='com.waveset.ui.FormUtil'>
            <ref>display.session</ref>
            <s>Resource</s>
          </invoke>
        </Derivation>
      </Field>
      <Field name='organizations'>
        <Derivation>
          <invoke class='com.waveset.ui.FormUtil'>
            <ref>display.session</ref>
            <s>ObjectGroup</s>
          </invoke>
        </Derivation>
      </Field>
    </Form>
  </Extension>
</Configuration>

You use the runForm request to create custom SPML requests that return information obtained by calling the Identity Manager Session API. For example, when configuring a user interface for editing user accounts, you might want to provide a selector that displays the names of the organizations, roles, resources, and policies that can be assigned to a user.

You can configure the SPML interface to expose these objects as SPML object classes and use searchRequest to query for their names. However, this configuration requires four searchRequest requests to gather the information. To reduce the number of SPML requests, encode the queries in a form by using a single runForm request to perform the queries and return the combined results.

Using Trace With SPML

SPML includes options for turning on trace output so you can log Identity Manager SPML traffic and diagnose problems.

For more information about tracing SPML, see Chapter 5, Tracing and Troubleshooting, in Sun Identity Manager 8.1 System Administrator’s Guide.