You can develop a plug-in that allows Oracle Access Management Identity Federation to process SAML messages that contain custom elements and attributes often required by third party or custom SAML implementations. In effect, you will be extending the functionality of the OIFMessageProcessingPlugin.
This chapter contains the following sections.
Because SAML is an extensible protocol, custom elements and attributes can be inserted into SAML messages where needed. Third party or custom SAML implementations might require these particular custom elements or attributes to function. For example, an Identity Provider (IdP) might require a custom <CompanyInfo> element included in the SAML extensions portion of the message to provide the name of the company issuing the SAML request. The Oracle Access Management Identity Federation (Identity Federation) OIFMessageProcessingPlugin can be modified to process these custom elements.
Note:
Only one plug-in is allowed in your Oracle Access Management environment but you can use conditional logic in the plug-in to accomplish different things for different messages.Follow this procedure to extend the OIFMessageProcessingPlugin code.
Create a directory.
In this tutorial, we will call it plugindev.
Create the following subdirectories.
plugindev/src/msgprocplugin
Create SampleMsgProcPlugin.java using the content in Example 19-1.
Oracle Access Management overrides the standard JDK XML classes with Oracle-specific ones so the DOM factory objects are retrieved directly from the System Class Loader using Class.forName.
Example 19-1 SampleMsgProcPlugin.java
package msgprocplugin;
import java.io.*;
import java.util.*;
import javax.xml.parsers.*;
import oracle.security.am.plugin.*;
import oracle.security.fed.plugins.fed.msgprocessing.*;
import org.w3c.dom.*;
import org.w3c.dom.ls.*;
import org.xml.sax.*;
import static java.lang.System.err;
public class SampleMsgProcPlugin extends OIFMessageProcessingPlugin {
private boolean monitoringStatus;
public ExecutionStatus process(MessageContext messageCtx) throws MessageProcessingException {
try {
String msg = "";
msg += "************************************\n";
msg += "* SAMPLE MESSAGE PROCESSING PLUGIN *\n";
msg += "************************************\n";
msg += "Partner Name: " + messageCtx.getPartnerName() + "\n";
msg += "Message Type: " + messageCtx.getMessageType() + "\n";
msg += "Message Version: " + messageCtx.getMessageVersion() + "\n";
msg += "User DN: " + messageCtx.getUserDN() + "\n";
msg += "User ID: " + messageCtx.getUserID() + "\n";
msg += "User ID Store: " + messageCtx.getUserIDStore() + "\n";
// Determine if this message meets our criteria for modification
boolean matches =
"LoopbackIDP".equals("" + messageCtx.getPartnerName()) &&
"SSO_AUTHN_REQUEST_OUTGOING".equals("" + messageCtx.getMessageType()) &&
"SAML2.0".equals("" + messageCtx.getMessageVersion());
if (!matches)
msg += "@@@@@@ CRITERIA NOT MET - SKIPPING THIS MESSAGE @@@@@@\n";
else {
// your business logic here
}
msg += "=================ENDS===================\n";
err.println(msg);
return ExecutionStatus.SUCCESS;
} catch (Exception e) {
e.printStackTrace();
throw handle(e);
}
}
@Override
public String getDescription(){
return "Sample Message Processing Plugin";
}
@Override
public Map<String, MonitoringData> getMonitoringData(){
return null;
}
@Override
public boolean getMonitoringStatus(){
return monitoringStatus;
}
@Override
public String getPluginName(){
return "SampleMsgProcPlugin";
}
@Override
public int getRevision() {
return 123;
}
@Override
public void setMonitoringStatus(boolean status){
this.monitoringStatus = status;
}
}
Place SampleMsgProcPlugin.java in the plugindev/src/msgprocplugin directory.
Create the SampleMsgProcPlugin.xml plug-in manifest using the content in Example 19-2.
In this step, you can also define configuration settings for the plug-in that can then be modified using the Oracle Access Management Console.
Example 19-2 SampleMsgProcPlugin.xml
<?xml version="1.0"?> <Plugin type="Message Processing"> <author>John Doe</author> <email>donotreply@example.com</email> <creationDate>2015-04-16 12:53:37</creationDate> <description>Sample Message Processing Plugin</description> <configuration> </configuration> </Plugin>
Put SampleMsgProcPlugin.xml in the plugindev/ directory
Create the MANIFEST.MF file using the content in Example 19-3.
This represents the OSGi bundle metadata. It lists the Java packages required by the plug-in.
Note:
Note that Import-Package is all on one-line.Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: SampleMsgProcPlugin Bundle-SymbolicName: SampleMsgProcPlugin Bundle-Version: 1 Bundle-Activator: oracle.ateam.msgprocplugin.SampleMsgProcPlugin Import-Package: javax.xml.parsers,oracle.security.am.plugin,oracle.security.fed.plugins.fed.msgprocessing,org.osgi.framework;version="1.3.0",org.w3c.dom,org.w3c.dom.ls,org.xml.sax Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Put MANIFEST.MF in the plugindev/ directory
Create the compile.sh shell script using the content in Example 19-4.
This shell script compiles the plug-in. Another option would be to use ANT or Maven. The path DOMAIN_HOME and the SERVER_NAME will need to be changed for your environment. Also note that JARS= is all on one line.
Note:
Note that JARS= is all on one-line.#!/bin/bash DOMAIN_HOME=/idmtop/config/domains/IAMAccessDomain SERVER_NAME=wls_oam1 JARS="$(find $DOMAIN_HOME/servers/$SERVER_NAME/tmp/_WL_user/oam_server_11.1.2.0.0/ -name fed.jar -o -name oam-plugin.jar -o -name felix.jar | tr '\n' ':' | sed -e 's/:$//')" SRCS="$(find src -name '*.java')" rm -rf build mkdir build javac -d build -classpath $JARS $SRCS cp SampleMsgProcPlugin.xml build mkdir build/META-INF cp MANIFEST.MF build/META-INF cd build jar cvmf META-INF/MANIFEST.MF ../SampleMsgProcPlugin.jar *
Put compile.sh in the plugindev/ directory
Run compile.sh to create SampleMsgProcPlugin.jar.
Use this procedure to import and activate the SampleMsgProcPlugin.jar.
Login to Oracle Access Management Console as administrator.
Click Application Security at the top of the Console.
Click Authentication Plug-ins under the Plug-ins section.
The Authentication Plug-ins screen is used to configure all Oracle Access Management plug-ins.
Click Import Plug-in.
An Import Plug-in screen is displayed.
Click Browse and search for the SampleMsgProcPlugin.jar that was built in "Extending the OIFMessageProcessingPlugin".
Click Import to upload the JAR.
Refresh the table and search for the plug-in you just imported.
Click Distribute Selected.
Click the Refresh icon to confirm that the status has changed to Distributed.
Click Activate Selected.
Click the Refresh icon to confirm that the status has changed to Activated.
The plug-in has now been installed and activated.
Use this procedure to tell Identity Federation that the SampleMsgProcPlugin.jar is ready for use.
Open the $DOMAIN_HOME/config/fmwconfig/oam-config.xml file in a text editor.
Find the Setting with name messageprocessingeplugin tag defined under the Setting with name fedserverconfig tag.
Change the value of messageprocessingeplugin to the name of the plug-in.
Find the Setting with name messageprocessingenabled tag defined under the Setting with name fedserverconfig tag.
Change the value of messageprocessingenabled from false to true.
Find the Setting with name Version (near the top of the file) and increment the version number.
This should be done every time the oam-config.xml file is modified.
Save the file.
When the version number in the oam-config.ref file in the same directory has increased to the new version number, the modifications have been loaded.