Chapter 5 Using SPML 2.0 with Identity Manager Web Services

Previous Contents Index Next
Sun[TM] Identity Manager 8.0 Deployment Tools

Chapter 5
Using SPML 2.0 with Identity Manager Web Services

This 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 Begin

Overview

Configuring Identity Manager to Use SPML 2.0

Extending the System

Sample SPML 2.0 Adapter

Before You Begin

Review the following sections before you start working with Identity Manager Web Services:

Intended Audience

Important Notes

Related Documentation and Web Sites

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.

http://www.openspml.org

Overview

This section explains some basic concepts about SPML 2.0:

How SPML 2.0 Compares to SPML 1.0

How SPML 2.0 Concepts Are Mapped to Identity Manager

Supported SPML 2.0 Capabilities

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).

You can “extend” SPML 1.0 using ExtendedRequest, but there is no guidance about what those requests can be. SPML 2.0 defines a set of “standard capabilities” that allow you to add support in well-defined ways.

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.

Table 5-1  SPML Capabilities

SPML 1.0

SPML 2.0

Add

Add

Modify

Modify

Delete

Delete

Lookup

Lookup

SchemaRequest

ListTargets

Search

Search as a “standard” Capability (not supported this release)

ExtendedRequest

Captured in “standard” Capabilities:

Async: Asynchronous processing of requirements

Batch: Process a batch of requests

Bulk: Process modifies or deletes using iteration

Password: Change, set, reset, validate, or expire passwords

Reference: Refer to PSOs between targets

Suspend: Enable or disable PSOs

Update: Find change records for objects that have been updated (can also be captured in “custom” Capabilities.)

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

PSO

PSOIdentifier

Open Content and Operational Attributes

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

A repoType that is provided to support additional targets later.

A form that maps the attributes to and from the Identity Manager view.

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

Async Capabilities

Batch Capability

Bulk Capabilities

Password Capabilities

Suspend Capabilities

Note

Identity Manager does not support the Reference capability, the Search capability, the Updates capability, or the CapabilityData class.

None of the supported capabilities use the CapabilityData class, so Identity Manager does not support it. (The CapabilityData class is used to implement custom capabilities.)

The OpenSPML 2.0 Toolkit supports CapabilityData in the marshallers, unmarshallers, and so forth.

Core Capabilities

Identity Manager supports the following Core capabilities:

Table 5-2  Core Capabilities

Capability

Description

Caveats

AddRequest

Adds a specified PSO to the system.

Identity Manager officially supports only a single target.

DeleteRequest

Deletes a specified PSO from the system.

Identity Manager officially supports only a single target.

ListTargetsRequest

Lists the targets that are available through Identity Manager.

Identity Manager officially supports a single target.

Identity Manager does not require you to use listTargets as the first call in a conversation; however, it does allow operationalAttributes on this request to specify a username/password pair for establishing a session with the server. (You can also use Waveset.properties.)

In general, it is more efficient to login and use the session token. Identity Manager provides a class called SessionAwareSpml2Client for this purpose.

LookupRequest

Finds and returns the attributes of the named PSO.

None

ModifyRequest

Modifies specified PSO attributes.

Due to a discrepancy between the main SPML 2.0 specification and the DSML Profile specification, Identity Manager does not support select (and component, etc.). Instead Identity Manager uses the DSML Modification Mode and elements according to the DSML Profile.

Note

General caveats include:

You can provide username and password values for the ListTargetsRequest request. These values are used as credentials to establish a session, which is identified by the session token value returned in theListTargetsRequest response. This session is the context for all following requests that include that session token value as an operational attribute.

Another way to set up the session is to provide values for the soap.username and soap.password attributes in Waveset.properties. In this case, no session token is required.

Identity Manager supports only the DSML Profile.

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-1  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

client.login("configurator", "password");

// AddRequest

String rid = "rid-spmlv2"; // The RequestId is not strictly required.

Extensible data = new Extensible();

data.addOpenContentElement(new DSMLAttr("accountId", user));

data.addOpenContentElement(new DSMLAttr("objectclass", "spml2Person"));

data.addOpenContentElement(new DSMLAttr("credentials", password));

AddRequest add = new AddRequest(rid, // String requestId,

ExecutionMode.SYNCHRONOUS, // ExecutionMode executionMode,

null, // PSOIdentifier type,

null, // PSOIdentifier containerID,

data, // Extensible data,

null, // CapabilityData[] capabilityData,

null, // String targetId,

null // ReturnData returnData

);

// Submit the request

Response res = client.send( add );

%>

<%= res.toString()%>

</body>

</html>

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.0

This section describes how to configure to use Identity Manager to use SPML 2.0. The topics include:

Deciding Which Attributes to Manage

Configuring the SPML2 Configuration Object

Configuring web.xml

Configuring SPML Tracing

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.

Note

You can have more than one attribute in the 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:

accountId

objectclass

credentials

firstname

lastname

emailAddress

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>



<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>

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 System

You 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.

If you do not want to use SOAP, just replace the dispatcher in the first case.

If you do not want to use HTTP, replace the router with a different kind of servlet.

If you want different XML parsing, replace the Marshaller with your own.

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 Adapter

Identity 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.

Previous      Contents      Index      Next

. Copyright 2008 Sun Microsystems, Inc. All rights reserved.


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.


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 1.0	SPML 2.0
Add	Add
Modify	Modify
Delete	Delete
Lookup	Lookup
SchemaRequest	ListTargets
Search	Search as a “standard” Capability (not supported this release)
ExtendedRequest	Captured in “standard” Capabilities: Async: Asynchronous processing of requirements Batch: Process a batch of requests Bulk: Process modifies or deletes using iteration Password: Change, set, reset, validate, or expire passwords Reference: Refer to PSOs between targets Suspend: Enable or disable PSOs Update: Find change records for objects that have been updated (can also be captured in “custom” Capabilities.)


Note	See the OASIS SPML 2.0 Specifications at http://www.openspml.org/.


Note	Identity Manager only manages Users and requires you to define a user extended attribute called spml2ObjectClass.


Note	Identity Manager does not support the Reference capability, the Search capability, the Updates capability, or the CapabilityData class. None of the supported capabilities use the CapabilityData class, so Identity Manager does not support it. (The CapabilityData class is used to implement custom capabilities.) The OpenSPML 2.0 Toolkit supports CapabilityData in the marshallers, unmarshallers, and so forth.

Capability	Description	Caveats
AddRequest	Adds a specified PSO to the system.	Identity Manager officially supports only a single target.
DeleteRequest	Deletes a specified PSO from the system.	Identity Manager officially supports only a single target.
ListTargetsRequest	Lists the targets that are available through Identity Manager.	Identity Manager officially supports a single target. Identity Manager does not require you to use listTargets as the first call in a conversation; however, it does allow operationalAttributes on this request to specify a username/password pair for establishing a session with the server. (You can also use Waveset.properties.) In general, it is more efficient to login and use the session token. Identity Manager provides a class called SessionAwareSpml2Client for this purpose.
LookupRequest	Finds and returns the attributes of the named PSO.	None
ModifyRequest	Modifies specified PSO attributes.	Due to a discrepancy between the main SPML 2.0 specification and the DSML Profile specification, Identity Manager does not support select (and component, etc.). Instead Identity Manager uses the DSML Modification Mode and elements according to the DSML Profile.


Note	General caveats include: You can provide username and password values for the ListTargetsRequest request. These values are used as credentials to establish a session, which is identified by the session token value returned in theListTargetsRequest response. This session is the context for all following requests that include that session token value as an operational attribute. Another way to set up the session is to provide values for the soap.username and soap.password attributes in Waveset.properties. In this case, no session token is required. Identity Manager supports only the DSML Profile.

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

Capability	Description	Operational Attributes	Caveats
BulkDeleteRequest	Executes a bulk delete of PSOs.	None
BulkModifyRequest	Executes a bulk modify of matching PSOs.	None

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.

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.


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.


Note	See Extending the System for more information about extensions.


Note	The web.xml file ships with a default installation and no action is required for this component.


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.