|
| |
| Sun Java System Identity Manager 6.0 Deployment Tools 2005Q4M3 | |
7
Using Identity Manager Web Services
This chapter describes the SOAP-based Web service interface provided by the Identity Manager server.
Application developers and developers who are responsible for integrating Identity Manager at customer sites can use the SPML classes described here to format request messages and parse response messages.
Identity Manager Web Service InterfacesIdentity Manager Web services are accessed using SOAP messages over an HTTP connection. Identity Manager supports the emerging standard for communication with provisioning systems: the Service Provisioning Markup Language (SPML).
SPML is the open standard protocol for the integration and interoperation of service provisioning requests. Identity Manager provides a Java toolkit to assist in issuing SPML requests.
SPML is the defacto standard for providing an open interface to service provisioning activities. It has the support of independent software vendors.
Note For best performance, you should use the OpenSPML toolkit that is bundled with Identity Manager.
Configuring SPMLTo expose the SPML interface, you must properly configure the Identity Manager server. SPML configuration involves the installation and modification of the repository objects as well as editing the waveset.properties file.
Configuration Objects
SPML configuration involves the installation and modification of the repository objects described in the following table.
Sample SPML Configuration Objects
A sample set of SPML configuration objects is distributed in the sample/spml.xml file. This file is not imported by default when the repository is initialized. Instead, you must import it manually.
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.
Try to avoid customizing the person class. Instead, keep it consistent with the standard schema.
Editing the waveset.properties File
The following table 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.
Caution This is a dangerous configuration if the HTTP port on which the server is responding is generally accessible. Anyone who knows the URL of the Identity Manager server and understands how to build SPML requests can perform any Identity Manager operation that the proxy user could perform.
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.
Configuring SPML to work with Identity Manager involves working with the following configuration objects:
Editing 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, we cannot directly include them in an Identity Manager XML document. Instead, they must be included 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. It 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
The following example shows the default SPML configuration. The text of the SPML schema definitions have been omitted for brevity.
<Configuration name='SPML'>
<Extension>
<Object>
<Attribute name='classes'>
<List>
<Object name='person'>
<Attribute name='type' value='User'/>
<Attribute name='form' value='SPMLPerson'/>
<Attribute name='default' value='true'/>
<Attribute name='identifier' value='uid'/>
</Object>
<Object name='request'>
<Attribute name='type' value='TaskInstance'/>
<Attribute name='filter'>
<AttributeCondition attrName='defName' operator='equals' operand='SPMLRequest'/>
</Attribute>
</Object>
</List>
</Attribute>
<Attribute name='schemas'>
<List>
<String>
<![CDATA[
<schema xmlns="urn:oasis:names:tc:SPML:1:0"
...SPML standard schema...
</schema>
]]>
</String>
<String>
<![CDATA[
<schema xmlns="urn:oasis:names:tc:SPML:1:0"
...Waveset custom schema...
</schema>
]]>
</String>
</List>
</Attribute>
</Object>
</Extension>
</Configuration>
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 we 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, we 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:
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:
<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. We generally try 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.
<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
Any attribute that you want to use in an SPML search filter must be declared in the <QueryableAttrNames> section of the UserUIConfig object. Any attribute that you want to return in an optimized SPML search result must be declared in the <SummaryAttrNames> section.
<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>
In the preceding code sample, we have defined the extended attribute telephone as a queryable and summary attribute. We also have declarations for firstname and lastname but those are usually already declared. You can customize these lists according to the needs of your site.
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.
A negative value indicates the request instance will never be removed automatically.
Tip Set the value of resultLimit to the shortest possible time to avoid cluttering the repository.
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 this:
<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.
How the Request is 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 (for example, accounts[Lighthouse] or accountinfo).
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
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 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:
The following table 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.
ExtendedRequest Examples
The following table describes the ExtendedRequest classes used to send and receive messages on the client:
The server code converts the extended requests into view operations.
Sample Extended Request
Extended requests typically take this format:
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("changeUserPassword");
req.setAttribute("accountId", "jlarson");
req.setAttribute("password", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = client.request(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, it should only update 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
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("deleteUser");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = client.request(req);
View — Deprovision view
disableUser
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("disableUser");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = client.request(req);
View — Disable view
enableUser
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("enableUser");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = client.request(req);
View — Enable view
resetUserPassword
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("resetUserPassword");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = client.request(req);
View — Reset User Password view
changeUserPassword
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("changeUserPassword");
req.setAttribute("accountId", "jlarson");
req.setAttribute("password", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = client.request(req);
View — Change User Password view
launchProcess
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("launchProcess");
req.setAttribute("accountId", "jlarson");
req.setAttribute("accounts", "xyzzy");
req.setAttribute("accounts","Lighthouse,LDAP,RACF");
ExtendedResponse res = client.request(req);
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
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("listResourceObjects");
req.setAttribute("resource", "LDAP");
req.setAttribute("type", "group");
The resource attribute specifies the name of a Resource object in the Identity Manager repository. The type attribute specifies the type of an object supported by that resource.
runForm
ExtendedRequest req = new ExtendedRequest();
req.setOperationIdentifier("runForm");
req.setAttribute("form", "SPML Get Object Names");
Form — name of a Configuration object containing a form
Example Form
The following example form runs queries and returns 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 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
There are several ways to trace SPML messages to assist in diagnosing problems. The SpmlClient and LighthouseClient classes provide a setTrace method that takes a Boolean argument. When trace is enabled, the XML for the request sent by the client, and the XML for the response received from the server are printed to the client's console as they are sent and received. For example:
SpmlClient client = new SpmlClient();
client.setURL("http://www.company.com/idm/spml");
client.setTrace(true);
A similar trace can be enabled by passing an operational attribute named trace in the request. For example:
AddRequest ar = new AddRequest();
ar.setOperationalAttribute("trace", "true");
This will cause the XML of the request to be printed on the console of the *server* rather than the client. This can be useful of the client application is not associated with a console window.
ExamplesThe following examples show some of the most typical ways of implementing SPML. in this environment. These examples include:
Add Request Example
The following is an example 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@waveset.com");
SpmlResponse res = client.request(req);
if (res.getResult() .equals(SpmlResponse.RESULT_SUCCESS))
System.out.println("Person was successfully created");
Modify Request Examples
Following are two example Authenticated SPML Requests. The only difference between these examples is that the Example 2 uses the LighthouseClient class, and two additional method calls to client.setUser and client.setPassword.
Example 1: 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@waveset.com");
SpmlResponse res = client.request(req);
if (res.getResult() .equals(SpmlResponse.RESULT_SUCCESS))
System.out.println("Person was successfully modified");
Example 2: 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@waveset.com");
SpmlResponse res = client.request(req);
if (res.getResult() .equals(SpmlResponse.RESULT_SUCCESS))
System.out.println("Person was successfully modified");
Search Request Example
The following is an example 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"));
}
}