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.
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:
Java class model for SPML messages
Classes to send and receive messages on the client
Classes to receive and process requests on the server
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
host is the machine on which you are running Identity Manager Service Provider.
port is the number of the TCP port on which the server is listening.
You can enable trace for Service Provider to print Service Provider SPML messages to standard output.
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:
The following example shows the typical format for an ExtendedRequest.
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:
accountId – Identifies the Identity Manager user name.
accounts – Presents resource names in a comma-delimited list.
If you pass an accounts argument, the specified SPML operation only updates the specified resources. You must include the Lighthouse attribute in a non-null accounts list if you want to update the Identity Manager user in addition to specific resource accounts.
If you do not pass an accounts argument, the operation updates all resource accounts linked to the user, including the Identity Manager user account.
The following example shows the typical format for a deleteUser request (View -> Deprovision view).
If you customize this request, there might be side effects.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("deleteUser"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.send(req); |
The following example shows the typical format for a disableUser request (View -> Disable view).
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("disableUser"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.send(req); |
The following example shows the typical format for an enableUser request (View -> Enable view).
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("enableUser"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.send(req); |
The following example shows the typical format for a launchProcess request (View -> Process view).
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:
launchProcess – Starts the custom processes.
process – Name of the TaskDefinition object in the Identity Manager repository to start.
taskName – Name of the task needed to start the workflow.
The task instance object holds the runtime state of the process.
The remaining attributes are arbitrary and they are passed into the task.
The following example shows the typical format for a listResourceObjects request.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("listResourceObjects"); req.setAttribute("resource", "LDAP"); req.setAttribute("type", "group"); ExtendedResponse res = (ExtendedResponse) client.send(req); |
where:
resource – Specifies the name of a resource object in the Identity Manager repository.
type – Specifies the object type supported by that resource.
The following example shows the typical format for a resetUserPassword request (View -> Reset User Password view).
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("resetUserPassword"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.send(req); |
The following example shows the typical format for a 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.
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.
<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.
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.