Working with the APIs

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:

Import the classes by inserting the following line into your code:

import com.rsa.authagent.authapi.*;
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.
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();
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.
To free open resources and clear sensitive data, finalize all session objects by calling the session's close method.
For example:

authSession.close();
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.

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.
Include the JDK 1.5 or JDK 1.6 bin directory in your application path.
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)

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:

Identify the location of the existing Java SDK libraries.
Extract the 8.1 SP2 Java Authentication SDK files to a different local location.
Copy the lib folder.
Replace the existing lib folder with the new lib folder from the 8.1 SP2 Java SDK.
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:

Delete the node secret file (securid file) from the agent.
Clear the node secret from the Authentication Manager server.
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:

Change to the util directory.
Change to the required platform-specific folder.
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:

Set RSA_ENABLE_DEBUG=YES and RSA_DEBUG_TO_FILE=YES in the properties file (rsa_api.properties).
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.
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