This guide describes the RSA Authentication Agent application programming interfaces (APIs) for Java, and how to use them. The intended audience includes developers who use the APIs to integrate RSA SecurID into custom or third-party applications.

The RSA Authentication Agent APIs for Java enable developers to integrate RSA SecurID into custom or third-party applications.

Developers using this API to create their own agents must have an understanding of the basic operations involved in RSA SecurID authentication, which include:

• Verifying the user's passcode
• Processing the data when a user creates a new PIN in the New PIN mode
• Verifying the tokencode when a user is placed in the Next Tokencode mode

In addition, the developer must take necessary precautions to protect all user-supplied data when in use and clear the data when it is not in use.

Agent Administrator Tasks

This guide is primarily intended for API developers; however, the sections Configuring Advanced API Settings, Working with Load Balancing and Deployment Guidelines are intended for agent administrators.

RSA recommends that agent administrators read the RSA Authentication Manager Administrator's Guide available with RSA Authentication Manager to familiarize themselves with agent functionality.

Printing

To print this document, use the print-friendly version, print.html. Samples and specific pages of any reference material, if any, must be printed separately.

 

The Authentication Agent API for Java enables you to develop your own custom agents to protect required resources. For information about agents, see Authentication Agents.

API Features

The following sections describe the Authentication Agent API features:

Two-Step Authentication

To prevent an unauthorized person from capturing data from a SecurID authentication request, and using this data to authenticate to another RSA Authentication Manager, the agent sends a lock request before sending the user’s passcode.

The Authentication Manager locks the user name, which prevents it from being accepted by any other server in the realm, and waits for the corresponding passcode to be submitted. Once the user enters the correct passcode, the Authentication Manager unlocks the user name and authenticates the user. This process is called two-step authentication.

Note: Two-step authentication is different from two-factor authentication. RSA Authentication Manager 7.1 does not support two-step authentication.

Load Balancing

An agent that you link with the Authentication Agent API can communicate with multiple Authentication Managers in a realm. The API incorporates load-balancing routines to help the agent select the best Authentication Manager for communication. Load balancing occurs automatically based on data that the agent gathers dynamically at runtime and data acquired from the configuration files.

As an alternative to the automatic load-balancing process, you can also balance the load manually. In the sdopts.rec file, which resides on the agent host, specify which of the Authentication Managers each agent host must use to process requests.

For more information on load balancing, see Working with Load Balancing.

Thread Safety

All Authentication Agent API functions are thread-safe, which means you can safely call them from multithreaded applications without program failure or data corruption.

Synchronous Functions

All of the Java API functions are synchronous.

 

Before you start using the Authentication Agent APIs, review the following section to ensure that your system meets the necessary minimum requirements. The Authentication Agent API supports the Java 2 Platform, Standard Edition, versions 1.5 and 1.6.

Platform Support

The Authentication Agent API supports the following operating systems:

Windows

Version	Binary Compatibility
Windows 2003 R2 SP2	64-bit
Windows 2008 SP2 (Data Center, Standard, Enterprise, and Web Server Editions) Windows 2008 R2 Windows 2008 R2 SP1	32-bit and 64-bit 64-bit 32-bit and 64-bit
Windows Vista (Business and Enterprise Editions)	32-bit and 64-bit
Windows 7 Windows 7 SP1	32-bit and 64-bit 32-bit and 64-bit

UNIX

Version	Binary Compatibility
AIX 5.3 and 6.1	32-bit and 64-bit
HPUX 11i v3 Update 5	32-bit and 64-bit
RHEL 4.8 (AS/ES) and 5.5	32-bit and 64-bit
SUSE Linux 10 SP2 and 11	32-bit and 64-bit
Sun Solaris 10 with and without Zones	32-bit and 64-bit

Authentication Agent API is supported on VMware ESX 3.5 and VMware vSphere 4 with the following operating systems.

Hosted Operating System	VMware ESX 3.5	VMware vSphere 4
Windows 7 Enterprise edition (32-bit and 64-bit)	X	X
Windows Vista Business and Enterprise editions (32-bit and 64-bit)	X	X
Windows 2008 R2 Standard, Enterprise, Datacenter, and Web Server editions (64-bit)	X	X (64-bit)
RHEL 5.5 (32-bit and 64-bit)	X	X (64-bit)
Solaris 10 with and without Zones (32-bit and 64-bit)	X	X (64-bit)
SUSE Enterprise Linux 11 (32-bit and 64-bit)	X	X (64-bit)

Compatibility

This release of the Authentication APIs is compatible only with certain versions of the Authentication Manager server.

Interoperability with Authentication Manager

This release of the Authentication Agent API supports Authentication Manager 6.1.2 and 7.1 SP2 and 7.1 SP3.

Backward Compatibility

You can reuse your existing agent code which uses APIs from version 8.1. See Upgrading from Version 8.1 for information.

Top

 

You are required to work with the APIs, and also perform a few setup tasks before you can develop a custom agent to communicate with the Authentication Manager server.

The Auth SDK zip or tar kit contains the properties file, rsa_api.properties, the Release Notes and the following folders:

• doc. Contains the Developer’s Guide and the Javadocs.
• examples. Contains the sample code. This includes examples that can be used to test and run the function calls.
• lib. Contains the libraries.
• util. Contains the agent_nsload utility.

Critical and Sensitive Files

In addition to the Authentication API jar files (authapi.jar, log4j-1.2.8.jar, and cryptoj.jar), the Authentication API maintains critical and sensitive files as listed below. The application using the SDK must restrict access to these files. One of the ways to restrict access, is by setting appropriate file permissions on the files and the complete directory structure in which they reside, before invoking the API.

• sdconf.rec - This file is generated by the Authentication Manager server, and contains configuration information that controls the behavior of the Authentication API. Non-privileged users must not be able to read or edit this file.
• JAStatus.1 - This file is generated by the Authentication API to track last known status of the Authentication Manager servers. Non-privileged users must not be able to read or edit this file.
• securid - This file contains a shared secret key used to protect the communication between the local machine and the Authentication Manager. Non-privileged users must not be able to read or edit this file.

Note:The filenames listed above are the default filenames. They can be customized using the rsa_api.properties file.

Using the APIs

To work with the APIs:

1. Import the classes by inserting the following line into your code:
   
   import com.rsa.authagent.authapi.*;
2. Create an instance of the Authentication API (AuthSessionFactory) using the getInstance method from the AuthSessionFactory class. Use the API instance to create user sessions and display information related to the Authentication Manager. You can create multiple instances of the AuthSessionFactory.

   For example:
   
   AuthSessionFactory api = AuthSessionFactory.getInstance(); or
   AuthSessionFactory api = AuthSessionFactory.getInstance(config_path)
   
   where config_path is the path to the custom properties file. For more information, see Configuring Advanced API Settings.

3. Associate each user with an individual session object using the createUserSession method from the AuthSessionFactory instance, which returns a user session object with the interface AuthSession.

   For example:
   
   AuthSession authSession = api.createUserSession();

4. Set up the authentication processes. There are various methods within each session object, which you can use for different authentication processes. The methods you use most often are check, next, and pin.

   For example:
   
   int status = authSession.check(userID, passCode);

   For more information, see the Javadoc Reference Documentation.

5. To free open resources and clear sensitive data, finalize all session objects by calling the session's close method.

   For example:
   
   authSession.close();

6. When the agent application no longer needs to use the API, shut down the API so that API data is saved and sensitive data is scraped. Configure the agent application to call the shutdown method in the AuthSessionFactory.

   For example:
   
   api.shutdown();

For examples of correct calling sequences, refer to the sample code. See Using the Sample Code for information on how to use the sample code.

Top

Custom Agent Setup Tasks

Once you have created a custom agent, you must complete the required setup tasks before you can use the agent to communicate with the Authentication Manager server.

1. Using Authentication Manager, do the following:

   • Register the agent as an agent host in Authentication Manager.

     Note: You must select DES as the encryption type for the agent host.

   • Obtain the Authentication Manager configuration file (sdconf.rec). Copy the sdconf.rec file to the default application directory.
   • In addition, if a node secret file (securid) exists, copy this file.
2. Include the JDK 1.5 or JDK 1.6 bin directory in your application path.
3. Untar or unzip the Authentication Agent API for Java kit, and store the following files in the class path of each application that uses the Authentication API:
• lib/authapi.jar (RSA Authentication API jar file)
• lib/log4j-1.2.8.jar (third-party logging API jar file)
• lib/cryptoj.jar (RSA BSAFE Crypto-J API jar file)
4. Store the RSA Authentication API configuration file (rsa_api.properties) in the default application directory.

   Note: If you use a custom properties file, you must pass the path to the file as an argument to the factory method getInstance in the AuthSessionFactory class.

Top

Upgrading from Version 8.1

To upgrade an agent created with 8.1 APIs to the 8.1 SP2 APIs, you must complete the following tasks.

Upgrade the APIs to 8.1 SP2

Convert or renew the node secret

Verify authentication with the Authentication Manager

Upgrade the APIs to 8.1 SP2

To upgrade the APIs to 8.1 SP2:

1. Identify the location of the existing Java SDK libraries.
2. Extract the 8.1 SP2 Java Authentication SDK files to a different local location.
3. Copy the lib folder.

4. Replace the existing lib folder with the new lib folder from the 8.1 SP2 Java SDK.
5. Update the jar files in the class path of each application that uses the Authentication API.

Note: Ensure that the new jar file cryptoj.jar is added to the class path.

Convert or Renew the Node Secret

The existing node secret in the 8.1 format is rendered unrecognizable once you upgrade the APIs to the 8.1 SP2 APIs. You must then either convert the existing node secret to the new format, or renew the node secret by deleting the existing node secret and creating a new one.

For information on converting an existing node secret to the 8.1 SP2 format, see Convert an Existing Node Secret to 8.1 SP2 Format

Renew the Node Secret

To renew the node secret:

1. Delete the node secret file (securid file) from the agent.
2. Clear the node secret from the Authentication Manager server.
3. Create a new node secret.

Create a Node Secret File

A node secret file ensures encrypted communication between the agent host and the Authentication Manager server. A node secret file can be created either automatically or manually.

The node secret file is automatically created at the first test authentication. For more information, see Performing a Test Authentication.

You can manually create a node secret file in the Authentication Manager server. This file must be exported from the Authentication Manager server and imported into the agent host. Once imported, it must be extracted and loaded appropriately. See Load a New Node Secret for information.

For information on how to manually create a node secret, see "Node Secret File" in the RSA Authentication Manager Administrator’s Guide.

If the node secret on the agent host is corrupted or does not match the node secret in the Authentication Manager server, encrypted communication between the agent and Authentication Manager does not work. The agent gets an ACCESS_DENIED error code, and logs a node verification failure message in the Authentication Manager Server Activity Monitor. To resolve this issue, delete the securid file from the agent, and clear it from the Authentication Manager server.

Top

Using the agent_nsload Utility

The agent_nsload utility available with the authentication SDK is used to:

Convert an Existing Node Secret to 8.1 SP2 Format

Load a New Node Secret

Note:You must use the agent_nsload utility available with the authentication SDK and not the utility available with the Authentication Manager server.

Convert an Existing Node Secret to 8.1 SP2 Format

You can convert the existing node secret to the new format by running the agent_nsload utility.

Note: If you have multiple agents installed on the same host, see Multiple Agents on a Host Authenticating With a common Authentication Manager before you convert the node secret.

To run the agent_nsload utility to convert the node secret:

1. Change to the util directory.
2. Change to the required platform-specific folder.
3. Run the agent_nsload utility as below, and give the path to the existing SecurID file location in the machine as the first parameter and the new destination location of the SecurID file as the second parameter.
   agent_nsload -c <Existing_Securid_file_path> <New_Securid_dir_path>

where:

Existing_Securid_file_path is the path where the SecurID file exists.

New_Securid_dir_path is the directory where the newly generated SecurID file should be stored.

For example:

On Windows:

agent_nsload -c C:\RSA\securid C:\My_Dir

On UNIX:

agent_nsload -c /tmp/RSA/securid /var/ace/

Load a New Node Secret

You can manually create a node secret in the Authentication Manager server and export it to the agent host. Once the node secret file is imported into the agent host machine, you must run the agent_nsload utility to extract the node secret file and store it appropriately. The node secret can be stored either in the default path or in a user-defined path.

Note:The sdconf.rec file must be present in the destination folder on the host machine before you can extract and load the node secret file.

To run the agent_nsload utility to extract the node secret to the default location, type:

On UNIX: agent_nsload -f /default_dir/nodesecret.rec

On Windows: agent_nsload -f C:\default_path\ nodesecret.rec

You will then be prompted for the password. Type the password and press Enter.

To run the agent_nsload utility to extract the node secret to a user-defined location, type:

On UNIX: agent_nsload -f /VAR_ACE/nodesecret.rec -d /VAR_ACE/new_dir/

On Windows: agent_nsload -f C:<windows path>\System32\ nodesecret.rec -d C:\<windows path>\System32\new_dir\

You will then be prompted for the password. Type the password and press Enter.

Top

Perform a Test Authentication

It is important that you perform an initial test authentication prior to rolling out an agent. In addition to verifying the authentication environment, the first successful authentication creates a node secret that is shared between the agent and the Authentication Manager. A copy of the node secret is encrypted and sent to the agent, which saves the received node secret to a securid file. Unless a specific path is provided, this file is saved in the current directory.

You can use the code in the sample code file AuthUser.java to perform a test authentication. See Using the Sample Code for more information.

A JAStatus.1 file is also created at the first authentication. This file is stored in the default application directory. It contains the current status of all the Authentication Manager servers in the realm.

Verify the Status of the Authentication Manager

You can verify the status of the Authentication Manager by running the code given in the sample code file AceStatus.java. This returns the status of each Authentication Manager on which the agent is registered as an agent host, and details including server name and address.

The following table lists the information displayed in the Authentication Manager section.

Returned Information	Description
Configuration Version	The version of the sdconf.rec file that is in use. For Authentication Manager 5.1 or later, this number is 14.
DES Enabled	If your configuration environment supports legacy protocols, YES is displayed.
Client Retries	The number of times the agent sends authentication data to Authentication Manager before a time-out occurs.
Client Timeout	The amount of time (in seconds) that the agent waits before resending authentication data to Authentication Manager.
Server Release	The version number of Authentication Manager.
Communication Protocol	The protocol version used by Authentication Manager and the agent.

The following table lists the status information displayed in the Authentication Manager section.

Status Information	Description
Server Active Address	The IP address that the agent uses to communicate with the server. This address could be the actual IP address of the server you have selected, or it could be an alias IP address assigned to the server. An IP address of 0.0.0.0 indicates that the agent has not yet received communication from the server.

The following table lists the server status information displayed in the Authentication Manager section.

Server Status	Description
Available for Authentications	This server is available to handle authentication requests.
Unused	The server has not yet received an authentication request.
For Failover only	The server is reserved for failover use only.
Default Server During initial requests	Only this server is available to handle requests at this time.

Top

Identify the Version and Build Number of the Authentication API

Perform the following steps to determine the version and the build number of the authentication APIs:

1. Set RSA_ENABLE_DEBUG=YES and RSA_DEBUG_TO_FILE=YES in the properties file (rsa_api.properties).
2. Perform an authentication.
   A debug logfile rsa_api_debug.txt is created in the path specified by the RSA_DEBUG_FILE in the properties file.
3. In this file, search for the string "RSA Authentication API started". This line contains the version and build number information.

Result Codes

For a list of result codes, see the AuthSession Field Summary table in the Javadoc Reference Documentation.

Top

By default, when you create the API instance, the API loads the rsa_api.properties file, which contains the default advanced configuration settings. You also have the option of using a custom properties file, or the system properties of your application.

Note: If you choose to use a custom properties file, the path to the file must be passed as an argument to the factory getInstance method in the AuthSessionFactory class.

If the default properties file and a custom properties file are both present, the API loads the properties in the following order—default, custom, and system properties. If the API finds duplicate keys in more than one set of properties, it uses the value defined in the last loaded properties.

For example, if the different sets of properties have the following key-value settings:

• Default properties file: KEY1=VALUE-1A, KEY2=VALUE-2A, KEY3=VALUE-3A
• Custom properties file: KEY2=VALUE-2B, KEY3=VALUE-3B
• System properties: KEY3=VALUE-3C

If the API loads all three sets of properties, the API uses the following key values:

• KEY1=VALUE-1A
• KEY2=VALUE-2B
• KEY3=VALUE-3C

If the custom file is missing, the API uses the following key values:

• KEY1=VALUE-1A
• KEY2=VALUE-2A
• KEY3=VALUE-3C

You can configure advanced settings to do the following:

• Set up event logging for the APIs.
• Set the minimum logging level.
• Set the location for storing the logs (console or log file).
• Set the type of log tracing required (function entries, function exits, or regular statements).

To configure advanced settings:

1. Using a text editor, open rsa_api.properties and modify the appropriate values.

   Note: The API accepts only pre-defined keys and ignores any unknown keys. Modify only the values.

2. Save rsa_api.properties in the current application directory.
3. Run the program.

Top

The following table describes the key-value settings in the properties file.

IP Override
Key	Description	Acceptable Values
RSA_AGENT_HOST	Indicates the IP address of the agent host in the Authentication Manager database. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	Any valid IP address. Note: Specify a local IP address if the agent host has multiple IP addresses.
Refresh Interval
Key	Description	Acceptable Values
RSA_CONFIG_READ_INTERVAL	Indicates the interval of time in seconds that separates each reloading of the configuration file. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	0-86400 (24 hours) The default value is 600 seconds.
Server Configuration
Key	Description	Acceptable Values
SDCONF_TYPE	Indicates the data type of the Authentication Manager configuration file, or the sdconf.rec file. Changes made to this file take effect only on initialization/restart.	The data type is always FILE.
SDCONF_LOC	Indicates the path to the Authentication Manager configuration file, or the sdconf.rec file. Changes made to this file take effect only on initialization/restart.	The applicable path. For example: /var/ace/api/sdconf.rec or C:\\WINDOWS\\system32\\sdconf.rec
Server Status
Key	Description	Acceptable Values
SDSTATUS_TYPE	Indicates the data type of the Authentication Manager server status file. Changes made to this file take effect only on initialization/restart.	The data type is always FILE.
SDSTATUS_LOC	Indicates the path to the Authentication Manager server status file. Changes made to this file take effect only on initialization/restart.	The applicable path. For example: /var/ace/api/JAStatus.1 or C:\\WINDOWS\\system32\\JAStatus.1
Optional Configuration
Key	Description	Acceptable Values
SDOPTS_TYPE	Indicates the data type of the Authentication Manager optional configuration file. Changes made to this file take effect only on initialization/restart.	The data type is always FILE.
SDOPTS_LOC	Indicates the path to the Authentication Manager optional configuration file. Changes made to this file take effect only on initialization/restart.	The applicable path. For example: /usr/ace/api/sdopts.rec or C:\\WINDOWS\\system32\\sdopts.rec
RSA_SERVER_EXCHANGE_INITIAL_TIMEOUT (initial_timeout)	Enables you to set the initial_ timeout coefficient, which is used to calculate socket time out for ACE time request.	The default value is 1000 millliseconds When the number of consecutive requests is zero, the socket timeout(in milliseconds) is calculated as, timeout=initial_timeout
RSA_SERVER_EXCHANGE_TIMEOUT_OFFSET (offset)	Enables you to set the offset timeout coefficient, which is used to calculate socket time out for ACE time request.	The default value is 200 milliseconds When the number of consecutive requests is greater than zero, the socket timeout(in milliseconds) is caluclated as: timeout= offset+ increment*number_of_consecutive_requests
RSA_SERVER_EXCHANGE_TIMEOUT_INCREMENT (increment)	Enables you to set the increment coefficient, which is used to calculate socket time out for ACE time request.	The default value is 100 milliseconds When the number of consecutive requests is greater than zero, the socket timeout(in milliseconds) is caluclated as: timeout= offset+ increment*number_of_consecutive_requests
Node Secret
Key	Description	Acceptable Values
SDNDSCRT_TYPE	Indicates the data type of the Authentication Manager node secret file. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	The data type is always FILE.
SDNDSCRT_LOC	Indicates the path to the Authentication Manager node secret file. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	The applicable path. For example: /var/adm/ace/api/securid or C:\\WINDOWS\\system32\\securid
Event Log
Key	Description	Acceptable Values
RSA_LOG_TO_CONSOLE	If set to YES, event logs are sent to the console. If set to NO, event logs are not sent. Valid only if RSA_LOG_LEVEL is not set to OFF. Changes made to this parameter take effect based on intervals set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.
RSA_LOG_TO_FILE	If set to YES, event logs are sent to the log file specified by RSA_LOG_FILE. If set to No, event logs are not sent. Valid only if RSA_LOG_LEVEL is not set to OFF. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is YES.
RSA_LOG_FILE	Indicates the path to the log file. Valid only if RSA_LOG_TO_FILE is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	The applicable path. For example: /var/ace/api/my_api_events.log or C:\\WINDOWS\\system32\\my_api_events.log
RSA_LOG_LEVEL	Indicates the minimum log level. Events below this level are not logged. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	OFF, DEBUG, INFO, WARN, ERROR, or FATAL The default value is INFO.
Debug Trace
Key	Description	Acceptable Values
RSA_ENABLE_DEBUG	If set to YES, debug tracing is enabled. If set to NO, debug tracing is disabled. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.
RSA_DEBUG_TO_CONSOLE	If set to YES, debug traces are sent to the console. If set to NO, debug traces are not sent. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.
RSA_DEBUG_TO_FILE	If set to YES, debug traces are sent to the file specified by RSA_DEBUG_FILE. If set to NO, debug traces are not sent. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is YES.
RSA_ DEBUG_FILE	Indicates the path to the debug trace file. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	The applicable path. For example: /usr/ace/api/my_api_debug.log or C:\\WINDOWS\\system32\\my_api_debug.log
RSA_DEBUG_ENTRY	If set to YES, function entries are traced. If set to NO, function entries are not traced. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.
RSA_DEBUG_EXIT	If set to YES, function exits are traced. If set to NO, function exits are not traced. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.
RSA_DEBUG_FLOW	If set to YES, flow statements are traced. If set to NO, flow statements are not traced. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.
RSA_DEBUG_NORMAL	If set to YES, regular statements are traced. If set to NO, regular statements are not traced. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.
RSA_DEBUG_LOCATION	If set to YES, class name and line number are displayed in the trace. If set to NO, class name and line number are not displayed in the trace. Valid only if RSA_ENABLE_DEBUG is set to YES. Changes made to this parameter take effect based on the interval set in RSA_CONFIG_READ_INTERVAL	YES or NO The default value is NO.

Top

An agent that you link with the Authentication Agent API can communicate with multiple Authentication Managers in a realm. The API incorporates load balancing routines to help the agent select the best Authentication Manager for communication. Load balancing occurs automatically based on the data that the agent gathers dynamically at runtime and from data acquired from configuration files. Load balancing can be either dynamic or manual.

Dynamic Load Balancing

By default, the API uses dynamic load balancing, in which the agent sends a request to each RSA Authentication Manager server in the realm and determines a priority list based on the response time of each Authentication Manager server. The Authentication Manager server with the fastest response time gets the highest priority and receives the largest number of authentication requests. Other Authentication Manager servers get lower priorities and receive fewer requests. This priority list is refreshed each time a time request or authentication request times out, or when the internal server status differs from the status received in the server's response. To perform dynamic load balancing, the agent connects to the Authentication Manager server through firewalls using the alternate IP addresses (aliases) for the Authentication Manager servers. The Authentication Manager servers provide the list of aliases to the authentication agent during a response to an authentication request. The IP addresses are stored in the configuration record file (sdconf.rec) on the authentication agent host. For more information, see Configuring the sdopts.rec File.

Manual Load Balancing

With manual load balancing, you specify the Authentication Manager server that each agent host uses. You also assign a priority to each Authentication Manager server so that the authentication agent can direct authentication requests to some Authentication Manager servers more frequently than the others. You specify manual load balancing by including the USESERVER statement in the sdopts.rec file, and associating priority settings with each Authentication Manager server specified for use. For more information, see Configuring the sdopts.rec File.

 

Using the sdopts.rec File

This section describes how to create an sdopts.rec file. It also provides examples of ways you can use the components to set up load balancing.

Create the sdopts.rec File

To create the sdopts.rec file:

1. Using a text editor, create an sdopts.rec file, and store it in the default application directory where you have stored the sdconf.rec file.
2. Configure the sdopts.rec file to be read-only.
3. Specify the location of the sdopts.rec in the rsa_api.properties file. For more information, see Configuring Advanced API Settings.

Configure the sdopts.rec File

Note:Each time you modify the sdopts.rec file, you must restart the agent to register the changes made.

The sdopts.rec file can contain the following types of lines:

• Comments, where each line must start with a semicolon
• Keyword-value pairs

Keyword value pairs can be any of the following:

• CLIENT_IP=<ip_address>. Specifies an overriding IP address for the authentication agent host. The CLIENT_IP keyword can appear only once in the file. For information, see Specifying an Overriding IP Address.
• USESERVER=<ip_address>, <priority>. Specifies an Authentication Manager server to receive authentication requests from the authentication agent host according to a specified priority value. Use one setting for each Authentication Manager server that the authentication agent host uses. The combined maximum number of Authentication Manager servers that you can specify in the sdopts.rec and sdconf.rec files is 11.

Note: Including this value in the sdopts.rec file enables manual load balancing. Each USESERVER keyword value must consist of the actual Authentication Manager IP address separated by a comma from the assigned priority. The priority specifies if or how often an Authentication Manager server can receive authentication requests.

The following table describes the priority values that you can specify.

Priority	Description
2-10	The number of times that the agent communicates with Authentication Manager during a round, which is the sum of all assigned priorities. For example, Authentication Manager A has a priority of 5, and Authentication Manager B has a priority of 10. For every 5 authentication requests that go to Authentication Manager A, 10 authentication requests go to Authentication Manager B, for a total of 15 authentication requests.
1	Use this Authentication Manager only if no Authentication Manager servers of higher priority are available.
0	Ignore this Authentication Manager server.

You must assign a priority to each Authentication Manager server that you add to the sdopts.rec file. Otherwise, the entry is invalid. You must use priority values as specified or within the specified range only.

The IP addresses in the file are verified against the list of valid Authentication Manager servers that the agent receives as part of its initial authentication.

• ALIAS=ip_address, alias_ip_address_1,[alias_ip_address_2, alias_ip_address_3]. Specifies one or more alternate IP addresses (aliases) for an Authentication Manager server in addition to the aliases listed for the Authentication Manager server in the sdconf.rec file. You can specify up to three aliases per Authentication Manager server. The value for the ALIAS keyword must consist of the actual IP address of the Authentication Manager server, followed by up to three aliases for that Authentication Manager server. The ALIAS specified must be a valid IP address and the Authentication Manager must be able to resolve the IP address from its current network. This means that the Authentication Manager must be able to communicate with the alias IP address. The Authentication Manager list provides actual and alias IP address information about all known Authentication Managers in the realm, and the agent receives the list from an Authentication Manager, after it validates an authentication request.

• ALIASES_ONLY[=ip_address]. When you provide an actual IP address of an Authentication Manager server as the value, this keyword instructs the agent to use only the alias IP addresses to contact the Authentication Manager. When you do not provide a value, this keyword instructs the agent to send requests only to the Authentication Manager servers that have alias IP addresses assigned to them. You can create exceptions by including no more than 10 IGNORE_ALIASES keywords in the sdopts.rec file to specify which Authentication Manager servers must be contacted through their actual IP addresses. For an example of such exceptions, see Specifying Alias IP Addresses for Use or Exclusion. If you use this keyword, make sure that at least one Authentication Manager has an alias IP address specified for it in the sdconf.rec file or in the sdopts.rec file.
• IGNORE_ALIASES[=ip_address]. If you do not provide a value, this keyword specifies that all alias IP addresses found in the sdopts.rec and sdconf.rec files, or on the Authentication Manager list, are ignored. You can create exceptions by including no more than 10 ALIASES_ONLY keywords in the sdopts.rec file to specify which Authentication Manager servers must be contacted through their alias IP addresses. For an example on such exceptions, see Specifying Alias IP Addresses for Use or Exclusion. When you provide an actual IP address as the value, this keyword instructs the agent to use only the actual IP address to contact Authentication Manager.
• AVOID[=ip_address]. When you provide an actual IP address of an Authentication Manager server as a value, this keyword instructs the agent to exclude this Authentication Manager server from use during dynamic load balancing.

Top

Example: Configuring Manual Load Balancing

You configure manual load balancing by including the USESERVER keyword in the sdopts.rec file to specify IP addresses of the Authentication Manager servers that you want the agent host to use.

You can list the IP addresses in the sdopts.rec file in any order, but you must list each separately, one per line. The following example shows how to use the USESERVER keywords to specify the IP addresses.

;Any line of text that starts with a semicolon is ignored

;(is considered a comment).

;Do not put a blank space between a keyword and its

;equal sign. Blank spaces are permitted after the

;equal sign, after the IP address, and after the

;comma that separates an IP address from a priority value.

USESERVER=192.168.10.23, 10

USESERVER=192.168.10.22, 2

USESERVER=192.168.10.20, 1

USESERVER=192.168.10.21, 0

In this example, the Authentication Manager server identified by IP address 192.168.10.23 receives five times more authentication requests than the Authentication Manager server with IP address 192.168.10.22. Authentication Manager server with IP address 192.168.10.20 is used only if the Authentication Manager servers of higher priority are unavailable. The Authentication Manager server with IP address 192.168.10.21 is ignored except in rare circumstances (as described in Configuring the sdopts.rec File.)

Note: You can use the USESERVER and ALIAS keywords together in the sdopts.rec file. However, USESERVER keywords must use actual not alias IP addresses, and ALIAS keywords have no effect on load balancing.

Example: Specifying Alias IP Addresses for Use or Exclusion

You can use the sdopts.rec file to specify alias IP addresses for use or for exclusion.

You can list the settings in the sdopts.rec file in any order, but you must list each setting separately, one setting per line. The following example shows how to use the ALIAS keywords in the sdopts.rec file.

;Any line of text that starts with a semicolon is ignored

;(is considered a comment).

;Do not put a blank space between a keyword and its

;equal sign. Blank spaces are permitted after the

;equal sign, after the IP address, and after the

;comma that separates an IP address from a priority value.

USESERVER=192.168.10.23, 10

USESERVER=192.168.10.22, 2

USESERVER=192.168.10.20, 1

USESERVER=192.168.10.21, 0

ALIAS=192.168.10.23, 192.168.4.1, 192.168.4.2, 192.168.4.3

ALIAS=192.168.10.22, 192.168.5.2, 192.168.5.3

ALIAS=192.168.10.20, 192.168.5.2

ALIAS=192.168.10.21, 192.168.1.1

ALIAS_ONLY=192.168.10.23

IGNORE_ALIASES=192.168.10.22

In this example, the default is to use the alias or actual IP addresses, with some exceptions. The Authentication Manager server with the actual IP address 192.168.10.23 has three alias addresses specified for it, while Authentication Manager servers with IP addresses 192.168.10.20 and 192.168.10.21 each have only one alias. The Authentication Manager server with IP address 192.168.10.22 has two alias IP addresses. The alias IP addresses specified by the ALIAS keywords are in addition to any aliases specified in the sdconf.rec file and in the Authentication Manager server.

Note: This example shows how to use the USESERVER and ALIAS keywords together in the sdopts.rec file. However, USESERVER keywords do not affect the alias addresses used to connect to the Authentication Manager servers, and ALIAS keywords have no effect on which Authentication Manager servers are specified for use.

In this example, the default is to ignore aliases, with two exceptions:

IGNORE_ALIASES

ALIASES_ONLY=192.168.10.23

ALIASES_ONLY=192.168.10.22

The ALIASES_ONLY exceptions specify that the authentication agent must send its requests to RSA Authentication Manager server 192.168.10.23 and 192.168.10.22 by using only their alias IP addresses.

In the following example, the default is to use aliases, with two exceptions:

ALIASES_ONLY

IGNORE_ALIASES=192.168.10.23

IGNORE_ALIASES=192.168.10.22

The IGNORE_ALIASES exceptions specify that the authentication agent must send its requests to the RSA Authentication Manager servers 192.168.10.23 and 192.168.10.22 by using only their actual IP addresses.

Top

Example: Specifying an Overriding IP Address

When the authentication agent runs on a host that has multiple network interface cards, and therefore multiple IP addresses, you must specify a primary agent host IP address to be used for encrypted communication between the agent and Authentication Manager. Agent hosts typically attempt to discover their own IP addresses. An agent host with multiple addresses can select an address that is unknown to the Authentication Manager, thus making communication between the agent and Authentication Manager impossible. You can specify an overriding primary IP address by including the CLIENT_IP keyword in an sdopts.rec file on the authentication agent host.

For example:

CLIENT_IP=192.168.10.19

This statement ensures that the authentication agent host always uses the specified IP address to communicate with Authentication Manager.

The Dynamic Host Configuration Protocol allocates IP addresses to agent hosts dynamically. To avoid address conflicts, do not enable DHCP for agent hosts with multiple IP addresses. Conversely, it is unnecessary to specify the CLIENT IP for agent hosts that have single IP addresses, because there are no alternative addresses to override. For more information, see the RSA Authentication Manager Administrator's Guide.

If you have specified secondary IP addresses for the agent host, you must enter these in the properties file record also, and update all addresses in this record if they change.

Important: If your Authentication Manager system uses auto-registration of agent hosts, the primary IP address of each agent host is entered automatically to the Authentication Manager's agent host record and is updated whenever the IP address changes. However, if agent hosts are registered manually, you must ensure that the agent’s primary IP address in the agent host record in the Authentication Manager database is identical to the primary IP address specified in the agent host’s sdconf.rec or in an sdopts.rec file. If these two settings do not match, communication between the agent host and Authentication Manager fails. If any agent host address changes at any time, inform the Authentication Manager administrator in time to update the agent host record in the Authentication Manager database.

Example: Excluding an Authentication Manager Server During Dynamic Load Balancing

In dynamic load balancing, you exclude an Authentication Manager server from use for authentication by including the AVOID keyword in the sdopts.rec file. When you provide the actual IP address of an Authentication Manager server as a value, this keyword instructs the authentication agent to exclude this Authentication Manager server from use during dynamic load balancing.

Important: Use the AVOID keyword only for dynamic load balancing. Do not use it with the USESERVER keyword for manual load balancing. If the AVOID keyword is included in an sdopts.rec file that includes a USESERVER statement, the AVOID statement is considered an error.

If you use the AVOID statement with the IP address of the default Authentication Manager server, the statement is ignored unless another Authentication Manager server is available. The default Authentication Manager server is the server where the sdconf.rec file was created. If an Authentication Manager server is designated as the master, however, it becomes the default Authentication Manager server regardless of where the sdconf.rec file was created. The following example shows how to use the AVOID keywords in the sdopts.rec file:

AVOID=192.100.123.5

In this example, the Authentication Manager server with the IP address 192.100.123.5 will not be used for authentication.

Top

 

 

The following table maps the C functions from the RSA Authentication Agent API for C, to each Java method from the RSA Authentication Agent API for Java.

 

RSA Authentication Agent API C Functions	Equivalent RSA Authentication Agent API Java Methods
AceGetAuthenticationStatus	AuthSession.getAuthStatus
AceGetPinParams	AuthSession.getPinData
AceGetShell	AuthSession.getShell
AceGetTime	AuthSession.getAceTime
AceInitialize	AuthSessionFactory.getInstance
AceInitializeEx	AuthSessionFactory.getInstance(path)
AceShutdown	AuthSessionFactory.shutdown
SD_Check	AuthSession.check
SD_ClientCheck	AuthSession.clientCheck
SD_Close	AuthSession.close
SD_Init	AuthSessionFactory.createUserSession
SD_Lock	AuthSession.lock
SD_Next	AuthSession.next
SD_PIN	AuthSession.pin
AceGetAlphanumeric	AuthSession.getPinData.isAlphanumeric
AceGetMaxPinLen	AuthSession.getPinData.getMaxPinLength
AceGetMinPinLen	AuthSession.getPinData.getMinPinLength
AceGetSystemPin	AuthSession.getSystemPin
AceGetUserSelectable	AuthSession.getPinData.isUserSelectable
AceAgentStatusDisplay	AuthSessionFactory.getAceServerStatus

Install, upgrade and uninstall options for an agent may differ depending on the deployment environment. This section describes a few generic recommendations for agent deployment, and important points to be considered during installation and upgrade in different deployment scenarios.

Single Agent on a Host

A single agent on a host machine may store the jar files (authapi.jar, log4j-1.2.8.jar, cryptoj.jar) and configuration files (sdconf.rec, sdopts.rec, securid, jastatus.1) either in the default location (default application directory) or in a customized location. The agent APIs can be upgraded to the 8.1 SP2 APIs by updating the jar files. See Upgrading from 8.1.

Multiple Agents on a Host Authenticating with a Common Authentication Manager

The Java API looks for configuration information in the property file (default: rsa_api.properties). If the SDCONF_LOC, SDOPTS_LOC and SDNDSCRT_LOC have not been specified in this properties file, Java API looks for them in the default application directory. Since the application directory is specific to the application, multiple Java agents on the same host will have separate configuration files. Depending upon whether the authapi.jar is placed in an agent-specific class path or a class path common to all the deployed agents, they can either use a different set or the same set of jar files.

The possible deployment types:

Common Jar Files and Common Configuration Files

Common Jar Files and Separate Configuration Files

Separate Jar Files and Common Configuration Files

Separate Jar Files and Separate Configuration Files

Common Jar Files and Common Configuration Files

Install Scenario

Agent-A is installed on a host and successfully authenticating with the Authentication Manager. The jar files are placed in a class path common to all deployed agents and the API configuration file (rsa_api.properties) specifies the locations of the configuration files.

Agent-B is installed on the same host. The jar files are placed in the same class path common to all deployed agents, and the API configuration file (rsa_api.properties) specifies the same locations as Agent-A.

Upgrade

When upgrading to 8.1 SP2, both agents must be upgraded. Since the jar files and the configuration files used are the same, when one agent is upgraded, the other agent automatically gets upgraded. For upgrade instructions, see Upgrading from 8.1.

Uninstall

If one of the agents is uninstalled, shared configuration files and jar files used by the other agent may get deleted, thus breaking the other agent.

Top

Common Jar Files and Separate Configuration Files

Install Scenario

Agent-A is installed on a host and successfully authenticating with the Authentication Manager. The jar files are placed in a class path common to all deployed agents and the configuration files are in the default application directory.

Agent-B is installed on the same host. The jar files are placed in the same class path common to all deployed agents, and the configuration files are in the default application directory. The configuration files of Agent-A must be copied to Agent-B's default application directory for the new agent to successfully authenticate with the Authentication Manager.

Upgrade

When upgrading to 8.1 SP2, both agents must be upgraded. Since the jar files used are the same, when one agent is upgraded, the other agent automatically gets upgraded. Once the node secret for Agent-A is converted, it must be copied to the default application directory of Agent-B. For upgrade instructions, see Upgrading from 8.1.

Uninstall

If one of the agents is uninstalled, shared jar files used by the other agent may get deleted, thus breaking the other agent.

Top

Separate Jar Files and Common Configuration Files

Install Scenario

Agent-A is installed on a host and successfully authenticating with the Authentication Manager. The jar files are placed in an agent-specific class path and the API configuration file (rsa_api.properties) specifies the locations of the configuration files.

Agent-B is installed on the same host. The jar files are placed in an agent-specific class path and the API configuration file (rsa_api.properties) specifies the same locations as Agent-A.

Upgrade

Since the jar files for each agent are separate, you can upgrade one agent at a time. Getting the upgraded agent to connect to the Authentication Manager server would require that the node secret be converted to the new 8.1 SP2 format. Since the configuration files are common, converting the node secret to the new format would make it unrecognizable by the other 8.1 agent. Hence the second agent must be upgraded too. For upgrade instructions, see Upgrading from 8.1.

Uninstall

If one of the agents is uninstalled, shared configuration files used by the other agent may get deleted, thus breaking the other agent.

Top

Separate Jar Files and Separate Configuration Files

Install Scenario

Agent-A is installed on a host and successfully authenticating with the Authentication Manager. The jar files are placed in an agent-specific class path and the configuration files are in the default application directory.

Agent-B is installed on the same host. The jar files are placed in an agent-specific class path and the configuration files are in the default application directory. The configuration files of Agent-A must be copied to Agent-B's default application directory for the new agent to successfully authenticate with the Authentication Manager.

Upgrade

Since the jar files and configuration files for each agent are separate, you can upgrade one agent at a time. For upgrade instructions, see Upgrading from 8.1.

To renew the node secret during upgrade or later, you must renew the node secret using the 8.1 agent, and obtain the node secret in the old format. This must then be converted to the new format for the upgraded agent.

Important:Renewing the node secret using the 8.1 SP2 agent will render it unrecognizable by the 8.1 agent. Conversion from 8.1 SP2 format to 8.1 format is not supported, and therefore communication between the 8.1 agent and the server will not be possible.

Uninstall

Since the jar files and configuration files for each agent are stored separately, one agent can be uninstalled without affecting the other.

Top

 

To view the documentation for the RSA Authentication Agent classes, fields, and methods in the Java APIs, click here, or see the /doc/Javadoc directory.

The RSA Authentication Agent API for Java includes a finished API application that you can run as a sample, as well as sample code for using the Java Authentication and Authorization Service (JAAS) implementation for BEA WebLogic Server.

For information about using the sample code, click here or see /examples/sample/build.xml.

For information about using the JAAS sample, click here or see /examples/securid_JAAS/build.xml.

 

 

 

This table lists the differences between the Java and C APIs.

 

Feature	Java APIs	C APIs
Offline Authentication	Not Supported	Supported (on Windows platform only)
Synchronous APIs	Yes	Yes
Asynchronous APIs	No	Yes
Password Integration	Not Supported	Supported (on Windows platform only)
EAP 32 and the Generic Credential API	Not Supported	Supported
Supplies User Prompts	No	Yes
Two-Step Authentication Support	Yes	Yes
Load Balancing	Yes	Yes
Expiration Facility and Cleanup Callbacks	No	Yes
Thread Safety	Yes	Yes
AceInitialize Error Detection	No	Yes
Data Encapsulation	Yes	Yes

 

The RSA SecurID solution provides two-factor authentication to protect access to data and applications. This access can be through remote dial-in connections, local access, domain and terminal services access, Internet and VPN connections, intranet and extranet applications.

The SecurID solution consists of an Authentication Manager server, an authentication agent that communicates with it, and authenticators that provide the tokencode. The authentication agent initiates a SecurID authentication session when a user attempts to access a protected resource. It verifies data provided by a user with data stored in the Authentication Manager server. Based on the result, the user is either allowed or denied access.

Apart from the RSA SecurID Agent, RSA also provides authentication agent APIs which can be used to develop a custom agent to communicate with the Authentication Manager server. These APIs are available as a dynamic library (.jar, .dll, or .so). Using these APIs, you can develop custom agents to protect required resources.

Functioning of an Authentication Agent

An agent created using the RSA Authentication Agent APIs performs the steps detailed below in a secure manner.

1. Intercepts all access attempts, such as attempts to log on or access a URL.
2. Determines whether the specific requested resource is protected by RSA SecurID:
• If the requested resource is not protected, the agent either ignores the request, or takes appropriate action, such as writing an audit message in the UNIX syslog or in the Windows Event Log.
• If the requested resource is protected by RSA SecurID, the agent continues the authentication process.
3. Prompts the user for the user name so that Authentication Manager can validate that the tokencode is generated from the authentication device registered to that user.
4. Locks the user name to prevent replay attacks when Authentication Manager replicas are deployed (not available in RSA Authentication Manager 7.1).
5. Requests the user for passcode.
6. Combines the passcode with a secret known only to the agent and its associated Authentication Manager in the realm, and delivers the combined data to a server for validation:
• If Authentication Manager approves the request, the agent grants access to the protected resource and takes other appropriate actions.
• If Authentication Manager denies access, the agent prevents the user from accessing the protected resource and takes other appropriate actions.

In addition to providing basic access checks during standard authentication, agents also handle several security-related housekeeping tasks, such as those related to Next Tokencode mode and New PIN Mode. In the Next Tokencode mode, the Authentication Manager requests for the next tokencode displayed on the user’s token. If the next tokencode is not properly sent to the Authentication Manager, the authentication fails. The Authentication Manager administrator determines that the user associated with a particular token requires a new PIN. The administrator determines the characteristics of PINs, which your custom agent can test using the API functions.

It is the agent you create, and not the API that handles all user input and user output associated with processing an authentication request.

Top

 

RSA SecurCare Online
https://knowledge.rsasecurity.com

Customer Support Information
http://www.rsa.com/support/

RSA Secured Partner Solutions Directory
www.rsasecured.com