Oracle® Fusion Middleware Administrator's Guide for Oracle Identity Federation 11g Release 1 (11.1.1) E13400-04 |
|
Previous |
Next |
Oracle Identity Federation provides a plug-in framework to customize the business processing of the operations performed by the server. Plug-in features and an example are provided here.
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.
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.
Operations
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.
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>
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 the same directory
Copy commons-httpclient-3.1.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:
Oracle Fusion Middleware Business Processing Plug-in Java API Reference for Oracle Identity Federation