|
| |
| Sun Java[TM] System Identity Manager 7.1 Deployment Tools | |
Chapter 7
Using SPML 1.0 with Identity Manager Web ServicesThis chapter describes SPML 1.0 support in Identity Manager and Identity Manager Service Provider Edition; including which features are supported and why, how to configure SPML 1.0 support, and how to extend support in the field.
The information is organized as follows:
Note
This chapter focuses exclusively on SPML 1.0.
Unless noted otherwise, all references to SPML in this chapter indicate the 1.0 version.You will also find concepts discussed here useful when you read about SPML 2.0 in Chapter 8, "Using SPML 2.0 with Identity Manager Web Services."
Who Should Read This ChapterApplication developers and developers who are responsible for integrating Identity Manager can use the SPML 1.0 classes described in this chapter to format service provisioning request messages and to parse response messages.
Working with Identity Manager Web Service InterfacesIdentity Manager Web services are accessed using SOAP messages for HTTP. Identity Manager supports both versions of the OASIS standard for communication with provisioning systems; the Service Provisioning Markup Language (SPML) — versions1.0 and 2.0.
SPML 1.0 is an OASIS standard for providing an open interface to service provisioning activities. SPML 1.0 also has the support of independent software vendors.
Note
For best performance when working with the Identity Manager Web Interfaces, use the OpenSPML Toolkit that is bundled with Identity Manager. Using the openspml.jar file from the http://www.openspml.org/ website might cause memory leaks.
Note
The SPE REF Kit provides an SpmlUsage.java file that demonstrates how to use the SPE SPML interface.
Configuring SPMLTo expose the SPML interface, you must properly configure the Identity Manager server. You must install and modify specific repository objects and edit the waveset.properties file.
Installing and Modifying Repository Objects
Table 7-1 describes the repository objects you must install and modify to configure SPML for Identity Manager.
Identity Manager provides a sample set of SPML configuration objects in the sample/spml.xml file. You must import this file manually because it is not imported by default when the repository is initialized.
The sample configuration defines a class named person that tracks the evolving standard schema defined by the SPML working group. Though the working group has not yet published a standard user schema, it will almost certainly be based upon the popular LDAP inetorgperson schema.
Editing the waveset.properties File
Table 7-2 describes three optional entries in the waveset.properties file that you can use to control how SPML requests are authorized.
Editing the soap.epassword and soap.password Properties
The user specified with soap.username is referred to as the proxy user. If you want to define a proxy user, you must set soap.username, but only one of the two password entries must be set. Using soap.password is the simplest, but this exposes a clear text password in the properties file. Using soap.epassword is more secure, but requires extra steps to generate the encrypted password.
Establishing a proxy user is convenient for clients because they are not required to authenticate to use the Web service. This is a common configuration for portal environments where the Identity Manager server is accessed only by another application that itself handles authentication of users.
The SPML standard does not specify how authentication and authorization are performed. There are several related Web standards for authentication but these will not be in widespread use for some time. Probably, the most common near-term approach for authentication will be to rely on the use of SSL between applications and the server. How SSL is configured cannot be dictated by Identity Manager.
In cases where neither a proxy user or SSL can be used, Identity Manager does support a vendor-specific extension to SPML that allows the client to log in and maintain a session token that is used to authenticate subsequent requests. The easiest way to do this is to use the LighthouseClient class, an extension of the SpmlClient class that provides support for specifying credentials, performing a login request, and passing a session token in all SPML requests.
Obtaining an Encrypted Password
One way to obtain an encrypted password is to use the encrypt command in the Identity Manager console. Another way is to view the XML for the proxy user in the Debug pages or from the console. Look in the WSUser element for the value of the password attribute. You can use this value as the value for the soap.epassword property.
Editing Configuration Objects
Applications require a mechanism to send SPML messages and receive SPML responses.
To configure SPML for Identity Manager, you must work with the following configuration objects:
Editing the Configuration: SPML
The SPML object contains definitions for the SPML schemas you want to expose and information about how those SPML schemas are mapped into Identity Manager views. This information is represented using a GenericObject that is stored as an extension of the Configuration object.
There are two attributes defined in this GenericObject: schemas and classes.
- Schemas: A list of strings, where each string contains the escaped XML for one SPML <schema> element. Because the SPML elements are not defined in waveset.dtd, you cannot directly include them in an Identity Manager XML document. Instead, you must include them as escaped text.
- Classes: A list of objects containing information about the supported SPML classes and how they are mapped onto views. There should be one object on this list for each class defined by the SPML schemas on the schemas list.
The distinction between the two lists can be confusing at first. The information about the schemas list defines what Identity Manager will return in response to an SPML SchemaRequest message. This information can be used by the client to understand which attributes can be included in other messages such as AddRequest. Identity Manager does not care about the contents of the schemas list. This list is simply returned verbatim to the client.
You are not required to define any SPML schemas. Identity Manager works without schemas. If no SPML schema has been defined, Identity Manager returns an empty response when it receives a schema request message. Without a schema, clients must rely on pre-existing knowledge about the supported classes and attributes. While this is often the case, it is still considered good practice to write SPML schemas, so that general purpose tools such as the OpenSPML Browser can be used to build requests.
Default SPML Configuration
Code Example 7-1 shows the default SPML configuration. The text of the SPML schema definitions have been omitted for brevity.
Two classes are defined in this example: the standard person and an Identity Manager extension named request. The following attributes are supported in a class definition:
- name: Identifies the name of the class. This value can correspond to an <ObjectClassDefinition> element in an SPML schema, although this is not required. This name is used as the value of the objectclass attribute in an Add request or Search request.
- type: Defines the Identity Manager view type used to manage instances of this class. This is usually User, but can be any repository type that can be accessed through a view. For information about views, see Sun Java™ System Identity Manager Workflows, Forms, and Views.
- form: Identifies the name of a configuration object containing a form. This form contains the rules for transforming between the external attributes defined by the class and the internal view attributes.
- default: When set to true, indicates that this is the default class for this type only. If you have more than one SPML class implemented on the same type, one should be designated as the default.
- identifier: Each class typically defines one attribute that is considered to be the identity of the object. Where possible, the value of this attribute is used as the name of the corresponding repository object that you create to represent the instance. The identifier attribute in the class definition specifies which attribute represents the identity.
- filter: When an SPML search request is evaluated for a class, you typically include all repository objects associated with that class in that search. This is fine for User objects, but some classes may be implemented using generic types such as TaskDefinition or Configuration, not all of which are considered instances of the SPML class.
To prevent unwanted objects from being included in the search, you can specify the filter attribute. The value is expected to be an <AttributeCondition> element or a <List> of <AttributeCondition> elements. Because custom classes are almost always made for the User type, using a filter is uncommon. The default configuration uses them to expose a subset of the TaskInstance objects that are known to have been created to handle asynchronous SPML requests.
Default Schemas
The schemas attribute contains a list of strings that contain the escaped XML for an SPML <schema> element. If you examine the spml.xml file, you will notice the schema elements are surrounded with a CDATA marked section, which is more convenient for escaping long strings of XML. When this is normalized, it will be converted into a string containing < character entities.
The default configuration includes two schemas:
Editing the Configuration: SPMLPerson Object
Each class defined in Configuration:SPML typically has an associated form object that contains the rules for transforming between the external attribute model defined by the class and the internal model defined by the associated view.
The standard person class references the following form (Code Example 7-2):
Code Example 7-2 Standard Person Class References Form
<Configuration name='SPMLPerson'>
<Extension>
<Form><Field name='cn'>
<Derivation><ref>global.fullname</ref></Derivation>
</Field>
<Field name='global.fullname'>
<Expansion><ref>cn</ref></Expansion>
</Field><Field name='email'>
<Derivation><ref>global.email</ref></Derivation>
</Field>
<Field name='global.email'>
<Expansion><ref>email</ref></Expansion>
</Field><Field name='description'>
<Derivation>
<ref>accounts[Lighthouse].description</ref>
</Derivation>
</Field>
<Field name='accounts[Lighthouse].description'>
<Expansion><ref>description</ref></Expansion>
</Field><Field name='password'>
<Derivation><ref>password.password</ref></Derivation>
</Field>
<Field name='password.password'>
<Expansion><ref>password</ref></Expansion>
</Field><Field name='sn'>
<Derivation><ref>global.lastname</ref></Derivation>
</Field>
<Field name='global.lastname'>
<Expansion><ref>sn</ref></Expansion>
</Field><Field name='gn'>
<Derivation><ref>global.firstname</ref></Derivation>
</Field>
<Field name='global.firstname'>
<Expansion><ref>gn</ref></Expansion>
</Field><Field name='telephone'>
<Derivation>
<ref>accounts[Lighthouse].telephone</ref>
</Derivation>
</Field>
<Field name='accounts[Lighthouse].telephone'>
<Expansion><ref>telephone</ref></Expansion>
</Field></Form>
</Extension>
</Configuration>
Note
SPML class forms contain no <Display> elements. These forms are defined only for data transformation, not for interactive editing.
For every attribute in a class definition, there is a pair of field definitions. One field uses a <Derivation> expression to transform the internal view attribute name to the external name. One field uses an <Expansion> expression to transform the external name to the internal name.
The form is processed in such a way that when attributes are returned to the client, only the result of the <Derivation> expressions are included. When attributes are being sent from the client to the server, only the results of the <Expansion> expressions are assimilated back into the view. The effect is similar to the schema map of a Resource definition.
Editing the Configuration: User Extended Attributes Object
Any attributes that you want to use in an SPML search filter must be defined as an extended attribute for Identity Manager users. This causes the value of the attribute to be stored in the Identity Manager repository, even if that value is also stored as a resource account attribute. You should generally try to minimize the number of extended attributes because it increases repository size as well as the chances of consistency problems between attributes stored in Identity Manager and the real value of the attribute stored on a resource. But for an attribute to be used in an Identity Manager query, it must be declared as extended so that the value is always accessible when the repository query indexes are built.
You must define as an extended attribute any attribute that you want to include in the set of summary attributes for the user. You can use summary attributes to optimize searches by avoiding deserialization of the object XML, and instead return only a few of the most important attributes of the user. In the Identity Manager SPML implementation, summary attributes are returned whenever you do not explicitly provide a list of return attributes in the search request.
In the default SPML configuration, the attributes telephone and description from the standard person schema are declared as extended attributes.
Code Example 7-3 telephone and description Declared as Extended Attributes
<Configuration id='#ID#Configuration:UserExtendedAttributes' name='User Extended Attributes'>
<Extension>
<List>
<!-- this is the standard set -->
<String>firstname</String>
<String>lastname</String>
<String>fullname</String>
<!-- these are the SPML extensions -->
<String>description</String>
<String>telephone</String>
</List>
</Extension>
</Configuration>
You can customize the list of attributes according to the needs of your site.
The names you choose for the extended attributes depend on the mappings performed in the class form. Because the default SPMLPerson form maps sn into lastname, the extended attribute must be declared as lastname. Because the form does not transform the name of telephone or description, the extended attribute name comes directly from the SPML schema.
Beyond declaring extended attributes, you must also modify the Configuration:UserUIConfig object to declare which of the attributes are to be queryable (that is, usable in an SPML filter) and which are to be summary attributes (returned by an optimized search result).
Editing the Configuration: UserUIConfig Object
You must declare:
Code Example 7-4 defines the extended attribute telephone as a queryable and summary attribute. It also has declarations for firstname and lastname but those are usually already declared. You can customize these lists according to the needs of your site.
Code Example 7-4 telephone Defined as Queryable and Summary Attribute
<Object>
<Attribute name='add'>
<Object>
<Attribute name='SummaryAttrNames'>
<List>
<!-- these are usually there, but make sure -->
<String>firstname</String>
<String>lastname</String>
<!-- this is an SPML addition -->
<String>telephone</String>
</List>
</Attribute>
<Attribute name='QueryableAttrNames'>
<List>
<!-- these are usually there, but make sure -->
<String>firstname</String>
<String>lastname</String>
<!-- this is an SPML addition -->
<String>telephone</String>
</List>
</Attribute>
</Object>
</Attribute>
</Object>
Editing the TaskDefinition: SPMLRequest Object
The spml.xml file also includes a brief definition for a new system task named SpmlRequest. This task is used to implement asynchronous SPML requests. When the server receives an asynchronous request, a new instance of this task is launched, and the SPML message is passed as an input variable for the task. The repository ID of the task instance is then returned in the SPML response for later status requests.
<TaskDefinition name='SPMLRequest'
executor='com.waveset.rpc.SpmlExecutor'
execMode='asyncImmediate'
resultLimit='86400'>
</TaskDefinition>
You must not change the name of the definition, the name of the executor, or the execution mode. You may, however, want to change the value of resultLimit. When an asynchronous request has completed, the result is typically retained for a period of time so that the client can issue an SPML status request to obtain the results. How long the results should be retained will be site-specific.
If non-negative, resultLimit specifies the time (in seconds) that the system will retain results after a task has completed. The default value for SPMLRequests is typically 3600 seconds, or approximately one hour. Other tasks default to 0 seconds unless the task is changed to another value.
If negative, the request instance will never be removed automatically.
Deployment Descriptor
The Identity Manager deployment descriptor, typically found in the file WEB-INF/web.xml, must contain a declaration for the servlet that receives SOAP messages.
If you are having difficulty contacting the SPML web service, look in the web.xml file for a servlet declaration that looks like Code Example 7-5:
Code Example 7-5 Servlet Declaration
<servlet>
<servlet-name>rpcrouter2</servlet-name>
<display-name>OpenSPML SOAP Router</display-name>
<description>no description</description>
<servlet-class>
org.openspml.server.SOAPRouter
</servlet-class>
<init-param>
<param-name>handlers</param-name>
<param-value>com.waveset.rpc.SimpleRpcHandler</param-value>
</init-param>
<init-param>
<param-name>spmlHandler</param-name>
<param-value>com.waveset.rpc.SpmlHandler</param-value>
</init-param>
<init-param>
<param-name>rpcHandler</param-name>
<param-value>com.waveset.rpc.RemoteSessionHandler</param-value>
</init-param>
</servlet>
This declaration allows you to access the addRequest, modifyRequest, and searchRequest web services through the URL:
http://<host>:<port>/idm/servlet/rpcrouter2
You do not need to define a <servlet-mapping> (although you can). Do not modify the contents of this servlet declaration.
Understanding How Requests Are ProcessedThis section gives a general overview of how SPML requests are processed in Identity Manager.
How an Add Request is Processed
The following steps describe the processing of an Add request.
- An SPML <addRequest> message is received. The request must include a value for the objectclass attribute.
- The server examines the Configuration:SPML object to find the definition for the class. From the class definition, it obtains the associated view type and form name.
- The server calls the Session.createView method to construct a new view for that type.
- The attributes included in the request are processed by the class form. The results of the <Expansion> expressions are assimilated into the view.
- The view is checked in.
How a Modify Request is Processed
The following steps describe how a Modify request is processed:
- An SPML <modifyRequest> message is received. The request can include an optional objectclass attribute. The request must contain an identifier for an existing object. The identifier must include both the repository type and the object name.
- The server calls Session.checkoutView for the existing object.
- The server examines the Configuration:SPML object to find the definition for the class. If an objectclass attribute was passed in the request, that value determines the class. Otherwise, the class marked as the default class for the repository type is used.
- The attributes included in the request are processed by the form that is specified by the class definition. The results of the <Expansion> expressions are assimilated into the view.
- The view is checked in.
How a Search Request is Processed
The following steps describe how a Search request is processed:
- An SPML <searchRequest> message is received. The request can include an optional objectclass attribute.
- The server examines the Configuration:SPML object to find the definition for the class. If an objectclass attribute was passed in the request, that determines the class. Otherwise, the class marked as the default class for the User type is used.
- If the request includes a filter, it is converted to a list of AttributeCondition objects. Because the filter terms are written using the external names, the class form is consulted to convert these into the names of queryable attributes on the repository type.
- The server calls the Session.listObjects method with the repository type and optional conditions.
- The server builds the search response by iterating over each row of the listObjects call applying the following steps.
- If no list of return attributes is specified in the search, only the summary attributes defined for the repository type are returned. The class form is used to convert the internal summary attribute names into the external names.
- If a list of return attributes is specified, and these all correspond to summary attributes, the summary attribute values are returned. The form is again used to convert internal to external names.
- If a return attribute is specified that is not a summary attribute, the server calls Session.getView on this object to materialize the view. The view is processed with the class form and the results of the <Derivation> expressions are captured and returned as the results for that row.
Identity Manager first attempts to satisfy a search request using only the summary attributes defined for a type. The result is a much faster search, especially if no filter is specified and many objects are included in the result. If a view must be instantiated to perform the search, the search will be substantially slower, and should only be performed if a filter is specified that restricts the result to a small number of objects.
If you know the identity of an object and want to retrieve its attributes without writing a filter expression, use the identity as the value of the baseContext in the search request. This will result in a faster search, because Identity Manager can avoid the query and just build the view.
If you do not specify return attributes, only the summary attributes are returned. Consequently, if you want all attributes, you must explicitly include them in the return attribute list. Because requesting all available attributes is a common operation, this is somewhat inconvenient. As an alternative to specifying a complete list of attributes, Identity Manager recognizes a single return attribute named view to indicate that the object view should be fully instantiated and processed with the class form to produce the result.
You can also specify an attribute level (such as accounts[Lighthouse] or accountinfo). If you specify a level, Identity Manager will return all attribute values within the scope of that level for the fully instantiated view.
Launching the SPML BrowserYou can use the OpenSPML Browser application to test the Identity Manager SPML configuration.
To launch the browser from the command line, type:
lh spml
Note
For more information about using the lh spml command, see Sun Java™ System Identity Manager Administration.
Connecting to the Identity Manager ServerTo connect to the Identity Manager server, open the Connect page and enter the URL of the Identity Manager server. For example, if your server is running on port 8080 on the local machine, the URL would be:
http://localhost:8080/idm/servlet/rpcrouter2
Where localhost is the machine on which you are running Identity Manager.
Testing and Troubleshooting the SPML ConfigurationTo test your SPML configuration:
If you cannot establish a successful connection
- Double-check the URL you entered.
- If the error you receive contains phrases such as “no response” or “connection refused,” then the problem is most likely the host or port used in the connection URL.
- If the error suggests that a connection was made, but the web application or servlet could not be located, the problem is most likely in the
WEB-INF/web.xml file. See “Deployment Descriptor” on page 43 for more information.
Developing SPML ApplicationsOnce the server is configured, an application will need a mechanism to send SPML messages and receive SPML responses. For Java applications, the easiest way to accomplish this is to make use of the OpenSPML Toolkit. The toolkit is available from www.openspml.org and is bundled with Identity Manager.
The toolkit provides the following components:
Table 7-3 summarizes the most important classes provided by the toolkit. Each request type has a corresponding class. Consult the JavaDocs distributed with the toolkit for complete information.
Table 7-3 Classes Provided by OpenSPML Toolkit
Class
Description
AddRequest
Constructs a message that requests the creation of a new object.
The type of object to create is defined by passing an attribute named objectclass. Other attributes passed should adhere to the schema associated with the object class. SPML does not yet define any standard schemas. Identity Manager can be configured to support any desired schema.ModifyRequest
Constructs a message that requests the modification of an existing object. You need include only those attributes that you want to modify in the request. Attributes not included in the request retain their current value.
DeleteRequest
Constructs a message that requests the deletion of an object.
SearchRequest
Constructs a message that requests attributes of objects that match certain criteria.
BatchRequest
Constructs a message that can contain more than one SPML request.
CancelRequest
Constructs a message that cancels a request that was formerly executed asynchronously.
SchemaRequest
Constructs a message that requests information about the SPML object classes supported by the server.
StatusRequest
Constructs a message that requests the status of a request that was formerly executed asynchronously.
SpmlResponse
The base class for objects representing response messages sent back from the server. Each request class has a corresponding response class: AddResponse and ModifyResponse, for example.
SpmlClient
Provides a simple interface for sending and receiving SPML messages.
Note
The SPE REF Kit provides an SpmlUsage.java file that demonstrates how to use the SPE 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 SPE SPML interface and defaults to
http://localhost:8080/idm/spespml
If you enable trace for SPE, all SPE SPML messages will be printed to the standard output.
ExtendedRequest Examples
Table 7-4 describes the ExtendedRequest classes used to send and receive messages on the client.
Table 7-4 ExtendedRequest Classes for Sending and Receiving Messages
ExtendedRequest
Description
deleteUser
Constructs a message that requests the deletion of a user.
disableUser
Constructs a message that requests the disabling of a user.
enableUser
Constructs a message that requests the enabling of a user.
resetUserPassword
Constructs a message that requests the reset of a user password.
changeUserPassword
Constructs a message that requests the change of a user password.
launchProcess
Constructs a message that requests 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.
runForm
Allows you to create custom SPML requests that return information obtained by calling the Identity Manager Session API.
The server code converts the extended requests into view operations.
Sample Extended Request
Extended requests typically take the format shown in Code Example 7-6:
Code Example 7-6 Extended Request Format
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("changeUserPassword");
req.setAttribute("accountId", "jlarson");
req.setAttribute("password", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);
Most SPML extended requests take the following arguments:
If you do not pass an accounts attributes, the operation will update all resource accounts linked to the user, including itself. If you do pass accounts, the operation updates only the specified resources. You must include Lighthouse in a non-null accounts list if you want to update the Identity Manager user in addition to specific resource accounts.
deleteUser
Code Example 7-7 shows a typical format for deleteUser request
(View — Deprovision view).
Code Example 7-7 deleteUser Request
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("deleteUser");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);
disableUser
Code Example 7-8 shows a typical format for disableUser request
(View — Disable view).
Code Example 7-8 disableUser Request
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("disableUser");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);
enableUser
Code Example 7-9 shows a typical format for enableUser request
(View — Enable view).
Code Example 7-9 enableUser Request
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("enableUser");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);
resetUserPassword
Code Example 7-10 shows a typical format for resetUser request
(View — Reset User Password view).
Code Example 7-10 resetUser Request
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("resetUserPassword");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);
changeUserPassword
Code Example 7-11 shows a typical format for changeUserPassword request. (
View — Change User Password view).
Code Example 7-11 changeUserPassword Request
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("changeUserPassword");
req.setAttribute("accountId", "jlarson");
req.setAttribute("password", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = (ExtendedResponse) client.send(req);
launchProcess
Code Example 7-12 shows a typical format for launchProcess request.
(View — Process view).
Code Example 7-12 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 process attribute names a Task Definition object in the Identity Manager repository that is to be run. The taskName attribute is used to name the Task Instance object that is created to hold the runtime state of the process. The remaining attributes are arbitrary, and are passed into the task. The launchProcess request can be used to start any custom process.
listResourceObjects
Code Example 7-13 shows a typical format for listResourceObjects request.
Code Example 7-13 listResourceObjects Request
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("listResourceObjects");
req.setAttribute("resource", "LDAP");
req.setAttribute("type", "group");
ExtendedResponse res = (ExtendedResponse) client.send(req);
Where:
runForm
Code Example 7-14 shows a typical format for a runForm request.
Code Example 7-14 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 Form
The form shown in Code Example 7-15 runs queries and returns a list of the Role, Resource, and Organization names accessible to the current user.
Code Example 7-15 Query Form
<Configuration name='SPML Get Object Names'>
<Extension>
<Form>
<Field name='roles'>
<Derivation>
<invoke name='com.waveset.ui.FormUtil'>
<ref>display.session</ref>
<s>Role</s>
</invoke>
</Derivation>
</Field>
<Field name='resources'>
<Derivation>
<invoke name='com.waveset.ui.FormUtil'>
<ref>display.session</ref>
<s>Resource</s>
</invoke>
</Derivation>
</Field>
<Field name='organizations'>
<Derivation>
<invoke name='com.waveset.ui.FormUtil'>
<ref>display.session</ref>
<s>ObjectGroup</s>
</invoke>
</Derivation>
</Field>
</Form>
</Extension>
</Configuration>
The runForm request allows you 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 users, 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 then use a searchRequest to query for their names. However, this would require four searchRequests to gather the information. You can reduce the number of SPML requests by instead encoding the queries in a form, then using a single runForm request to perform the queries and return the combined results.
Using Trace with SPML
SPML provides the following options for turning on trace output so you can log Identity Manager’s SPML traffic and to help you diagnose problems.
Method 1
The SpmlClient and LighthouseClient classes both provide a setTrace method that takes a Boolean argument. If you enable this setTrace method, the XML for the request sent by the client and the XML for the response received from the server will be printed to the client console as they are sent and received.
For example
SpmlClient client = new SpmlClient();
client.setURL("http://www.company.com/idm/spml");
client.setTrace(true);
Method 2
To turn tracing on for an individual SPML RPC request, you can pass the trace operational attribute to the RPC request on the server side.
Tracing occurs during servlet initialization, and it controls how information is output for the RPC traffic of a servlet handling SPMLv2 requests. For example, the trace prints the raw XML that is sent back and forth on whatever the System.out is for that servlet (which is a function of the App container). For example:
How using the trace attribute will affect server operation is vendor-specific. Currently, Identity Manager prints the raw request and response data to the server console, which is useful if the client application is not associated with a console window.
The code is not yet implemented in Identity Manager, so for more information consult your OpenSPML Toolkit product documentation.
ExamplesThis section provides the following examples to illustrate several common methods for implementing SPML:
Add Request
An example Add Request is shown in Code Example 7-16:
Code Example 7-16 Add Request
SpmlClient client = new SpmlClient();
client.setURL("http://www.company.com/idm/spml");AddRequest req = new AddRequest();
req.setObjectClass("person");
req.setIdentifier("maurelius");
req.setAttribute("gn", "Marcus");
req.setAttribute("sn", "Aurelius");
req.setAttribute("email", "maurelius@example.com");SpmlResponse res = client.request(req);
if (res.getResult() .equals(SpmlResponse.RESULT_SUCCESS))
System.out.println("Person was successfully created");
Modify Request
This section provides two example Authenticated SPML Modify Requests.
The only difference between these examples is that the Code Example 7-18 uses the LighthouseClient class and two additional method calls to client.setUser and client.setPassword.
Code Example 7-17 Authenticated SPML Request
SpmlClient client = new SpmlClient();
client.setURL("http://www.company.com/idm/spml");ModifyRequest req = new ModifyRequest();
req.setIdentifier("maurelius");
req.setModification("email", "marcus.aurelius@example.com");SpmlResponse res = client.request(req);
if (res.getResult() .equals(SpmlResponse.RESULT_SUCCESS))
System.out.println("Person was successfully modified");
Code Example 7-18 Authenticated SPML Request with LighthouseClient
LighthouseClient client = new LighthouseClient();
client.setURL("http://www.company.com/idm/spml");
client.setUser("maurelius");
client.setPassword("xyzzy");ModifyRequest req = new ModifyRequest();
req.setIdentifier("maurelius");
req.setModification("email", "marcus.aurelius@example.com");SpmlResponse res = client.request(req);
if (res.getResult() .equals(SpmlResponse.RESULT_SUCCESS))
System.out.println("Person was successfully modified");
Search Request
An example Search Request is shown in Code Example 7-19:
Code Example 7-19 Search Request
SpmlClient client = new SpmlClient();
client.setURL("http://www.company.com/idm/spml");
SearchRequst req = new SearchRequest();
// specify the attributes to return
req.addAttribute("sn");
req.addAttribute("email");
// specify the filter
FilterTerm ft = new FilterTerm();
ft.setOperation(FilterTerm.OP_EQUAL);
ft.setName("gn");
ft.setValue("Jeff");
req.addFilter(ft);
SearchResponse res = (SearchResponse)client.request(req);
// display the results
List results = res.getResults();
if (results != null) {for (int i = 0 ; i < results.size() ; i++) {
SearchResult sr = (SearchResult)results.get(i);
System.out.println("Identifier=" +
sr.getIdentifierString() +
" sn=" +
sr.getAttribute("sn") +
" email=" +
sr.getAttribute("email"));
}
}