19 Developing a Message Processing Plug-in

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.

19.1 Understanding Custom SAML Elements

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.


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.

19.2 Extending the OIFMessageProcessingPlugin

Follow this procedure to extend the OIFMessageProcessingPlugin code.

  1. Create a directory.

    In this tutorial, we will call it plugindev.

  2. Create the following subdirectories.


  3. 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";
                            return ExecutionStatus.SUCCESS;
                    } catch (Exception e) {
                            throw handle(e);
            public String getDescription(){
                    return "Sample Message Processing Plugin";
            public Map<String, MonitoringData> getMonitoringData(){
                    return null;
            public boolean getMonitoringStatus(){
                    return monitoringStatus;
            public String getPluginName(){
                    return "SampleMsgProcPlugin";
            public int getRevision() {
                    return 123;
            public void setMonitoringStatus(boolean status){
                    this.monitoringStatus = status;
  4. Place SampleMsgProcPlugin.java in the plugindev/src/msgprocplugin directory.

  5. 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>
      <creationDate>2015-04-16 12:53:37</creationDate>
      <description>Sample Message Processing Plugin</description>
  6. Put SampleMsgProcPlugin.xml in the plugindev/ directory

  7. 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 that Import-Package is all on one-line.

    Example 19-3 MANIFEST.MF

    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
  8. Put MANIFEST.MF in the plugindev/ directory

  9. 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 that JARS= is all on one-line.

    Example 19-4 compile.sh

    JARS="$(find $DOMAIN_HOME/servers/$SERVER_NAME/tmp/_WL_user/oam_server_11. -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
    cd build
    jar cvmf META-INF/MANIFEST.MF ../SampleMsgProcPlugin.jar *
  10. Put compile.sh in the plugindev/ directory

  11. Run compile.sh to create SampleMsgProcPlugin.jar.

19.3 Deploying the Message Processing Plug-in

Use this procedure to import and activate the SampleMsgProcPlugin.jar.

  1. Login to Oracle Access Management Console as administrator.

  2. Click Application Security at the top of the Console.

  3. Click Authentication Plug-ins under the Plug-ins section.

    The Authentication Plug-ins screen is used to configure all Oracle Access Management plug-ins.

  4. Click Import Plug-in.

    An Import Plug-in screen is displayed.

  5. Click Browse and search for the SampleMsgProcPlugin.jar that was built in "Extending the OIFMessageProcessingPlugin".

  6. Click Import to upload the JAR.

  7. Refresh the table and search for the plug-in you just imported.

  8. Click Distribute Selected.

  9. Click the Refresh icon to confirm that the status has changed to Distributed.

  10. Click Activate Selected.

  11. Click the Refresh icon to confirm that the status has changed to Activated.

The plug-in has now been installed and activated.

19.4 Enabling the Message Processing Plug-in

Use this procedure to tell Identity Federation that the SampleMsgProcPlugin.jar is ready for use.

  1. Open the $DOMAIN_HOME/config/fmwconfig/oam-config.xml file in a text editor.

  2. Find the Setting with name messageprocessingeplugin tag defined under the Setting with name fedserverconfig tag.

  3. Change the value of messageprocessingeplugin to the name of the plug-in.

  4. Find the Setting with name messageprocessingenabled tag defined under the Setting with name fedserverconfig tag.

  5. Change the value of messageprocessingenabled from false to true.

  6. 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.

  7. 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.