Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Identity Manager
11g Release 2 (11.1.2)

Part Number E27150-17
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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:

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 request. 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 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 General Considerations

Perform the following to ensure that SPML works with Oracle Identity Manager:

32.2.1 Assigning SPML Admin Role to the User

Oracle Identity Manager provides an admin role for SPML. The user with this admin role is able to perform SPML requests for all usecases. The name of the SPML admin role is SPML Admin.

The SPML Admin admin role has the following permissions:

  • Create, modify, and delete users via request

  • Search users on all the attributes

  • Enable user status via request

  • Disable user status via request

  • Add role memberships via request

  • Delete role memberships via request

  • Search roles on all the attributes

  • Create, modify, and delete roles via request

The SPML Admin admin role is a global admin role published to the TOP organization. Therefore, only System Administrator or Organization Administrator of the TOP organization can assign this admin role to any user, in scope of the TOP organization.

In a new deployment of Oracle Identity Manager, the SPML Admin admin role is not assigned to any users by default. As a result, System Administrator or Organization Administrator of the TOP organization must manually assign this role to relevant users. In addition, the SPML Admin admin role can be assigned in scope of the TOP organization with include hierarchy or include sub-orgs option enabled. As a result, all permissions of the SPML Admin admin role are assigned to the user for all organizations in Oracle Identity Manager.

Note:

In an upgraded deployment of Oracle Identity Manager, the existing SPML users are upgraded to assign SPML Admin admin role so that they can continue to perform SPML requests.

To assign SPML Admin admin role to a user:

  1. Login to Oracle Identity Self Service. If you want to assign the SPML Admin admin role to a new user, then create the user.

  2. Open the TOP organization, and click the Admin Roles tab.

  3. Select the SPML Admin admin role, and assign the user with this role.

  4. Modify the newly added membership to select the include-suborgs option, and then click Apply.

32.2.2 Creating Autoapproval Policies

Autoapproval policy rules are required so that SPML requests are auto-approved. In Oracle Identity Manager 11g Release 2 (11.1.2), there are no request templates. Therefore, the autoapproval policy rules must be manually created by System Administrators for each SPML user.

The autoapproval policies created can be based on user login, and the approval process configuration for each policy must be selected as Auto Approval. You must create autoapproval policies for each SPML operation, such as create user, modify user, create role, and so on, so that all the SPML requests raised by SPML user for these operations are approved at both request level and operational level.

Note:

Only request-level approval policies are required for role create, role modify, and role delete operations.

To create the autoapproval policy rules:

  1. Create new auto approval policy rules for the following:

    • Create user request level

    • Create user operation level

    • Modify user request level

    • Modify user operation level

    • Delete user request level

    • Delete user operation level

    • Enable user request level

    • Enable user operation level

    • Disable user request level

    • Disable user operation level

    • Assign roles request level

    • Assign roles operation level

    • Remove roles request level

    • Remove roles operation level

    • Create role request level

    • Modify role request level

    • Delete role request level

  2. Create rules in each policy based on the user login. Ensure that user login evaluation is case-sensitive. Figure 32-1 shows a sample rule.

    Figure 32-1 Sample Approval Policy Rule

    Description of Figure 32-1 follows
    Description of "Figure 32-1 Sample Approval Policy Rule"

Note:

The autoapproval policies created for a SPML user based on the user login cause all requests raised by the user to be auto-approved irrespective of the request being raised via SPML, UI, or any other flow.

32.3 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 autogenerated in Oracle Identity Manager if the appropriate plug-ins are installed.

  • For creating a user with a given password, provide the user password in Base64 encoded format within SPML create user payload. For example:

    <pso:password>
    <pso:value>V2VsY29tZTc=</pso:value>
    </pso:password>
    

    You can use any standard Java library to obtain the Base64 encoded value for a string. An example of such a library is Apache commons library - org.apache.commons.codec.binary.Base64. encodeBase64("PASSWORD".getBytes()).

  • Role created by user with SPML Admin role are autopublished to the TOP organization including its suborganizations.

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

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.

Examples

See the Appendix for these examples:


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

You implement the SPML modifyRequest service for these tasks:

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.5 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.6 Check Request Status (SPML Core Service: statusRequest)

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

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 "SPML Example - Status Request"


32.7 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 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.8 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.9 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.10 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.11 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.12 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.13 Securing SPML Web Services

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

32.13.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.13.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.13.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.14 Operations Not Supported

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

32.15 SPML Attributes and LDAP Mappings, and Oracle Identity Manager Attributes

The SPML XSD Web Service uses Oracle Identity Manager as a back-end service to provide provisioning functionality to Fusion applications. A key building block of the SPML Web Service is the SPML Provisioning Service Object (PSO), which defines the object to be provisioned. Examples of PSO are identity and role.

This appendix shows the supported PSO attributes and their LDAP mappings, and explains the character restrictions on Oracle Identity Manager attributes. Finally, it describes additional operational data that the application can pass to the SPML Web Service. It contains the following sections:

32.15.1 Identity PSO Attributes

Table 32-11 shows identity attributes supported by the SPML implementation in Oracle Identity Manager and how these attributes map to LDAP objects/attributes.

Note:

The syntax column lists relevant attribute properties such as the type, required, and so on.

Table 32-11 Identity PSO Attributes

SPML Attribute Name Syntax Description LDAP Mapping (Oracle Internet Directory)

ID

String, Read-Only, Required, Single

The identifier used to identify a user for modify request.

orclUserV2: orclguid

activeEndDate

Timestamp, Single

Termination time and date for the user

orclUserV2: orclActiveEndDate

activeStartDate

Timestamp, Single

Activation time and date for the user

orclUserV2: orclActiveStartDate

commonName

String,

Required

The common names of the person, typically the person's full name and any variations of the same.

person: cn

countryName

String, Single

The business country of the person, expressed as a two-letter [ISO3166] country code.

orclUserV2: c

departmentNumber

String, Single

Codes for the departments within an organization to which this person belongs. This can be strictly numeric or alphanumeric.

inetOrgPerson: departmentNumber

description

String, Single

Human-readable descriptive phrases about the person.

person: description

displayName

String, Single, MLS

The preferred name to use when displaying an entry for the person.

Provides MultiLingual Support (MLS) and also accepts language values for locale, for example "en" and "fr".

inetOrgPerson: displayName

employeeNumber

String, Single

Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization.

inetOrgPerson: employeeNumber

employeeType

String, Single

Identifies the type of employee. For the list of valid values see Table 32-12.

inetOrgPerson: employeeType

facsimileTelephoneNumber

String, Single

Telephone numbers for the person's business facsimile (FAX) terminals.

organizationalPerson: facsimileTelephoneNumber

generationQualifier

String, Single

Name strings that are typically the suffix part of the person's name (e.g. "III", "3rd", "Jr.").

N/A

givenName

String, Single

Name strings that are part of a person's name that is not their surname (for example, first name).

inetOrgPerson: givenName

hireDate

Timestamp, Single

Date of hire.

orclUserV2: orclHireDate

homePhone

Single, String

Home telephone numbers associated with the person.

inetOrgPerson:homePhone

homePostalAddress

Single, String

The home postal addresses of the person.

inetOrgPerson: homePostalAddress

initials

String, Single

Some or all of an individual's names, except the surname(s)

inetOrgPerson: initials

localityName

Single, String

Names of a business locality or place, such as a city, county, or other geographic region.

N/A

mail

Single, String

Business Internet mail addresses of the person in Mailbox [RFC2821] form.

inetOrgPerson: mail

manager

Single, String

The manager of the person.

N/A

middleName

String, Single

The middle names of the person.

orclUserV2: middleName

mobile

Single, String

Mobile telephone numbers associated with the person.

inetOrgPerson: mobile

organization

String, Single

Name of an organization—for example, my_company.

organization

organizationUnit

String, Single

Name of a unit within an organization, for example, IT Support.

organizationalUnitName

pager

Single, String

The business pager telephone numbers of the person.

inetOrgPerson: pager

password

String, Single

Password of the user.

person: userPassword

postalAddress

String, Single

Business addresses used by a Postal Service to perform services for the person.

organizationalPerson: postalAddress

postalCode

String, Single

Codes used by a Postal Service to identify postal service zones of the person's business.

organizationalPerson: postalCode

postOfficeBox

String, Single

Postal box identifiers that a Postal Service uses when a customer arranges to receive mail at a box on the premises of the Postal Service.

organizationalPerson: postOfficeBox

preferredLanguage

String, Single

The preferred written or spoken language for the person. This is useful for international correspondence or human-computer interaction. Values for this attribute type MUST conform to the definition of the Accept-Language header field defined in [RFC2068] with one exception: the sequence "Accept-Language" ":" should be omitted.

inetOrgPerson: preferredLanguage

state

String, Single

Full names of business states or provinces of the person.

organizationalPerson: st

street

String, Single

Site information from a business postal address (that is, the street name, place, avenue, and the house number) of the person.

organizationalPerson: street

surname

String, Single

Name strings for the family names (last name) of the person.

person: sn

telephoneNumber

String, Single

Business telephone number of the person

organizationalPerson: telephoneNumber

title

String, Single

Title of the person in their organizational context.

organizationalPerson: title

username

String, Single

Computer system login names associated with the person.

uid

userType

String, Single

The type of user. This attribute is used to provide Design Console access to the end-users. The allowed values are true and false.

 

Table 32-12 shows the valid values for the employeeType attribute:

Table 32-12 Valid Values of employeeType

Value Meaning

Full-Time

Full-Time Employee

Part-Time

Part-Time Employee

Temp

Temp

Intern

Intern

Consultant

Consultant

Contractor

Contractor

EMP

Employee

CWK

Contingent Worker

NONW

Non Worker

OTHER

Other Employee Type


Note:

Oracle Identity Manager passes only the codes shown in the Value column; the meaning of each code is shown for reference.

32.15.1.1 Custom Identity Attributes

Custom attributes are provided to support Oracle Identity Manager functionality; these attributes are present in Oracle Identity Manager (such as when a user-defined field is added) but not in the PSO.

The custom attribute name must match the attribute name specified in the corresponding request dataset for the mapping to work end-to-end.

Here are some examples of custom attributes:

...
<data>
<pso:identity>
 <pso:attributes>
 <pso:attr name="Number Format">
 <pso:value>#,##0.##[.,]</pso:value>
</pso:attr>
 <pso:attr name="Currency">
 <pso:value>USD</pso:value>
</pso:attr>
</attributes>
...

32.15.2 Role PSO Attributes

Table 32-13 lists the role attributes supported by the SPML implementation in Oracle Identity Manager and how these attributes map to LDAP objects/attributes.

Table 32-13 PSO Role Attributes

Attribute Name Syntax Description

ID

String, Read-Only, Required, Single

The PSO identifier that uniquely identifies a role. Usually directory GUID.

commonName

String, Required, MLS

The common name of the role.

description

Single

Human readable role description

displayName

String, Single, MLS

The preferred name to use when displaying an entry for the role.


32.15.2.1 Custom Role Attributes

Custom attributes are provided to support Oracle Identity Manager functionality; these attributes are present in Oracle Identity Manager but not in the PSO.

The custom attribute name must match the attribute name specified in the corresponding request dataset for the mapping to work end-to-end.

Here is an example of a custom role attribute:

...
<pso:attributes>
<pso:attr name="Role Category Name">
<pso:value>Cat1</pso:value>
</pso:attr>
...

Role Category Name is a special custom role attribute. It is the namespace for the roles. Each role belongs to a role category. This can be specified while creating a new role. If not specified, then the Default role category is selected. Each role category and role name uniquely identifies a role.

32.15.3 Preference Attributes

Table 32-14 lists the preference attributes supported by the SPML implementation in Oracle Identity Manager:

Table 32-14 Preference Attributes

Attribute Name Syntax Description LDAP Mapping

Number Format

String

The format to display numbers

orclNumberFormat

Values are:

#,##0.##[.,]

#,##0.###[\u00A0,]

#,##0.###

#,##0.###;#,##0.###-

#,##0.###[.,]

#,##0.###;(#,##0.###)[.,]

#,##0.##[\u00A0,]

#,##0.###['.]

#,##0.###[',]

Currency

String

The symbol that must be used for currency

orclCurrency

Sample values are:

USD

YUN

NZD

INR

Date Format

String

The format to display the date

orclDateFormat

Values are:

MM-dd-yyyy

MM-dd-yy

MM.dd.yyyy

MM.dd.yy

MM/dd/yyyy

MM/dd/yy

M-d-yyyy

M-d-yy

M.d.yyyy

M.d.yy

M/d/yyyy

M/d/yy

dd-MM-yyyydd-MM-yy

d-M-yyyy

d-M-yy

dd.MM.yyyy

dd.MM.yy

d.M.yyyy

d.M.yy

dd/MM/yyyy

dd/MM/yy

d/M/yyyy

d/M/yy

yyyy-MM-dd

yy-MM-dd

yyyy-M-d

yy-M-d

yyyy.MM.dd

yy.MM.dd

yyyy.M.d

yy.M.d

yy. M. d

yyyy/MM/dd

yy/MM/dd

yyyy/M/d

yy/M/d

Time Format

String

The format to display the time

orclTimeFormat

Values are:

HH.mm

HH.mm.ss

HH:mm

HH:mm:ss

H:mm

H:mm:ss

H.mm

H.mm.ss

a hh.mm

a hh.mm.ss

a hh:mm

a hh:mm:ss

ah:mm

ah:mm:ss

hh.mm a

hh.mm.ss a

hh:mm a

hh:mm:ss a

Embedded Help

String

Whether or not to show embedded help

orclEmbeddedHelp

Values are:

true

false

Font Size

String

The size of the font

orclFontSize

Values are:

LARGE

MEDIUM

Color Constrast

String

Constrast of the color

orclColorContrast

Values are:

STANDARD

HIGH

Accessibility Mode

String

Accessibility mode for the user

orclAccessibilityMode

Values are:

screenReader

inaccessible

default

FA Language

String

The default preference language

orclFALanguage

User Name Preferred Language

String

The preference language of the user used to only show the display name of the user in that language

Note: The value set for this attribute is not used in Oracle Identity Manager.

orclDisplayNameLanguagePreference


32.15.4 Special Character Restrictions in Oracle Identity Manager Attributes

This section lists character restrictions applicable to Oracle Identity Manager attributes. Failure to observe these restrictions will cause errors when performing operations with attributes.

32.15.4.1 Characters Available in All Attributes

Alphanumeric characters (a through z, A through Z, and 0 through 9) and the underscore character (_) can be used in all Oracle Identity Manager attributes.

32.15.4.2 Special Characters in the Password Field

The following special characters can be used in the Password field:

  • Percent sign ( % )

  • Plus sign ( + )

  • Equal sign ( = )

  • Comma ( , )

  • Backslash ( \ )

  • Single quotation mark ( ' )

  • Slash ( / )

  • Vertical bar ( | )

32.15.4.3 Usage of Single Quotation Mark

The single quotation mark ( ' ) can be used only in the following attributes:

  • Login

  • Manager ID

  • First Name

  • Last Name

  • Middle Name

  • Group Name

  • Organization Name

  • Resource Name

32.15.4.4 Usage of Semicolon

The semicolon ( ; ) can be used only in access policy names.

32.15.4.5 Unsupported Special Characters

The following special characters are not supported in any Oracle Identity Manager attribute:

  • Period ( . )

  • Number sign ( # )

  • Slash ( / )

  • Percent sign ( % )

  • Equal sign ( = )

  • Vertical bar ( | )

  • Plus sign ( + )

  • Comma ( , )

  • Backslash ( \ )

  • Double quotation mark ( " )

  • Less than symbol ( < )

  • Greater than symbol ( > )

32.15.5 Operation Data

Requesting application such as HCM Fusion Application will act as a SPML requestor. In addition to PSO data, the application can also pass some operational data to the SPML Web Service. This section describes how applications can pass the operation data.

32.15.5.1 Passing Operation Data

It is possible to pass a requestor ID for each operation. When the Fusion application supplies credentials in a request, that is an application ID. For auditing purposes, it is also possible to pass a requestor ID. Oracle Identity Manager audits this ID, instead of the application ID, as the actual requestor of the operation.

Along with the requestorID, a justification for the request can also be specified.

The following is an example of the operation data:

...
</pso:identity>
</data>
<capabilityData
capabilityURI="http://xmlns.oracle.com/idm/identity/OperationData"
mustUnderstand="true">
<operationData
xmlns="http://xmlns.oracle.com/idm/identity/OperationData" requestorGUID="1"
justification="i need this account">
</capabilityData>
</addRequest>

32.15.5.2 Passing Reference Data

The application is also required to pass some reference data to SPML so that when a callback is received, it can be identified with the reference data for the callback in context. This is pass-through data, which is ignored by Oracle Identity Manager, but will be returned in the callback.

The following is an example that contains the <LdapRequestId>:

...
...
</pso:identity>
</data>
<capabilityData
capabilityURI="http://xmlns.oracle.com/idm/identity/OperationData"
mustUnderstand="true">
<operationData
xmlns="http://xmlns.oracle.com/idm/identity/OperationData" requestorGUID="1"
justification="i need this account">
<LdapRequestId
xmlns="http://xmlns.oracle.com/apps/hcm/users/ldapRequestService/">102329090340
</operationData>
</capabilityData>
</addRequest>

32.16 SPML Examples

This appendix provides the following SPML XSD examples:

32.16.1 SPML Example - Add User

The Request is as follows:

<addRequest xmlns="urn:oasis:names:tc:SPML:2:0" xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous" locale="en" policyURI="http://www.sample.com/string/string" requestID="string" returnData="identifier" targetID="string">
<!--Zero or more repetitions:-->
<data>
<!--You have a CHOICE of the next 3 items at this level-->
<pso:identity>
<!--Optional:-->
<pso:attributes>
<!--Here, My Attribute is a UDF, with 'My Attribute' also added in CreateUserDataset.xml -->
<pso:attr name="My Attribute">
<pso:value>New Value</pso:value>
</pso:attr>
</pso:attributes>
<!--Optional:-->
<pso:activeEndDate>2009-06-12T16:00:00</pso:activeEndDate>
<!--Optional:-->
<pso:activeStartDate>2009-06-11T18:00:00</pso:activeStartDate>
<pso:commonName>
<pso:value>All Optional Values</pso:value>
</pso:commonName>
<!--Optional:-->
<pso:countryName>India</pso:countryName>
<!--Optional:-->
<pso:departmentNumber>
<!--1 or more repetitions:-->
<pso:value>123456</pso:value>
</pso:departmentNumber>
<!--Optional:-->
<pso:description>
<!--1 or more repetitions:-->
<pso:values>
<!--1 or more repetitions:-->
<pso:value>All Optional Fields Profile</pso:value>
</pso:values>
</pso:description>
<!--Optional:-->
<pso:displayName>
<!--1 or more repetitions:-->
<pso:value locale="en">All Optional Values</pso:value>
</pso:displayName>
<!--Optional:-->
<pso:employeeNumber>24073</pso:employeeNumber>
<!--Optional:-->
<pso:employeeType>
<!--1 or more repetitions:-->
<pso:values>
<!--1 or more repetitions:-->
<pso:value>Part-Time</pso:value>
</pso:values>
</pso:employeeType>
<!--Optional:-->
<pso:facsimileTelephoneNumber>
<!--1 or more repetitions:-->
<pso:number>08041085304</pso:number>
</pso:facsimileTelephoneNumber>
<!--Optional:-->
<pso:generationQualifier>
<!--1 or more repetitions:-->
<pso:value>II</pso:value>
</pso:generationQualifier>
<!--Optional:-->
<pso:givenName>
<!--1 or more repetitions:-->
<pso:value>OptionalGivenName</pso:value>
</pso:givenName>
<!--Optional:-->
<pso:hireDate>2009-06-11T16:00:00</pso:hireDate>
<!--Optional:-->
<pso:homePhone>
<!--1 or more repetitions:-->
<pso:number>9999999999</pso:number>
</pso:homePhone>
<!--Optional:-->
<pso:homePostalAddress>
<!--1 or more repetitions:-->
<pso:value>marathahalli</pso:value>
</pso:homePostalAddress>
<!--Optional:-->
<pso:initials>
<!--1 or more repetitions:-->
<pso:value>SJ</pso:value>
</pso:initials>
<!--Optional:-->
<pso:localityName>
<!--1 or more repetitions:-->
<pso:value>Munekolala</pso:value>
</pso:localityName>
<!--Optional:-->
<!--pso:mail>
<pso:value>jdong12@mycompany.com</pso:value>
</pso:mail-->
<!--Optional:-->
<pso:middleName>MiddleName</pso:middleName>
<!--Optional:-->
<pso:mobile>
<!--1 or more repetitions:-->
<pso:number>9886078373</pso:number>
</pso:mobile>
<!--Optional:-->
<pso:organization>
<pso:value>2</pso:value>
</pso:organization>
<!--Optional:-->
<pso:organizationUnit>
<pso:value>Marketing</pso:value>
</pso:organizationUnit>
<!--Optional:-->
<pso:pager>
<!--1 or more repetitions:-->
<pso:number>7777</pso:number>
</pso:pager>
<!--Optional:-->
<pso:password>
<!--1 or more repetitions:-->
<!--base64 encoded password of johnd-->
<pso:value>c2Fpamhh</pso:value>
</pso:password>
<!--Optional:-->
<pso:postalAddress>
<!--1 or more repetitions:-->
<pso:value>Marathahalli</pso:value>
</pso:postalAddress>
<!--Optional:-->
<pso:postalCode>
<!--1 or more repetitions:-->
<pso:value>560037</pso:value>
</pso:postalCode>
<!--Optional:-->
<pso:postOfficeBox>
<!--1 or more repetitions:-->
<pso:value>999</pso:value>
</pso:postOfficeBox>
<!--Optional:-->
<pso:preferredLanguage>en</pso:preferredLanguage>
<!--Optional:-->
<pso:state>
<!--1 or more repetitions:-->
<pso:value>Karnataka</pso:value>
</pso:state>
<!--Optional:-->
<pso:street>
<!--1 or more repetitions:-->
<pso:value>Satyam Street</pso:value>
</pso:street>
<!--Optional:-->
<pso:surname>
<pso:values>
  <!--1 or more repetitions:-->
<pso:value>Jha</pso:value>
</pso:values>
</pso:surname>
<!--Optional:-->
<pso:telephoneNumber>
<!--1 or more repetitions:-->
<pso:number>08041085304</pso:number>
</pso:telephoneNumber>
<!--Optional:-->
<pso:title>
<pso:value>Mr</pso:value>
</pso:title>
<!--Optional:-->
<pso:username>
<!--1 or more repetitions:-->
<pso:value>jsmith</pso:value>
</pso:username>
<pso:manager>5</pso:manager>
</pso:identity>
</data>
</addRequest>

The Add User Response sample if user login already exists is as follows:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"><env:Header/>
<env:Body>
<ns3:addResponse xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO" xmlns:ns3="urn:oasis:names:tc:SPML:2:0" xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend" xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username" xmlns:ns6="urn:oasis:names:tc:SPML:2:0:password" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:reference" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async" xmlns:ns9="urn:names:spml:ws:header" status="failure" error="malformedRequest" extendedError="IAM-3076048">
<ns3:errorMessage>username jsmith already exists.</ns3:errorMessage>
</ns3:addResponse>
</env:Body>
</env:Envelope>

The Add User Response sample if multiple values are passed for attributes that accept only single value:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<ns3:addResponse xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO" xmlns:ns3="urn:oasis:names:tc:SPML:2:0" xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend" xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username" xmlns:ns6="urn:oasis:names:tc:SPML:2:0:password" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:reference" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async" xmlns:ns9="urn:names:spml:ws:header" status="pending" requestID="5" error="malformedRequest" extendedError="IAM-3071022"><ns3:errorMessage>The attribute commonName is not multi-language enabled in OIM. Only the value John Smith will be saved.</ns3:errorMessage>
<ns3:errorMessage>The attribute organization is not multi-language enabled in OIM. Only the value 1 will be saved.
</ns3:errorMessage>
</ns3:addResponse>
</env:Body>
</env:Envelope>

Note:

  • To find the status of the add user request, see "SPML Example - Status Request".

  • The displayName attribute has Multiple Language Support (MLS), and language values can be specified as "en", "fr", and so on.

32.16.2 SPML Example - Delete User

The Request is as follows:

<deleteRequest xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous"
locale="en" policyURI="http://www.sample.com/string/string"
requestID="string" returnData="identifier" targetID="string">
<psoID ID="identity:6C9B96E99FC8DC32E040E50A3D5252F5" />
</deleteRequest>

The Response is as follows:

<ns9:ResponseType xmlns="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns2="urn:oasis:names:tc:SPML:2:0"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns6="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns7="urn:names:spml:ws:header" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="19" status="pending"/>

32.16.3 SPML Example - Modify User

The Request is as follows:

<modifyRequest xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous"
locale="string" policyURI="http://www.sample.com/string/string"
requestID="string" returnData="identifier">
<capabilityData capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
mustUnderstand="true" />
<psoID ID="identity:6C9B96E99FC8DC32E040E50A3D5252F5" />
<modification modificationMode="add">
<component path="/identity" namespaceURI="http://www.w3.org/TR/xpath20" />
<data>
<pso:identity>
<pso:initials>
<!--1 or more repetitions:-->
<pso:value>J S</pso:value>
</pso:initials>
                                        </pso:identity>
                                </data>
                        </modification>
                        <modification modificationMode="replace">
                                <component path="/identity" namespaceURI="http://www.w3.org/TR/xpath20" />
                                <data>
                                        <pso:identity>
                                                <pso:localityName>
                                                        <!--1 or more repetitions:-->
                                                        <pso:value>new_locality</pso:value>
                                                </pso:localityName>
                                                <pso:homePhone>
                                                        <!--1 or more repetitions:-->
                                                        <pso:number>0123456789</pso:number>
                                                </pso:homePhone>
                                                <pso:commonName>
                                                        <!--1 or more repetitions:-->
                                                        <pso:values>
                                                                <!--1 or more repetitions:-->
                                                                <pso:value>FR Alice Krug1</pso:value>
                                                        </pso:values>
                                                </pso:commonName>
                                        </pso:identity>
                                </data>
                        </modification>
                        <modification modificationMode="delete">
                                <component path="/identity" namespaceURI="http://www.w3.org/TR/xpath20" />
                                <data>
                                        <pso:identity>
                                                <pso:pager>
                                                        <!--1 or more repetitions:-->
                                                        <pso:number>333</pso:number>
                                                </pso:pager>
                                        </pso:identity>
                                </data>
                        </modification>
                </modifyRequest>

The Response is as follows:

<ns9:ModifyResponseType xmlns="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns2="urn:oasis:names:tc:SPML:2:0"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns6="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns7="urn:names:spml:ws:header" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="15" status="pending"/>

32.16.4 SPML Example - Resume User

The Request is as follows:

<resumeRequest xmlns="urn:oasis:names:tc:SPML:2:0:suspend"
requestID="120">
<psoID ID="6C9B96E99FC8DC32E040E50A3D5252F5" />
</resumeRequest>

The Response is as follows:

<ns9:ResponseType xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns6="urn:names:spml:ws:header" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns8="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="120" status="pending"/>

32.16.5 SPML Example - Suggest User Name

The Request is as follows:

<ns4:suggestUsernameRequest
xmlns:ns4="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns3="http://xmlns.oracle.com/idm/identity/PSO">
<ns2:identity>
<ns3:givenName>
<ns3:value>testfn</ns3:value>
</ns3:givenName>
<ns3:surname>
<ns3:values>
<ns3:value>testln</ns3:value>
</ns3:values>
</ns3:surname>
</ns2:identity>
</ns4:suggestUsernameRequest>

The Response is as follows:

<ns9:SuggestUsernameResponseType xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns3="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns6="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns7="urn:names:spml:ws:header"
xmlns:ns8="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns9="oasis:names:tc:SPML:2:0" status="success">
<ns3:username>testfn.testln@mycompany.com</ns3:username>
</ns9:SuggestUsernameResponseType>

32.16.6 SPML Example - Suspend User

The Request is as follows:

<suspendRequest xmlns="urn:oasis:names:tc:SPML:2:0:suspend"
requestID="139">
<psoID ID="6C9B96E99FC8DC32E040E50A3D5252F5"/>
</suspendRequest>

The Response is as follows:

<ns9:ResponseType xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns6="urn:names:spml:ws:header" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns8="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="28"
status="pending"/><ns9:ResponseType xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns6="urn:names:spml:ws:header" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns8="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="139" status="pending"/>

32.16.7 SPML Example - Validate User Name

The Request is as follows:

<validateUsernameRequest
xmlns="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username">
<username>testfn.testln</username>
</validateUsernameRequest>

The Response is as follows:

<ns9:ValidateUsernameResponseType xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns3="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns6="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns7="urn:names:spml:ws:header"
xmlns:ns8="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns9="oasis:names:tc:SPML:2:0" valid="true" status="success"/>

32.16.8 SPML Example - Check If User is Active

The request is as follows:

<activeRequest xmlns="urn:oasis:names:tc:SPML:2:0:suspend" requestID="143">
<psoID ID="5" targetID="string"/>
</activeRequest>

The Response is as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns4:ResponseType xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns3="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns4="oasis:names:tc:SPML:2:0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns2:ActiveResponseType" active="true" requestID="143"
status="success" />

32.16.9 SPML Example - Lookup Username Policy

The Request is as follows:

<lookupUsernamePolicyRequest
xmlns="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username">
</lookupUsernamePolicyRequest>

The Response is as follows:

<ns9:LookupUsernamePolicyResponseType
xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns3="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns6="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns7="urn:names:spml:ws:header"
xmlns:ns8="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns9="oasis:names:tc:SPML:2:0" status="success"
<ns3:description>Generates user name based on email id if it is available, else generate based on first name and last name appended with domain name.</ns3:description>
>

Note:

To view policy description in a specific locale, you can set locale attribute in the payload. If this locale is not supported, then by is displayed in the server locale by default, as shown:

<lookupUsernamePolicyRequest locale="th"
xmlns="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username">
</lookupUsernamePolicyRequest>

32.16.10 SPML Example – Add User with Role Assignment

The Request to create user (identity) is as follows:

Note:

  • There can only be one toPsoID element under a reference element. For multiple roles, individual reference element must be used.

  • The GUID must be of 32 characters for all requests.

<addRequest 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="urn:oasis:names:tc:SPML:2:0"
    xmlns:spml="urn:oasis:names:tc:SPML:2:0" 
    executionMode="asynchronous" 
    policyURI="create_identity_policy_prc02.xml">
        <spml:data xsi:type="spml:PSOType">
           <identity
             xmlns="http://xmlns.oracle.com/idm/identity/PSO"
             xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO">
            <pso:commonName>
              <pso:values>
                <pso:value>John Doe</pso:value>
              </pso:values>
            </pso:commonName>
            <pso:displayName>
              <pso:value>John Doe</pso:value>
            </pso:displayName>
            <pso:givenName>
              <pso:value>John</pso:value>
            </pso:givenName>
            <pso:mail>
               <pso:value>john.doe@acme.com</pso:value>
            </pso:mail>
            <pso:middleName/>
            <pso:organization>
              <pso:values>
                <pso:value>ACME, Inc.</pso:value>
              </pso:values>
            </pso:organization>
             <pso:password>
              <!--base64 encoded password of johnd-->
              <pso:value>c2Fpamhh</pso:value>
             </pso:password>
            <pso:surname>
              <pso:values>
                <pso:value>Doe</pso:value>
              </pso:values>
            </pso:surname>
            <pso:username>
               <pso:value>jdoe</pso:value>
            </pso:username>
          </identity>
        </spml:data>
        <spml:capabilityData
           capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
           mustUnderstand="true" >
           <reference xmlns="urn:oasis:names:tc:SPML:2:0:reference"
              typeOfReference="memberOf">
              <toPsoID ID="15"/>
 <!--To make the user a member of a default role-->
            </reference>       
           
 
           <reference xmlns="urn:oasis:names:tc:SPML:2:0:reference"
              typeOfReference="memberOf">
              <toPsoID ID="6C9B96E99FC8DC32E040E50A3D5252F5"/>
            </reference>       
      </spml:capabilityData>        
</addRequest>

The Response is as follows:

<spml:addResponse
    xmlns:spml="urn:oasis:names:tc:SPML:2:0"
    status="pending"
    requestID="10821"/>

The Add User with Role Assignment response sample containing partial invalid roles is as follows:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<ns3:addResponse xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO" xmlns:ns3="urn:oasis:names:tc:SPML:2:0" xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend" xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username" xmlns:ns6="urn:oasis:names:tc:SPML:2:0:password" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:reference" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async" xmlns:ns9="urn:names:spml:ws:header" status="pending" requestID="5" error="malformedRequest" extendedError="IAM-3071022">
<ns3:errorMessage>Request contains an invalid Id/Guid identifier - xyzxyzxyz.</ns3:errorMessage>
</ns3:addResponse>
</env:Body>
</env:Envelope>

32.16.11 SPML Example - Assign Role Membership

The Request example is as follows:

Note:

only those roles can be granted to users via SPML Add Role Membership that are:

  • Either published to the TOP organization with hierarchy, OR

  • Published to at least one member organization of the user to whom the role is to be granted via SPML

All other role grant attempts via SPML will fail authorization checks. These roles must be explicitly published to relevant organizations by using the UI or APIs to let SPML Role grant work.

<modifyRequest
xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO"
executionMode="asynchronous"
locale="en"
policyURI="gant_role_01">
<psoID ID="identity:6C9B96E99FC8DC32E040E50A3D5252F5" />
<modification modificationMode="add">
<capabilityData
                  capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
mustUnderstand="true">
<reference
                        xmlns="urn:oasis:names:tc:SPML:2:0:reference"
typeOfReference="memberOf">
<toPsoID ID="6C9B96E99FC8DC32E040E50A3D5252F5" />
</reference>
</capabilityData>
</modification>
</modifyRequest>

The Response example is as follows:

<spml:modifyResponse
    xmlns:spml="urn:oasis:names:tc:SPML:2:0"
    status="pending"
    requestID="10822"/>

32.16.12 SPML Example – Revoke Role Membership

The Request is as follows:

<modifyRequest
xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO"
executionMode="asynchronous"
locale="en"
policyURI="revoke_role_01">
<psoID ID="identity:6C9B96E99FC8DC32E040E50A3D5252F5" />
<modification modificationMode="delete">
<capabilityData
                  capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
mustUnderstand="true">
<reference
                        xmlns="urn:oasis:names:tc:SPML:2:0:reference"
typeOfReference="memberOf">
<toPsoID ID="6C9B96E99FC8DC32E040E50A3D5252F5" />
</reference>
</capabilityData>
</modification>
</modifyRequest>

The Response is as follows:

<spml:modifyResponse
    xmlns:spml="urn:oasis:names:tc:SPML:2:0"
    status="pending"
    requestID="10826"/>

32.16.13 SPML Example - Add Role

The Request is as follows:

<addRequest xmlns="urn:oasis:names:tc:SPML:2:0" xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous" locale="en_us" policyURI="Role Creation" requestID="string"  returnData="identifier" targetID="string">
    <!--Zero or more repetitions:-->
    <capabilityData capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"  mustUnderstand="true" />
    <data>
        <!--You have a CHOICE of the next 3 items at this level-->
        <pso:role>
            <pso:attributes>
                <pso:attr name="Role Category Name">
                    <!-- pso:value>OIM Roles</pso:value-->
                    <pso:value>Default</pso:value>
                </pso:attr>
            </pso:attributes>
            <pso:commonName>
                <!--1 or more repetitions:-->
                <pso:values>
                    <!--1 or more repetitions:-->
                    <pso:value>TempAdmin</pso:value>
                </pso:values>
            </pso:commonName>
            <pso:description>
                <!--1 or more repetitions:-->
                <pso:values>
                    <!--1 or more repetitions:-->
                    <pso:value>Temporary Administrator</pso:value>
                </pso:values>
            </pso:description>
            <pso:displayName>
                <!--pso:value locale="en">Alice Krug_en_US</pso:value-->
                <!--pso:value locale="fr">Alice Kru_fr</pso:value-->
                <pso:value locale="base">Alice Kru_base</pso:value>
            </pso:displayName>
        </pso:role>
    </data>
</addRequest>

The Response is as follows:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<ns3:addResponse xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO" xmlns:ns3="urn:oasis:names:tc:SPML:2:0"    xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend" xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username" xmlns:ns6="urn:oasis:names:tc:SPML:2:0:password" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:reference" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async" xmlns:ns9="urn:names:spml:ws:header" status="pending" requestID="21792"/>
</env:Body>
</env:Envelope>

32.16.14 SPML Example - Add Role with Parent

The Request is as follows:

<addRequest xmlns="urn:oasis:names:tc:SPML:2:0"                        xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous"
locale="en" policyURI="http://www.sample.com/string/string"
requestID="string" returnData="identifier" targetID="string">
    <data>
           <!--You have a CHOICE of the next 3 items at this level-->
           <pso:role>
                 <pso:commonName>
                      <!--1 or more repetitions:-->
                      <pso:values>
                           <!--1 or more repetitions:-->
                           <pso:value>TempAdmin</pso:value>
                      </pso:values>
                 </pso:commonName>
                 <pso:description>
                      <!--1 or more repetitions:-->
                      <pso:values>
                           <!--1 or more repetitions:-->
                           <pso:value>Temporary Administrator</pso:value>
                      </pso:values>
                 </pso:description>
           </pso:role>
    </data>
    <capabilityData capabilityURI="urn:oasis:names:tc:SPML:2:0:reference" mustUnderstand="true">
           <reference typeOfReference="inheritsFrom" xmlns="urn:oasis:names:tc:SPML:2:0:reference">
                      <toPsoID ID="6C9B96E99F77DC32E040E50A3D5252F5" />
           </reference>
    </capabilityData>
</addRequest>

The Response is as follows:

<ns9:AddResponseType xmlns="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns2="urn:oasis:names:tc:SPML:2:0"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns6="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns7="urn:names:spml:ws:header" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="22" status="pending"/>

32.16.15 SPML Example - Modify Role

The Request is as follows:

<modifyRequest xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous"
locale="string" policyURI="http://www.sample.com/string/string"
requestID="string" returnData="identifier">
<capabilityData capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
mustUnderstand="true" />
<psoID ID="role:6C9B96E99FC8DC32E040E50A3D5252F5" />
<modification modificationMode="replace">
<component path="/role" namespaceURI="http://www.w3.org/TR/xpath20" />
<data>
<pso:role>
<pso:description>
<!--1 or more repetitions:-->
<pso:values>
<pso:value>UK Updated Administrator</pso:value>
</pso:values>
</pso:description>
</pso:role>
</data>
</modification>
</modifyRequest>

The Response is as follows:

<ns9:ModifyResponseType xmlns="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns2="urn:oasis:names:tc:SPML:2:0"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns6="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns7="urn:names:spml:ws:header" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="24" status="pending"/>

32.16.16 SPML Example - Add Parent to a Role

The Request is as follows:

<modifyRequest xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous"
locale="string" policyURI="http://www.sample.com/string/string"
requestID="string" returnData="identifier">
 
<psoID ID="role:26" targetID="target" />
<modification modificationMode="modify">
<component path="/role" namespaceURI="http://www.w3.org/TR/xpath20" />
<data>
<pso:role>
<pso:description>
<!--1 or more repetitions:-->
<pso:values>
<!--1 or more repetitions:-->
<pso:value>UK Updated Administrator</pso:value>
</pso:values>
</pso:description>
</pso:role>
</data>
 
<capabilityData capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
mustUnderstand="true">
<reference typeOfReference="inheritsFrom"
xmlns="urn:oasis:names:tc:SPML:2:0:reference">
<toPsoID ID="25" />
</reference>
</capabilityData>
</modification>
</modifyRequest>

The Response is as follows:

<ns9:ModifyResponseType xmlns="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns2="urn:oasis:names:tc:SPML:2:0"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns6="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns7="urn:names:spml:ws:header" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="25" status="pending"/>

32.16.17 SPML Example - Role Grant

You cannot assign a role to multiple identities by using a SPML payload. If multiple identities are given, then the latest identity only is assigned with the role. You remove either of the identity from the payload.

The Request is as follows:

<modifyRequest xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous"
locale="string" policyURI="http://www.sample.com/string/string"
requestID="string" returnData="identifier">
<!--Zero or more repetitions:-->
<capabilityData capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
mustUnderstand="true" />
<psoID ID="identity:6C9B96E99FC8DC32E040E50A3D5252F5" />
<psoID ID="identity:6C9B96E99FC8DC32E040E50A3D5252F5" />
<!--1 or more repetitions:-->
<modification modificationMode="add">
<capabilityData capabilityURI="urn:oasis:names:tc:SPML:2:0:reference"
mustUnderstand="true">
<reference xmlns="urn:oasis:names:tc:SPML:2:0:reference"
typeOfReference="memberOf">
<toPsoID ID="6C9B96E99FC8DC32E040E50A3D5252F5" />
</reference>
</capabilityData>
</modification>
</modifyRequest>

The Response is as follows:

<ns9:ResponseType xmlns="urn:oasis:names:tc:SPML:2:0"
xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns5="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns6="urn:names:spml:ws:header" 
xmlns:ns7="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns8="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns9="oasis:names:tc:SPML:2:0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns4:ActiveResponseType" requestID="143" status="failure"/>

32.16.18 SPML Example - Delete Role

The Request is as follows:

<deleteRequest xmlns="urn:oasis:names:tc:SPML:2:0"
                        xmlns:pso="http://xmlns.oracle.com/idm/identity/PSO" executionMode="asynchronous"
                        locale="en" policyURI="http://www.sample.com/string/string"
                        requestID="string" returnData="identifier" targetID="string">
                        <psoID ID="role:6C9B96E99FC8DC32E040E50A3D5252F5" />
                </deleteRequest>

The Response is as follows:

<ns9:ResponseType xmlns="http://xmlns.oracle.com/idm/identity/PSO"
xmlns:ns2="urn:oasis:names:tc:SPML:2:0"
xmlns:ns3="urn:oasis:names:tc:SPML:2:0:reference"
xmlns:ns4="urn:oasis:names:tc:SPML:2:0:password"
xmlns:ns5="urn:oasis:names:tc:SPML:2:0:suspend"
xmlns:ns6="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username"
xmlns:ns7="urn:names:spml:ws:header" xmlns:ns8="urn:oasis:names:tc:SPML:2:0:async"
xmlns:ns9="oasis:names:tc:SPML:2:0" requestID="18" status="pending"/>

32.16.19 SPML Example - Status Request

The Request is as follows:

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

The Response is as follows:

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

Another Request is as follows:

<statusRequest xmlns="urn:oasis:names:tc:SPML:2:0:async"    requestID="12" asyncRequestID="1" returnResults="true" />

Here. returnResults=true. Therefore, the response will have all the attributes of the request.

The Response is as follows:

<ns9:StatusResponseType xmlns="urn:oasis:names:tc:SPML:2:0" xmlns:ns2="urn:oasis:names:tc:SPML:2:0:async" xmlns:ns3="http://xmlns.oracle.com/idm/identity/PSO" xmlns:ns4="urn:oasis:names:tc:SPML:2:0:reference" xmlns:ns5="urn:oasis:names:tc:SPML:2:0:password" xmlns:ns6="urn:oasis:names:tc:SPML:2:0:suspend" xmlns:ns7="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username" xmlns:ns8="urn:names:spml:ws:header" xmlns:ns9="oasis:names:tc:SPML:2:0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:StatusResponseType" requestID="12" status="success">
    <ns2:addResponse requestID="14" status="success">
        <pso>
            <psoID targetID="Identity"/>
            <data>
                <ns4:Identity xmlns:ns4="oasis:names:tc:SPML:2:0" xmlns:ns2="http://xmlns.oracle.com/idm/identity/PSO" xmlns:ns3="urn:oasis:names:tc:SPML:2:0:async" xmlns:ns5="urn:oasis:names:tc:SPML:2:0:async" xmlns:ns6="http://xmlns.oracle.com/idm/identity/spmlv2custom/Username" xmlns:ns7="urn:oasis:names:tc:SPML:2:0:suspend">
                    <ns2:attributes>
                        <ns2:attr xmlns="" xmlns:ns11="urn:oasis:names:tc:SPML:2:0" name="Organization">
                            <ns2:value>1</ns2:value>
                        </ns2:attr>
                    </ns2:attributes>
                    <ns2:activeEndDate>2009-12-25T16:00:00.000Z</ns2:activeEndDate>
                    <ns2:activeStartDate>2009-12-24T18:00:00.000Z</ns2:activeStartDate>
                    <ns2:commonName>
                        <ns2:values>
                            <ns2:value>Alice Krug</ns2:value>
                        </ns2:values>
                    </ns2:commonName>
                    <ns2:countryName>Canada</ns2:countryName>
                    <ns2:departmentNumber>
                        <ns2:value>123</ns2:value>
                    </ns2:departmentNumber>
                    <ns2:description>
                        <ns2:values>
                            <ns2:value>Alice Krugs profile</ns2:value>
                        </ns2:values>
                    </ns2:description>
                    <ns2:displayName>
                        <ns2:value>Alice Krug</ns2:value>
                    </ns2:displayName>
                    <ns2:employeeNumber>333</ns2:employeeNumber>
                    <ns2:employeeType>
                        <ns2:values>
                            <ns2:value>Full-Time</ns2:value>
                        </ns2:values>
                    </ns2:employeeType>
                    <ns2:facsimileTelephoneNumber>
                        <ns2:number>6506072253</ns2:number>
                    </ns2:facsimileTelephoneNumber>
                    <ns2:generationQualifier>
                        <ns2:value>II</ns2:value>
                    </ns2:generationQualifier>
                    <ns2:givenName>
                        <ns2:value>Alice</ns2:value>
                    </ns2:givenName>
                    <ns2:hireDate>1999-12-24T16:00:00.000Z</ns2:hireDate>
                    <ns2:homePhone>
                        <ns2:number>8888888888</ns2:number>
                    </ns2:homePhone>
                    <ns2:homePostalAddress>
                        <ns2:value>Baker street</ns2:value>
                    </ns2:homePostalAddress>
                    <ns2:initials>
                        <ns2:value>J S</ns2:value>
                    </ns2:initials>
                    <ns2:localityName>
                        <ns2:value>SFO</ns2:value>
                    </ns2:localityName>
                    <ns2:middleName>A</ns2:middleName>
                    <ns2:mobile>
                        <ns2:number>4083485309</ns2:number>
                    </ns2:mobile>
                    <ns2:organization>
                        <ns2:values>
                            <ns2:value>1</ns2:value>
                        </ns2:values>
                    </ns2:organization>
                    <ns2:organizationUnit>
                        <ns2:values>
                            <ns2:value>Sales</ns2:value>
                        </ns2:values>
                    </ns2:organizationUnit>
                    <ns2:pager>
                        <ns2:number>333</ns2:number>
                    </ns2:pager>
                    <ns2:postalAddress>
                        <ns2:value>Baker street 222</ns2:value>
                    </ns2:postalAddress>
                    <ns2:postalCode>
                        <ns2:value>4081</ns2:value>
                    </ns2:postalCode>
                    <ns2:postOfficeBox>
                        <ns2:value>333n</ns2:value>
                    </ns2:postOfficeBox>
                    <ns2:preferredLanguage>en</ns2:preferredLanguage>
                    <ns2:state>
                        <ns2:value>CA</ns2:value>
                    </ns2:state>
                    <ns2:street>
                        <ns2:value>Baker</ns2:value>
                    </ns2:street>
                    <ns2:surname>
                        <ns2:values>
                            <ns2:value>Krug</ns2:value>
                        </ns2:values>
                    </ns2:surname>
                    <ns2:telephoneNumber>
                        <ns2:number>6506072253</ns2:number>
                    </ns2:telephoneNumber>
                    <ns2:title>
                        <ns2:values>
                            <ns2:value>Mr</ns2:value>
                        </ns2:values>
                    </ns2:title>
                    <ns2:username>
                        <ns2:value>akrug3478</ns2:value>
                    </ns2:username>
                    <ns2:userType>End-User</ns2:userType>
                </ns4:Identity>
            </data>
        </pso>
    </ns2:addResponse>
</ns9:StatusResponseType>