Sun[TM] Identity Manager 8.0 Deployment Tools |
Chapter 5
Using SPML 2.0 with Identity Manager Web ServicesThis chapter describes SPML 2.0 support in Identity Manager 8.0; 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 4, "Using SPML 1.0 with Identity Manager Web Services," which also contains useful information about using SPML.
This information is organized as follows:
Before You BeginReview the following sections before you start working with Identity Manager Web Services:
Intended Audience
This chapter is intended for application developers and developers who are responsible for deploying Identity Manager, implementing procedural logic, and using SPML 2.0 classes to format service provisioning request messages and to parse response messages.
Important Notes
You should be aware of the following information before working with SPML 2.0:
- For best performance when working with the Identity Manager Web Service Interfaces, use the OpenSPML Toolkit supplied with Identity Manager. Using the openspml.jar file from the http://www.openspml.org/ web site might cause memory leaks.
- When implementing SPML 2.0, you must modify the configuration to add the spml2ObjectClass attribute to your schema. The objectclass attribute value provided in previous releases is now maintained in the spml2ObjectClass attribute.
- You cannot access Identity Manager Service Provider (Service Provider) features through SPML 2.0. (These features are available with SPML version 1.0.)
Related Documentation and Web Sites
In addition to the information provided in this chapter, consult the publications and web sites listed in this section for information related to using SPML.
Recommended Reading
See Chapter 4, "Using SPML 1.0 with Identity Manager Web Services," in this book for information about using SPML version 1.0.
Useful Web Sites
Visit the following web site for information about using OpenSPML, to read SPML 2.0 Specifications, and to download the OpenSPML 2.0 Toolkit.
OverviewThis section explains some basic concepts about SPML 2.0:
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 4, "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.
- 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 (see Table 5-1) that will make it possible for you to extend capabilities or add new capabilities in the future.
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.
Note
See the OASIS SPML 2.0 Specifications at http://www.openspml.org/.
This section describes how the following SPML 2.0 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.
A supported target is the one target defined in the spml2.xml file (Configuration:SPML2 object). For example, in Code Example 5-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
Identity Manager only manages Users and requires you to define a user extended attribute called spml2ObjectClass.
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
PSOIdentifier
SPML includes an object ID that is called a PsoID.
OASIS SPML 2.0 Specifications recommend that PSOIdentifiers (PsoID) should be opaque to a requestor (client). Consequently, Identity Manager uses repository IDs (repoIDs) as the PsoID when adding PSOs to the system.
The repoID is distinct and it 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. If this attribute is not there when a request is made, Identity Manager allows you to specify and use a “default” objectclass, such as SPMLUser. Internally, the objectclass value is maintained as an spml2ObjectClass attribute for users. For Identity Manager this attribute must be a user extended attribute. You might not see an spml2ObjectClass 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 supports all Core capabilities in the SPML 2.0 Specification that use 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, where Identity Manager (knowingly) varies from the specification and profile document, and which operational attributes are required by Identity Manager.
This information is organized into the following sections:
Core Capabilities
Identity Manager supports the following Core capabilities:
AddRequest and ListTargetRequest examples follow.
AddRequest Examples
This section provides several AddRequest examples.
The following example shows a .jsp that invokes a ListTargetsRequest through Identity Manager's SessionAwareSpml2Client class.
Code Example 5-2 shows the SPML 2.0 request that was sent.
Code Example 5-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 5-3 shows the body of the SPML request that is returned to the client.
Code Example 5-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 5-4 shows a .jsp invokes a ListTargetsRequest via Identity Manager's SessionAwareSpml2Client class.
Code Example 5-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://host:port/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 5-5 shows the body of the SPML request that is sent.
Code Example 5-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 5-6 shows the body of the SPML request that is received by or returned to the client.
Code Example 5-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 Capabilities
Identity Manager supports the Async capabilities described in Table 5-3:
Table 5-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
Identity Manager supports the Batch capability described in Table 5-4.
Table 5-4 Batch Capability
Capability
Description
Operational Attributes
Caveats
BatchRequest
Executes a batch of requests.
None
Bulk Capabilities
Identity Manager supports the Bulk capabilities described in Table 5-5:
Table 5-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 Capabilities
Identity Manager supports the Password capabilities described in Table 5-6:
Table 5-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 (1 or less), 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 5-7 is an example ResetPasswordRequest.
Code Example 5-7 Example ResetPasswordRequest
ResetPasswordRequest rpr = new ResetPasswordRequest();
...
PSOIdentifier psoId = new PSOIdentifier(accountId, null, null);
rpr.setPsoID(psoId);
...
SetPasswordRequest Example
Code Example 5-8 is an example SetPasswordRequest.
Code Example 5-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 5-9 is an example ValidatePasswordRequest.
Code Example 5-9 Example ValidatePasswordRequest
ValidatePasswordRequest vpr = new ValidatePasswordRequest();
...
PSOIdentifier psoId = new PSOIdentifier(accountId, null, null);
vpr.setPsoID(psoId);
vpr.setPassword("apassword");
...
Suspend Capabilities
Identity Manager supports the Suspend capabilities described in Table 5-7.
Table 5-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.
Configuring Identity Manager to Use SPML 2.0This section describes how to configure to use Identity Manager to use SPML 2.0. The topics include:
Deciding Which Attributes to Manage
When 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:
You must map these attributes to the User view.
This section also provides short examples that demonstrate how to manage PSOs using SPML 2.0 support in Identity Manager.
Identity Manager provides a sample set of SPML configuration objects in the sample/spml2.xml file. You must manually import the sample/spml2.xml file because it is not imported by default when the repository is initialized. See the contents of this file for detailed information.
Note
The spml2ObjectClass attribute is not present in the User schema by default. If this attribute is not already enabled, you must manually add the spml2ObjectClass attribute to your schema before Identity Manager can function as an SPML 2.0 server.
The spml2ObjectClass attribute has been defined in the schema.xml supplied with Identity Manager, but the section where you add this attribute to the configuration is commented out. Assuming that your production schema is in a file derived from that original, you can uncomment that section, import or re-import the schema file, and restart Identity Manager to enable use of the SPML 2.0 feature.
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.
Configuring the SPML2 Configuration Object
The sample/spml2.xml file contains an out-of-the-box configuration for SPML 2.0 support. You can import this file, or one derived from this file, to define the objects that Identity Manager needs to support SPML 2.0.
You can use the SPML2 configuration type object to change how SPML 2.0 support behaves or to extend the system.
Note
See Extending the System for more information about extensions.
Configuring web.xml
If you are using a servlet container like Tomcat, you use web.xml to set up the openspmlRouter servlet, which is the servlet that handles SPML 2.0 requests.
Note
The web.xml file ships with a default installation and no action is required for this component.
The web.xml file contains an optional init-param that you can use to open a monitor window (in Swing) that displays the flow of SPML 2.0 messages. You can use this window to monitor the flow of SPML 2.0 messages, which is useful for debugging purposes.
The following example shows how to add the init-param.
<init-param>
<param-name>monitor</param-name>
<param-value>org.openspml.v2.util.SwingRPCRouterMonitor</param-value>
</init-param>
The following example contains a commented section and contains information about other init-params.
Code Example 5-10 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>
Configuring SPML Tracing
SPML provides options for turning on trace output so you can log Identity Manager’s SPML traffic and diagnose problems.
For more information about tracing SPML, see the “Tracing and Troubleshooting Identity Manager” chapter in the Identity Manager Tuning, Troubleshooting, and Error Messages book.
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. The following figure shows the OpenSPML 2.0 Toolkit architecture.
Figure 5-1 OpenSPML 2.0 Toolkit Architecture
Sample SPML 2.0 AdapterIdentity Manager provides a sample SPML 2.0 resource adapter. Using this adapter as a starting point, you can modify the content to communicate with Identity Manager installations or third-party resources that support SPML 2.0 core operations.
Note
You will find this sample adapter in the Sun Resource Extension Facility Kit on your product CD or in your install image located in /REF.