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:

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:

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:

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:

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

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.