Guide to Getting Started with the AM 8.x REST-API Test App

[VasanthBalakris]

Recently I had a customer use case that required integrating SecurID Access authentication into one of their web applications. With the release of Authentication Manager (AM) 8.2 SP1, and continuing with AM 8.3, there is a new built-in RESTful web API for authentication. A REST-compliant API allows for much easier integration of SecurID authentication into web-based applications and sign-on workflows. In a few hours of testing, I was able to get an RSA-provided test application up and running using this API in my Authentication Manager 8.2 SP1 lab. One cool thing about this new REST API is that it allows you to use the same API for AM with traditional SecurID authenticators but also the new SecurID Access Cloud Authentication Service and new authenticators such as push-to-approve, biometrics and the Authenticate app token codes.

This guide is written for a non-programmer to get the RSA test application up and running against a local AM 8.2 SP1 test/lab instance. The guide is also based on a Windows client PC or VM but a knowledgeable Linux admin could easily get it running on a Linux client.

Requirements

• Local AM 8.2 SP1 Primary instance, ideally patched to the latest version, P2 as of this post, with Super Admin access
• Windows host or VM with network connectivity to AM 8.2 SP1 Primary
• rsa-securid-authentication-api-example.zip file from rsa-am-extras-8.2.1.0.0 ZIP file package under the \RSA SecurID Authentication API folder. This Extras package is available for existing SecurID Customers and Partners at the Version Upgrade Downloads on Link. (login required)
• The README text file inside the API example test app zip file is very helpful and notes two other requirements in order to build and run the test applications:
  • Java SDK 1.7.0 (or later) I used the latest JDK 8u141 on Windows which worked for me.
  • Apache Maven 3.0.4 or later Maven is an open source build automation tool. This tool does require internet connectivity from the lab client VM.

References

• RSA SecurID Authentication API Developer's Guide PDF
  • The OpenAPI references in the Preface section of this PDF are helpful to developers
• rest-java-client/target/generated-sources/swagger/index.html Documentation generated during install/compile
• openapi-yaml/rsa-securid-authentication-api.yaml This OpenAPI interface definition source (YAML) file which contains details on the endpoints and JSON objects

Setting Up Java JDK and Apache Maven Steps

1. Java JDK - If it’s not already installed, download the appropriate version of the Java JDK for your client platform and install it using the defaults. Once it’s installed, on a Windows PC, you can launch the command prompt and type java -? and you should get output to make sure the JDK is installed and the PATH is set correctly.
2. Maven - Follow the Apache install instructions which is basically to unzip it to a directory of your choice and create a PATH environment variable to the /bin directory inside the Maven package. I unzipped it to: C:\Program Files\apache-maven-3.5.0 .
   1. Maven requires the JAVA_HOME variable to bet set for the JDK executable and it does not seem to be properly set by the JDK installer on my Windows VM when you also have the Java Runtime Environment (JRE) installed. If you don't get an actual path when you type in echo %JAVA_HOME% on the command prompt, the Atlassian website has a good guide on this.
   2. If everything is installed correctly, on a command line mvn -v should give you similar output to this:
      
      Notice it is jdk and not jre when the JAVA_HOME environment variable is set correctly. If it points to the JRE you will get a Maven compile error in the next step.
3. Extract the entire rsa-securid-authentication-api-example.zip file preserving directories into a directory of your choice. In this example, it is c:\SID-REST. From now you can follow the instructions from the README text file contained inside that zip. When you run mvn clean install from the unzipped directory, it will download a bunch of Maven cloud repo Java libraries and then compile the test app based on the pom.xml file. You will see some warnings which is OK but eventually you should something like this BUILD SUCCESS message:
   
4. Finally, we are now ready to configure AM 8.2 SP1 to start testing. However, first it’s never a bad idea to ping the Primary test instance to make sure your Windows VM can talk to it:
   
5. We know AM is up so we can configure the instance to accept REST API connections. Log into the AM 8.2 SP1 Primary instance Security Console as Super Admin. On the main dashboard at the bottom left under Quick Links, go into System Settings. With 8.2 SP1 we now have a link for RSA SecurID Authentication API on the top left quadrant. Click into it:
   
   Enable the API checkbox and keep the default port unless you need to change it, click Apply Settings:
   
   Note the Access ID and Access Key - it may be handy to cut paste those into a text editor.
6. Now if you haven't already, either create a test user in the internal database or find a user in a lab identity source (AD or LDAPv3) and assign them a token. TIP: If your AM lab is like mine it probably only has soft tokens. You'll need to use the Windows Desktop token on the client VM or configure iOS or Android with the CTF soft token profile. Note: CTF is considered an insecure soft token provisioning method by RSA and is not recommended for production environments. For a test lab this is fine. You can then go in as admin, assign a soft token and distribute it with that CTF profile. Cut and paste the CTF activation code and email it to an account on your smart phone. After you install the RSA SecurID soft token app from the app store, that email code will allow you to import the token. The specific instructions for this set of steps are beyond the scope of this guide but it's straightforward. Make sure you go into the Self Service Console (SSC) as that user and set the PIN (if not set with SSC) and test the token to make sure authentication is working and you have a good token:
   
   
7. Now we can get back to the README file and start testing the Java test REST-API app. I find the test authentication client (rest-test-auth) is a lot easier than the single-step CLI client (rest-test-CLI.) The readme instructions are fairly general so let’s take it step-by-step. Go into the \rest-rest-auth\target subdirectory and run the java executable:
   cd rest-test-auth\target
   java -jar rest-test-auth-jar-with-dependencies.jar
   
8. You should get output like this assuming your JRE is installed correctly:
   
   Notice the testclient.properties file is not found because this is the first time to run this test Java client that creates it. There’s also an SSL warning since we haven’t yet downloaded the root certificate from our lab AM primary instance. First step is to select 1) and configure the client API. We will configure these in order:
   1. Base server URL - After compile and install this app defaults to localhost. It’s easiest to just cut and paste this existing default URL and edit it to the correct FQDN of your lab primary instance with the correct configured port and type enter:
   2. Agent Name - The app defaults to the local FQDN so just cut & paste that and make sure you go over to your Primary, login as Super Admin and add a standard agent record for your Windows client VM. In my lab, this box happens to also be the AD server:
      
   3. For the next 5 options just keep the default values:
      
      
   4. Root Certificate File - Now we come to the AM instance certificate file option so that verified HTTPS can be established between this client app and REST-API service running on the AM instance. If you don't do this, the test app will just throw a warning but it will still work. Nevertheless, it's not hard to fix. I found the easiest thing is to use the Firefox browser to log into the primary Security Console. Click the padlock icon on the URL bar top left, click the arrows and More Information button until you get to the View Certificate button and click into it. (Note not all steps are shown below as screenshots for the sake of brevity:)
      
      
      Click the Details tab and then you click the Export button and export to an X.509 Certificate (PKCS#7) format taking note of the filename. Copy the p7c file to the same directory as your rest-test-auth-jar-with-dependencies.jar file. You can then update the root certificate filename at the command line:
   5. API Key Type - keep the default value of KEY. The RSA SecurID Authentication API Developer's Guide (linked above) goes into details on these two options.
   6. Access ID & Access Key - These two will be from your temporary text file copied from the AM Security Console. Make sure you cut & paste carefully without truncating or padding spaces. (The screenshot below shows the values being updated because I changed the regenerated the API keys on the AM Security Console between screenshots.)
   7. Policy ID (for RSA SecurID Access) - This next option does not apply since we are using the SecurID REST-API on Authentication Manager so just leave the default as shown in bottom of the screenshot above.
9. Once everything is configured correctly, this program will write a testclient.properties local file. You will be returned to the main menu and we can see SSL verification is enabled:
   We are finally ready to try out authentication with our test user token! The 4) option is the choice for a regular hard or soft token. My lab has user ID auser with a soft token on iOS. It's also helpful to go to your AM Security Console and run the Authentication Monitor. Switch back to the command line and run option 4 and test your confirmed working user and token. The screenshots below show iOS soft token PIN entry, passcode display and 2FA credential entry into the test app:
   

SUCCESS!

It's cool to get this working after all those steps, I think you can agree. The option 3) in the app is a multi-step authentication mostly applicable to the SecurID Access Cloud Authentication service but it also works for an On-Demand enabled user where you must enter a PIN and then the tokencode is delivered via SMS or email, then entered by the user as a multi-step authentication. Now you or your development teams can start testing the REST-API and building in SecurID Access authentication into any application that supports a RESTful API integration.

Important Considerations

The biggest caveat is that traditional SecurID native API clients written to our Java or C APIs will by default support the built-in load balancing and high availability in the SecurID (SDI) protocol. That will include automatically discovering all Replica instances during the first authentication and failing over to the next available instance. This new RESTful API explicitly requires the API client to connect to a Primary or Replica instance. Failover functionality must be handled by the client. In this respect it is very similar to the RADIUS server functionality built into each AM instance with explicit primary and failover RADIUS servers defined at every client agent.

If you want to check out the Java code in this sample app, there are /src directories in the test app package with the Java source that can be examined in a text editor.