The callback service invokes deployment-specific logic at predetermined points during Oracle Identity Manager event processing. Callback service is described in the following sections:
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:
Post-processing callbacks that are returned to external applications. For example, a request to provision a user profile in the configured Oracle Identity Manager data store is sent from an external application to Oracle Identity Manager as a Web service call. The profile is created and a post-processing callback is returned to the application to confirm the profile creation. These callbacks can be synchronous or asynchronous depending on the Oracle Identity Manager configuration.
Status change callbacks are sent to interested parties 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 because of a Segregation of Duties (SoD) check, then a status change callback is sent.
Note:
This functionality was previously referred to as a completion callback.Callback responses are generated by third parties and communicate to Oracle Identity Manager that a response to a post-processing callback will be returned. This Callback Response Service is manually configured as documented in "Configuring the Callback Service"
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:
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:
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.
Oracle Identity Manager initiates an SoD validation with Oracle Applications Access Control Governor (OAACG).
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).
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.
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.
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.
AMX Rules decipher the tag and determine that CFO approval is required so that the task is assigned to the person with title 'CFO'.
The CFO either approves the request, or rejects it.
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.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.
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.
Figure 35-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.
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.
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 "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 35-1 defines how Oracle Identity Manager user type attributes are represented in callbacks using SPML PSOs.
Table 35-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 |
|
|
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 35-2 defines how Oracle Identity Manager role type attributes are represented in callbacks using SPML PSOs.
Table 35-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.
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 35-3 summarize the user and role events for which Oracle Identity Manager makes callbacks and the information returned with the callback.
Table 35-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. |
|
|
User Modify |
All sources: third party requests, the console and through a reconciliation event. |
|
|
User Delete |
All sources: third party requests, the console and through a reconciliation event. |
|
|
User Suspend (disable) |
All sources: third party requests, the console and through a reconciliation event. |
|
|
User Resume (enable) |
All sources: third party requests, the console and through a reconciliation event. |
|
|
User Assign Role - add |
All sources: third party requests, the console and through a reconciliation event. |
|
|
User Revoke Role - delete |
All sources: third party requests, the console and through a reconciliation event. |
|
|
Role Add |
Third party requests only. No callbacks when a role is created using the console and through a reconciliation event. |
|
|
Role Modify |
All sources: third party requests, the console and through a reconciliation event. |
|
|
Role Delete |
All sources: third party requests, the console and through a reconciliation event. |
|
|
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.
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.
Note:
ConstraintAttribute and ConstraintAttributeValue are not multi-valued attributes in the callback policies. Therefore, you can provide only one constraintAttribute and constraintAttributeValue attribute for each callback policy. If you specify multiple constraintAttribute and constraintAttributeValue in a single callback policy, then the callback will be triggered even if all the constraints do not match.Tenant GUID: Indicates the tenant GUID to which a callback policy is applicable in the multi-tenant (MT) mode of Oracle Identity Manager. The callback URLs for different policies in the MT mode are different, and therefore, the tenant GUID must be specified to uniquely identify the tenant to which the callback is to be sent. An example of the usage of this tag is <tenantGUID>202</tenantGUID>. This tag is not used in the non-MT mode.
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 35-1 is a sample configuration file.
Example 35-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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.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://myhost.mycompany.com:7001/testCallbackService/ PostProcessingPluginRequestPortImplTest</stepName> <description>Webservice url for this policy</description> </asyncSteps> </postProcessing> </provisioningSteps> </policy> </callbackConfiguration>
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.
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 FrameworkImport CallbackConfiguration.xml to the Metadata Services (MDS) repository using the Oracle Enterprise Manager.
It should be loaded under the /metadata/iam-features-callbacks/sample_data/ namespace.
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.
In non-MT mode of Oracle Identity Manager, the OIM.DefaultTenantGUID system property must be set with a value that works as a tenant GUID for applications that expect a value for the tenant GUID. A sample value for this is 201. Oracle Identity Manager will not send any callback if this property is not set. If the application receiving the callbacks does not expect any specific tenant GUID, then provide any random value.
See Table 5-2: Nondefault System Properties in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about this system property.
Table 35-4 lists the troubleshooting steps that you can perform if you encounter callback service errors:
Table 35-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. |