Introduction to SPML

Service Provisioning Markup Language (SPML) is an XML representation for creating service requests to provision user accounts or for processing service requests related to the management of user account services. As discussed earlier in this chapter, service provisioning is a loosely defined term. According to the OASIS SPML specification (refer to [SPML10], pp. 9-10), provisioning refers to "the automation of all the steps required to manage (set up, amend, and revoke) user or system access entitlements or data relative to electronically published services." The scope of service provisioning is primarily the management of user account services, not the underlying operating systems or application environment.

OASIS's service provisioning introduces the SPML domain model, which uses a Requesting Authority (a client requester that creates service provisioning requests to a known service point) to send service provisioning requests to the Provisioning Service Point (a service provider that intercepts service provisioning requests and processes them). The Provisioning Service Point handles the service provisioning request and creates or modifies user account information in the Provisioning Service Targets (target application systems where the service provisioning requests are executed and implemented).

SPML is different from SAML (refer to Chapter 12 for details). SPML defines the processes and steps that are required in order to prepare for user account services to be available, while SAML defines security assertions related to authentication or authorization after the user accounts are available. Directory Services Markup Language (DSML) is an XML specification for expressing directory queries, updates, and the results of directory operations. SPML is different from DSML in that SPML may use directory servers (using DSML) as one of the underlying data store mechanisms to implement some of the user account service requests.

Like any SOAP-based messaging, SPML faces security threats such as message replay, message insertion, message deletion, and message modification. The security protection mechanisms discussed in Chapter 6, "Web Services SecurityStandards and Techniques," is also applicable here.

Service Provisioning Operations

The SPML version 1.0 specification allows security architects and developers to perform the following operations:

• Add Operation. The add operation uses the message AddRequest (see Example 13-2) to allow the Requesting Authority (a special term used in SPML for a system that is authorized to make a service request for a resource) to add a new provisioning object, which may be a user account or user profile in the target system. It specifies the user account information in the element <attributes>. The service provisioning system will respond to the service request using a message AddResponse (see Example 13-1), where any error message will be returned in the element <errorMessage>.

• Modify Operation. The modify operation uses the message ModifyRequest to allow the Requesting Authority to make a change request to the provisioning object. It specifies the change request in the element <modifications>. The service provisioning system will respond to the change request using a message ModifyResponse, where any error message will be returned in the element <errorMessage>.

• Delete Operation. The delete operation uses the message DeleteRequest to allow the Requesting Authority to delete a unique identifier for a provisioning data set such as user account or managed data. It specifies the unique identifier (for example, e-mail address) in the element <identifier>. The service provisioning system will respond to the deletion request using the message DeleteResponse, where any error message will be returned in the element <errorMessage>.

• Search Operation. The search operation uses the message SearchRequest to allow an SPML client to perform a search of provisioning objects (user information defined or associated with the service provisioning system) by specifying partial user information, such as last name or part of the directory server objects (for example, "cn=raylai"). It specifies the starting point in the element <searchBase>, the search criteria in the element <filter>, and the attributes to be returned in the element <attributes>. Upon completion of the search operation, the provisioning system will return the search result in the element <searchResultEntry> of the message SearchResponse. Similarly, any error message will be returned in the element <errorMessage> of the SearchResponse message.

• Extended Operations. The purpose of the extended operations is to specify additional or new operations for services that are not defined or provided in the existing protocol or specification. Security architects and developers can specify the custom operation in the elements <providerIdentifier> and <operationIdentifier>, and the user object details in the elements <identifier> and <attributes>. For example, if the security architects and developers want to define an extended operation to delete a mailbox, they may specify the service provider object identifier (such as 1.2.3.4.5.678.7.6.5.4.1.1.1.2.3456) in the element <providerIdentifer> and the operation identifier (such as urn:namredips.com. mailservice.ops:purge) in the element <operationIdentifier> with the mailbox ID (such as [e-mail]) in the element <identifier>.

The SPML specification allows service provisioning products the flexibility to implement how to handle and process service provisioning requests. It defines the language semantics of add, delete, search, and extended operations. Nevertheless, it does not specify the underlying operations of how to create a user account in an application system.

Features in SPML

There are a few unique design features in the SPML version 1.0 specification that are worth discussing. They allow security architects and developers to build SPML-enabled interfaces or integrate SPML-enabled products with their existing architecture with more flexibility and extensibility. These unique design features include:

• Flexible Request-Reply Model. SPML supports both synchronous (or singleton request) and asynchronous (or multi-request batch) models to meet different technical requirements. In the synchronous request-reply model, the client (also known as the Requesting Authority) creates a session and issues a request to provision a user account. While it is waiting for the server to reply to the service provisioning request, the client will hold the session by using a "blocking" wait loop. In other words, it will not issue any new service provisioning request or handle other processing logic while waiting for the server response. The synchronous model is useful for legacy systems that support only synchronous communication. In the asynchronous request-reply model, the client and the server can freely exchange service provisioning requests and replies in any order or sequence. This allows the service provisioning system to manage a large volume of service provisioning transactions simultaneously.

• Extensibility Using the Open Content Model. The SPML schema follows an open content model in which architects and developers can add additional child elements or attributes to extend the service provisioning requests on top of standard schema. This allows individual service provisioning products to add custom information, such as additional user account profile details or configuration management details, in the SPML schema for the target application systems.

• Custom Error Handling. Error codes are important in handling error control for service provisioning requests. Different service provisioning systems usually have their own error code system that may not be shared and reusable by other systems. When returning an error to a service request, it is fairly helpful to use custom error handling that includes an error message that carries information other than just the specific error code. In SPML, errors are reported in the attribute "error" in the response message if the result of the SPML request shows a failure status in the attribute "result." For example, Example 13-1 illustrates an example of the message addResponse that shows a custom error status for a request to add the e-mail account [e-mail]. The custom error status is a non-standard error code in SPML that provides an additional detailed description of the service request error. In the sample message, the attribute "Result" indicates whether this is a success, failure, or pending operation. The attribute "ErrorCode" details the reason for the failure. The attribute "errorMessage" further provides the description of the custom error code. This allows security architects and developers to define their custom error messages and descriptions.

Example 13-1. Sample SPML message for custom error handling

<addResponse    request     result="urn:oasis:names:tc:SPML:1.0#failure"     error="urn:oasis:names:tc:SPML:1.0#customError"     errorMessage="my custom error message">    <identifier         type="urn:oasis:names:tc:SPML:1.0#EMailAddress">       <spml:id>[e-mail]</id>    </identifier>    <attributes>       <attr name="mailBoxLimit">          <value>1000MB</value>       </attr>    </attributes> </addResponse> 

Adopting a SAML Implementation

There are a few SPML-compliant commercial service provisioning systems available, such as Sun Java System Identity Manager (previously known as Waveset Technologies' Lighthouse) and Thor's Xellerate. Refer to the "References" section for more vendor products. These service provisioning systems allow creating and managing user account information as well as synchronizing user passwords across systems. Some products come with an SPML API library that allows custom applications or legacy systems to intercept and process SPML service requests. If security architects and developers want to use an open source implementation, they can also download OpenSPML Toolkit from http://www.openspml.org as well.

Example 13-2 provides a sample SPML client using OpenSPML Toolkit (supporting SPML version 0.5). The OpenSPML Toolkit can be installed on any Web container (such as Apache Tomcat Web container or J2EE System Application Server).

Example 13-2. SPML client to add a user

package com.csp.provisioning; import java.util.HashMap; import org.openspml.client.SpmlClient; import org.openspml.message.AddRequest; import org.openspml.message.AddResponse; public class AddUser {     protected SpmlClient client = new SpmlClient();     protected AddRequest request = new AddRequest();     protected HashMap userAttr = new HashMap();     protected AddResponse response;     protected final String url = "http://localhost:8080/lighthouse/servlet/ rpcrouter2";     protected final String firstName = "Mary";     protected final String lastName = "Parker";     protected final String fullName = "Mary Jane Parker";     protected final String password = "peterIsSpidey123";     protected final String email = "[e-mail]";     protected final String identifier = "maryjane";     /**      * Creates a new instance of AddUser      */     public AddUser() {         try {             System.out.println             ("Creating a SPML request to add user");             create();             System.out.println               ("SPML request generation is complete.");         } catch (Throwable addUser) {             // add your exception handling             System.out.println(addUser.toString());         }     }     /**      * Create SPML request for add user      *      * @exception Exception ex      */     private void create() throws Exception {         this.client.setTrace(true);         // Use a generic SPML client         // Assumptions         // 1. SOAPRouter and TestSpmlHandler are registered using this URL below         //    customize this URL for your local environment         // 2. Lighthouse is a resource resembling your SPML server         this.client.setUrl(this.url);         this.request.setIdentifier(this.identifier);         this.request.setObjectClass("user");         // define user attributes         this.userAttr.put("password", this.password);         this.userAttr.put("email", this.email);         this.userAttr.put("firstname", this.firstName);         this.userAttr.put("lastname", this.lastName);         this.userAttr.put("fullname", this.fullName);         this.request.setAttributes(userAttr);         // generate SPML request to add user         response =             (AddResponse)this.client.request(request);         this.client.throwErrors(response);     }     public static void main(String args[]) {         new AddUser();     } } 

Executing the sample SPML client will create an SPML request, as depicted in Example 13-3. This is an add operation to create an e-mail user account for user Mary Jane Parker.

Example 13-3. Output from the sample SPML client

C:\Dev\OpenSPML\src>java -classpath %SPML_LIB%\openspml.jar;%SPML_LIB%\soap.jar; %SPML_LIB%\j2ee.jar;%SPML_LIB%\xercesImpl.jar;%SPML_LIB%\xmlParserAPIs.jar com.csp.provisioning.AddUser SpmlClient: sending to http://localhost:82/lighthouse/servlet/rpcrouter2 <spml:addRequest xmlns:spml='urn:oasis:names:tc:SPML:1:0' xmlns:dsml='urn:oasis: names:tc:DSML:2:0:core'>   <spml:identifier type='urn:oasis:names:tc:SPML:1:0#GUID'>     <spml:id>maryjane</spml:id>   </spml:identifier>   <spml:attributes>     <dsml:attr name='objectclass'>       <dsml:value>user</dsml:value>     </dsml:attr>     <dsml:attr name='fullname'>       <dsml:value>Mary Jane Parker</dsml:value>     </dsml:attr>     <dsml:attr name='email'>       <dsml:value>[e-mail]</dsml:value>     </dsml:attr>     <dsml:attr name='password'>       <dsml:value>peterIsSpidey123</dsml:value>     </dsml:attr>     <dsml:attr name='lastname'>       <dsml:value>Parker</dsml:value>     </dsml:attr>     <dsml:attr name='firstname'>       <dsml:value>Mary</dsml:value>     </dsml:attr>   </spml:attributes> </spml:addRequest>