|
| |
| Sun Java[TM] System Identity Manager 7.1 Deployment Tools | |
Chapter 8
Using SPML 2.0 with Identity Manager Web ServicesThis chapter describes SPML 2.0 support in Identity Manager 7.1; including which features are supported and why, how to configure SPML 2.0 support, and how to extend support in the field.
Note
This chapter focuses exclusively on SPML 2.0. Unless noted otherwise, all references to SPML in this chapter indicate the 2.0 version.
You should also read Chapter 7, "Using SPML 1.0 with Identity Manager Web Services," which also contains useful information about using SPML.
This information is organized as follows:
Who Should Read This ChapterApplication developers and developers who are responsible for integrating Identity Manager can use the SPML classes described in this chapter to format service provisioning request messages and to parse response messages.
OverviewIdentity Manager’s Web services are SOAP-based programmatic interfaces that enable Identity Manager to communicate with other Web-based applications — without being restricted to a particular operating system or programming language.
Web services interfaces are hosted on a Web server, and their functions are exposed through the following open standards over an Internet protocol framework:
You can access Identity Manager Web services using SOAP messages over an HTTP connection.
How SPML 2.0 Compares to SPML 1.0
Identity Manager Web services support both SPML version 1.0 and version 2.0 protocols (open standards for service provisioning using XML) for communication with provisioning systems.
Note
See Chapter 7, "Using SPML 1.0 with Identity Manager Web Services" for information about using SPML version 1.0 with Identity Manager.
SPML 2.0 offers many improvements over SPML 1.0, including:
- Where SPML 1.0 has been called a slightly improved DSML, SPML 2.0 defines an extensible protocol (through Capabilities) with support for a DSML profile, as well as XML Schema profiles. SPML 2.0 differentiates between the protocol and the data it carries.
- An SPML 2.0 provider can provide multiple targets, or endpoints.
- The SPML 2.0 protocol enables better interoperability between vendors — especially for the Core capabilities (those found in 1.0).
- SPML 2.0 provides additional capabilities that enable progressive support (see Table 8-1)
How SPML 2.0 Concepts Are Mapped to Identity Manager
SPML 2.0 uses its own terminology to discuss the objects that are managed by a provisioning system — defining terms like PSO and psoID. This section discusses the how these concepts are mapped into Identity Manager.
Target
A target is a logical end-point in the server. Each target is named and declares the schema of the objects (see the following PSO section) that it manages. The target also declares which capabilities (set of requests) are supported.
Currently, Identity Manager supports only one target — you cannot declare multiple targets. You can name this target anything you want, but the data objects’ format must conform to the DSML-profile.
The supported target is the one target defined in the spml2.xml file (Configuration:SPML2 object). For example, in Code Example 8-6 ListTargetResponse returns one target, spml2-DSML-Target.
PSO
As mentioned in the previous section, targets manage PSOs. A PSO (Provisioning Service Object) is somewhat analogous to a view in Identity Manager, but without behavior. Consequently, you can think of a PSO as the data portion of an Identity Manager view; a user view in particular.
Note
As of this release, Identity Manager only manages Users and requires you to define a UserExtendedAttribute called objectclass.
For Identity Manager’s purposes, a PSO is a collection of attributes that are mapped (via a form) to and from a user view. Each object specifies an objectclass attribute that is used to map the object to an objectclass definition in the schema defined for the target. This attribute is used in turn to find a repoType and a form that maps the attributes to and from the Identity Manager view.
PSOIdentifier
SPML includes an object ID, called a PsoID.
Because the specification recommends that a PSOIdentifier (PsoID) be opaque to a requestor (client), Identity Manager uses its repository ID (repoID) as the PsoID when adding PSOs to the system.
The repoID is distinct and is not meant for presentation to a user. When a requestor displays a PSO to a user, it should use the equivalent of the waveset.accountid (or whatever attributes are used in the Identity template) to present the object’s ID.
When identifying the PSO (as in a ModifyRequest), the requestor should use the repoID and not the waveset.accountId. Although the requestor can use the waveset.accountId as a PSOIdentifier, doing so is not recommended and it may change in a future release. Requestors should try to keep the PsoID opaque.
PSOs use an objectclass attribute to specify the object type. For Identity Manager this attribute must be a UserExtendedAttribute. If this attribute is not there when a request is made, Identity Manager allows you to specify a “default” to use. You might not see an objectclass attribute for users that existed before you enabled SPML 2.0.
Open Content and Operational Attributes
SPML makes heavy use of xsd:any in the .xsds to provide what the specification refers to as Open Content. In SPML, Open Content means that most elements can contain elements of any type. Identity Manager uses this idea to provide OperationalNVPs (NameValuePairs) and OperationalAttributes that control processing. OperationalNVPs appear as elements in the XML, while Operational Attributes appear as attributes. See the OpenSPML 2.0 Toolkit at http://www.openspml.org for more information.
OperationalNVPs and Operational Attributes are discussed further in theSupported SPML 2.0 Capabilities, section; however, you use one NVP in all requests (except ListTargets) and in all responses. Identity Manager stores a sessionToken in an OperationalNVP called session, which allows the system to cache sessions on behalf of the user and improves efficiency.
Supported SPML 2.0 Capabilities
Identity Manager 7.0 supports all of the Core capabilities in the SPML 2.0 specification, using the DSML profile. Identity Manager also supports some of the optional Standard capabilities (such as Batch and Async) and partially supports some Standard capabilities (such as Bulk).
This section describes which SPML 2.0 capabilities are supported in Identity Manager 7.0, where Identity Manager (knowingly) varies from the specification and profile document, and which operational attributes are required by Identity Manager.
Supported Core Capabilities
Identity Manager supports the following Core capabilities:
AddRequest and ListTargetRequest examples follow.
AddRequest Examples
This section provides several AddRequest examples.
Code Example 8-1 is a .jsp that invokes a ListTargetsRequest through Identity Manager's SessionAwareSpml2Client class.
Code Example 8-2 shows the body of the SOAP message that was sent.
Code Example 8-2 Example Request XML
<addRequest xmlns='urn:oasis:names:tc:SPML:2:0' requestID='rid-spmlv2' executionMode='synchronous'>
<openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml' name='session' value='AAALPgAAYD0A...'/>
<data>
<dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='accountId'>
<dsml:value>exampleSpml2Person</dsml:value>
</dsml:attr>
<dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='objectclass'>
<dsml:value>spml2Person</dsml:value>
</dsml:attr>
<dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='credentials'>
<dsml:value>pwdpwd</dsml:value>
</dsml:attr>
</data>
</addRequest>
Code Example 8-3 shows the body of the SOAP message that is returned to the client.
Code Example 8-3 Example Response XML
<addResponse xmlns='urn:oasis:names:tc:SPML:2:0' status='success' requestID='rid-spmlv2'>
<openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml' name='session' value='AAALPgAAYD0A...'/>
<pso>
<psoID ID='anSpml2Person'/>
<data>
<dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='accountId'>
<dsml:value>anSpml2Person</dsml:value>
</dsml:attr>
<dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='objectclass'>
<dsml:value>spml2Person</dsml:value>
</dsml:attr>
<dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='credentials'>
<dsml:value>pwdpwd</dsml:value>
</dsml:attr>
</data>
</pso>
</addResponse>
ListTargetsRequest Examples
The following examples show ListsTargetRequest that are available via Identity Manager.
Code Example 8-4 shows a .jsp invokes a ListTargetsRequest via Identity Manager's SessionAwareSpml2Client class.
Code Example 8-4 Example Client Code
<%@page contentType="text/html"%>
<%@page import="org.openspml.v2.client.*,
com.sun.idm.rpc.spml2.SessionAwareSpml2Client"%>
<%@page import="org.openspml.v2.profiles.dsml.*"%>
<%@page import="org.openspml.v2.profiles.*"%>
<%@page import="org.openspml.v2.util.xml.*"%>
<%@page import="org.openspml.v2.msg.*"%>
<%@page import="org.openspml.v2.msg.spml.*"%>
<%@page import="org.openspml.v2.util.*"%>
<%
final String url = "http://localhost:8080/idm/servlet/openspml2";
%>
<html>
<head><title>SPML2 Test</title></head>
<body>
<%
// need a client.
SessionAwareSpml2Client client = new SessionAwareSpml2Client( url );
// login (sends a ListTargetsRequest)
Response res = client.login("configurator", "password");
%>
<%= res.toString()%>
</body>
</html>
Code Example 8-5 shows the body of the SOAP message that is sent.
Code Example 8-5 Example Request XML
<listTargetsRequest xmlns='urn:oasis:names:tc:SPML:2:0' requestID='rid[7013]' executionMode='synchronous'>
<openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml' name='accountId' value='configurator'/>
<openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml' name='password' value='password'/>
</listTargetsRequest>
Code Example 8-6 shows the body of the SOAP message that is received by or returned to the client.
Code Example 8-6 Example Response XML
<listTargetsResponse xmlns='urn:oasis:names:tc:SPML:2:0' status='success' requestID='rid[6843]'>
<openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml'
name='session' value='AAALPgAAYD0A...'/><target targetID='spml2-DSML-Target' profile='urn:oasis:names:tc:SPML:2:0:DSML'>
<schema>
<spmldsml:schema xmlns:spmldsml='urn:oasis:names:tc:SPML:2:0:DSML'>
<spmldsml:objectClassDefinition name='spml2Person'>
<spmldsml:memberAttributes>
<spmldsml:attributeDefinitionReference required='true' name='objectclass'/>
<spmldsml:attributeDefinitionReference required='true' name='accountId'/>
<spmldsml:attributeDefinitionReference required='true' name='credentials'/>
<spmldsml:attributeDefinitionReference name='firstname'/>
<spmldsml:attributeDefinitionReference name='lastname'/>
<spmldsml:attributeDefinitionReference name='emailAddress'/>
</spmldsml:memberAttributes>
</spmldsml:objectClassDefinition>
<spmldsml:attributeDefinition name='objectclass'/>
<spmldsml:attributeDefinition description='Account Id' name='accountId'/>
<spmldsml:attributeDefinition description='Credentials, e.g. password'
name='credentials'/><spmldsml:attributeDefinition description='First Name' name='firstname'/>
<spmldsml:attributeDefinition description='Last Name' name='lastname'/>
<spmldsml:attributeDefinition description='Email Address' name='emailAddress'/>
</spmldsml:schema>
<supportedSchemaEntity entityName='spml2Person'/>
</schema>
<capabilities>
<capability namespaceURI='urn:oasis:names:tc:SPML:2:0:async'/>
<capability namespaceURI='urn:oasis:names:tc:SPML:2:0:batch'/>
<capability namespaceURI='urn:oasis:names:tc:SPML:2:0:bulk'/>
<capability namespaceURI='urn:oasis:names:tc:SPML:2:0:pass'/>
<capability namespaceURI='urn:oasis:names:tc:SPML:2:0:suspend'/>
</capabilities>
</target>
</listTargetsResponse>
Async Capability Support
Identity Manager supports the Async capabilities described in Table 8-3:
Table 8-3 Async Capabilities
Capability
Description
Operational Attributes
Caveats
CancelRequest
Cancels a request, using the request ID.
None
StatusRequest
Returns the status of a request, using the request ID.
None
Batch Capability Support
Identity Manager supports the Batch capability described in Table 8-4.
Table 8-4 Batch Capability
Capability
Description
Operational Attributes
Caveats
BatchRequest
Executes a batch of requests.
None
Bulk Capability Support
Identity Manager supports the Bulk capabilities described in Table 8-5:
Table 8-5 Bulk Capabilities
Capability
Description
Operational Attributes
Caveats
BulkDeleteRequest
Executes a bulk delete of PSOs.
None
BulkModifyRequest
Executes a bulk modify of matching PSOs.
None
Password Capability Support
Identity Manager supports the Password capabilities described in Table 8-6:
Table 8-6 Password Capabilities
Capability
Description
Operational Attributes
Caveats
ExpirePasswordRequest
Expires a password.
None
- You cannot specify resources/targets. Doing so causes the Identity Manager User object password to expire; which then causes the password on all user's resources to expire.
- Identity Manager does not support the remainingLogins attribute.
If you set this attribute to anything other than the default, an OperationNotSupported error occurs.ResetPasswordRequest
Resets the password and returns the new value on all accounts.
None
Passwords are sensitive. Use SSL or some other secure transport.
SetPasswordRequest
Sets the password.
None
Passwords are sensitive. Use SSL or some other secure transport.
ValidatePasswordRequest
Determines whether the given password is valid.
None
Passwords are sensitive. Use SSL or some other secure transport.
Example Password capabilities follow.
ResetPasswordRequest Example
Code Example 8-7 is an example ResetPasswordRequest.
Code Example 8-7 Example ResetPasswordRequest
ResetPasswordRequest rpr = new ResetPasswordRequest();
...
PSOIdentifier psoId = new PSOIdentifier(accountId, null, null);
rpr.setPsoID(psoId);
...
SetPasswordRequest Example
Code Example 8-8 is an example SetPasswordRequest.
Code Example 8-8 Example SetPasswordRequest
SetPasswordRequest spr = new SetPasswordRequest();
...
PSOIdentifier psoId = new PSOIdentifier(accountId, null, null);
spr.setPsoID(psoId);
spr.setPassword("newpassword");
spr.setCurrentPassword("oldpassword");
...
ValidatePasswordRequest Example
Code Example 8-9 is an example ValidatePasswordRequest.
Code Example 8-9 Example ValidatePasswordRequest
ValidatePasswordRequest vpr = new ValidatePasswordRequest();
...
PSOIdentifier psoId = new PSOIdentifier(accountId, null, null);
vpr.setPsoID(psoId);
vpr.setPassword("apassword");
...
Suspend Capability Support
Identity Manager supports the Suspend capabilities described in Table 8-7.
Table 8-7 Suspend Capabilities
Capability
Description
Operational Attributes
Caveats
ResumeRequest
Resumes (enables) a PSO User.
None
Does not support EffectiveDate.
If you set EffectiveDate, Identity Manager returns an OperationNotSupported error.
SuspendRequest
Suspends an accounts/PSO (disable)
None
Does not support EffectiveDate.
If you set EffectiveDate, Identity Manager returns an OperationNotSupported error.
Which SPML 2.0 Features Are Not Supported
Identity Manager 7.1 does not support the Reference capability, the Search capability, or the Updates capability.
In addition, none of the supported capabilities use the CapabilityData class, so there is no infrastructure in the Identity Manager code base to support it, which is significant if you want to implement custom capabilities. Note that the OpenSPML 2.0 Toolkit does support CapabilityData in the marshallers, unmarshallers, and so forth.
Why No References?
Identity Manager does not support references for two reasons; the Reference Capability is typically used to refer across targets or to refer between objects on the same target.
Because Identity Manager officially only supports one target, the first use-case is out. Additionally, because User is the only repoType supported by Identity Manager (mapped to a PSO type using objectclass), and these objects do not refer to other objects, there is no need to support References at this time.
Why No Search Capability?
Currently, Search support is provided only through SPML 1.0.
Identity Manager does not support the SPML 2.0 Search Capability because the capability does not perform a search very efficiently yet. In short, the Search filters operate on the full User View and therefore need to instantiate every User object into a full view; which is not very efficient, but it is necessary as a provisioning system. Because of this, Identity Manager cannot reasonably provide iteration (or an efficient search) over the results of the search. Adding the Search capability will be addressed in a future release.
Why No Updates?
Identity Manager does not support the Updates Capability because it does not track Change Records, which are required information for this capability.
Configuring Identity Manager to Use SPML 2.0When configuring an Identity Manager server to use SPML 2.0, the first step is to decide which attributes you want to manage through your target.
Decide which attribute sets (objectclasses) the interface clients will use when managing users in the Identity Manager instance that uses this interface. This set of attributes is a PSO.
You must also know how to map those attributes to and from a User View using a form.
This section describes how to configure a system that uses PSOs containing the following attributes for a DSML objectclass called spml2Person:
These attributes are mapped to the User View. This section also provides short examples to demonstrate how to manage these PSOs using SPML 2.0 support in Identity Manager. Note that this configuration is delivered in the sample/spml2.xml file provided with the product. You can see this file for detailed information.
After deciding on the format of a PSO; enable the service as described in the next section, which discusses web.xml and what has been added for SPML 2.0.
The SPML2 Configuration Object
The out-of-the-box configuration for SPML 2.0 support is provided in sample/spml2.xml. This file defines the objects that Identity Manager needs to support SPML 2.0.
One of these Configuration type objects, named SPML2, is discussed in this section. You use this object to change how SPML 2.0 support behaves or to extend the system. (A separate section will discuss extensions in more detail.)
The following example is an annotated export of the object.
Code Example 8-10 Annotated Export of the SPML2.XML Object
<Configuration name='SPML2' authType='SPML'>
<Extension>
<Object>
<!-- Each of the objects in this list represents a tuple of an "executorClass"
and the set of Requests that it knows how to handle. A Request type can
appear in more than one executor tuple. This results in a chain of
executors for that type. If the first one cannot handle a given instance
of that type, the request is passed to the next one in the chain.
It's important to note that this list (executors) is processed in order.
Generally, you'll leave this section alone. -->
<Attribute name='executors'>
<List>
<Object name='com.sun.idm.rpc.spml2.core.ListTargetsExecutor'>
<Attribute name="requests" value="org.openspml.v2.msg.
spml.ListTargetsRequest"/></Object>
<Object name='com.sun.idm.rpc.spml2.pass.PasswordRequestExecutor'>
<Attribute name='requests'>
<List>
<String>org.openspml.v2.msg.pass.SetPasswordRequest</String>
<String>org.openspml.v2.msg.pass.ResetPasswordRequest</String>
<String>org.openspml.v2.msg.pass.ValidatePasswordRequest</String>
<String>org.openspml.v2.msg.pass.ExpirePasswordRequest</String>
</List>
</Attribute>
</Object>
<Object name='com.sun.idm.rpc.spml2.core.AddRequestExecutor'>
<Attribute name="requests"
value='org.openspml.v2.msg.spml.AddRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.core.DeleteRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spml.DeleteRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.core.LookupRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spml.LookupRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.core.ModifyRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spml.ModifyRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.suspend.SuspendRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlsuspend.SuspendRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.suspend.ResumeRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlsuspend.ResumeRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.suspend.ActiveRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlsuspend.ActiveRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.batch.BatchRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlbatch.BatchRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.bulk.BulkDeleteRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlbulk.BulkDeleteRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.bulk.BulkModifyRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlbulk.BulkModifyRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.async.StatusRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlasync.StatusRequest'/></Object>
<Object name='com.sun.idm.rpc.spml2.async.CancelRequestExecutor'>
<Attribute name='requests'
value='org.openspml.v2.msg.spmlasync.CancelRequest'/></Object>
</List>
</Attribute>
<Attribute name='targets'>
<List>
<!-- This is the name of the target; broken out so it easy to read
and refer too. This becomes the targetID as the name of this Object
replaces the $OBJECT_NAME$ variable in 'xmlTemplate'. -->
<Object name="spml2-DSML-Target">
<!-- You can state that the Target is attached to a profile;
replaces $PROFILE_ATTRIBUTE$ with 'profile="<value>"' in the
'xmlTemplate'.-->
<Attribute name="profile" value="urn:oasis:names:tc:SPML:2:0:DSML"/>
<!-- This is the target definition; the first two lines, and the last,
are always the same (for each Object in the "targets" list) -->
<Attribute name='xmlTemplate'>
<String><![CDATA[
<target targetID="$OBJECT_NAME$" $PROFILE_ATTRIBUTE$>
<schema>
<spmldsml:schema xmlns:spmldsml="urn:oasis:names:tc:SPML:2:0:DSML">
<spmldsml:attributeDefinition name="objectclass"/>
<spmldsml:attributeDefinition name="accountId" description="Account Id"/>
<spmldsml:attributeDefinition name="credentials" description="Credentials,
e.g. password"/><spmldsml:attributeDefinition name="firstname" description="First Name"/>
<spmldsml:attributeDefinition name="lastname" description="Last Name"/>
<spmldsml:attributeDefinition name="emailAddress" description="Email Address"/>
<spmldsml:objectClassDefinition name="spml2Person">
<spmldsml:memberAttributes>
<spmldsml:attributeDefinitionReference name="objectclass"
required="true"/><spmldsml:attributeDefinitionReference name="accountId" required="true"/>
<spmldsml:attributeDefinitionReference name="credentials"
required="true"/><spmldsml:attributeDefinitionReference name="firstname"/>
<spmldsml:attributeDefinitionReference name="lastname"/>
<spmldsml:attributeDefinitionReference name="emailAddress"/>
</spmldsml:memberAttributes>
</spmldsml:objectClassDefinition>
</spmldsml:schema>
<supportedSchemaEntity entityName="spml2Person"/>
</schema>
<capabilities>
<capability namespaceURI="urn:oasis:names:tc:SPML:2:0:async"/>
<capability namespaceURI="urn:oasis:names:tc:SPML:2:0:batch"/>
<capability namespaceURI="urn:oasis:names:tc:SPML:2:0:bulk"/>
<capability namespaceURI="urn:oasis:names:tc:SPML:2:0:pass"/>
<capability namespaceURI="urn:oasis:names:tc:SPML:2:0:suspend"/>
</capabilities>
</target>
]]></String>
</Attribute>
</Object>
</List>
</Attribute>
<!-- This is like the "classes" list in the spml.xml config. We added the
ability to apply a mapping to one or more targets, in case the they
have common objectclass / type names. See the SPML 1.0 file and
docs for more info.-->
<Attribute name='mappings'>
<List>
<Object name='spml2Person'>
<Attribute name='type' value='User'/>
<Attribute name='form' value='spml2PersonForm'/>
<Attribute name='default' value='true'/>
<Attribute name='targets'>
<String>"spml2-DSML-Target"</String>
</Attribute>
</Object>
<Object name='request'>
<Attribute name='type' value='TaskInstance'/>
<Attribute name='filter'>
<AttributeCondition attrName='defName' operator='equals'
operand='SPML2Request'/>
</Attribute>
</Object>
</List>
</Attribute>
</Object>
</Extension>
</Configuration>
<!-- We ALSO need to define the Form that maps the attributes in our objectclass(es) to and from the view. The following form does this for the spml2Person objectclass.-->
<Configuration name='spml2PersonForm' authType='SPML'>
<Extension>
<Form>
<Field name='accountId'>
<Derivation>
<ref>waveset.accountId</ref>
</Derivation>
</Field>
<Field name='waveset.accountId'>
<Expansion>
<ref>accountId</ref>
</Expansion>
</Field>
<Field name='emailAddress'>
<Derivation>
<ref>waveset.email</ref>
</Derivation>
</Field>
<Field name='global.email'>
<Expansion>
<ref>emailAddress</ref>
</Expansion>
</Field>
<Field name='objectclass'>
<Derivation>
<ref>accounts[Lighthouse].objectclass</ref>
</Derivation>
</Field>
<Field name='accounts[Lighthouse].objectclass'>
<Expansion>
<ref>objectclass</ref>
</Expansion>
</Field>
<Field name='credentials'>
<Derivation>
<ref>password.password</ref>
</Derivation>
</Field>
<Field name='password.password'>
<Expansion>
<ref>credentials</ref>
</Expansion>
</Field>
<Field name='lastname'>
<Derivation>
<ref>accounts[Lighthouse].lastname</ref>
</Derivation>
</Field>
<Field name='global.lastname'>
<Expansion>
<ref>lastname</ref>
</Expansion>
</Field>
<Field name='firstname'>
<Derivation>
<ref>accounts[Lighthouse].firstname</ref>
</Derivation>
</Field>
<Field name='global.firstname'>
<Expansion>
<ref>firstname</ref>
</Expansion>
</Field>
</Form>
</Extension>
</Configuration>
web.xml
The following section in web.xml sets up the openspmlRouter servlet, which is the servlet that handles SPML 2.0 requests.
Note
This section of web.xml ships with a default installation, and no action is required for this component.
Code Example 8-11 Setting-Up the openspmlRouter Servlet
<servlet>
<servlet-name>openspmlRouter</servlet-name>
<display-name>OpenSPML SOAP Router</display-name>
<description>A router of RPC traffic - nominally SPML 2.0 over SOAP</description>
<servlet-class>
org.openspml.v2.transport.RPCRouterServlet
</servlet-class>
<init-param>
<param-name>dispatchers</param-name>
<param-value>org.openspml.v2.transport.SPMLViaSoapDispatcher</param-value>
</init-param>
<init-param>
<param-name>trace</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>SpmlViaSoap.spmlMarshallers</param-name>
<param-value>com.sun.idm.rpc.spml2.UberMarshaller</param-value>
</init-param>
<init-param>
<param-name>SpmlViaSoap.spmlMarshallers.UberMarshaller.trace</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>SpmlViaSoap.spmlExecutors</param-name>
<param-value>com.sun.idm.rpc.spml2.UberExecutor</param-value>
</init-param>
</servlet>
This file contains an optional init-param that you can add to open a monitor window (in Swing) that displays the flow of SPML 2.0 messages. You will find this monitor window useful for debugging.
The following example shows you what to add.
<init-param>
<param-name>monitor</param-name>
<param-value>org.openspml.v2.util.SwingRPCRouterMonitor</param-value>
</init-param>
In Code Example 8-12, the section is commented and provides information about the other init-params.
Code Example 8-12 Commented Example
<servlet>
<servlet-name>openspmlRouter</servlet-name>
<display-name>OpenSPML SOAP Router</display-name>
<description>A router of RPC traffic - nominally SPML 2.0 over SOAP</description>
<servlet-class>
org.openspml.v2.transport.RPCRouterServlet
</servlet-class>
<!--
The Router uses dispatchers to process SOAP messages. This is one that is in the
toolkit that knows about SOAP. It has its own parameters, via naming convention.
See below.-->
<init-param>
<param-name>dispatchers</param-name>
<param-value>org.openspml.v2.transport.SPMLViaSoapDispatcher</param-value>
</init-param>
<!--
Turn on trace to have the servlet write informational messages to the log.
-->
<init-param>
<param-name>trace</param-name>
<param-value>false</param-value>
</init-param>
<!--
The SpmlViaSOAPDispatcher (yes, the one above) uses marshallers; there can be
a chain, to move XML to SPML objects and back. We use one; we implemented
UberMarshaller for this purpose. It's really a composition of toolkit classes.-->
<init-param>
<param-name>SpmlViaSoap.spmlMarshallers</param-name>
<param-value>com.sun.idm.rpc.spml2.UberMarshaller</param-value>
</init-param>
<!--
Our marshaller (UberMarshaller) has its own trace setting; which doesn't really
do anything in this release-->
<init-param>
<param-name>SpmlViaSoap.spmlMarshallers.UberMarshaller.trace</param-name>
<param-value>true</param-value>
</init-param>
<!--
Finally, the dispatcher has a list of executors that actually implement the
functionality. So, it sees a request, takes the SOAP envelope off, take the body
from XML to OpenSPML Request classes, and then asks the list of executors if they can
process it. We provided one, UberExecutor. It will redispatch the request to our
other executors. Those are specified in spml2.xml (Configuration:SPML2).-->
<init-param>
<param-name>SpmlViaSoap.spmlExecutors</param-name>
<param-value>com.sun.idm.rpc.spml2.UberExecutor</param-value>
</init-param>
</servlet>
Using Trace with SPML
SPML provides the following options for turning on trace output so you can log Identity Manager’s SPML traffic and diagnose problems.
Method 1
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 controls what information is output for the RPC traffic of a servlet handling SPMLv2 requests. For example:
How using the trace attribute will affect server operation is vendor-specific. Currently, Identity Manager prints the raw XML request and response data to the server console, which is useful if the client application is not associated with a console window.
For more information consult your OpenSPML toolkit product documentation.
Method 2
You can also turn tracing on by initializing the SOAP rpcrouter servlet, which controls the output of RPC traffic information for the servlet handling SPML requests. The rpcrouter servlet takes an <init parameter> that enables SOAP tracing on the server side. The servlet’s initialization logic checks for a trace configuration parameter and then, if the parameter’s value is true, prints the raw request and response data to the console.
For example, it prints the raw XML that is sent back and forth to whatever System.out has been specified for that servelet. (Where System.out is a function of the application container.)
Note
The SOAP rpcrouter servlet is a third-party, open source org.openspml.server.SOAPRouter class from the SPML organization. For more information about this servlet, refer to your OpenSPML Toolkit documentation.
The next section describes spml2.xml, with some annotations.
Extending the SystemYou extend the schema by modifying the configuration object, and you can add executors for requests by changing the section. Using forms, you can map DSML to Views and back.
It is less obvious, but you can also replace the dispatcher, marshaller, and the UberExecutor, with those of your own devising.
SPML 2.0 provides a wide-open array of pluggability, which is due to Identity Manager's use of the OpenSPML 2.0 Toolkit. Figure 8-1 illustrates the OpenSPML 2.0 Toolkit architecture.
Figure 8-1 OpenSPML 2.0 Toolkit Architecture
Sample SPML 2.0 AdapterIdentity Manager provides a sample SPML 2.0 resource adapter that can be modified and used to talk to multiple Identity Manager 7.0 installations or third-party resources that are supporting SPML 2.0 core operations.
Note
This sample adapter is provided in the Sun Resource Extension Facility Kit on your product CD or install image (located in /REF).
