3 Developing Custom Authentication Plug-ins

The OAM Server uses both authentication and authorization controls to limit access to the resources that it protects. Authentication is governed by specific authenticating schemes, which rely on one or more plug-ins to test the credentials provided by a user when he or she tries to access a resource. The plug-ins can be taken from a standard set provided with OAM Server installation, or the custom plug-ins created by your own Java developers.

This chapter provides the following sections regarding authentication plug-ins.

See Also:

For information about deploying and managing authentication plug-ins using the Oracle Access Management Administration Console, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

3.1 Introduction to Authentication Plug-ins

The 11g release provides authentication modules for immediate use out-of-the-box as well as the following:

  • Authentication plug-in interfaces and SDK tooling to build customized authentication modules (plug-ins) to bridge the out-of-the-box features with individual requirements. The new interfaces and SDK tooling:

    • Provide backward compatibility to support custom Oracle Access Manager 10g plug-ins.

    • Include a deterministic method to orchestrate custom plug-ins within an authentication module.

  • A mechanism that enables quick deployment of customized authentication plug-ins.

  • A mechanism to maintain the complete plug-in State lifecycle.

The development of custom plug-ins for credential collection is supported for authentication (steps you can orchestrate).

Figure 3-1 provides an overview of the tasks involved in custom plug-in deployment.

Figure 3-1 Custom Plug-in Deployment Workflow

Description of Figure 3-1 follows
Description of ''Figure 3-1 Custom Plug-in Deployment Workflow''

The following overview identifies the tasks involved in custom plug-in deployment.

  1. Planning:

    Identify the business requirements for this plug-in and consider the authentication flow when a user requests a resource, as described in Section 3.1.2, "About Planning, the Authentication Model, and Plug-ins."

    The security architect knows how Access Manager 11g is used and knows the customer's user base. System architects can identify points of improvement in a customer's implementation.

  2. Development:

    The developer translates what a security architect has designed into the actual plug-in using common libraries to interface custom authentication modules.

    1. Write the plug-in.

    2. Write the metadata XML for the custom module.

    3. Prepare the manifest file.

    4. Add the following jar files to the CLASSPATH: felix.jar, identitystore.jar, oam-plugin.jar, utilities.jar.

  3. Deployment:

    Oracle Access Management administrators deploy and orchestrate multiple plug-ins to work together in an authentication module and also tests and monitors plug-ins. Common deployment tasks include the following:

    1. Adding custom plug-ins, which includes configuring the plug-in data source or domain, distributing, and activating the plug-in.

    2. Creating a custom Authentication Module for custom plug-ins, which includes adding and orchestrating steps and outcomes OnSuccess, OnFailure, and OnError.

    3. Creating Authentication Schemes with custom Authentication Modules.

    4. Configuring logging for custom plug-ins.

    5. Testing the plug-in using the Access Tester as described in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management

    6. Monitoring the plug-in and provide feedback to the security or system architects to allow for any revisions to the business requirements and architecture.

For information about deploying authentication plug-ins using the Oracle Access Management Administration Console, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

3.1.1 About the Custom Plug-in Life Cycle

The life cycle of a plug-in centers around the ability to add plug-ins to the OAM Server and use the plug-in to create more features. This allows users to build features and work flows based on the standard (out-of-the-box) plug-ins and user-added plug-ins that act as extension features to the server.

The typical plug-in life cycle is as follows:

  • Planning

  • Plug-in development time, includes generating the plug-in metadata artifact

  • Load and lifecycle of the plug-in

    • Import: Upload the plug-in into Access Manager and use it without restarting servers

    • Distribute: Propagate the plug-in jar file from one local OAM Server file system to all manage servers in a cluster, without server downtime

    • Activate: Load the plug-in implementation at run time when this plug-in is used in any Authentication Module flow

    • Use the start-up parameters or configuration for the plug-in

    • Push and pull plug-in configuration data into oam-config.xml

    • Maintain complete State life-cycle of OAM Server

  • State of the deployed plug-in

  • Monitoring and auditing the plug-in

    • Collect the matrix data of time taken to execute a plug-in and the number of times the plug-in is executed

    • Collect the matrix data of plug-in input and output

    • Collect the matrix data of plug-in execution start time and end time

    • Audit the plug-in life-cycle methods code

When a new plug-in JAR file is available, the deployer can import it to a Weblogic Server DOMAIN_HOME/oam/plugins from the administration console's Import action.

Table 3-1 describes the states of a plug-in life cycle that are controlled by Oracle Access Management administrators. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

Table 3-1 Plug-in Life Cycle States

State Description


Adds the plug-in JAR file to an Weblogic Server DOMAIN_HOME/oam/plugins and begins plug-in validation.


Propagates the plug-in to all registered OAM Servers.


After successful distribution the plug-in can be activated on all registered OAM Servers.


Deactivation checks the plug-in entry flag in oam-config.xml.

If any OAM Server fails during the de-activation process, the "De-activation failed" message is propagated.


Removes the given plug-in (JAR) from DOMAIN_HOME/config/fmwconfig/oam/plugins directory on Weblogic Server, which notifies all OAM Servers.

3.1.2 About Planning, the Authentication Model, and Plug-ins

Plug-ins on the OAM Server are part of a custom authentication scheme. Different types of plug-ins can be used to add the following functionality. This is not a complete listing; other types of plug-ins are supported.

  • User Identity Mapping

    Plug-ins can add functionality to handle with forms of user input not in the form of a log-in username. Fingerprints, a series of security questions, and other methods can be used. The plug-in translates these inputs and checks them against the database.

  • User Authentication

    Responses (not provided out-of-the-box) might be needed when authenticating the user. Custom plug-ins can fulfill this need.

  • Custom Responses

    Custom plug-ins can be used for responses and how these responses interact with the rest of the system.

Figure 3-2 illustrates the authentication flow when a user requests a protected resource. Remember that authentication is a process and not a protocol. The green dotted line arrows are custom responses generated by plug-ins that are deployed on the OAM Server.

Figure 3-2 Authentication Model and Plug-ins

Description of Figure 3-2 follows
Description of ''Figure 3-2 Authentication Model and Plug-ins''

Before designing and developing custom authentication plug-ins, Oracle recommends that developers analyze the Access Manager authentication decision process closely to determine how a user should be authenticated.

When a certain request comes in, there are two possible ways to handle it. One is to have specific schemes run depending on the attributes of the request, using a decision engine to run one or multiple schemes to properly authenticate the user. This requires less code within each scheme and allows for more modularity. The second option is to have every scheme be hard-coded to handle the various attributes of requests for specific purposes, not using a decision engine to piece together which schemes need to be run (only one scheme is run). Each request approach has its own advantages and disadvantages as documented in Table 3-2.

Table 3-2 Request Approach Comparison

Approach Description

Decision Engine

Divides authentication schemes into smaller sequential modules that can orchestrated to work together as needed.


  • Code re-use is the primary advantage.

  • Mirroring the approach of Oracle Adaptive Access Manager is a secondary advantage.


Leaves nothing to be decided; resembles a complete set of If-Else statements that the user must pass to authenticate.

Advantages: Could result in greater security.

Suppose a user wants to log in to his online bank account using his home computer, at midnight. The differences between the two approaches are simple but important and developers must decide which approach best meets their requirements. The following process overviews outline the differences between the decision engine approach and the hard-coded approach. About the Decision Engine Approach Process

  1. The request comes from the user with a certain IP address at midnight.

  2. The decision engine determines it has previously handled this IP address. It also determines that a user trying to authenticate at midnight is suspicious and requires the user to answer a security question, in addition to a username and password.

  3. The security question scheme is run for the specified user, and is successful. This is the first of two authentication schemes selected by the decision engine.

  4. The user-password scheme is run, and the user authenticates successfully. This is the second authentication scheme selected by the decision engine. About the Hard-Coded Approach Process

  1. The request comes from the user with a certain IP address at midnight.

  2. The online bank account access scheme is chosen from among other authentication schemes (credit card access scheme, new account creation and verification, and so on).

  3. The scheme first checks the IP address to determine if the user has previously made attempts to connect from the computer. It determines the user has.

  4. The scheme checks the time. It requires a security question to be answered, which is answered successfully.

  5. The scheme requires the user to enter his login credentials, and he authenticates successfully.

3.2 Introduction to Multi-Step Authentication Framework

This section provides the following topics:

3.2.1 About the Multi-Step Framework

The Multi-Step Authentication Framework requires a custom authentication plug-in to transmit information to the backend authentication scheme several times during the login process. All information collected by the plug-in and saved in the context will be available to the plug-in through the authentication process. Context data also can be used to set cookies or headers in the login page.

Events are the building blocks of the authentication flow. Events are created using exposed methods of the authentication module plug-in implementation. These events can be combined with the rules to build a deterministic workflow for the authentication. The Workflow controller is the module responsible for orchestrating the authentication workflow. Workflow configuration is defined in the Workflow definition language.

Multi-Factor Authentication is a business term that refers to the collection of multiple credentials necessary to authenticate a user. The Multi-Step Authentication Framework can implement Multi-Factor Authentication requirements. It can also implement Single Factor Authentication requirements using multiple steps as necessary. For example, the username and password can be collected on separate pages. Multi-step authentication relies on:

  • WebGate using a credential collector (DCC or ECC) for dynamic credential collection with multi-step authentication flows. This enables greater flexibility for interactions with users or programmatic entities when collecting authentication-related information that involves several methods to establish the identity of the user.

  • Authentication module chaining, where modules of a similar challenge mechanism are grouped and the credentials are collected in one pass, then validated against each module. You can chain multiple authentication modules in a new authentication scheme, and define a new scheme plug-in containing the flows.

    The challenge mechanism defines how to collect the credentials. The following mechanisms are available: FORM, BASIC, X509, WNA, OAM10G, TAP, and NONE. The challenge mechanism controls the way in which the required credentials are collected. Currently, this is tied to the authentication scheme.

See Also:

"Configuring 11g WebGate for Detached Credential Collection" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management

3.2.2 Process Overview: Multi-Step Authentication

  1. Process Request: The Master Controller processes the authentication request and passes it to the plug-in.

  2. Process Event: The authentication scheme is executed and the plug-in determines whether any input is needed to continue the authentication. If input is required, the plug-in returns an execution status of PAUSE which suspends the event flow.

    PAUSE indicates that the authentication processing cannot proceed until additional information is obtained from user. As such, redirection is allowed. When the requested information is supplied, processing continues from the point it was paused. The request is updated with details of the associated ACTION that must be performed. The ActionContext has all the information to execute the ACTION.

    For example, if PAUSE is associated with CREDCOLLECT_ACTION, the Master Controller saves the plug-in execution state and begins executing events corresponding to the ACTION by mapping this CREDCOLLECT_ACTION to the CRED_COLLECT event and proceeding with collection as specified by the plug-in's CredentialParameter object.

  3. The saved plug-in state is revived and plug-in execution resumes until either a state of SUCESS or FAILURE is reached. FAILURE indicates that the authentication attempt has failed. If so, OAM Server will take attempt to reauthenticate the user once again. For example, the user is presented with a login form.

    • If a valid subject is available, a session is created for the user, which is used to save the execution state. Otherwise, the execution state is stored in the request object. This session has the lowest Authentication Level (configured through global (Common) System Configuration).

    • When user authentication is finished, the session is updated to a fully valid session with the authentication level defined in the authentication scheme and the session timeout configured for the OAM Server.

  4. When the events in the dynamic flow controller finish executing, control is merged back to the parent controller and the execution state is updated.

  5. When authentication completes, access is granted to the requested resource.

3.2.3 About the PAUSE State

In multi-step authentication mode, the plug-in can either collect the credentials from start or use the credentials obtained from the default login page and collect extra credentials if required. If the challenge parameter initial_command=NONE is set in the authentication scheme, control comes to the plug-in directly and the plug-in controls the credentials to be collected.

The plug-in can employ the PAUSE status to pass the UserAction parameter for user interaction to collect credentials. All the credentials required by the module can be collected in one or more passes to the client. During a PAUSE execution, the plug-in execution state and the context data will be saved. Once control returns back to the plug-in, the paused execution resumes and all the collected data is available to the plug-in.

When the plug-in is set to a PAUSE state, the plug-in can:

  • Specify the data to be collected

  • Specify the URL to redirect or forward to

  • Specify the query string, if any

3.2.4 About Information Collected

The following types of information can be conveyed to the credential collector page. UserContextData

  • UserContextData specifies metadata: name, display name and type of parameter to be collected by the login page. For example, to collect a user name from the login application:

    final UserContextData userNameContext = new UserContextData(form_username,
    form_username, new CredentialMetaData(PluginConstants.TEXT));

    where name of the attribute is form_username.

  • UserContextData specifies the login page URL to direct a user to for collecting credentials. CredentialMetaData with URL type specifies the login page URL. For example:

    final UserContextData urlContext = new UserContextData (loginPageURL, new CredentialMetaData("URL"))

    where loginPageURL specifies the URL to be directed to.

  • UserContextData is used to pass query parameters to the login page URL. CredentialMetaData with QUERY_STRING type specifies the query parameters to be sent with the loginPageURL. This can be processed by the login page. For example:

    String queryString = "queryParam1=testParameter";
           final UserContextData queryStringContext =new UserContextData
     (queryString, new CredentialMetaData("QUERY_STRING")); UserActionContext

UserActionContext holds the UserContextData metadata collected from the login page. UserAction

UserAction class is used to collect the credentials. The action forwards or redirects (based on the UserActionMetaData parameter) to the login page to collect more credentials.

The following example shows how the classes can be used to specify information to the login page:

//create a user name context data. 
   UserContextData userNameContext =
      new UserContextData("form_username", "form_username",
                               new CredentialMetaData(PluginConstants.TEXT));
   //create a password context data
   // Any form parameter containing the words  "password", "passcode" and "_pin"  will be treated as sensitive values for debug logging
   UserContextData passwordContext =
      new UserContextData("form_password", "form_password",
                     new CredentialMetaData(PluginConstants.PASSWORD));
   // create URl context data for login page                            
   UserContextData urlContext = new UserContextData (loginPageURL, 
                        new CredentialMetaData ("URL")); 
   UserActionContext actionContext = new UserActionContext ();
   //add the UserContextData to the CredentialActionContext
   //specify if we FORWARD or REDIRECT with a GET/POST to the login page
   UserActionMetaData userAction = UserActionMetaData. FORWARD;
   // create a UserAction object and set it to the authentication context.
   UserAction action = new UserAction (actionContext, userAction);
   authContext.setAction(action); UserActionMetaData

UserActionMetaData specifies the action type to be used with UserAction. The UserAction performs a forward or a redirect (with a GET or POST) to the login page based on the UserActionMetaData value. Possible values for UserActionMetaData are: FORWARD, REDIRECT_GET, and REDIRECT_POST.

3.3 Introduction to Plug-in Interfaces

This section provides the following topics:

3.3.1 About the Plug-in Interfaces

This topic introduces the hierarchy for packages, classes, interfaces, and annotations.

Custom plug-in implementation includes writing plug-in implementation class artifacts. The plug-in implementation class must extend the AbstractAuthenticationPlugIn class and implement initialize and process methods. Custom plug-in implementers must implement actual custom authentication processing logic in this method and return the final authentication execution status.

A plug-in's configuration requirements must be given in XML format. This configuration data (metadata) includes plug-in name, author, creation date, version, interface class, implementation class, and configuration data in the form of Attribute / Value pairs. The new plug-in name must be included in the manifest file. A period ( . ) is not a valid character in the plug-in name.

The 11g release provides a generic plug-in interface and a more specific authentication interface as described in the following topics: GenericPluginService


The public interface, oracle.security.am.plugin, is a generic plug-in interface that provides methods to get plug-in name, plug-in implementation class name, plug-in version, plug-in execution status, plug-in monitoring data, plug-in configuration data, and start and stop the plug-in.


The public abstract class oracle.security.am.plugin.AbstractAMPlugin extends java.lang.Object implements GenericPluginService, org.osgi.framework.BundleActivator.


This is a Abstract plug-in class that needs to be extended by all Access Manager plug-ins. This provides base implementations for plug-ins start and stop methods AuthnPluginService


The public interface oracle.security.am.plugin.authn.AuthnPluginService extends GenericPluginService.

This is a authentication plug-in interface that provides an additional authentication specific method to access and process all the data available in the AuthenticationContext object and return the process execution status. Plug-in can then set response that will be added to SESSION, request and redirect contexts.


The public abstract class oracle.security.am.plugin.authn.AbstractAuthenticationPlugIn extends AbstractAMPlugin implements AuthnPluginService.


This is an authentication Abstract plug-in class that will be exposed to the plug-in developers. All the custom plug-in implementations should extend this AbstractPlugInService class. Plug-ins that needs to handle the resource cleanup should override shutdown(Map < String, Object > OAMEnvironmentContext) method. This will also provide an instance of java.util.Logger to plug-ins.

3.3.2 About Plug-in Hierarchies

This topic provides a look at the hierarchies:

Figure 3-3 Plug-in Package Hierarchy

Plug-in Package Hierarchy

Figure 3-4 Plug-in Class Hierarchy

Plug-in Class Hierarchy

Figure 3-5 Plug-in Interface Hierarchy

Plug-in Interface Hierarchy

Figure 3-6 Plug-in Annotation Type Hierarchy

Plug-in Annotation Type Hierarchy

Figure 3-7 Plug-in Enum Hierarchy

Plug-in Enum Hierarchy

3.4 Sample Code: Custom Database User Authentication Plug-in

This section provides snapshots of a sample implementation for a database user authentication plug-in to illustrate developer tasks. The following topics are provided:

3.4.1 Sample Code: Database User Authentication Plug-in

Following figures illustrate a sample implementation for a Database user authentication plug-in, which is presented in three parts:

See Also:

Oracle Fusion Middleware Oracle Access Manager Java API Reference

Figure 3-8 Database User Authentication Plug-in Part 1

Database User Authentication Plug-in Part 1

Continued ..

Figure 3-9 Database User Authentication Plug-in Part 2

Database User Authentication Plug-in Part 2


Figure 3-10 Database User Authentication Plug-in Part 3

Database User Authentication Plug-in Part 3

3.4.2 Sample Plug-in Configuration Metadata Requirements

The plug-in's configuration requirements must be given in XML format.

This configuration data (metadata) includes plug-in name, plug-in author, creation date, plug-in version, plug-in interface class, plug-in implementation class, and plug-in configuration data in the form of Attribute / Value pairs.

Figure 3-11 shows the XML Schema Definition (XSD) file containing metadata for the sample: Database User Authentication Plug-in implementation.

Figure 3-11 XSD Configuration Data: Database User Authentication Plug-in

XSD Configuration Data: Database User Authentication Plug-in

Example 3-1 shows the XML metadata for the sample: Database User Authentication Plug-in.

Example 3-1 XML Metadata: Database User Authentication Plug-in

<Plugin type="Authentication">
<creationDate>09:32:20, 2010-12-02</creationDate>
<description>Custom User Authentication Plugin Validation Against Domain Name</description>
<Attribute type="string" length="20">DataSource</Attribute>

3.4.3 Sample Manifest File for the Plug-in

Beginning with the 11.1.2 release, the plug-in manifest file contains the following information:

  • The plug-in version is taken from the Bundle-Version field. This field must be an integer

  • The name=attribute parameter, which used to be read from the XML file in earlier releases, is now read from the Bundle-SymbolicName or the Bundle-Name field. This parameter does not need to be in the XML file.

  • The implementation parameter, which used to be read from the XML file in earlier releases, is now read from the Bundle-Activator field. This parameter does not need to be in the XML file.

  • The following can be removed from the XML file: <interface>oracle.security.am.plugin.authn.AbstractAuthenticationPlugIn</interface>.

Example 3-2 Sample Manifest File

Manifest-Version: 1.0
Bundle-Version: 10-->Note this to be an integer.
Bundle-Name: MFASamplePlugin
Bundle-Activator: mfasampleplugin.MFASamplePlugin
Bundle-ManifestVersion: 2
Bundle-SymbolicName: MFASamplePlugin
A corresponding sample modified XML file is :
<Plugin type="Authentication">
<creationDate>09:32:20 2010-12-02</creationDate>
<description>Custom MFA Sample Auth Plugin</description>
<!-- Attribute "actiontype" indicates if the plugin wants to REDIRECT or
FORWARD to the login page to collect credentials-->
<Attribute type="string" length="20">actiontype</Attribute>

3.4.4 Plug-in JAR File Structure

The JAR file structure for the sample (Database User Authentication Plug-in) is listed here:

3.5 Developing an Authentication Plug-in

The developer translates what a security architect has designed into the actual plug-in using common libraries to interface custom authentication modules.

This section guides as you develop an authentication plug-in for use with Access Manager 11g authentication schemes. The following topics are discussed:

3.5.1 About Writing a Custom Authentication Plug-in

Writing the custom plug-in implementation includes writing the plug-in implementation class to:

Table 3-3 describes the methods required for the plug-in's functionality.

Table 3-3 Required Plug-in Methods

Required Method Description


Gives a handle to the PluginConfig object.

The PluginConfig object can be exercised to get plug-in specific system configuration data that is entered when the plug-in is uploaded. This data is required for the plug-in's own functionality.


Gives a handle to the AuthenticationContext object, which can be exercised to get plug-in specific run time configuration data that is:

  • either updated at plug-in instance level

  • or updated during plug-in orchestration steps

The AuthenticationContext object extends PluginContext object which gives different methods to get the:

  • plug-in configuration data

  • exception data

  • plug-in environment data

In addition, the AuthenticationContext object provides methods to get the:

  • Authentication scheme

  • Authenticated Subject

  • Credential object

  • Run time policy resource


Custom plug-in developers must implement actual custom authentication processing logic in this method and return the final authentication execution status.

The following tips will help in developing custom plug-ins.

  • An external JAR is required in both the Weblogic class path and inside the plug-in as there is no visibility of the external JAR inside the plug-in.

  • The plug-in does not use the Weblogic class path and must have its own class path for the external JAR defined in the manifest file; for example, Bundle-ClassPath:

  • The package name must be individually specified in the manifest file. Wildcards are not supported, and even nested packages must be specified in the Import-Package: section. For example:

  • To avoid bundle constraint exceptions during plug-in activation, put ;resolution:=optional in the packages.

  • If the JAR file is not present inside the plug-in AND its classpath (even though available in the Weblogic class path) it will throw a classnotfound exception.

  • If the JAR file is not available in the Weblogic classpath, a type cast exception is thrown.

3.5.2 Writing a Custom Authentication Plug-in

This section provides steps to write a custom authentication plug-in. The following overview describes the actions a developer must take after the system architect identifies the business requirements for this plug-in and considers the authentication flow when a user requests a resource. For more information, see Section 3.1.2, "About Planning, the Authentication Model, and Plug-ins".

  1. Extend AbstractAuthenticationPlugIn class and implement the following methods (see also Section 3.5.1, "About Writing a Custom Authentication Plug-in"):

    • Implement initialize method

    • Implement process method

  2. Develop plug-in code using appropriate Access Manager 11g interfaces and packages. See:

  3. Prepare Metadata for the Custom Plug-in. See:

  4. Prepare the Plug-in Jar file and manifest and turn these over to your deployment team. See:

  5. Proceed to:

3.5.3 Error Codes in an Authentication Plug-In

In the case where a plug-in needs to exchange data to the login page, error page, or client application pages, this data can be sent as PluginResponses. The response is in the format as a Name=Value pair that provides details about the data. The OAM Server sends these responses to the custom page as HTTP request parameters. The following response types facilitate the exchange:

  • CLIENT: Enables the plug-in to communicate data about the authentication process or about the user to the client application. The request parameter is PLUGIN_CLIENT_RESPONSE.

  • ERROR: Enables a plug-in to communicate any error about the authentication process. The request parameter is PLUGIN_ERROR_RESPONSE.

Example 3-3 Error Code in a Custom Authentication Plug-in

//Setting responses
PluginResponse rsp = new PluginResponse();
rsp = new PluginResponse();
rsp = new PluginResponse();
rsp.setValue("Card Expired");

String errorResponse = request.getParameter(GenericConstants.PLUGIN_ERROR_RESPONSE);
String clientResponse = request.getParameter(GenericConstants.PLUGIN_CLIENT_RESPONSE);

3.5.4 JAR Files Required for Compiling a Custom Authentication Plug-in

Several JAR files are required to compile a custom authentication plug-in:

  • felix.jar

  • oam-plugin.jar

  • utilities.jar

  • identity-provider.jar

These JAR files are located in the following path: