32 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 the following topics:

See Also:

"SPML Example - Add User" for information about customizing the SPML service with custom attributes

32.1 Introduction

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

32.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, and reset password requests. For asynchronous interactions, 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. For add and reset password requests, delayed (conditional ) notification is supported. Delayed notification data can be sent as part of payload.

For username services, all services are synchronous.

Search APIs

For search APIs in the Identity Management realm, refer to Oracle Identity Management APIs in the Oracle Fusion Middleware Java API Reference for Oracle Identity Manager.

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

32.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 by 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 32-1 lists the features of identity creation with addRequest operation.

Table 32-1 Identity Creation with addRequest

Item/Feature Description

SPML Execution Mode

Asynchronous only

Input

addRequest element as defined by [SPMLv2].

Optional, notificationData for controlling user email notifications.

Output

addResponse element as defined by [SPMLv2].

Processing

The add operation allows adding identity. Optionally, existing roles may be assigned to the identity.

The runtime errors are reported by using the customError SPML custom error code. Only validation errors are returned in the Response. No request ID is returned.

Optionally, notification data can be sent as input as:

  • SentNotification: Boolean flag that determines whether or not to send notification.

  • SendNotificationTo: Comma separated email address.

Examples

See the Appendix for these examples:

32.3 Modify Users, 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 32-2 lists the features of role membership management with modifyRequest operation.

Table 32-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:

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

You implement the SPML deleteRequest service to delete an existing role or user, as described in Table 32-3.

Table 32-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".

32.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 32-4 lists the features of the statusRequest operation.

Table 32-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.20, "SPML Example - Status Request"

32.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 32-5 lists the features of obtaining targets with listTargets.

Table 32-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.

32.7 Disable a User (SPML Suspend Service: suspendRequest)

The suspend operation enables the requestor to suspend a user.

Table 32-6 lists the features of the suspendRequest operation.

Table 32-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".

32.8 Enable a User (SPML Suspend Service: resumeRequest)

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

Table 32-7 lists the features of the resumeRequest operation.

Table 32-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".

32.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 32-8 lists the features of the activeRequest operation.

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

Item/Feature Description

SPML Execution Mode

Synchronous

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

32.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 32-9 lists the features of the resumeRequest operation.

Table 32-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".

32.11 Obtain a Username (SPML Username: suggestUsername)

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

Table 32-10 lists the features of the suggestUsername operation.

Table 32-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".

32.12 Reset Password (SPML Core Service: resetPasswordRequest)

The resetPasswordRequest operation enables a requestor to reset the password for a user.

Table 32-11 lists the features of the resetPasswordRequest operation.

Table 32-11 Reseting the user password with resetPasswordRequest

Item/Feature Description

SPML Execution Mode

Synchronous

Input

resetPasswordRequest element as defined by [SPMLv2].

Optional notification data for controlling end user email notification.

Output

resetPasswordRequest element as defined by [SPMLv2].

Processing

This operation takes user key or user GUID as an input to reset the password with random generated password.

Optionally, notification data can be sent as input as:

  • SentNotification: Boolean flag to determine whether or not to send notification.

  • SendNotificationTo: Comma separated email address.

Processing errors are reported with SPML customError code.

Examples

See the Appendix for these examples:

32.13 Lookup Username Policy (SPML Username Service: lookupUsernamePolicy)

The lookupUsernamePolicy operation enables a requestor to obtain details about the configured username policy in Oracle Identity Manager. You can also provide locale in the request to obtain details in the provided locale.

Table 32-12 lists the features of the lookupUsernamePolicy operation.

Table 32-12 Lookup Username policy details with lookupUsernamePolicy

Item/Feature Description

SPML Execution Mode

Synchronous

Input

lookupUsernamePolicyRequest element as defined by [SPMLv2].

Output

lookupUsernamePolicyResponse element as defined by [SPMLv2].

Processing

This operation returns the information about configured user name policy in Oracle Identity Manager.

Examples

See the example Section C.23, "SPML Example - Lookup User Name Policy".

32.14 Cancel/Withdraw Request (SPML Async Service: cancelRequest)

The cancel request operation enables the requestor to withdraw the specified request ID. If the request is withdrawn successfully, then all the pending approvals are also withdrawn. Only the requester of the submitted request can withdraw it.

Table 32-13 lists the features of the cancelRequest operation.

Table 32-13 Cancel a Request with cancelRequest

Item/Feature Description

SPML Execution Mode

Synchronous

Input

cancelRequest element as defined by [SPMLv2].

Output

cancelResponse element as defined by [SPMLv2].

Processing

This operation cancels/withdraws the specified request. The runtime errors are reported by using the customError SPML custom error code.

Examples

See the example Section C.24, "SPML Example - Cancel Request".

32.15 Batch Request (SPML Batch Request Service: batchRequest)

The batch operation combines any number of individual requests into a single request as defined by SPML v2. Examples of individual requests that can be combined into a single request are creating a user Robert Klein, updating a user Terrence Hill, deleting a user John Doe, and reset password for a user Jane Doe in a single request.

Batch request does not support transactional semantics, which means that the failure of a nested request does not undo a nested request that has already been completed. Each individual response occupies the same position within the <batchResponse> that the corresponding individual request occupies within the <batchRequest>.

This operation supports parallel processing only ("processing='parallel'") and runs the nested requests within the <batchRequest> in any order. When error condition occurs, it continues processing the subsequent subrequests, specified by "onError='resume'". If a request fails to be processed, then the next request is processed. If one or more of the nested requests in that batch fails, then operation returns a <batchResponse> with "status='failure'", even if some of the requests in that batch succeed.

lists the features of the batchRequest operation.

Table 32-14 Executing Batch Request with batchRequest

Item/Feature Description

SPML Execution Mode

Synchronous

Input

batchRequest element as defined by [SPMLv2].

Output

batchResponse element as defined by [SPMLv2].

Processing

This operation supports only four types of sub requests: addRequest for identity, modifyRequest for identity, deleteRequest for identity, resetPasswordRequest.

Examples

See the example Section C.25, "SPML Example - Batch Request".

32.16 Securing SPML Web Services

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

32.16.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 policies:

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.

  • SAML or username token service policy with message protection:

    oracle/wss11_username_token_with_message_protection_client_policy

  • In the Fusion Applications environment, with the username token and message protection security:

    oracle/wss11_username_token_with_message_protection_client_policy

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

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

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

32.17 Operations Not Supported

Oracle Identity Manager 11g Release 1 (11.1.1) does not support the following SPML operations as part of the XSD profile:

  • Search user

  • Search role

  • Any operation, such as create, modify, delete, or search, on organizations