Using the Administration API in RSA Mobile.

Introduction

The RSA Mobile administration API allows you to perform five key tasks programmatically:

Add/Remove RSA Mobile attributes from a user record.

Activate or de-activate an RSA Mobile license for a user.

Change the SMS details for a user.

Manage user PINs.

Modify access times.

The Administration API has been designed to run on the Authorization Server or an Identity Manger in an RSA Mobile system. A working API program has three functional requirements:

1. The required JAR files available on the CLASSPATH.
2.  Configuration files.
3.  A mandatory series of parameters passed into the application.

It is not necessary for the Identity Manager to be running where the Admin API is being used; it is simply an expedient way of ensuring the correct configuration has been applied.  

To understand how to run the sample program, the easiest way is to follow the steps outlined below on an installed Identity Manager.

Any use of the Administration API will have two key phases

1.  Authentication into the API service as an RSA Mobile administrator.

2.  Manipulate some RSA Mobile credentials for a specified user.

Administrator authentication

The following code fragment is taken from the RegisterUserExample.java and shows the code involved in getting an administration session (note that this code then actually does nothing whatsoever).

        try {

            AuthenticationClientService authService =

                new AuthenticationServiceProxyClient();

            AuthenticationMethodID authMethodID =

                PasswordAuthenticationServiceMethod.getAuthenticationMethodID();

            // We will call the authentication service to create a ticket for us.

            // The userid and password are required.

            AuthenticationResponse authResponse =

                authService.authenticate(authMethodID, userid, password,

                                         userIpAddress);

            AuthenticationStatus authStatus = authResponse.getAuthStatus();

            if ((authResponse.getAuthStatus().equals (

 AuthenticationStatus.METHOD_SATISFIED))

                    == true) {

                System.out.println("Policy satisfied; got a ticket!");

                // Get the ticket from the response.

                ticket = authResponse.getXMLTicket();

//

//

// This is where the REAL work will now take place

//

//

            }

            else {

                System.out.println("Program exiting.... Could not get a valid

 ticket.");

                System.exit(0);

            }

        }

        catch (CsfSystemException e) {

            Debug.traceException(RegisterUserExample.class, e);

        }

        catch (Exception e) {

            Debug.traceException(RegisterUserExample.class, e);

        }

RSA Mobile record manipulation

Given the structure of a sample program as shown in the previous section, any of the five major activities which the Administration API manages may be carried out in the section with the comment ?This is where the REAL work will now take place?

Again, the example RegisterUserExample.java may be followed to understand how the Administration API may be used to achieve individual tasks.  The ?registerUser? method shows the key steps involved in registering a new use with RSA Mobile and so shows

Remember that RSA Mobile is not involved in general user management, this is handled by the standard Directory Server management tools (such as Active Directory management),  this means that a key argument that any RSA Mobile administration task will need is the name of an existing user, so for example, the sample code has the following code:

        // Get the ticket from the response.

        ticket = authResponse.getXMLTicket();

        RSAUser rsaUser = getRSAUser(ticket, userToRegister);

        if (rsaUser != null) {

            registerUser(ticket, rsaUser, pin, countryOperatorCode,

                           phoneNumber);

        }

        else {

            System.out.println("Program exiting.... Could not fetch user --> "

                              + userid);

            System.exit(0);

        }

The ?userToRegister?  value is the simple UserID value, as seen in the standard administration GUI.  This then means that the ?registerUser? method may be examined to understand how the individual tasks are performed for our selected user.  For example, to enable the user for RSA Mobile:

// First make the user an RSAUser

mobUser.setEnabled(true);

If we were disabling the user (for RSA Mobile), then the following would be true:

// First make the user an RSAUser

mobUser.setEnabled(false);

Remember that for any change is the users details, the record must be re-saved, hence:

adminService.update(ticket, mobUser);

The rest of the ?registerUser? method shows how the other tasks are carried out, although the enabling and disabling of temporary, emergency access is not shown, so the following code fragment shows how temporary access is enabled for an existing user:

mobUser.setEmergencyAccessStartTime(startTime);
mobUser.setEmergencyAccessEndTime(endTime);
mobUser.setEmergencyAccessCode(tempCode);

Setting non-zero values for the start and end times for emergency access has the implicit action of 'turning on' emergency access for the specified time period. Then the act of setting non-zero values with the two methods will "turn on" temporary access", hence:

mobUser.setEmergencyAccessStartTime(0);
mobUser.setEmergencyAccessEndTime(0);

It is, however, the programmers responsibility to ensure that valid time/date values are supplied.

Running the code

Once the administration API program has been compiled, it must then be run in the correct environment.  As outlined in the introduction, the program should be run on either an Identity Manger or the Authorization Server.  In either of these two environments, the correct configurations of parameter files, archive JARs and command line parameters can be assured.

The following command program (if run from <INSTALLDIR>/bin) shows how an administration API program may be run with the correct environment:

@echo off
SETLOCAL
cd ..\bea

@rem Set user-defined variables.
rem set WL_HOME=.
set BEA_HOME=.
set RSA_HOME=..
set JAVA_HOME=%BEA_HOME%\jdk131
set LIB_DIR=%RSA_HOME%\lib
set RSA_LIB=%RSA_HOME%\rsalib
set RSA_BIN=%RSA_HOME%\bin
set WEBAPP_LIB_DIR=wlserver\config\csfdomain\applications\rsaAdmin\WEB-INF\lib

:checkJDK
if exist "%JAVA_HOME%/bin/javaw.exe" goto runApp
echo.
echo Java wasn't found in directory %JAVA_HOME%/bin.
echo Please edit the runExample.cmd script so that the JAVA_HOME
echo variable points to the root directory of your JDK installation.
goto finish

:runApp
set PATH=%JAVA_HOME%\bin;%WINDIR%;%WINDIR%\SYSTEM32
set PATH=%RSA_HOME%\bin;%PATH%

set PROPERTIES_DIR=%RSA_HOME%\properties
set BUNDLE_DIR=%RSA_HOME%
for %%i in (%LIB_DIR%\*.jar) do call %RSA_BIN%\scp.cmd %%i
for %%i in (%RSA_LIB%\*.jar) do call %RSA_BIN%\scp.cmd %%i
for %%i in (%WEBAPP_LIB_DIR%\*.jar) do call %RSA_BIN%\scp.cmd %%i

set CLASSPATH=%BUNDLE_DIR%;%CD%;%CP%

set OPTIONS=-Dproperties.directory=%PROPERTIES_DIR%
set OPTIONS=%OPTIONS% -Dlog4j.configuration=file:%PROPERTIES_DIR%\webserverlogconfig.properties
set OPTIONS=%OPTIONS% -Djava.library.path=%RSA_BIN%;.

set SERVICE_TYPE=managed
call %RSA_BIN%\setserverenv.cmd

%JAVA_HOME%\bin\java -classpath "%CLASSPATH%" %OPTIONS% %RSA_OPTIONS% com.rsa.examples.RegisterUserExample %*
goto finish

:finish
ENDLOCAL

For the supplied example program, run the example script (from a command line in the <INSTALLDIR>\bin directory) with the required parameters, for example:

    C:\RSASecurity\rsawebserver\bin>   mytest.cmd admin passwd01 joesoap

If the Identity Manager has been installed solely for the Administration API, then (a) it never need be started and (b) files may be deleted to decrease the filespace used. In this situation to reclaim disk space from Identity Manager, then do the following:

1. Copy all *.jar files from <INSTALLDIR>\rsawebserver\bea\wlserver\config\csfdomain\applications\rsaAdmin\WEB-INF\lib

to <INSTALLDIR>\rsawebserver\rsalib

2. Remove <INSTALLDIR>\rsawebserver\bea\wlserver directory and subdirectories