Custom Authentication Module in OAM and SP

This article creates a new custom Authentication Module in OAM/SP that is made of existing OAM Federation Authentication Plugins and a custom plugin which:

For more information on how to design a custom Authentication Plugin, refer to the OAM Developer’s Guide, which describes how to develop such a module.

Focus on how to:

Federation Authentication Module

The OOTB Federation Authentication Module, called FederationPlugin, is made of two plugins:

The orchestration can be seen by:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole.

  2. Navigate to Access Manager , Authentication Modules.

  3. Open FederationScheme.

  4. Click on the Steps tab to see the plugins.

  5. Click on the Steps Orchestration tab to see the orchestration between the different plugins, and the plugin that is used to start the operation.

Description of the illustration Steps_Orchestration_Screen.jpg

FedAuthnRequestPlugin Plugin

The FedAuthnRequestPlugin can consume information from a previous custom Authentication Plugin that affects how the Federation SSO operation will be triggered.

The AuthenticationContext instance shared between the Authentications Plugins contains CredentialParam objects that allow the various plugins to communicate at runtime.

oracle.security.am.plugin.authn.AuthenticationContext: Context for the authentication operation Shared across the various Authentication Plugins

oracle.security.am.plugin.authn.Credential: Collection of credentials data Stored in the AuthenticationContext

oracle.security.am.plugin.authn.CredentialParam: Single credential parameter Referenced by a name, and has a type (string most of the time) Has a value, depending on the type Stored in the Credential instance

Using that mechanism, the FedAuthnRequestPlugin can consume various types of information when starting a Federation SSO operation, stored in the Credential instance:

Custom Authentication Plugin

Overview

The custom Authentication Plugin:

In the example, we have:

These three elements is bundled in a JAR file that is then uploaded to the OAM server via the OAM Administration Console. Once uploaded and activated, create a Federation Authentication Module.

Java Class

The class implementing my custom Authentication plugin must adhere to the following:

The following code is an example of the custom plugin.

 package userauthn;
 import java.util.Map;
 import oracle.security.am.plugin.ExecutionStatus; import oracle.security.am.plugin.MonitoringData;
 import oracle.security.am.plugin.authn.AbstractAuthenticationPlugIn; import oracle.security.am.plugin.authn.AuthenticationContext; import oracle.security.am.plugin.authn.AuthenticationException; import oracle.security.am.plugin.authn.CredentialParam;
 public class CustomIdPSelectionPlugin extends
 AbstractAuthenticationPlugIn
 {
  public ExecutionStatus process(AuthenticationContext context)
  throws AuthenticationException {
  // requested URL
  String resourceURL = context.getResourceURL();
  // determines the IdP based on the request resource
  String idpPartnerName = null;
  if (resourceURL.startsWith("http://company.com/businesspartners/acmebank"))
  idpPartnerName = "AcmeIdP";
  else if (resourceURL.startsWith("http://company.com/businesspartners/worldbank"))
  idpPartnerName = "WorldBank";
  else if (resourceURL.startsWith("http://company.com/businesspartners/worldinsurance"))
  idpPartnerName = "WInsuranceIdP";
  // if IdP was determined, create a Credential param
  // instance in the AuthenticationContext
  // the OAM/SP FedAuthnRequestPlugin will consume it
 to start Federation SSO if (idpPartnerName != null) {
  CredentialParam idpParam = new
 CredentialParam();
  idpParam.setName("KEY_FEDIDP");
  idpParam.setType("string");
  idpParam.setValue(idpPartnerName);

 context.getCredential().addCredentialParam("KEY_FEDIDP", idpParam);
  }
  // here, the plugin evaluates if the account subpath is being requested
  // if it is, it requests from IdP higher Fed Auth
 Method
  String fedAuthnMethod = null;
  if ("AcmeIdP".equals(idpPartnerName) &&
  resourceURL.startsWith("http://company.com/businesspartners/acmebank/account")) { // AcmeIdP supports X.509 as the higher
 authentication method
  fedAuthnMethod =
 "urn:oasis:names:tc:SAML:2.0:ac:classes:X509";
  } else if ("WorldBank".equals(idpPartnerName) &&
  resourceURL.startsWith("http://company.com/businesspartners/worldbank/account")) // WorldBank supports smart card as the higher
 authentication method
  fedAuthnMethod =
 "urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI";
  } else if ("WInsuranceIdP".equals(idpPartnerName)
 &&
  resourceURL.startsWith("http://company.com/businesspartners/worldinsurance/account"))
  {
  // WInsuranceIdP does not support another fed
 authn method
  }
  // if another fed authn method was requested, create a Credential param
  // instance in the AuthenticationContext
  // the OAM/SP FedAuthnRequestPlugin consumes it to start Federation SSO if (fedAuthnMethod != null) {
  CredentialParam fedAuthnParam = new
 CredentialParam();

 fedAuthnParam.setName("KEY_FEDAUTHNMETHOD")
  fedAuthnParam.setType("string");
  fedAuthnParam.setValue(fedAuthnMethod);

 context.getCredential().addCredentialParam("KEY_FEDAUTHNMETHOD fedAuthnParam);
  }
  // return success, which is mapped to
 FedAuthnRequestPlugin in the
  // Authentication Module steps orchestration
  return ExecutionStatus.SUCCESS;
  }
  public String getPluginName() {
  return "CustomIdPSelectionPlugin";
  }
  public String getDescription() {
  return "Custom IdP Selection Plugin";
  }
  public Map<String, MonitoringData> getMonitoringData() {
  return null;
  }
  public boolean getMonitoringStatus() {
  return false;
  }
  public int getRevision() {
  return 10;
  }
 public void setMonitoringStatus(boolean arg0) {
  } }

Plugin Registration File

The custom Authentication plugin must be defined in a plugin XML file such as:

<Plugin type="Authentication">
<author>uid=admin</author>
<email>admin@example</email>
<creationDate>08:00:00,2014-01-15</creationDate>
<description>Custom IdP Selection
Plugin</description>
<confguration>
</confguration>

Important Note: The XML file must have the same name as the class implementing the plugin, in this case CustomIdPSelectionPlugin.xml

See the OAM Developer’s Guide for more information

Manifest File

Before packaging the custom Authentication plugin in a JAR fle, a MANIFEST.MF must be defined such as:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: CustomIdPSelectionPlugin
Bundle-SymbolicName: CustomIdPSelectionPlugin
Bundle-Version: 10
Bundle-Activator: userauthn.CustomIdPSelectionPlugin Import-Package:
org.osgi.framework;version="1.3.0",oracle.security.am. plugin,oracle.security.am.plugin.authn Bundle-RequiredExecutionEnvironment: JavaSE-1.6

See the OAM Developer’s Guide for more information

Note: The manifest file must include the ImportPackage property which lists all the packages that are used in the plugin

Building the Plugin

Compiling

The following JAR files from the OAM deployment need to be used for compilation:

These files are found in the following locations:

In this example, we put the CustomIdPSelectionPlugin.java file in a src/userautn folder:

bash-4.1$ ls -l src/userauthn/total 4
-rw-r--r-- 1 root root 3894 Mar 1 11:42 CustomIdPSelectionPlugin.java

To compile, execute the following command:

$JDK_HOME/bin/javac -cp $IAM_HOME/oam/serve/lib/plugin/felix.jar:$IAM_HOME/oam/server/lib/plu /oam-plugin.jar src/userauthn/*.java

Packaging the Custom Plugin

We created the MANIFEST.MF in the current directory based on the content listed in the previous section, and the CustomIdPSelectionPlugin.xml in the src directory, which contains the plugin definition listed in the previous section.

find
.
./MANIFEST.MF
./src
./src/userauthn
./src/userauthn/CustomIdPSelectionPlugin.class
./src/userauthn/CustomIdPSelectionPlugin.java ./src/CustomIdPSelectionPlugin.xm

To create the CustomIdPSelectionPlugin.jar JAR file that contains the plugin and the required files, execute the following command:

jar cfvm CustomIdPSelectionPlugin.jar MANIFEST.MF -C src/ .
added manifest
adding: userauthn/(in = 0) (out= 0)(stored 0%) adding: userauthn/CustomIdPSelectionPlugin.class(in =2717) (out= 1267)(deflated 53%)
adding: userauthn/CustomIdPSelectionPlugin.java(in =3894) (out= 1055)(deflated 72%)
adding: CustomIdPSelectionPlugin.xml(in = 234) (out= 155)(deflated 33%)

This creates the CustomIdPSelectionPlugin.jar. To view the contents of the file:

unzip -l CustomIdPSelectionPlugin.jar Archive: CustomIdPSelectionPlugin.jar
Length Date Time Name
0 03-01-2014 10:14 META-INF/
425 03-01-2014 10:14 META-INF/MANIFEST.MF
0 03-01-2014 10:13 userauthn/
2717 03-01-2014 10:13 userauthn/CustomIdPSelectionPlugin.class
3894 03-01-2014 09:56 userauthn/CustomIdPSelectionPlugin.java
234 03-01-2014 10:03 CustomIdPSelectionPlugin.xml
7270     6 fles

Important Note: the JAR file must have the same name as the class implementing the plugin, in this case CustomIdPSelectionPlugin.jar

Deploying the Custom Authentication Plugin

Perform the following steps to deploy the custom Authentication plugin in OAM:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

  2. Navigate to Access Manager , Plugins

  3. Click Import Plug-In

  4. Select the plugin JAR file (CustomIdPSelectionPlugin.jar in this example)

Description of the illustration Import_Plug-In_Screen.jpg

The plugin will be in an uploaded state:

Description of the illustration Plug-In_State_Screen.jpg

You need to distribute the plugin to the runtime OAM servers and activate it:

Description of the illustration Activation_Status_Screen.jpg

You need to activate the plugin:

Description of the illustration Activate_Plugin_Screen.jpg

Creating the Authentication Module

Create a new Federation Authentication Module, based on the existing FederationPlugin Authentication Module, which differs from the existing one:

Perform the following steps to create a new Authentication Module:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

  2. Navigate to Access Manager, Authentication Modules

  3. Click Create Authentication Module

  4. Select Create Custom Authentication Module

  5. Enter a Name (CustomFedModule for example)

Description of the illustration Authentication_Module_Screen.jpg

Perform the following steps to add steps to the new Authentication Module:

  1. Click on the Steps tab

  2. Click Add to add the FedAuthnRequestPlugin step:

    1. Step name: FedAuthnRequestPlugin

    2. Plug-in Name: FedAuthnRequestPlugin

  3. Click OK

Description of the illustration Authentication_Steps_Screen.jpg

  1. Click Add to add the AssertionProcessing step:

    1. Step name: AssertionProcessing

    2. Plug-in Name: FedUserAuthenticationPlugin

  2. Click OK

Description of the illustration Assertion_Processing_Screen.jpg

  1. Click Add to add the IdPSelection step:

    1. Step name: IdPSelection

    2. Plug-in Name: CustomIdPSelectionPlugin

  2. Click OK.

Description of the illustration IdP_Selection_Screen.jpg

The Steps tab shows:

Description of the illustration Steps_Screen.jpg

Perform the following steps to define the steps orchestration for the new Authentication Module:

  1. Click on the Steps Orchestration tab

  2. Select IdPSelection as the Initial Step

  3. For FedAuthnRequestPlugin:

    1. Select success for On Success

    2. Select AssertionProcessing for On Failure

    3. Select failure for On Error

  4. For AssertionProcessing:

    1. Select success for On Success

    2. Select failure for On Failure

    3. Select failure for On Error

  5. For IdPSelection:

    1. Select FedAuthnRequestPlugin for On Success

    2. Select failure for On Failure

    3. Select failure for On Error

  6. Click Apply.

Description of the illustration Define_steps_orchestration_Screen.jpg

Authentication Scheme

Before being able to protect resources with an Authentication Policy that uses that new Authentication Module, a new Authentication Scheme needs to be created, referencing that new custom module. This is required, since the Authentication Policy is bound to an Authentication Scheme, not an Authentication Module.

To create a new Authentication Scheme for that custom module, perform the following steps:

  1. Go to the OAM Administration Console: http(s)://oam-admin-host:oam-adminport/oamconsole

  2. Navigate to Access Manager, Authentication Schemes

  3. Click Create Authentication Scheme

  4. Enter a name (for example CustomFedScheme) and a description

  5. Set the Authentication Level to an acceptable value (2 in my example) Select FORM as the Challenge Method

  6. Set the Challenge Redirect URL (In this example, we set it to /oam/server/)

  7. Select the newly created custom Authentication Module (CustomFedModule in the example)

  8. Set the Challenge URL (/pages/servererror.jsp in this example)

  9. Set the Context Type (customWar for example) Set the Context Value (/oam here, since we don’t use any pages)

  10. Enter the following for the Challenge Parameters at least: initial_command=NONE is_rsa=true

  11. Click Apply

Description of the illustration Authentication_Scheme_Screen.jpg

Test

Protect a resource with an Authentication Policy using the newly created Authentication Scheme. This invokes the custom Authentication Module.

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.