49 Integrating RSA SecurID Authentication with Access Manager

Oracle provides components that interface with RSA Security products to provide native RSA SecurID® authentication for Access Manager protected resources.

This chapter introduces SecurID authentication and the components, requirements, and processes needed to successfully integrate SecurID authentication with Access Manager 12c. The following topics are included:

49.1 Introduction to Access Manager and RSA SecurID Authentication

Access Manager 12c integrates with RSA components to provide SecurID authentication.

RSA SecurID authentication is based on two factors: something the user knows and something the user has:

  • Something the User Knows: This is a secret personal identification number (PIN), similar in concept to a personal bank code PIN. In this case, the PIN may be system generated or personally chosen and registered with the RSA Authentication Manager.

  • Something the User Has: This is the current code generated by a hand held device known as a token. Oracle Access Manager supports all RSA SecurID token form factors, both hardware and software-based.

These tokens algorithmically, based on an internal clock or event, generate tokencodes with unpredictable values. Together, the user's PIN and the SecurID tokencode become the user's Passcode.

Access Manager uses and supports RSA two-factor SecurID authentication security features and enables integration with SecurID authentication by providing:

  • The HTML forms required for SecurID authentication operations

  • The RSA SecurID Plugin you can use with the User Identification Plugin to create and orchestrate authentication

49.2 RSA Features Supported by Access Manager

Access Manager integrates with RSA Authentication Manager and provides the integration features described in Table 49-1.

Table 49-1 Access Manager Support for RSA Features

RSA Feature Access Manager Support

Authentication method

Native SecurID authentication

New PIN Mode (user-generated PINs)

Asks for new PIN with confirmation.

The token may be in New PIN mode the first time the user logs in or the Authentication Manager Administrator can enable New PIN mode. New PIN mode requires the user to complete a sequence of forms to define, or have the system generate, a new PIN number.

Oracle-Provided New PIN Forms and Functions:

  • System Generated PIN (not supported)

  • User Defined (4-8 Alpha/numeric characters)

  • User Defined (5-7 Numeric)

  • Deny 4 and 8 Digit PIN

  • Deny Alphanumeric PIN

  • Deny Numeric PIN

  • PIN Reuse

See Also: "SecurID New PIN Authentication".

Next Tokencode

During authentication, the Authentication Manager may direct the user to provide the next tokencode that appears on their SecurID token to prove that they have the assigned token. This operation is known as Next Tokencode mode, which can be triggered by one of the following situations:

See Also: "SecurID Next Tokencode Authentication"..


  • 16 Digit Passcode

  • 4 Digit Fixed Passcode

Load Balancing

RSA Authentication Manager Replicas.

Secondary server support


SecurID user specification

Designated users

SecurID protection of Administrators


Access Manager features and functions


Access Manager does not support the RSA features in Table 49-2.

Table 49-2 RSA Features Not Supported

RSA Feature Not supported by Access Manager

RSA Authentication Manager 7.1 SP2

Is not supported in an Active Directory Forest multi-domain environment

Multiple ACE Realms

The RSA Authentication API uses an automatic response time load balancing algorithm to determine where to send an authentication request. Such requests go to either a primary RSA Authentication Manager or a replica. The automatic algorithm can be overridden by creating a manual load balancing configuration file, sdopts.rec. However manually weighting an RSA Authentication Manager as a server of last resort does not preclude the Agent from communicating with it. As such, a true failover setup cannot be achieved with this method. For more information, see your RSA Authentication Manager documentation

System Generated PINs

Not supported by Access Manager.


Not supported for OAM SecurID Servers because only one OAM SecurID Server can perform SecurID authentication.

49.3 Components Required for SecurID Authentication

The following components are needed for the integration:

49.3.1 Supported Versions and Platforms

RSA Authentication Manager v8.3+ and the SecurID Authentication API are supported with OAM

49.3.2 Required RSA Components

The following RSA components are required for integrating Access Manager and SecurID Authentication. RSA Authentication Manager

Residing somewhere in your network are records of users, agents, tokens, and user's PINs. Portions of these records might reside in the Authentication Manager or in LDAP directories.

During authentication, Authentication Manager compares these records to the information it receives when a user attempts to access the network. If the records and tokencode or passcode match, the user is granted access. RSA SecurID Tokens

An RSA SecurID token is either a hardware device or software-based security token that generates and displays a random number that enables users to securely access protected resources.

The random number is called a tokencode. Before a user can authenticate with a token, the token must be recognized by Authentication Manager. RSA, or your vendor, ships a token seed file that you must import into the data store. Seeds listed in this file are assigned to tokens for generating the tokencode when an authentication request is received from an Authentication Manager agent.

During the SecurID authentication process, users must submit their username and passcode using an HTML form. The RSA Authentication Manager authenticates the identity of each user through a server that is registered with the Authentication Manager as a client (RSA Authentication Agent). One Access Server (known as the Oracle SecurID Access Server to distinguish it from other Access Servers) must be registered and set up as a client/Agent.

The RSA Authentication Manager compares the tokencode it has generated with the tokencode the user has entered. Tokencodes change at a specified interval, typically 60 seconds. Time synchronization ensures that the tokencode displayed on a user's token is the same code the Authentication Manager software has generated for that moment. Authentication is successful when the tokencodes match. Two-factor authentication provides stronger legal evidence of who performed the task. When properly configured, the Authentication Manager tracks all login requests and operations to reliably identify the user who is responsible for each logged action.

49.3.3 Installation and Configuration Requirements

SecurID requires affinity between the OAM Server and the RSA Authentication Manager for a user interaction. Therefore, the authentication dialog between the user and OAM Server must be sticky (this constraint is a security feature of SecurID authentication). In a cluster environment, if a load balancer is used to route requests to multiple managed server, ensure that stickiness is set between the load balancer and OAM Server. The SecurID Authentication API is bundled with Access Manager and installed on all OAM Servers. The SecurID Authentication API provides the connection functionality that eliminates the need for an Authentication Agent to be installed on the OAM Server. In other words, the API is the agent.

Every OAM Server must be registered as an RSA Authentication Agent host on the Authentication Manager along with the guidelines as follows:

  • Only one designated OAM SecurID Server can complete SecurID authentication. However, every OAM Server must be registered as an RSA Authentication Agent Host on the Authentication Manager.

  • Enable the OAM SecurID Server to be recognized as an Authentication Manager client.

  • Port 5500 (UDP) should be available for the Authentication Manager to communicate with authentication agents (OAM SecurId Server). This service receives authentication requests from Oracle SecurId Server and sends replies. For more details refer to your RSA Authentication Manager documentation.

  • Manage authentication requests from the client to the Authentication Manager.

  • Enforce two-factor authentication and block unauthorized access.

  • Provide automatic load balancing by detecting replica Authentication Manager response times and routing authentication requests accordingly.

  • Ensure that the system time on the client is correct to prevent the server and client from being out of sync.

  • Failover is not supported for Access Manager.

  • The SecurID Authentication Manager must be installed on a supported platform.

  • The system time must be correct to prevent the server and client from being out of sync.

  • The SecurID tokens or key fobs must be provisioned with the Authentication Manager by providing it with the token seed records.

  • Each user name must be mappable through an LDAP filter to a Distinguished Name in the directory.

  • An Authentication Manager slave and/or replicated Authentication Manager can provide failover if the primary Authentication Manager is down.

  • This integration requires a custom HTML login form and a properties file. Sample Oracle-provided custom html and custom html properties files can be found in:

    See Also:

49.4 SecurID Authentication Modes

The following scenarios illustrate the three modes of operation:

49.4.1 Standard SecurID Authentication

Here is an overview of the process that occurs when a user attempts to access a resource protected by the SecurID authentication scheme.

For information on Credential Collectors, see Understanding Credential Collection and Login.

Process overview: When the user requests a resource

  1. The WebGate intercepts the resource request and queries the Access Server to determine if and how the resource is protected, and if the user is authenticated.

  2. The OAM SecurId Server queries the directory for the authentication scheme, and receives authentication information from the directory.

  3. The WebGate redirects to the Credential Collector, which presents a form challenging the user for a two-part SecurID Passcode.

  4. The user submits credentials to the Credential Collector

  5. The Credential Collector hands off the credentials to the OAM SecurId Server

  6. The SecurID Authentication API on the OAM SecurId Server performs the authentication dialog and sends an LDAP bind to the Authentication Manager.

  7. The Authentication Manager database matches the SecurID passcode to the user ID and returns a success response to the Authentication Manager, which matches the user's PIN.

  8. The Authentication Manager returns the response to its Agent, the OAM SecurId Server.

  9. When the user's credentials are valid, SecurID authentication is successful. The OAM SecurId Server creates a session for the user and redirects the user to the Webgate, which then queries the OAM SecurId Server for resource authorization:

  10. The OAM SecurId Server evaluates the authorization request, which allows or denies access based upon the authorization rule.

  11. When access is granted, the OAM SecurId Server passes authorization to the WebGate, which presents the resource to the user.

49.4.2 SecurID Next Tokencode Authentication

When Next Tokencode mode is On, the user must supply the next tokencode on their SecurID token.

This mode can be triggered when:

  • An incorrect Passcode was provided repeatedly during login. When a user attempts authentication with incorrect passcodes four consecutive times, the Authentication Manager turns on Next Tokencode mode, as noted in the Authentication Manager's Activity Report. The next time the user successfully authenticates with their correct Passcode, they are challenged for the next tokencode that appears on their SecurID token.

  • The Authentication Manager requires confirmation of, or synchronization with the token. Even with a correct Passcode, the Authentication Manager Administrator might set the Next Tokencode mode On to force the user to confirm that they have the SecurID token or to synchronize the token with the Authentication Manager. When Next Tokencode mode is On, the Next Tokencode challenge form is presented to the user immediately following a successful login.

Process overview: When Next Tokencode is On

  1. The Credential Collector presents a form to challenge the user for the next tokencode on the token following a successful login.

  2. The user enters a username, waits 60 seconds, then enters the next tokencode on the SecurID token.

  3. When the tokencode is correct, the Passcode the user originally entered is accepted and the user is authenticated.

49.4.3 SecurID New PIN Authentication

When the user is required to have a new PIN, the Credential Collector prompts the user with specific forms.

Process overview: When New PIN is required

  1. The Credential Collector presents a form that allows the user to enter the PIN they want.

  2. The user enters the new PIN and then re-enters the new PIN to complete the form.

  3. The OAM SecurID Server forwards the information to the Authentication Manager.

  4. The Authentication Manager registers the new PIN, which becomes part of the Pincode the user must supply during subsequent logins.

  5. The Login Form appears again where the user enters the username and Passcode for a forced re-authentication.

49.5 Configuring Access Manager for RSA SecurID Authentication

Users with valid Oracle Access Management Administrator credentials can enable RSA SecurID authentication.


See Installation and Configuration Requirements for installation and configuration that is outside the scope of this manual) and which must be completed before you begin SecurID integration with Access Manager.

See Also:

To set up SecurID Authentication with Access Manager

  1. In your oam-config.xml, set the OAM SecurID Sever serverRequestCacheType parameter to BASIC, as follows:

    1. Stop all WebLogic servers (OAM Servers and AdminServer).

    2. Change the serverRequestCacheType from COOKIE (default) to BASIC, as follows:

      <Setting Name="serverRequestCacheType" Type="xsd:string">BASIC</Setting>

      See Updating OAM Configuration for information on how to update OAM configuration.

    3. Start all WebLogic Servers (OAM Servers and AdminServer).

  2. Register a Web agent from the RSA Console that will be used by Access Manager, then copy the agent configuration file (sdconf.rec) as follows:

  3. Using the Oracle Access Management Console, create a custom authentication module for RSA, as follows:

    1. Click Application Security at the top of the window.

    2. Select Create Custom Authentication Module from the Create (+) drop-down menu in the Plug-ins section.

    3. Select the General tab and enter the following:

      Name: RSA_AUTH
    4. Select the Steps tab and enter a name for the Step, then choose the RSA SecurID Plugin

      Step Name: stepRSA
      Plugin Name: RSA SecurID Plugin
    5. In the stepRSA, Step Details tab, enter and Save the Step Details shown in the next screen, which should also appear in your customhtml.properties file:

    6. Steps tab: Add the User Identification Plugin: Enter a name for the Step, then choose the RSA SecurID Plugin:

      Step Name: rsa_useridentification
      Plugin Name: UserIdentificationPlugin
    7. rsa_useridentification, Step Details: Enter and Save the following details for your environment:


      KEY_IDENTITY_STORE_REF: The registered Default Store.

      KEY_SEARCH_BASE_URL: dc=us,dc=example,dc=com

  4. Orchestrate the steps as follows: stepRSA should be first (to authenticate the user with the RSA Server); designate your User Identification Plugin for the success step.

    Initial Step: stepRSA
    Name: StepRSA
    On Success: rsa_useridentification
    On Failure: failure
    On Error: failure
    Name: rsa_useridentification
    On Success: Success
    On Failure: failure
    On Error: failure


    The On Failure and On Error fields must both be set to failure.

  5. Create a new authentication scheme (RSACredScheme, for example) that uses the custom authentication module that you just created for RSA with a custom HTML login form. Sample values are shown in the following screen:


    The authentication scheme's Context Value specifies the path to your custom HTML login form. Your custom HTML properties file must share the same name as the form (with a .properties extension) in the same directory path. This example uses customhtml.html and customhtml.properties.

    Challenge parameters specify the initial RSA command for authentication (RSA_USER_PASSCODE). The is_rsa=true parameter and value must be specified for RSA.

  6. Use this scheme in the Application Domain protecting resources requiring SecurID authentication.

  7. Ensure that your custom HTML file is present in:


    The Custom HTML for RSA Login Form requires form action set to /oam/server/auth_cred_submit, as follows:

    <form id="loginData" action="/oam/server/auth_cred_submit" method="post" name="loginData">
    <div id="oam_credentials" class="input-row"> 
    <span class="ctrl"></span>
    div class="button-row">
        <span class="ctrl"> 
    <input id="login_button" type="submit" value="Login" class="formButton" 
      onclick="this.disabled=true;document.body.style.cursor = 'wait'; 
      this.className='formButton-disabled';form.submit();return false;"/>
    <div id="oam_error_messages"></div>
  8. Ensure that your customHTML.properties file is:

    • Named as your custom HTML file with a .properties extension

    • Stored in the same path as your custom HTML file

    • Confirmed; settings match the RSA SecurID plugin configuration parameters. For example:

        passcode=Mother's maiden name 
        rsa_new_pin=RSA New Pin 
        rsa_new_pin_confirm=RSA Confirm New Pin 
        Pin=RSA Pin 
        rsa_sysgen_pin=RSA Create New Pin 
        rsa_sysgen_pin_confirm=RSA System Generated Pin 
        error1=Username not specified 
  9. Restart OAM Servers.

  10. Test your configuration by accessing the appropriate protected resource and validating the various modes.

  11. See "RSA SecurID Issues and Logs" for details if you experience problems.

49.6 Running a Custom RSA Plug-in

You can run a custom RSA plug-in located in <ORACLE_HOME>/oam/custom_plugins/rsa/RSAPlugin.jar.

To run a custom RSA plug-in:

  1. Download the RSA dependent libraries named authapi.jar and cryptoj.jar.
  2. Add the authapi.jar and cryptoj.jar libraries to <DOMAIN_HOME>/config/fmwconfig/oam/plugin-lib.
  3. Get the custom RSAPlugin.jar file from its directory and import the plugin to add it to the list of custom plugins.
  4. Once successfully imported, distribute and activate the plug-in.

    Activation will fail the first time. When it does, restart the server and activate again. After activation, use the plugin to specify the necessary orchestration steps.