This website uses cookies. By clicking OK, you consent to the use of cookies. Click Here to learn more about how we use cookies.
OK
  • RSA.com
  • Products
    • Archer®
      • Archer®
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Ideas
      • Knowledge Base
      • Archer® Exchange
      • Training
      • Upcoming Events
      • Videos
    • RSA® Fraud & Risk Intelligence Suite
      • RSA® Fraud & Risk Intelligence Suite
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® FraudAction Services
      • RSA® Web Threat Detection
      • Upcoming Events
      • Videos
    • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication Cloud
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Events
      • Ideas
      • Knowledge Base
      • Training
      • Upcoming Patch Content
      • Videos
    • RSA® Adaptive Authentication Mobile SDK
      • RSA® Adaptive Authentication Mobile SDK
      • Advisories
      • Events
      • Ideas
      • Knowledge Base
      • Request Access
      • Training
    • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Events
      • Ideas
      • Knowledge Base
      • Training
      • Videos
    • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 7.x
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Events
      • Ideas
      • Knowledge Base
      • Training
      • Videos
    • RSA® Adaptive Authentication for eCommerce
      • RSA® Adaptive Authentication for eCommerce
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Ideas
      • Knowledge Base
      • Training
      • Videos
    • RSA® FraudAction Services
      • RSA® FraudAction Services
      • Advisories
      • Discussions
      • Documentation
      • Ideas
      • Videos
    • RSA® Web Threat Detection
      • RSA® Web Threat Detection
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Ideas
      • Knowledge Base
      • Videos
    • RSA NetWitness® Platform
      • RSA NetWitness® Platform
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Ideas
      • Integrations
      • Knowledge Base
      • Training
      • Upcoming Events
      • Videos
    • RSA NetWitness® Detect AI
      • RSA NetWitness® Detect AI
      • Documentation
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
    • RSA NetWitness® Investigator
      • RSA NetWitness® Investigator
      • Documentation
      • Download the Client
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
    • RSA NetWitness® Orchestrator
      • RSA NetWitness® Orchestrator
      • Overview
      • Documentation
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
    • RSA SecurID® Suite
      • RSA SecurID® Suite
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Knowledge Base
      • Ideas
      • Integrations
      • Training
      • Videos
    • RSA® Identity Governance & Lifecycle
      • RSA® Identity Governance & Lifecycle
      • Advisories
      • Blog
      • Community Exchange
      • Discussions
      • Documentation
      • Downloads
      • Ideas
      • Knowledge Base
      • Training
      • Upcoming Events
      • Videos
    • RSA SecurID® Access
      • RSA SecurID® Access
      • Advisories
      • Blog
      • Discussions
      • Documentation
      • Downloads
      • Ideas
      • Integrations
      • Knowledge Base
      • Training
      • Upcoming Events
      • Videos
    • Other RSA® Products
      • Other RSA® Products
      • RSA® Access Manager
      • RSA® Data Loss Prevention
      • RSA® Digital Certificate Solutions
      • RSA enVision®
      • RSA® Federated Identity Manager
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
      •  
  • Resources
    • Advisories
      • Product Advisories on RSA Link
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication Hosted
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® FraudAction Services
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Product Advisories
    • Blogs
      • Blogs on RSA Link
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Blogs on RSA Link
    • Discussion Forums
      • Discussion Forums
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® FraudAction Services
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Discussion Forums on RSA Link
    • Documentation
      • Product Documentation
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication Mobile SDK
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® FraudAction Services
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Documentation on RSA Link
    • Downloads
      • Product Downloads
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Downloads on RSA Link
    • Ideas
      • Idea Exchange
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication Mobile SDK
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® FraudAction Services
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Documentation on RSA Link
    • Knowledge Base
      • Knowledge Base
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication Mobile SDK
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Knowledge Base Pages on RSA Link
    • Upcoming Events on RSA Link
      • Upcoming Events
    • Videos
      • Videos on RSA Link
      • Archer®
      • RSA® Adaptive Authentication Cloud
      • RSA® Adaptive Authentication On-Premise 7.x
      • RSA® Adaptive Authentication On-Premise 14.x
      • RSA® Adaptive Authentication for eCommerce
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
      • RSA® Web Threat Detection
      • All Videos on RSA Link
  • Support
    • RSA Link Support
      • RSA Link Support
      • News & Announcements
      • Getting Started
      • Support Forum
      • Support Knowledge Base
      • Ideas & Suggestions
    • RSA Product Support
      • RSA Product Support
      • General Security Advisories and Statements
      • Product Life Cycle
      • Support Information
      •  
      •  
      •  
      •  
      •  
  • RSA Ready
  • RSA University
    • Certification Program
      • Certification Program
    • Course Catalogs
      • Course Catalogs
      • Archer®
      • RSA NetWitness® Platform
      • RSA SecurID® Suite
    • On-Demand Subscriptions
      • On-Demand Subscriptions
      • Archer®
      • RSA NetWitness® Platform
      • RSA SecurID® Suite
    • Product Training
      • Product Training
      • Archer®
      • RSA® Fraud & Risk Intelligence Suite
      • RSA® Identity Governance & Lifecycle
      • RSA NetWitness® Platform
      • RSA SecurID® Access
    • Student Resources
      • Student Resources
      • Access On-Demand Learning
      • Access Virtual Labs
      • Contact RSA University
      • Enrollments & Transcripts
      • Frequently Asked Questions
      • Getting Started
      • Learning Modalities
      • Payments & Cancellations
      • Private Training
      • Training Center Locations
      • Training Credits
      • YouTube Channel
    • Upcoming Events
      • Upcoming Events
      • Full Calendar
      • Conferences
      • Live Classroom Training
      • Live Virtual Classroom Training
      • Webinars
Sign In Register Now
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results forĀ 
Search instead forĀ 
Did you mean:Ā 
Announcements

RSA SecurID® Access Blog

Subscribe to the official SecurID Access blog for information about new product features, industry insights, best practices, and more.
  • RSA Link
  • :
  • Products
  • :
  • RSA SecurID Suite
  • :
  • RSA SecurID Access
  • :
  • Blogs
  • :
  • Guide to Getting Started with the AM 8.x REST-API ...

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

VasanthBalakris
Employee VasanthBalakris
Employee
10 4 11.6K
  • Subscribe to RSS Feed
  • Mark as New
  • Mark as Read
  • Bookmark
  • Subscribe
  • Email to a Friend
  • Printer Friendly Page
  • Report Inappropriate Content
ā€Ž2017-07-20 06:31 PM

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:
      Windows Server 2008 R2 x64 AD Server VM-2017-07-19-16-51-01.png
      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:
    BlogPost2.png
  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:
    BlogPost3.png
  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:
    BlogPost4.PNG
    Enable the API checkbox and keep the default port unless you need to change it, click Apply Settings:
    BlogPost5.PNG
    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:
    BlogPost6.png
  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:
    BlogPost7.png

    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:BlogPost8.png
    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:BlogPost9.pngBlogPost10.png
    3. For the next 5 options just keep the default values:
      BlogPost11.png
    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:)
      BlogPost12.png
      BlogPost13.png
      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:BlogPost14.png
    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.)BlogPost15.png
    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:BlogPost16.png
    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:
    BlogPost17.pngBlogPost18.png

BlogPost19.pngBlogPost20.png

BlogPost21.png

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.
Tags (7)
  • Tags:
  • rest web service
  • RSA SecurID
  • RSA SecurID Access
  • rsasecurid
  • secuid access
  • SecurID
  • use the rest api
10 Likes
Share
4 Comments
PiersB
Respected Contributor PiersB Respected Contributor
Respected Contributor
ā€Ž2017-07-27 10:33 AM
  • Mark as Read
  • Mark as New
  • Bookmark
  • Permalink
  • Print
  • Email to a Friend
  • Report Inappropriate Content

Hi Vasanth,

Thanks for this excellent article on getting the API going. I'm going to have our user information team look at this post and see if there is additional information we should be providing in the API guide. 

 

You comments about load balancing are spot-on. Using the OpenAPI schema, there are a number of combinations of JSON parser and HTTP clients that can be used from a large number of different languages. Customers looking to use this interface should investigate the capabilities of these various HTTP clients (most of which provide interfaces to allow the programmer to control the load-balancing and fail-over behavior).

 

The other consideration is that, unlike the UDP protocol, the REST requests can be sent to the server through a network or web load-balancer. Many HTTP clients will support a server FQHN that resolves to multiple addresses and will distribute authentication requests to the address(es) returned from a DNS lookup of the server hostname. This mechanism also allows customers to control the servers to which requests are sent by updating DNS. A single "authentication service" DNS entry can be created that is configured (in DNS) to resolve to the server(s) to which requests should be sent.

 

-Piers

2 Likes
VasanthBalakris
Employee VasanthBalakris
Employee
ā€Ž2017-08-17 10:29 AM
  • Mark as Read
  • Mark as New
  • Bookmark
  • Permalink
  • Print
  • Email to a Friend
  • Report Inappropriate Content

Piers, here's a belated thank you for these insights.

0 Likes
SagarReddyBijja
SagarReddyBijja Beginner
Beginner
ā€Ž2017-11-06 06:47 PM
  • Mark as Read
  • Mark as New
  • Bookmark
  • Permalink
  • Print
  • Email to a Friend
  • Report Inappropriate Content

JKyVVWyGYRgpvEvvbTnBUZWGlbByii0866PnKLPBxxA=ā€Œ, 

 

Hi Piers, Excellent Blog! We are using cpp rest client (Since it is more suitable for our environment), And I am having trouble building the client downloaded from swagger. Life is even more difficult without a README file in the client package

Is there any similar setup guide/blog like this for a cpp rest client too? 

0 Likes
PiersB
Respected Contributor PiersB Respected Contributor
Respected Contributor
ā€Ž2017-11-14 12:07 PM
  • Mark as Read
  • Mark as New
  • Bookmark
  • Permalink
  • Print
  • Email to a Friend
  • Report Inappropriate Content

Hi Sagar,

I agree this is an excellent blog, but I did not write it. The blog was authored by 3r868LvytttmsqBAXCkO2AWdunIVhjR5pgkpqtnL7w0=. 

 

The example provided with RSA Authentication Manager has a commented-out section in the "rest-java-client" Project Object Model (pom.xml) that shows how it could be used to build a CPP rest interface as well. You should be able to use this to at least build the cpprest client.

 

For something more concrete examples, I would probably start by looking at the Swagger "Pet Store" CPP REST example. This should provide more guidance on how the generated interface should be used by your client code.

1 Like

You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.

  • Comment
Latest Articles
  • Defense-in-Depth: RSA SecurIDĀ® Access in November ...
  • Protect Stormshield VPN with RSA MFA
  • Optimize your Dynamic Workforce with RSA SecurID A...
  • Securing access to corporate endpoints is made eas...
  • New RSA SecurID Access & Authentication Manager Tr...
  • What's New for RSA SecurIDĀ® Access in June 2020
  • Cake for All! Secure & Convenient Login for The Ne...
  • macOSĀ® authentication with RSA SecurID Access
  • Where is my authentication framework? Does a free...
  • Reduce people & process overhead costs through a s...
Labels
  • Announcements 1
  • Resources 1
  • Tutorials 27
  • Use Cases 3
  • Videos 93
Powered by Khoros
  • Products
  • Resources
  • Solutions
  • RSA University
  • Support
  • RSA Labs
  • RSA Ready
  • About RSA Link
  • Terms & Conditions
  • Privacy Statement
  • Provide Feedback
© 2021 RSA Security LLC or its affiliates.
All rights reserved.