Configuring SPML

To expose the SPML interface, you must properly configure the Waveset server by installing and modifying specific repository objects and by editing the Waveset.properties file.

Instructions for configuring the SPML interface are provided in the following sections:

• Installing and Modifying Repository Objects

• Editing the Waveset.properties File

• Editing Configuration Objects

Installing and Modifying Repository Objects

The following table describes the repository objects that you must install and modify to configure SPML for Waveset.

Waveset includes a sample set of SPML configuration objects in the sample/spml.xml file. You must manually import the sample/spml.xml file because the file is not imported by default when the repository is initialized.

The sample configuration defines a person class to track the evolving standard schema defined by the SPML working group. Do not customize this class. You must keep the person class consistent with the standard schema, except when you are configuring the Service Provider SPML interface.

When configuring the Service Provider SPML interface, you must install and modify the Configuration:SPE SPML configuration object as follows:

• Configure the person class (the only object class defined by default) to use the Service Provider-specific view handler (IDMXUser).

• Use the form attribute to define a user form that translates between the SPML request or SPML response and the view.

  The form attribute can take a special value (view): in which no form processing is applied to the view. For example, the view is passed directly between the client and Waveset.

You access the Service Provider SPML interface from the following (default) path:

/servlet/spespml

For example, if you deploy Waveset in the /idm context on host:port, you can access the interface at the following URL:

http://host:port/idm/servlet/spespml

where:

• host is the machine on which you are running Waveset.

• port is the number of the TCP port on which the server is listening.

See the SPML 1.0 Specification at http://www.openspml.org for the most current information about the standard SPML schema.

Editing the Waveset.properties File

The following table describes three optional entries in the Waveset.properties file that you can use to control how SPML requests are authorized.

Editing soap.epassword and soap.password Properties

The user specified in soap.username is known as the proxy user.

You can specify only one password property for the proxy user:

• Specifying soap.password is the simplest option, but this property exposes a clear text password in the properties file.

• Specifying soap.epassword is a more secure option, but you must perform extra steps to generate an encrypted password.

Establishing a proxy user is convenient for clients because authentication is not required by the web service. This configuration is common for portal environments where the Waveset server is only accessed by other applications that handle user authentication.

Using a proxy user can be dangerous if the HTTP port on which the responding server resides is generally accessible. Anyone who knows the Waveset server’s URL and understands how to build SPML requests can configure Waveset operations for the proxy user to perform.

The SPML standard does not specify how to perform authentication and authorization. Several related web standards are available for authentication, but these standards are not yet in common use. At this time, the most common approach for authentication is to use the Secure Socket Layer (SSL) between applications and the server. Waveset does not dictate how to configure SSL.

If you cannot use a proxy user or SSL, Waveset supports a vendor-specific extension to SPML that allows the client to log in and maintain a session token, which can be used to authenticate subsequent requests. You can use the LighthouseClient class (an extension of the SpmlClient class that includes support for specifying credentials) to perform a login request and pass a session token in all SPML requests.

The Service Provider SPML interface does not support authentication and authorization. However, you can configure the Waveset SPML interface to use the IDMXUser view instead of using Service Provider SPML.

Service Provider assumes that clients accessing Waveset have been authenticated and authorized by an access management application. The client has all possible rights when using the Service Provider SPML interface.

To prevent sensitive data from being exposed between the client and Waveset, consider accessing the Service Provider SPML interface over SSL.

Creating an Encrypted Password

Use one of the following methods to create an encrypted password:

• Open the Waveset console and use the encrypt command.

• Open the Waveset Debug pages or console and view the XML for the proxy user. Find the WSUser element for the password attribute value and use that value for the soap.epassword property.

  ---

  Note –

  To access the Debug pages, open the Waveset Administrator interface and type the following URL:

  http://host:port/idm/debug

  where host is the local server where Waveset is running, and port is the TCP port on which the server is listening.

  ---

Editing Configuration Objects

Applications require a mechanism to send SPML messages and to receive SPML responses.

To configure SPML for Waveset, you must edit the following configuration objects:

• Configuration: SPML Object

• Configuration: SPMLPerson Object

• Configuration: IDM Schema Configuration Object

• TaskDefinition: SPMLRequest Object

• Deployment Descriptor

The Service Provider SPML interface has only one configuration object, Configuration:SPE SPML, which is similar to the Configuration:SPML object in structure.

Configuration: SPML Object

The Configuration: SPML object contains definitions for the SPML schemas that you want to expose, and information about how those SPML schemas are mapped into Waveset views. This information is represented by using a GenericObject that is stored as an extension of the configuration object.

The following attributes are defined in GenericObject: schemas and classes:

• Schemas. A list of strings, where each string contains the escaped XML for one SPML <schema> element. Because the SPML elements are not defined in the waveset.dtd, you cannot directly include them in an Waveset XML document. Instead, you must include them as escaped text.

• Classes. A list of objects containing information about the supported SPML classes and how those classes are mapped into views. Define one object from this list for each class defined by the SPML schemas on the schemas list.

Initially, the distinction between the two lists might be confusing. The information in the schemas list defines what Waveset returns in response to an SPML SchemaRequest message. The client uses this information to decide which attributes can be included in other messages such as AddRequest. Waveset does not care about the contents of the schemas list. This list is simply returned verbatim to the client.

You are not required to define SPML schemas. Waveset works without schemas. If you do not define an SPML schema, Waveset returns an empty response after receiving a schema request message. Without a schema, clients must rely on pre-existing knowledge about the supported classes and attributes.

Best Practice:

Writing SPML schemas is considered a best practice, because it enables you to use general purpose tools (such as the OpenSPML Browser) to build requests.

Default SPML Configuration

The following example shows the default SPML configuration. The text of the SPML schema definitions have been omitted for brevity.

Example 1–1 Default SPML Configuration

<Configuration name='SPML' authType='SPML'>
<Extension>
<Object>
  <Attribute name='classes'>
    <List>
      <Object name='person'>
        <Attribute name='type' value='User'/>
        <Attribute name='form' value='SPMLPerson'/>
        <Attribute name='default' value='true'/>
        <Attribute name='identifier' value='uid'/>
      </Object>
      <!-- Class 'user' defines no form so we'll default to a builtin 
simplified schema. I don't really like this but SimpleRpc currently depends on it.
      -->
      <Object name='user'>
        <Attribute name='type' value='User'/>
        <Attribute name='identifier' value='waveset.accountId'/>
      </Object>
      <!-- Class 'userview' defines the form "view" which causes the view 
to pass through unmodified-->      <Object name='userview'>
        <Attribute name='type' value='User'/>
        <Attribute name='form' value='view'/>
        <Attribute name='identifier' value='waveset.accountId'/>
        <Attribute name='multiValuedAttributes'>
          <List>
            <String>waveset.resources</String>
            <String>waveset.roles</String>
            <String>waveset.applications</String>
          </List>
        </Attribute>
      </Object>
      <Object name='role'>
        <Attribute name='type' value='Role'/>
        <Attribute name='form' value='SPMLRole'/>
        <Attribute name='default' value='true'/>
        <Attribute name='identifier' value='name'/> <!--  attribute ...for now? -->
      </Object>
</Configuration>

Two classes are defined in this example:

• The standard person class

• An Waveset extension named request

The following attributes are supported in a class definition:

• name – Identifies the class name. The name value can correspond to an <ObjectClassDefinition> element in an SPML schema, although this value is not required. You can use this name as the value for the objectclass attribute in an AddRequest or a SearchRequest.

• type – Defines the Waveset view type used to manage instances of this class. Generally, this attribute is User, but it can be any repository type that is accessible through a view. For information about views, see Oracle Waveset 8.1.1 Deployment Reference.

• form – Identifies the name of a configuration object containing a form. This attribute contains the rules for transforming between the external attributes defined by the class and the internal view attributes.

• default – Specify true to indicate that this attribute is the default class for this type only. For more than one SPML class implemented on the same type, you must designate one class as the default.

• identifier – Each class typically defines one attribute as the object identity. The identifier attribute in the class definition specifies which attribute represents the identity. Where possible, use the identifier attribute value as the name of the corresponding repository object you create to represent the instance.

• filter – When evaluating an SPML search request for a class, you typically include all repository objects associated with that class in that search. This approach is fine for User objects, but some classes might be implemented by using generic types such as TaskDefinition or Configuration, not all of which are considered instances of the SPML class.

  To prevent unwanted objects from being included in the search, you can specify the filter attribute. The value is expected to be an <AttributeCondition> element or a <List> of <AttributeCondition> elements. Because custom classes are typically created for the User type, using a filter is uncommon. The default configuration uses filters to expose a subset of the TaskInstance objects that are known to have been created to handle asynchronous SPML requests.

Default Schemas

The schemas attribute contains a list of strings that contain the escaped XML for an SPML <schema> element. If you examine the spml.xml file, note that the schema elements are surrounded by a CDATA-marked section. Using CDATA-marked sections is convenient for escaping long strings of XML. When Waveset normalizes the spml.xml file, the CDATA-marked sections are converted into strings containing &lt; and &gt; character entities.

The default SPML configuration includes two schemas:

• A standard schema that is being defined by the SPML working group.

• A custom schema that is defined by Waveset. Do not customize these schemas.

  The Waveset schema contains a class definition for request and various extended requests for common account management operations.

Configuration: SPMLPerson Object

Each class defined in the Configuration:SPML object typically has an associated form object containing the rules for transforming between the external attribute model defined by the class and the internal model defined by the associated view.

The following example shows how the standard person class references a form.

Example 1–2 Standard Person Class Referencing a Form

<Configuration name='SPMLPerson'>
   <Extension>
      <Form>
         <Field name='cn'>
            <Derivation><ref>global.fullname</ref></Derivation>
         </Field>
         <Field name='global.fullname'>
            <Expansion><ref>cn</ref></Expansion>
         </Field>
         <Field name='email'>
            <Derivation><ref>global.email</ref></Derivation>
         </Field>
         <Field name='global.email'>
            <Expansion><ref>email</ref></Expansion>
         </Field>
         <Field name='description'>
            <Derivation>      
               <ref>accounts[Lighthouse].description</ref>
            </Derivation>
         </Field>
         <Field name='accounts[Lighthouse].description'>
            <Expansion><ref>description</ref></Expansion>
         </Field>
         <Field name='password'>
            <Derivation><ref>password.password</ref></Derivation>
         </Field>
         <Field name='password.password'>
            <Expansion><ref>password</ref></Expansion>
         </Field>
         <Field name='sn'>
            <Derivation><ref>global.lastname</ref></Derivation>
         </Field>
         <Field name='global.lastname'>
            <Expansion><ref>sn</ref></Expansion>
         </Field>
         <Field name='gn'>
            <Derivation><ref>global.firstname</ref></Derivation>
         </Field>
         <Field name='global.firstname'>
            <Expansion><ref>gn</ref></Expansion>
         </Field>
         <Field name='telephone'>
            <Derivation>
               <ref>accounts[Lighthouse].telephone</ref>
            </Derivation>
         </Field>
         <Field name='accounts[Lighthouse].telephone'>
            <Expansion><ref>telephone</ref></Expansion>
         </Field>
      </Form>
   </Extension>
</Configuration>

SPML class forms

• Contain no <Display> elements

• Are only defined for data transformation

• Are not intended for interactive editing

Each attribute in a class definition contains two field definitions:

• One field uses a <Derivation> expression to transform the internal view attribute name to the external name.

• One field uses an <Expansion> expression to transform the external name to the internal name.

The form is processed in such a way that when attributes are returned to the client, only the result of the <Derivation> expressions are included. When attributes are being sent from the client to the server, only <Expansion> expression results are assimilated back into the view. The effect is similar to the schema map of a Resource definition.

Configuration: IDM Schema Configuration Object

If you want to use attributes in an SPML search filter, you must define those attributes as extended attributes for Waveset users. Waveset stores extended attribute values in the repository, even when that value is also stored as a resource account attribute.

Try to minimize the use of extended attributes. Too many extended attributes can increase the repository size and might cause consistency problems between attributes stored in Waveset and the real value of the attribute stored on a resource. To use an attribute in an Waveset query, you must declare the attribute as an extended attribute to ensure that the value is accessible when the repository query indexes are built.

To include attributes in a user’s set of summary attributes, you must define those attributes as extended attributes. You can use summary attributes to optimize searches by avoiding deserialization of the object XML, and instead return only a few of the most important user attributes. In the Waveset SPML implementation, summary attributes are returned when you do not explicitly provide a list of return attributes in the search request.

In the following example, firstname, lastname, fullname, description, and telephone are extended attributes that are present on the User IDMObjectClassConfiguration after being defined in IDMAttributeConfigurations. Only firstname, lastname, and telephone are queryable and summary attributes.

Example 1–3 telephone and description Declared as Extended Attributes

<Configuration name="IDM Schema Configuration"
                  id=’#ID#Configuration:IDM_Schema_Configuration’
                  authType=’IDMSchemaConfig’>
       <IDMSchemaConfiguration>
           <IDMAttributeConfigurations>
               <!-- this is the standard set -->
               <IDMAttributeConfiguration name=’firstname’
                                          syntax=’STRING’/>
               <IDMAttributeConfiguration name=’lastname’
                                          syntax=’STRING’/>
               <IDMAttributeConfiguration name=’fullname’
                                          syntax=’STRING’/>
               <!-- these are the SPML extensions -->
               <IDMAttributeConfiguration name=’description’
                                          syntax=’STRING’/>
               <IDMAttributeConfiguration name=’telephone’
                                          syntax=’STRING’/>
           </IDMAttributeConfigurations>
           <IDMObjectClassConfigurations>
               <IDMObjectClassConfiguration name=’User’
                                            extends=’Principal’
                                            description=’User description’>
                   <IDMObjectClassAttributeConfiguration name=’firstname’
                                                         queryable=’true’
                                                         summary=’true’/>
                   <IDMObjectClassAttributeConfiguration name=’lastname’
                                                         queryable=’true’
                                                         summary=’true’/>
                   <IDMObjectClassAttributeConfiguration name=’fullname’/>
                   <IDMObjectClassAttributeConfiguration name=’description’/>
                   <IDMObjectClassAttributeConfiguration name=’telephone’
                                                         queryable=’true’
                                                         summary=’true’/>
               </IDMObjectClassConfiguration>
           </IDMObjectClassConfigurations>
       </IDMSchemaConfiguration>
   </Configuration>

You can customize the list of attributes according to the needs of your site.

The names you choose for extended attributes depend on the mappings performed in the class form. Because the default SPMLPerson form maps sn into lastname, you must declare the extended attribute as lastname. The form does not transform the name of telephone or description, so the extended attribute name comes directly from the SPML schema.

Beyond declaring extended attributes, you must also modify the same Configuration: object to declare which of the attributes are queryable, or usable in an SPML filter, and which attributes are summary attributes to be returned by an optimized search result.

TaskDefinition: SPMLRequest Object

The spml.xml file also includes a brief definition for a new system task named SpmlRequest. You can use this task to implement asynchronous SPML requests. When the server receives an asynchronous request, it launches a new instance of this task and passes the SPML message as an input variable for the task. The server then returns the task instance repository ID in the SPML response for later status requests. For example:

<TaskDefinition name=’SPMLRequest’
   executor=’com.waveset.rpc.SpmlExecutor’
   execMode=’asyncImmediate’
   resultLimit=’86400’>
</TaskDefinition>

Do not change the definition name, the executor name, or the execution mode. You can change the resultLimit value. When asynchronous requests have completed, the system typically retains the result value for a specified time so the client can issue an SPML status request to obtain the results. How long to retain these results is site-specific.

Use a positive resultLimit value to specify how long (in seconds) the system can retain results after completing a task. The default value for SPMLRequest is typically 3600 seconds or approximately one hour. Other tasks default to 0 seconds unless you change the task name to a different value.

If negative, the request instance is never removed automatically.

To avoid cluttering the repository, set the resultLimit value to the shortest possible time.

The Service Provider SPML interface does not support asynchronous requests.

Deployment Descriptor

You must edit the Waveset deployment descriptor, typically found in the WEB-INF/web.xml file, to contain a declaration for the servlet that receives SPML requests.

If you are having difficulty contacting the SPML web service, look in the web.xml file for a servlet declaration. The following example shows a servlet declaration.

Example 1–4 Servlet Declaration

<servlet>
   <servlet-name>rpcrouter2</servlet-name>
   <display-name>OpenSPML SOAP Router</display-name>
   <description>no description</description>
   <servlet-class>
      org.openspml.server.SOAPRouter
   </servlet-class>
   <init-param>
      <param-name>handlers</param-name>
      <param-value>com.waveset.rpc.SimpleRpcHandler</param-value>
   </init-param>
   <init-param>
      <param-name>spmlHandler</param-name>
      <param-value>com.waveset.rpc.SpmlHandler</param-value>
   </init-param>
   <init-param>
      <param-name>rpcHandler</param-name>
      <param-value>com.waveset.rpc.RemoteSessionHandler</param-value>
   </init-param>
</servlet>

This declaration allows you to access addRequest, modifyRequest, and searchRequest web services through the URL:

http://<host>:<port>/idm/servlet/rpcrouter2

where

• host is the machine on which you are running Waveset.

• port is the number of the TCP port on which the server is listening.

Although you can, you are not required to define a servlet-mapping. Do not modify the contents of this servlet declaration.