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

Part Number E14309-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

4 Using the Callback Service

The callback service invokes deployment-specific logic at predetermined points during Oracle Identity Manager event processing. Callback service is described in the following sections:

4.1 Introducing the Callback Service

The callback service triggers notifications and callbacks that allow external applications to perform some action as a part of Oracle Identity Manager event processing. For example, if a user is created by using Oracle Identity Manager, an external application that is registered to be apprised of that type of provisioning event will be notified, and therefore, the application can add the same user information to their own local data store. This is a notification. Notifications allow applications to sync changes and data.

Note:

A Web service endpoint for the external application must be registered in the Callback Service configuration. See "Configuring the Callback Service" for more information.

When an external application initiates the user provisioning event with Oracle Identity Manager, other external applications that are registered to be apprised of that type of provisioning event are contacted by Oracle Identity Manager. If Oracle Identity Manager itself is invoked by the external application as part of the provisioning process, then the notification is referred to as a callback. Therefore, a callback is simply notification of an external application followed by a callback to Oracle Identity Manager. Callbacks sync up information about an event between all registered parties and Oracle Identity Manager. A callback can also indicate success or failure status for the event.

Note:

The callback service infrastructure handles both callbacks and notifications. In this document, callbacks is used to refer to both.

There are a number of callback types handled by the callback service. They include:

The callback service is built to invoke callbacks for events from any source including a user interface, Oracle Identity Manager request API or Service Provisioning Markup Language (SPML) client. It is a listener service that receives responses to asynchronous client callbacks. When a client Web service is invoked, Oracle Identity Manager generates a unique identifier and sends it along with the call. When the client responds back, it must use this identifier to correlate the response with the original Web service request. The callback service takes appropriate action based on the client response. The following sections contain additional information regarding the components of the Callback Service:

4.1.1 Using Callbacks

This section describes a use case for Oracle Identity Manager callbacks. This use case is specific to Segregation of Duties (SoD) status change notifications. The use case concerns James North, an existing user and member of the POApprover role. James is requesting two additional roles: the POCreator and Buyer. The request goes through the following process:

  1. Oracle Identity Manager receives the request and creates an Assign Roles request with an ID of 21.

    A Request ID is a unique identifier generated by Oracle Identity Manager and used to correlate the request with future responses and communications.

  2. Oracle Identity Manager initiates an SoD validation with Oracle Applications Access Control Governor (OAACG).

  3. The Oracle Identity Manager request status changes and a callback is returned to the callbacks-registered Web services indicating SoD Check in Progress. The callback contains the request ID, the requested operation (MODIFY), the target type (IDENTITY), the targetGUID (JNORTH) and the locale (en_US).

  4. OAACG returns an Approved with Conditions response indicating the Buyer role is acceptable but the POCreater role is in violation due to James' existing POApprover role.

  5. The Oracle Identity Manager request status changes and a second callback is sent to the callbacks-registered Web services indicating an SoD Remediation In Progress. It contains the same identification information as the previous callback.

  6. A TAG named CFOOVERRIDE is placed in the rejection notes, indicating the Chief Financial Office (CFO) can approve this violation in selective cases.

    You must configure OBR rules to invoke an exception approval if any tag is placed with the rejection notes that uses 'OVERRIDE' at the end.

  7. AMX Rules decipher the tag and determine that CFO approval is required so that the task is assigned to the person with title 'CFO'.

  8. The CFO either approves the request, or rejects it.

    1. If the request is rejected, then the Oracle Identity Manager request status changes and a third callback is returned as SoD Remediation Rejected. The Oracle Identity Manager request is then closed with the SoD Remediation Rejected status.

      Note:

      If one portion of the request is rejected, then the entire request is rejected. Therefore, in this example, although the Buyer role does not have an SoD violation, it is not provisioned to the user.

    2. If the request is approved, then the Oracle Identity Manager request status changes and a third callback is returned as SOD Remediation Approved. The Oracle Identity Manager request is updated with the SOD Remediation Approved status. OAACG and requesting application is notified of the approval, and the roles are provisioned.

  9. When the Oracle Identity Manager request status changes to Request Completed, then a final callback is sent to all the callbacks-registered Web services indicating that the request is completed with the Request Completed status.

4.1.2 Understanding Event Processing

Figure 4-1 illustrates how an event is processed. Oracle Identity Manager uses asynchronous invocation, giving the calling applications flexibility to process the event as needed, such as starting a human approval workflow.

Figure 4-1 Callback Service Process

Description of Figure 4-1 follows
Description of "Figure 4-1 Callback Service Process"

For this release, the callback service supports a handler and a plugin event. They are:

  • Post-processing Handler: Invoked after the provisioning event is processed but before the request is marked as complete. The default post-processing handler will invoke multiple callbacks based on the callback service configuration.

  • Status Change Plugin: Invoked when there is any change in the request status; for example, if the status of a user provisioning request is changed to completed or failed, or a request status change is recognized due to a Segregation of Duties (SoD) check, then a status change callback will be sent. The default Status Change Plugin may invoke multiple callbacks based on the callback service configuration.

4.1.3 Retrying Callbacks

The callback service retries callbacks if there are network errors when invoking a service. Oracle Identity Manager retries the callback a fixed three times after a fixed five second interval. These values are not configurable.

4.2 Mapping Oracle Identity Manager Attributes

The names of attributes used by Oracle Identity Manager are proprietary. For example, a third-party application may refer to a user's last name as surname while Oracle Identity Manager uses Last Name. Because of this, attribute mapping is essential.

Note:

The callback service uses the same attributes defined by the Service Provisioning Markup Language (SPML) layer of Oracle Identity Manager. These are referred to (singularly) as a SPML Provisioning Service Object (PSO). See Appendix B, "SPML Attributes and LDAP Mappings, and Oracle Identity Manager Attributes" for details.

Mapped attribute names are used in messages sent as well as in callback configuration (particularly, in the ConstraintAttribute parameter). Table 4-1 defines how Oracle Identity Manager user type attributes are represented in callbacks using SPML PSOs.

Table 4-1 Oracle Identity Manager / Callback Service User Attribute Mapping

Callback Service Attribute (PSO) Oracle Identity Manager User Attribute

activeEndDate

End Date

activeStartDate

Start Date

commonName

Common Name

countryName

Country

departmentNumber

Department Number

description

Description

displayName

Full Name

employeeNumber

Employee Number

employeeType

Role

facsimileTelephoneNumber

Fax

generationQualifier

Generation Qualifier

hireDate

Hire Date

homePhone

Home Phone

homePostalAddress

Home Postal Address

initials

Initials

localityName

Locality Name

mail

Email

middleName

Middle Name

mobile

Mobile

organization

LDAP Organization

organizationUnit

LDAP Organization Unit

pager

Pager

password

Password

postalAddress

Postal Address

postalCode

Postal Code

postOfficeBox

PO Box

preferredLangauage

Language

state

State

street

Street

surname

Last Name

telephoneNumber

Telephone Number

title

Title

userId

usr_key

userName

User Login


Table 4-2 defines how Oracle Identity Manager role type attributes are represented in callbacks using SPML PSOs.

Table 4-2 Oracle Identity Manager / Callback Service Role Attribute Mapping

Callback Service Attribute (PSO) Oracle Identity Manager Role Attribute

commonName

Role Name

description

Role Description

displayName

Display Name


If the attribute name is not in either of these tables, it is referenced by its Oracle Identity Manager attribute.

4.3 Sending Event Callbacks

By default, callbacks are enabled (sent) for all Oracle Identity Manager events listed in EventHandlers.xml, the handler invoked by the Orchestration Engine during the post-processing stage of the provisioning process. Each event specifies the applicable entity type and operation. Specific callbacks may be disabled by changing the configuration. Table 4-3 summarize the user and role events for which Oracle Identity Manager makes callbacks and the information returned with the callback.

Table 4-3 Callback Initiated Events

Entity / Operation Event Initiator Returned in Post-Processing Handler Returned in Status Change Plugin Callback

User Create

Third party requests only. No callbacks when a user is created using the console or through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • Provisioning Service Object (PSO) with created attributes and values (except password and challenge questions)

    Note: PSO is used for create operations. Modification objects are used for modify operations.

  • Roles assigned to the user

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

User Modify

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • Modification object* with modified attributes and values (except password and challenge questions)

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

User Delete

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

User Suspend (disable)

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

User Resume (enable)

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

User Assign Role - add memberOf

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • Modification object* with GUIDs of assigned roles

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

User Revoke Role - delete memberOf

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • Modification object* with GUIDs of assigned roles

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

Role Add

Third party requests only. No callbacks when a role is created using the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • PSO* with created attributes and values

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

Role Modify

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • Modification object* with modified attributes and values

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID

Role Delete

All sources: third party requests, the console and through a reconciliation event.

  • Target Type

  • Target GUID

  • Operation

  • Request ID

  • OIM Request Status

  • Target Type

  • Target GUID

  • Operation

  • Request ID


4.4 Configuring the Callback Service

Configuration of the callback service specifies how and when one or more callbacks are invoked. The following sections contain information on the configuration file and the procedure to import this file to the Metadata Services repository.

4.4.1 Understanding CallbackConfiguration.xml

The configuration is stored in a single file called CallbackConfiguration.xml. This configuration file is located in the Oracle Identity Manager meta directory repository. It is used by the default event handlers and validation plug-in. The following parameters are configurable:

  • Policy name: Defines the name of the callback policy. The value comes from the provisioning request. This is unique to Oracle Identity Manager and takes a string value.

  • Entity type: Refers to the entity type for which the callback policy is applicable. It is a required, single value. Possible values are User, Role, and RoleUser.

  • Operation: Refers to the database operations for which the callback policy is applicable. The required value may be either Create or Delete.

  • Description: Takes a localized string that is a description of the policy.

  • ConstraintAttribute and ConstraintAttributeValue: Fields specify a simple constraint that allows handlers and plug-in code to decide whether to invoke the particular callback for the given object. The attribute will be searched for in the entity data available to the handler, either in the form of orchestration data or RequestData. If the data does not exist, the constraint will not apply.

    • ConstraintAttribute: Takes as a value the name of an attribute on which the constraint is specified. The name must be the attribute name as defined on the application side as opposed to the name defined on the Oracle Identity Manager side. See "Mapping Oracle Identity Manager Attributes" for more information.

    • ConstraintAttributeValue: Takes a value equal to the value the ConstraintAttribute must have. The value here must be the same as the value of the ConstraintAttribute present in the orchestration or request data. If the data has multiple values, at least one must match. This parameter is relevant only when ConstraintAttribute itself has a value.

  • Provisioning Steps: Specifies the orchestration step for which this callback policy should be used. Possible values are:

    • validation

    • preProcessing

    • approval

    • postProcessing

    • completion

  • stepName: Refers to a Web service endpoint for the external application.

  • description: Takes a localized string that is a description of the Web service endpoint.

  • InvokeOnChange: Takes as a value one or more attribute names and is applicable only to modify operations. The callback will be invoked only when one of the attributes listed as a value of this parameter has changed. The value must be the attribute name as defined on the application side as opposed to the name defined on the Oracle Identity Manager side. See "Mapping Oracle Identity Manager Attributes" for more information.

  • CallbackOnly: Specifies whether Oracle Identity Manager should wait for a response from the external application. Possible values are true or false. If true, then Oracle Identity Manager will wait for a response from the application and, until a response is received, the orchestration process will be waiting. If false, then Oracle Identity Manager will not wait for a callback response and the orchestration process will continue.

  • targetIDAttribute: Takes as a value an attribute that should be used as the target GUID in the message. The value must be the attribute name as defined on the application side as opposed to the name defined on the Oracle Identity Manager side. See "Mapping Oracle Identity Manager Attributes" for more information. The default value is LDAP GUID.

  • roleIDAttribute: Takes as a value the role attribute that should be used as role GUID in the message. The value must be the attribute name as defined on the application side as opposed to the name defined on the Oracle Identity Manager side. See "Mapping Oracle Identity Manager Attributes" for more information. The default value is LDAP GUID.

Example 4-1 is a sample configuration file.

Example 4-1 Sample CallbackConfiguration.xml

<?xml version='1.0' encoding='UTF-8'?>
<callbackConfiguration xmlns="http://www.oracle.com/schema/oim/callback_config" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.oracle.com/schema/oim/callback_config">
<policy>
<policyName>User Creation1</policyName>
<entityType>User</entityType>
<operation>Create</operation>
<description>Policy to create  a user in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>User Enable1</policyName>
<entityType>User</entityType>
<operation>Enable</operation>
<description>Policy to enable  a user in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>User Delete1</policyName>
<entityType>User</entityType>
<operation>Delete</operation>
<description>Policy to delete  a user in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>User Disable1</policyName>
<entityType>User</entityType>
<operation>Disable</operation>
<description>Policy to disable  a user in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>User Modify1</policyName>
<entityType>User</entityType>
<operation>Modify</operation>
<description>First Policy to modify  a user in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>Role Assign1</policyName>
<entityType>RoleUser</entityType>
<operation>CREATE</operation>
<description>Policy to assign roles to the user</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>Role Revoke1</policyName>
<entityType>RoleUser</entityType>
<operation>Delete</operation>
<description>Policy to revoke role from the user</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>Role Creation1</policyName>
<entityType>Role</entityType>
<operation>Create</operation>
<description>Policy to create  a role in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>Role Delete1</policyName>
<entityType>Role</entityType>
<operation>Delete</operation>
<description>Policy to delete  a role in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
<policy>
<policyName>Role Modify1</policyName>
<entityType>Role</entityType>
<operation>Modify</operation>
<description>Policy to modify  a role in the store</description>
<provisioningSteps>
<postProcessing>
<asyncSteps>
<stepName>http://adc2120179.us.oracle.com:7001/testCallbackService/
   PostProcessingPluginRequestPortImplTest</stepName>
<description>Webservice url for this policy</description>
</asyncSteps>
</postProcessing>
</provisioningSteps>
</policy>
</callbackConfiguration>

4.4.2 Importing CallbackConfiguration.xml

Following is the procedure to configure the callback service. It entails importing the CallbackConfiguration.xml file. This file contains list of callback policies for a given entity type or operation.

  1. Create a credential entry in the Credential Store Framework (CSF) with the map name oim and key appid.keycredentials.

    This entry stores the user name and password that Oracle Identity Manager will use to identify itself for callbacks. The CSF is available as part of domain creation when Oracle Identity Manager is installed.

    See Also:

    Oracle Fusion Middleware Security Guide for information about the Credential Store Framework

  2. Import CallbackConfiguration.xml to the Metadata Services (MDS) repository using the weblogicImportMetadata.sh MDS utility.

    It should be loaded under the /metadata/iam-features-callbacks/sample_data/ namspace.

The following should be considered when importing CallbackConfiguration.xml:

  • Ensure that the CallbackConfiguration.xml file is imported to the MDS repository under the exact metadata namespace: /metadata/iam-features-callbacks/sample_data/

  • Remove old CallbackConfiguration.xml files in other metadata namespaces. For example, /metadata/iam-features-callbacks/old_config/CallbackConfiguration_st3b16.xml and /metadata/iam-features-callbacks/old_config/CallbackConfiguration.xml are not valid. Remove any invalid entries found in the MDS repository using weblogicDeleteMetadata.sh.

  • If modifications are made to CallbackConfiguration.xml after it has been imported, then reimport the modified file as documented and purge the Oracle Identity Manager cache by using the PurgeCache.sh utility located in the OIM_HOME/server/bin/ directory.

4.5 Troubleshooting the Callback Service

Table 4-4 lists the troubleshooting steps that you can perform if you encounter callback service errors:

Table 4-4 Trobleshooting Callback Service

Problem Solution

Not able to submit SPML request (Failed Authentication).

Make sure that the SPML request is submitted with a valid SPML user (member of SPML_App_Role group) with its correct credentials.

If the request is submitted from client APIs, then note that compatible client policy must be applied.

The following is the sample eror response displayed when a SPML request is submitted with incorrect credentials:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"><env:Header/><env:Body><env:Fault xmlns:ns0="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"><faultcode>ns0:FailedAuthentication</faultcode><faultstring>FailedAuthentication : The security token cannot be authenticated.</faultstring><faultactor/></env:Fault></env:Body></env:Envelope>

For a given request type, for example Assign Role, Oracle Identity Manager is making callbacks to more than one callback Web service although the policyName matches with one callback service.

This is because when callbackOnly is set to false for all the eligible entity type and operation, for example Assign Role request types, the callbacks are triggered for all matching entity types and operations.

PolicyName matching is ignored when callbackOnly attribute is set to false.

If callbackOnly Attribute is set to true, then it checks for the policy name. All the callback Web service URLs present in that policy are triggered when the entity type and operation condition is also met.

All the callback Web service URLs present in that policy are triggered when the entity type and operation condition is also met.

The policy reference URI 'oracle/wss_saml_or_username_token_service_policy' is not valid.

Make sure that WSM Policy Manager is deployed and targeted to the interacting servers such as Oracle Identity Manager and SPML request starting server.In addition, make sure that WSM Policy Manager is in active mode and is ready for serving the requests.

Not sure what is SPML APPID and Oracle Identity Manager APPID, and where these APPIDs are to be created.

SPML APPID is used for submitting SPML requests to Oracle Identity Manager. Any client that seeks user provisioning service with Oracle Identity Manager must contain SPML APPID in their repository. For example, when Fusion Applications is the client to Oracle Identity Manager, Fusion Applications typically use LDAP directory as their repository.

Oracle Identity Manager APPID is used for sending callbacks to all the Web services registered in the CallbackConfiguration.xml file for a given SPML request type.

Oracle Identity Manager repository or database contains only SPML APPID. Oracle Identity Manager APPID is not present in Oracle Identity Manager repository but is present in the Credentials Store Framework (CSF) under map name oim and with key appid.credentials.

SPML repository or LDAP contains both SPML APPID and Oracle Identity Manager APPID.

When Fusion Applications sends a SPML request to Oracle Identity Manager, it uses SPML APPID to communicate to Oracle Identity Manager. This SPML APPID is present in the SPML repository or LDAP. This user is authenticated at Oracle Identity Manager side against the database. Therefore, Oracle Identity Manager database contains SPML APPID in it.

When Oracle Identity Manager communicates with Fusion Applications, it uses Oracle Identity Manager APPID to communicate to Fusion Applications. This Oracle Identity Manager APPID is present in the CSF. This user is authenticated at Fusion Applications side again LDAP by checking the Oracle Identity Manager APPID in LDAP repository. Therefore, LDAP contains Oracle Identity Manager APPID in it.