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:
-
Evaluates the requested protected resource
-
Determines the IdP to be used in the Federation SSO operation
-
Requests a higher Federation Authentication Method from the IdP, depending on the resource being requested
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:
-
Implement the plugin
-
Compile it
-
Package it
-
Upload the plugin to OAM
-
Create a new Authentication Module
Federation Authentication Module
The OOTB Federation Authentication Module, called FederationPlugin
, is made of two plugins:
-
FedAuthnRequestPlugin
: Starts the Federation SSO flow, determines which IdP to use if not provided by a previous Authentication Plugin, creates an SSO request and redirects the user to the IdP -
AssertionProcessing
: Processes an incoming SAML/OpenID SSO Response and maps the message to a local user record in the LDAP directory
The orchestration can be seen by:
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/oamconsole
. -
Navigate to Access Manager , Authentication Modules.
-
Open
FederationScheme
. -
Click on the Steps tab to see the plugins.
-
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:
-
IdP to perform Federation SSO with Optional Referenced by the
KEY_FEDIDP
string-
Type
: string -
Value
: IdP Partner Name
-
-
The Federation Authentication Method to request from the IdP Optional Referenced by the
KEY_FEDAUTHNMETHOD
-
string
Type: string -
Value
: The Federation Authentication Method that should be set in the SSO request
-
-
The SAML 2.0 Federation Authentication Method Comparison attribute Optional Referenced by the
KEY_FEDAUTHNMETHODCOMP
string-
Type
: string -
Value
: The comparison to be used in the SAML
-
-
2.0 Authn Request message exact for exact better for better min for minimum max for maximum The Force
Authn
Wag Optional Referenced by theKEY_FEDFORCEAUTHN
string-
Type
: string -
Value
: The “true” or “false” string to indicate whether or not OAM/SP should request the IdP to challenge the user, even if the user is already authenticated at the IdP
-
-
The Is Passive Wag Optional Referenced by the
KEY_FEDISPASSIVE
string-
Type
: string -
Value
: The “true” or “false” string to indicate whether or not the IdP is allowed to interact with the user
-
Custom Authentication Plugin
Overview
The custom Authentication Plugin:
-
Evaluates the requested resource
-
Determines the IdP to be used
-
Requests a strong Federation Authentication Method from the IdP when a sensitive resource is requested, if the IdP supports a stronger Federation Authentication Method
In the example, we have:
-
Three IdP partners:
-
AcmeIdP which supports the following Federation Authentication Methods
-
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
(default, no need to specifically request it) -
urn:oasis:names:tc:SAML:2.0:ac:classes:X509
-
WorldBank
-
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
(default, no need to specifically request it)urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
-
WInsuranceIdP
-
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
(default, no need to specifically request it) -
Three high level resources:
-
http://company.com/businesspartners/acmebank
, bound toAcmeIdP
-
http://company.com/businesspartners/worldbank
, bound to WorldBank -
http://company.com/businesspartners/worldinsurance
, bound toWInsuranceIdP
-
-
Three sensitive resources, for the three high level resources:
-
http://company.com/businesspartners/acmebank/account
-
http://company.com/businesspartners/worldban/account
-
http://company.com/businesspartners/worldinsurance/account
-
-
Custom Authentication plugin is made of the following:
-
One Java class extending the
oracle.security.am.plugin.authn.AbstractAuthenticationPlugIn
class -
A
MANIFEST.MF
file describing the Java classes -
An XML file describing the plugin
-
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:
-
Extend the
oracle.security.am.plugin.authn.AbstractAuthenticationPlugIn
class -
Implement the following methods:
-
public
ExecutionStatus
-
process(
AuthenticationContext
context) throwsAuthenticationException
-
Must return a status (failure or success)
-
In our example, this method evaluates the requested resource
-
Set the
KEY_FEDIDP
CredentialParam
to indicate the IdP to be used -
Set the
KEY_FEDAUTHNMETHOD
CredentialParam
to request a specific Federation Authentication Method from the IdP
-
-
public String
getPluginName()
- Returns the name of the custom plugin
-
In our example it returns
CustomIdPSelectionPlugin
-
public String
getDescription()
-
Returns a description of the custom Authentication Plugin
-
In our example it returns “Custom IdP Selection Plugin”
-
-
public
Map <String, MonitoringData> getMonitoringData()
-
Not used in an Authentication Plugin flow
-
In our example it returns null
-
-
public boolean
getMonitoringStatus()
-
Not used in an Authentication Plugin flow
-
In our example it returns false
-
-
public int
getRevision()
-
Must be the same value than the version specified in the manifest file
-
In our example it returns 10
-
-
public void
setMonitoringStatus(boolean status)
-
Not used in an Authentication Plugin flow
-
In our example this method is empty
-
-
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:
-
felix.jar
-
oam-plugin.jar
These files are found in the following locations:
-
felix.jar
:$IAM_HOME/oam/server/lib/plug/felix.jar
-
oam-plugin.jar
:$IAM_HOME/oam/serve /lib/plugin/oam-plugin.jar
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:
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/oamconsole
-
Navigate to Access Manager , Plugins
-
Click Import Plug-In
-
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:
-
Select the plugin
-
Click Distribute Selected
-
The Activation Status tab of the plugin shows the state of the plugin
Description of the illustration Activation_Status_Screen.jpg
You need to activate the plugin:
-
Select the plugin
-
Click Activate Selected
-
The Activation Status tab of the plugin shows the state of 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:
-
CustomIdPSelectionPlugin
will be the initial step Orchestration: On Success will be mapped toFedAuthnRequestPlugin
-
On Failure mapped to failure
-
On Error mapped to failure
Perform the following steps to create a new Authentication Module:
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/oamconsole
-
Navigate to Access Manager, Authentication Modules
-
Click Create Authentication Module
-
Select Create Custom Authentication Module
-
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:
-
Click on the
Steps
tab -
Click Add to add the
FedAuthnRequestPlugin
step:-
Step name:
FedAuthnRequestPlugin
-
Plug-in Name:
FedAuthnRequestPlugin
-
-
Click OK
Description of the illustration Authentication_Steps_Screen.jpg
-
Click Add to add the
AssertionProcessing
step:-
Step name:
AssertionProcessing
-
Plug-in Name:
FedUserAuthenticationPlugin
-
-
Click OK
Description of the illustration Assertion_Processing_Screen.jpg
-
Click Add to add the
IdPSelection
step:-
Step name:
IdPSelection
-
Plug-in Name:
CustomIdPSelectionPlugin
-
-
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:
-
Click on the Steps Orchestration tab
-
Select
IdPSelection
as the Initial Step -
For
FedAuthnRequestPlugin
:-
Select success for On Success
-
Select
AssertionProcessing
for On Failure -
Select failure for On Error
-
-
For
AssertionProcessing
:-
Select success for On Success
-
Select failure for On Failure
-
Select failure for On Error
-
-
For
IdPSelection
:-
Select
FedAuthnRequestPlugin
for On Success -
Select failure for On Failure
-
Select failure for On Error
-
-
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:
-
Go to the OAM Administration Console:
http(s)://oam-admin-host:oam-adminport/oamconsole
-
Navigate to Access Manager, Authentication Schemes
-
Click Create Authentication Scheme
-
Enter a name (for example
CustomFedScheme
) and a description -
Set the Authentication Level to an acceptable value (2 in my example) Select FORM as the Challenge Method
-
Set the Challenge Redirect URL (In this example, we set it to
/oam/server/
) -
Select the newly created custom Authentication Module (
CustomFedModule
in the example) -
Set the Challenge URL (
/pages/servererror.jsp
in this example) -
Set the Context Type (
customWar
for example) Set the Context Value (/oam
here, since we don’t use any pages) -
Enter the following for the Challenge Parameters at least:
initial_command=NONE is_rsa=true
-
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.
Custom Authentication Module in OAM and SP
F60229-01
September 2022
Copyright © 2022, Oracle and/or its affiliates.