11 Configuring Oracle Identity Federation for the Business Processing Plug-in

Oracle Identity Federation provides a plug-in framework to customize the business processing of the operations performed by the server. This chapter explains plug-in features and provides an example:

11.1 About the Business Processing Plug-in

This section describes some key facts about the plug-in framework.

11.1.1 Basic Flow of Business Processing Plug-in

The processing flow is as follows:

  • You implement a plug-in that will be invoked in various sections of the business flows.

  • The plug-in can analyze data collected during the execution of the operation, and decide whether an extra business step should be required.

  • If any additional actions are to be performed, the plug-in returns to Oracle Identity Federation a URL where the user needs to be redirected.

  • The redirection URL can contain query string parameters set by the plug-in.

  • Oracle Identity Federation appends one query string parameter, referenced by refID, to be sent when the user is returning to Oracle Identity Federation

  • Once the extra operation is performed, the user must be redirected to Oracle Identity Federation with the refid parameter, to the following URL:


11.1.2 Implementation

The tasks needed to implement the business processing plug-in are:

11.1.3 Building the Plug-in, Operations and Parameters

Building the Plug-in

The plug-in will need to extend the oracle.security.fed.plugins.bizops.OperationListener interface, and will need to implement the "public ListenerResult process(int operationType, OperationData params)" method.

This method has two arguments; the first is the type of operation being performed and the second includes parameters related to the operation that allow the plug-in to make a decision. The method returns a ListenerResult class containing a status and an optional redirectURL. If the status is OK, Oracle Identity Federation resumes its operations, otherwise it redirects the user to the specified redirection URL.


The operations include:

  • OperationTypes.BUSINESS_IDP_CREATE_PERSISTENT_FEDERATION: indicates a persistent federation is created on the IdP side

  • OperationTypes.BUSINESS_IDP_CREATE_TRANSIENT_FEDERATION: indicates a transient federation is created on the IdP side

  • OperationTypes.BUSINESS_IDP_SSO: indicates an SSO operation performed on the IdP side

Parameters Passed

The parameters passed in the OperationData object are:

  • BusinessProcessingConstants.DATA_STRING_PROVIDERID: references the Service Provider ID. Type is String

  • BusinessProcessingConstants.DATA_STRING_USERID: references the User ID. Type is String

  • BusinessProcessingConstants.DATA_STRING_SESSIONID: references the Session ID. Type is String

  • BusinessProcessingConstants.DATA_STRING_NAMEID_FORMAT: references the Name ID Format of the federation being created. Type is String

  • BusinessProcessingConstants.DATA_STRING_PROTOCOL_VERSION: references the protocol being executed. Type is String

  • BusinessProcessingConstants.DATA_BOOLEAN_AUTHNREQUEST_ISPASSIVE: references the IsPassive field from the AuthnRequest. Type is Boolean

The returned status values of the ListenerResult class can be:

  • BusinessProcessingConstants.STATUS_OK: indicates that the plug-in does not require any particular action.

  • BusinessProcessingConstants.STATUS_REDIRECT: indicates that the plug-in wishes to redirect the user to a URL.

11.2 Configuring the Business Processing Plug-in

Follow these steps to add a plug-in to the Oracle Identity Federation configuration file:

  1. Open the $DOMAIN_HOME/config/fmwconfig/servers/wls_oif1/applications/OIF_11. file

  2. Locate the Config XML element whose attribute name is serverconfig.

  3. Locate the PropertiesList XML element whose attribute name is businessprocessingplugins.

  4. Add a Property XML child element to the PropertiesList. The text child of the Property element should be the classname of the plug-in, and the type attribute of this element should be string.

  5. Save and exit.

Here is an example of the configured file:

<FederationConfig xmlns="http://xmlns.oracle.com/fed/schema/oif-11_2.xsd" version="0" activationenabled="false">
   <Config name="serverconfig">
       <PropertiesList name="businessprocessingplugins">
          <Property type="string">oracle.security.fed.plugins.BusinessProcessingSample</Property>

11.3 Packaging the Plug-in

Take these steps to package your plug-in:

  1. Add the plug-in to a jar file.

  2. Copy the jar file to the Oracle WebLogic Server lib directory:

  3. Copy other required jar files to the same directory:

    • Copy oif.jar from Oracle/Middleware/Oracle_IDM1/fed/jlib/ to Oracle/Middleware/user_projects/domains/IDMDomain/lib.


      Repeat this step every time after you apply a patch set.

    • Copy commons-httpclient-3.1.jar to the same directory.

    • Copy commons-codec-1.2.jar to the same directory.

For details about the environment configuration, see Setting Up Environment Variables in the Oracle Fusion Middleware Administrator's Guide.

11.4 Configuring JavaEE Security

Update the WebLogic policy file which resides in this location:


Add these lines to the file:

grant codeBase "file:${user.domain}/lib/-" {
  permission java.security.AllPermission;
  grant codeBase
  permission java.security.AllPermission;

11.5 Example of Plug-in and Redirect Page

A sample plug-in might look like this:

package oracle.security.fed.plugins;
import java.net.URLEncoder;
import java.util.Set;
import java.util.HashSet;
import oracle.security.fed.plugins.bizops.BusinessProcessingConstants;
import oracle.security.fed.plugins.bizops.BusinessProcessingException;
import oracle.security.fed.plugins.bizops.ListenerResult;
import oracle.security.fed.plugins.bizops.OperationData;
import oracle.security.fed.plugins.bizops.OperationListener;
import oracle.security.fed.plugins.bizops.OperationTypes;
// in this example, the plug-in will redirect the user to an external page the first time a user 
// creates a persistent federation. Later on, if the user creates another federation (with the same
// provider or another one), the plug-in will not redirect the user anymore.
// Note: restarting the server will wipe out the cached information from the plug-in, resetting the data
// indicating whether or not any user was already redirected to the external page.
public class BusinessProcessingSample implements OperationListener {
    private Set licenseAgreements = new HashSet();
    public ListenerResult process(int operationType, OperationData params)
        throws BusinessProcessingException {
        ListenerResult result = new ListenerResult(BusinessProcessingConstants.STATUS_OK);
                   String userid = params.getStringProperty(BusinessProcessingConstants.DATA_STRING_USERID);
                   if (!licenseAgreements.contains(userid))
                       // redirect to remote page
                       StringBuffer sb = new StringBuffer();
                       // add the user to the license agreement set
        return result;

Here is a sample redirect page:

<%@ page language="java"
// Set the Expires and Cache Control Headers
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "Thu, 29 Oct 1969 17:04:19 GMT");
String providerid = request.getParameter("providerid");
String userid = request.getParameter("userid");
String refid = request.getParameter("refid");
String returnurl = "http://OIF-HOST:OIF-PORT/fed/user?refid=" + URLEncoder.encode(refid);
License Agreeement approved for:
ProviderID = <%=providerid%>
UserID = <%=userid%>
<a href="<%=returnurl%>">Click here to resume flow</a>

11.6 Business Processing Plug-in API

The Business Processing Plug-in API (javadoc) is available at:

Oracle Fusion Middleware Business Processing Plug-in Java API Reference for Oracle Identity Federation