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:
This section describes some key facts about the plug-in framework.
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:
http(s)://OIF-HOST:OIF-PORT/fed/user?refid=VALUE_RETRIEVED_FROM_REDIRECT_URL
The tasks needed to implement the business processing plug-in are:
Build the plug-in.
See Section 11.1.3, "Building the Plug-in, Operations and Parameters".
Register the plug-in in the Oracle Identity Federation configuration file.
See Section 11.2, "Configuring the Business Processing Plug-in".
Package the plug-in in a JAR file and add this file to the CLASSPATH.
Set up JavaEE security.
Restart Oracle WebLogic Server.
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
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.
Follow these steps to add a plug-in to the Oracle Identity Federation configuration file:
Open the $DOMAIN_HOME/config/fmwconfig/servers/wls_oif1/applications/OIF_11.1.1.2.0/configuration/config.xml file
Locate the Config XML element whose attribute name is serverconfig.
Locate the PropertiesList XML element whose attribute name is businessprocessingplugins.
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.
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>
</PropertiesList>
...
</Config>
...
</FederationConfig>
Take these steps to package your plug-in:
Add the plug-in to a jar file.
Copy the jar file to the Oracle WebLogic Server lib directory:
Oracle/Middleware/user_projects/domains/IDMDomain/lib
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.
Note:
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.
Update the WebLogic policy file which resides in this location:
Oracle/Middleware/wlserver_10.3/server/lib/weblogic.policy
Add these lines to the file:
grant codeBase "file:${user.domain}/lib/-" {
permission java.security.AllPermission;
};
grant codeBase
"file:/home/oracle/Oracle/Middleware/user_projects/domains/IDMDomain/lib/-"
{
permission java.security.AllPermission;
};
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);
switch(operationType)
{
case OperationTypes.BUSINESS_IDP_CREATE_PERSISTENT_FEDERATION:
String userid = params.getStringProperty(BusinessProcessingConstants.DATA_STRING_USERID);
if (!licenseAgreements.contains(userid))
{
// redirect to remote page
result.setStatus(BusinessProcessingConstants.STATUS_REDIRECT);
StringBuffer sb = new StringBuffer();
sb.append("http://WEB-SERVER-HOST:WEB-SERVER-PORT/businesstest.jsp?providerid=");
sb.append(URLEncoder.encode(params.getStringProperty(BusinessProcessingConstants.DATA_STRING_PROVIDERID)));
sb.append("&userid=");
sb.append(URLEncoder.encode(params.getStringProperty(BusinessProcessingConstants.DATA_STRING_USERID)));
result.setRedirectURL(sb.toString());
// add the user to the license agreement set
licenseAgreements.add(userid);
}
break;
}
return result;
}
}
Here is a sample redirect page:
<%@ page language="java"
import="java.net.*"%>
<%
// 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);
%>
<html>
<body>
License Agreeement approved for:
ProviderID = <%=providerid%>
<BR>
UserID = <%=userid%>
<BR>
<a href="<%=returnurl%>">Click here to resume flow</a>
</body>
</html>
The Business Processing Plug-in API (javadoc) is available at: