This chapter provides the following sections regarding authentication plug-ins.
See Also, Deploying and Managing Individual Plug-ins for Authentication in Fusion Middleware Administering Oracle Access Management.
3.1 Introduction to Authentication Plug-ins
The 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 previous release 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).
See Also, About the Plug-in Interfaces
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 Custom Plug-in Deployment Workflow"
The following overview identifies the tasks involved in custom plug-in deployment.
Identify the business requirements for this plug-in and consider the authentication flow when a user requests a resource, as described in About Planning, the Authentication Model, and Plug-ins.
The security architect knows how Access Manager is used and knows the customer's user base. System architects can identify points of improvement in a customer's implementation.
The developer translates what a security architect has designed into the actual plug-in using common libraries to interface custom authentication modules.
Write the plug-in.
Write the metadata XML for the custom module.
Prepare the manifest file.
Add the following jar files to the CLASSPATH: felix.jar, identitystore.jar, oam-plugin.jar, utilities.jar.
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:
Adding custom plug-ins, which includes configuring the plug-in data source or domain, distributing, and activating the plug-in.
Creating a custom Authentication Module for custom plug-ins, which includes adding and orchestrating steps and outcomes OnSuccess, OnFailure, and OnError.
Creating Authentication Schemes with custom Authentication Modules.
Configuring logging for custom plug-ins.
Testing the plug-in using the Access Tester as described in Testing User Authentication from the Access Tester Console
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 Deploying and Managing Individual Plug-ins for Authentication in Fusion Middleware Administering 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:
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 Deploying and Managing Individual Plug-ins for Authentication in Fusion Middleware Administering Oracle Access Management.
Table 3-1 Plug-in Life Cycle States
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.
Responses (not provided out-of-the-box) might be needed when authenticating the user. Custom plug-ins can fulfill this need.
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 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
Divides authentication schemes into smaller sequential modules that can orchestrated to work together as needed.
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.
126.96.36.199 About the Decision Engine Approach Process
In the decision engine approach to handling authorization requests:
The request comes from the user with a certain IP address at midnight.
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.
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.
The user-password scheme is run, and the user authenticates successfully. This is the second authentication scheme selected by the decision engine.
188.8.131.52 About the Hard-Coded Approach Process
In the hard-coded approach to handling authorization requests:
The request comes from the user with a certain IP address at midnight.
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).
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.
The scheme checks the time. It requires a security question to be answered, which is answered successfully.
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, OAM, TAP, and NONE. The challenge mechanism controls the way in which the required credentials are collected. Currently, this is tied to the authentication scheme.
About WebGate Configured as a Detached Credential Collector in Fusion Middleware Administering Oracle Access Management
3.2.2 Process Overview: Multi-Step Authentication
Process Request: The Master Controller processes the authentication request and passes it to the plug-in.
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
PAUSEwhich suspends the event flow.
PAUSEindicates 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
ACTIONthat must be performed. The
ActionContexthas all the information to execute the
For example, if
PAUSEis associated with
CREDCOLLECT_ACTION, the Master Controller saves the plug-in execution state and begins executing events corresponding to the
ACTIONby mapping this
CRED_COLLECTevent and proceeding with collection as specified by the plug-in's
The saved plug-in state is revived and plug-in execution resumes until either a state of
FAILUREindicates 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.
When the events in the dynamic flow controller finish executing, control is merged back to the parent controller and the execution state is updated.
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 Information types shared with the credential collector page
The following types of information can be conveyed to the credential collector page.
UserContextDataspecifies 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
UserContextDataspecifies the login page URL to direct a user to for collecting credentials.
URLtype specifies the login page URL. For example:
final UserContextData urlContext = new UserContextData (loginPageURL, new CredentialMetaData("URL"))
loginPageURLspecifies the URL to be directed to.
UserContextDatais used to pass query parameters to the login page URL.
QUERY_STRINGtype 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 holds the
UserContextData metadata collected from the login page.
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 actionContext.getContextData().add(userNameContext); actionContext.getContextData().add(passwordContext); actionContext.getContextData().add(urlContext); //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 specifies the action type to be used with
UserAction performs a forward or a redirect (with a
POST) to the login page based on the
UserActionMetaData value. Possible values for
3.3 Introduction to Plug-in Interfaces
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
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.
This OAM release provides a generic plug-in interface and a more specific authentication interface as described in the following topics:
184.108.40.206 About the 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
java.lang.Object implements GenericPluginService,
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
220.127.116.11 About the AuthnPluginService
The public interface
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
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
Figure 3-4 Plug-in Class Hierarchy
Figure 3-5 Plug-in Interface Hierarchy
Figure 3-6 Plug-in Annotation Type Hierarchy
Figure 3-7 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:
Oracle Fusion Middleware Oracle Access Manager Java API Reference
Figure 3-8 Database User Authentication Plug-in Part 1
Figure 3-9 Database User Authentication Plug-in Part 2
Figure 3-10 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
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"> <author>uid=User1</author> <email>User1@example.com</email> <creationDate>09:32:20, 2010-12-02</creationDate> <description>Custom User Authentication Plugin Validation Against Domain Name</description> <configuration> <AttributeValuePair> <Attribute type="string" length="20">DataSource</Attribute> <mandatory>true</mandatory> <instanceOverride>false</instanceOverride> <globalUIOverride>true</globalUIOverride> <value>jdbc/CISCO</value> </AttributeValuePair> </configuration> </Plugin>
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-Versionfield. This field must be an integer
name=attributeparameter, which used to be read from the XML file in earlier releases, is now read from the
Bundle-Namefield. This parameter does not need to be in the XML file.
implementationparameter, which used to be read from the XML file in earlier releases, is now read from the
Bundle-Activatorfield. This parameter does not need to be in the XML file.
The following can be removed from the XML file:
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 Import-Package: org.osgi.framework;version="1.3.0",oracle.security.am.plugin,oracle.security.a m.plugin.authn,oracle.security.am.plugin.impl,oracle.security.am.plugin.api,or acle.security.am.common.utilities.principal,oracle.security.idm,javax.security .auth Bundle-SymbolicName: MFASamplePlugin . A corresponding sample modified XML file is : <Plugin type="Authentication"> <author>uid=User2</author> <email>User2@example.com</email> <creationDate>09:32:20 2010-12-02</creationDate> <description>Custom MFA Sample Auth Plugin</description> <configuration> <!-- Attribute "actiontype" indicates if the plugin wants to REDIRECT or FORWARD to the login page to collect credentials--> <AttributeValuePair> <Attribute type="string" length="20">actiontype</Attribute> <mandatory>false</mandatory> <instanceOverride>false</instanceOverride> <globalUIOverride>true</globalUIOverride> <value>FORWARD</value> </AttributeValuePair> . </configuration> . </Plugin>
3.4.4 Understanding the Plug-in JAR File Structure
The JAR file structure for the sample (Database User Authentication Plug-in) is listed here:
<plugin>.class (per the package structure, as shown in Introduction to Plug-in Interfaces)
3.4.5 Error Codes Supported by Plugin Framework
The plugin framework (
oracle.security.am.plugin.authn.AuthenticationErrorCode) exposes authentication error codes.
Table 3-3 Error Codes supported by
oracle.security.am.plugin.authn.AuthenticationErrorCode plugin framework
|Error Codes||Error Messages|
|OAM-1006||USER_LOCKED_ERROR / DISABLED_USER|
|OAM-10017||INVALID_REMEMBER_ME_TOKEN / CHALLENGES_NOT_DEFINED|
These error codes can be used by other custom plugins to perform any appropriate customized actions.
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.
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:
AbstractAuthenticationPlugInclass (see About the Plug-in Interfaces)
Table 3-4 describes the methods required for the plug-in's functionality.
Table 3-4 Required Plug-in Methods
Gives a handle to the
Gives a handle to the
In addition, the
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:=optionalin 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 About Planning, the Authentication Model, and Plug-ins.
AbstractAuthenticationPlugInclass and implement the following methods (see also About Writing a Custom Authentication Plug-in):
- Develop plug-in code using appropriate Access Manager 11g interfaces and packages. See:
- Prepare Metadata for the Custom Plug-in. See:
- Prepare the Plug-in Jar file and manifest and turn these over to your deployment team. See:
- Proceed to:
For information about deploying and managing custom authentication plug-ins, see Deploying and Managing Individual Plug-ins for Authentication.
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
ERROR: Enables a plug-in to communicate any error about the authentication process. The request parameter is
Example 3-3 Error Code in a Custom Authentication Plug-in
//Setting responses PluginResponse rsp = new PluginResponse(); rsp = new PluginResponse(); rsp.setName("PluginClientCode"); rsp.setType(PluginAttributeContextType.CLIENT); rsp.setValue("Err-100"); context.addResponse(rsp); rsp = new PluginResponse(); rsp.setName("PluginErrorCode"); rsp.setType(PluginAttributeContextType.ERROR); rsp.setValue("Card Expired"); context.addResponse(rsp); 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:
These JAR files are located in the following path: