29 Using SPML Services

Oracle Identity Manager provides client applications with the Identity Management service, which makes use of the Service Provisioning Markup Language (SPML).

This chapter describes the SPML XSD Web service interfaces supported by Oracle Identity Manager. It contains these topics:

Introduction
Create Identity (SPML Core Service: addRequest)
Modify Roles, Change Attributes and Role Memberships (SPML Core Service: modifyRequest)
Delete an Identity or Role (SPML Core Service: deleteRequest)
Check Request Status (SPML Core Service: statusRequest)
List Available Targets (SPML Core Service: listTargets)
Disable a User (SPML Suspend Service: suspendRequest)
Enable a User (SPML Suspend Service: resumeRequest)
Check if User is Active (SPML Suspend Service: activeRequest)
Validate a Username (SPML Username Service: validateUsername)
Obtain a Username (SPML Username: suggestUsername)
Securing SPML Web Services

29.1 Introduction

This section introduces the use of SPML services using XSD profile in Oracle Identity Manager.

29.1.1 About SPML Interactions

Oracle Identity Manager provides the identity management service to enable client applications to manage identities (users and roles). The service makes use of the Service Provisioning Markup Language (SPML), which is an XML framework based on specifications from the OASIS committee that provides for exchanging user, resource and service provisioning information.

This document lists and describes the SPML interactions that Oracle Identity Manager supports.

Profile Support

SPML has two profiles: the XSD profile and the DSML profile. This release of Oracle Identity Manager makes use of the XSD profile.

Types of Interactions

The SPML specification allows interactions to be synchronous or asynchronous.

Oracle Identity Manager supports only asynchronous interactions for add, modify, delete, suspend, resume request. For username services all services are synchronous.

Oracle Identity Manager responds immediately with a pending status, and it is up to the requestor to get the current state by issuing a statusRequest.

Search APIs

For search APIs in the identity management realm, refer to the APIs supported by IGF/CARML interactions.

29.1.2 Integration Interface

The integration interface is defined in terms of the Service Provisioning Markup Language (SPML). In Oracle Identity Manager, implementation of SPML supports managing identities and roles, and username reservation capabilities.

Both the asynchronous and synchronous execution modes are supported, although not all services support both modes. If an invalid mode is specified in a request, the service returns an unsupportedExecutionMode SPML error code.

To use the SPML services, the application must create a Web service client. The WSDL for this client is available at the following URL:

http://OIM_HOST:OIM_PORT/spml-xsd/SPMLService?WSDL

As an alternative, you can also navigate to the WSDL and XML schema definitions using a hosted SPML Web service end-point URL.

The XSD (oracle_common_pso.xsd) is available at:$OIM_HOME/features/spml-xsd.jar

29.2 Create Identity (SPML Core Service: addRequest)

To create an identity with user or role attributes, you implement the addRequest operation which supports asynchronous execution mode. Successful request submission returns a request submission tracking identifier and the request status is listed as pending.

When creating a user, you can also assign role memberships to that user using the addRequest operation. To do this you must use the SPML reference capability with typeOfReference set to memberOf and include the role GUID as PSO reference ID.

Note:

If the username or password attributes are not provided, those attributes can be auto-generated in Oracle Identity Manager if the appropriate plug-ins are installed.

Table 29-1 Identity Creation with addRequest

Item/Feature	Description
SPML Execution Mode	Asynchronous only
Input	`addRequest` element as defined by [SPMLv2]. Optional, reference capability for role memberships.
Output	`addResponse` element as defined by [SPMLv2].
Processing	The add operation allows adding identity. Optionally, existing roles may be assigned to the identity. Other runtime errors are reported using `customError` SPML custom error code. Only validation errors are returned in the Response. No request ID is returned.
Examples	See the Appendix for these examples: "SPML Example - Add User" "SPML Example – Add User with Role Assignment"

29.3 Modify Roles, Change Attributes and Role Memberships (SPML Core Service: modifyRequest)

You implement the SPML modifyRequest service for these tasks:

to assign or revoke role memberships from an existing user (identity)
to modify an existing role
to modify user attributes

Table 29-2 Role Membership Management with modifyRequest

Item/Feature	Description
SPML Execution Mode	Asynchronous
Input	`modifyRequest` element as defined by [SPMLv2]. Use modificationMode="`delete`" for deleting role membership and modificationMode="`add`" for adding role membership. Role memberships declared using Reference capability, with typeOfReference="`inheritsFrom`" and Role GUID as PSO ID.
Output	`modifyResponse` element as defined by [SPMLv2].
Processing	The `modifyRequest` operation allows modifying an existing identity or existing role. This operation checks for SPML execution mode for both identity and role. Invalid execution mode returns an `unsupportedExecutionMode` SPML error code. If the modify request does not contain identity PSO object, or contains invalid GUIDs the operation returns `malformedRequest` or `invalidIdentifier` SPML malformed request error respectively. Other runtime errors are reported using customError SPML custom error code.
Examples	See the Appendix for these examples: Section C.11, "SPML Example - Assign Role Membership" Section C.12, "SPML Example – Revoke Role Membership"

29.4 Delete an Identity or Role (SPML Core Service: deleteRequest)

You implement the SPML deleteRequest service for these tasks:

to delete a role membership from an existing identity (user)
to delete an existing role or user

Table 29-3 Role Membership Deletion with deleteRequest

Item/Feature	Description
SPML Execution Mode	Asynchronous
Input	`deleteRequest` element as defined by [SPMLv2].
Output	`deleteResponse` element as defined by [SPMLv2].
Processing	The deleteRequest operation allows deletion of an existing identity or existing role. This operation checks for SPML execution mode for both identity and role. Invalid execution mode returns an `unsupportedExecutionMode` SPML error code. If the delete request does not contain identity PSO object, or contains invalid GUIDs the operation returns `malformedRequest` or `invalidIdentifier` SPML malformed request error respectively. Other runtime errors are reported using `customError` SPML custom error code.
Examples	See the example "SPML Example - Delete Role".

29.5 Check Request Status (SPML Core Service: statusRequest)

The status operation enables a requestor to determine whether an asynchronous operation has:

failed
pending
completed successfully

For any async operation, after the request is submitted, any errors after validation errors cannot be returned in the response. The errors, if any, are returned in the status response. If the statusRequest returns request status as failed, then the statusResponse might have some error message as well.

Table 29-4 Check Request Status

Item/Feature	Description
SPML Execution Mode	Synchronous
Input	`statusRequest` element as defined by [SPMLv2].
Output	`statusResponse` element as defined by [SPMLv2].
Processing	The status operation accepts attribute `asyncRequestID` which contains the asynchronous operation identifier. If the operation identifier is invalid the `noSuchIdentifier` error code will be returned. Result of the status operation is provided in the status attribute of `statusResponse` element.
Example	See the example Section C.18, "SPML Example - Status Request"

Request Example

Here is a request example:

<statusRequest xmlns="urn:oasis:names:tc:SPML:2:0:async"
 
     requestID="3456563" asyncRequestID="75779"/>

The Oracle Identity Manager request ID whose status is desired, must be provided to asyncRequestID.

Response Example

Here is a response example:

<statusResponse xmlns="urn:oasis:names:tc:SPML:2:0:async"     
 
requestID="3456563" status="success">    
 
<addResponse requestID="75779" status="pending"/>
 
</statusResponse>

29.6 List Available Targets (SPML Core Service: listTargets)

The SPML listTargets service enables a requestor to obtain the set of targets that a provider makes available for provisioning. The service also returns:

the object types that each target supports
the set of capabilities that the provider supports for each object in each target

The only target currently supported is Oracle Identity Manager; the object types that we support are all Oracle Identity Manager object types.

Table 29-5 Obtaining Targets with listTargets

Item/Feature	Description
SPML Execution Mode	Synchronous
Input	`listTargetsRequest` element as defined by [SPMLv2].
Output	`listTargetsResponse` element as defined by [SPMLv2].
Processing	Only the XML Schema profile is supported. Any another profile request results in a failure with the `unsupportedProfile` error code. A single, static provisioning target named `Oracle Identity Manager` is supported. The response is generated by inserting the PSO object schemas, the list of supported capabilities for each PSO, and the schema for the operation data capability into a `listTargetsResponse` element.
Examples	See the example "SPML Example - List Target".

29.7 Disable a User (SPML Suspend Service: suspendRequest)

The suspend operation enables the requestor to suspend a user.

Table 29-6 Suspending a User with suspendRequest

Item/Feature	Description
SPML Execution Mode	Asynchronous
Input	`suspendRequest` element as defined by [SPMLv2].
Output	`suspendResponse` element as defined by [SPMLv2].
Processing	This operation requires a valid user PSO ID and optionally an effective suspension date. If the PSO identifier is invalid, the `noSuchIdentifier` error code is returned. The suspend operation is applicable for users only. It returns `unsupportedOperation` error if the PSO object is not an identity.
Examples	See the example "SPML Example - Suspend User".

29.8 Enable a User (SPML Suspend Service: resumeRequest)

The resumeRequest operation enables the requestor to resume/enable a suspended user.

Table 29-7 Re-enabling a User with resumeRequest

Item/Feature	Description
SPML Execution Mode	Asynchronous
Input	`resumeRequest` element as defined by [SPMLv2].
Output	`resumeResponse` element as defined by [SPMLv2].
Processing	This operation requires a valid user PSO ID and optionally an effective resumption date. If the PSO identifier is invalid, the `noSuchIdentifier` error code is returned. The resume operation is applicable for users only. It returns `unsupportedOperation` error if the PSO object is not an identity.
Examples	See the example "SPML Example - Resume User".

29.9 Check if User is Active (SPML Suspend Service: activeRequest)

The activeRequest operation enables a requestor to determine whether a specified user is active or has been suspended.

Table 29-8 Checking if User Has Been Suspended with activeRequest

Item/Feature	Description
SPML Execution Mode	Asynchronous
Input	activeRequest element as defined by [SPMLv2].
Output	activeResponse element as defined by [SPMLv2].
Processing	This operation requires a valid user PSO ID. If the PSO identifier is invalid, the noSuchIdentifier error code is returned. If the request is valid and if the specified user exists, the provider must get the user status. The activeRequest operation is applicable for users only. It returns unsupportedOperation error if the PSO object is not an identity.
Examples	See the example "SPML Example - Check If User is Active".

29.10 Validate a Username (SPML Username Service: validateUsername)

The validateUsername operation enables a requestor to determine whether a username already exists or it is reserved.

Table 29-9 Checking Username Validity with resumeRequest

Item/Feature	Description
SPML Execution Mode	Synchronous
Input	`validateUsernameRequest` element as defined by [SPMLv2]. userName is the only input parameter accepted.
Output	`validateUsernameResponse` element as defined by [SPMLv2].
Processing	This operation takes a username and checks if the username exists. Processing errors are reported with SPML `customError` code.
Examples	See the example "SPML Example - Validate User Name".

29.11 Obtain a Username (SPML Username: suggestUsername)

The suggestUsername operation enables a requestor to obtain a valid username for a given policy.

Table 29-10 Obtaining a Username with suggestUsername

Item/Feature	Description
SPML Execution Mode	Synchronous
Input	`suggestUsernameRequest` element as defined by [SPMLv2].
Output	`suggestUsernameResponse` element as defined by [SPMLv2].
Processing	This operation takes user information and uses it to construct a username based on the applicable username policy. Processing errors are reported with SPML `customError` code.
Examples	See the example "SPML Example - Suggest User Name".

29.12 Securing SPML Web Services

This section explains how to secure SPML Web services. It contains these topics:

About Web Services Security
A Request Example
Applying Policies

29.12.1 About Web Services Security

SPML XSD Web service uses Oracle Web Services Security Manager to provide security. SPML Web services is protected by using the following SAML or username token service policy with message protection:

oracle/wss11_username_token_with_message_protection_client_policy

Note:

The SPML XSD profile Web services can be loaded only by users that are a member of the SPML_App_Role. This is done for added security.

See Oracle Fusion Middleware Security and Administrator's Guide for Web Services for information about configuring the MBeans for the Web service.

The default policy can be changed using Oracle Enterprise Manager Fusion Middleware Control.

29.12.2 A Request Example

A sample Request looks like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" >
   <soap:Header>
      <ns1:Security>
         <ns1:UsernameToken>
            <ns1:Username>weblogic</ns1:Username>
            <ns1:Password>weblogic1</ns1:******>
         </ns1:UsernameToken>
      </ns1:Security>
   </soap:Header>
    <soap:Body xmlns:ns1="urn:oasis:names:tc:SPML:2:0">
        <ns1:listTargetsRequest />
    </soap:Body>
</soap:Envelope>

29.12.3 Applying Policies

At deployment time, the administrator can use the Oracle Enterprise Manager Fusion Middleware Control Console to apply correct security policy to protect the service. Refer to the following documentation for details about using Fusion Middleware Control:

"Accessing the Security and Administration Tools" in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.