Implementing Google Authenticator in PeopleSoft

I previously demonstrated how I use Google Authenticator to protect sensitive resources in my PeopleSoft applications.  I would like to share the code involved to get this to work.  If you are unfamiliar with what Google Authenticator is and how it works, then I suggest reading about it here.  A while back, I read a nice article that demonstrated a simple Java implementation of the Time-based One-time Password (TOTP) algorithm (specified in RFC 6238) that is used with Google Authenticator. After making slight modifications to the code, I was able to easily integrate this Java implementation in my PeopleSoft application. I packaged the code up into a JAR file that I will explain how to use in this post. UPDATE:  I recently discovered that there are some other mobile applications that implement the same TOTP algorithm as Google Authenticator. Some examples of these applications are Duo, Authy, and even Oracle Mobile Authenticator.  This means that any of these other TOTP-generating applications can be used with the solution that I am demonstrating in this tutorial.

CLICK HERE to download the JAR file

The downloaded JAR file will need to be placed on to the PeopleSoft app server.  Specifically, the JAR file needs to reside in the class directory of the your PS_HOME.  The JAR file path should look like this:

%PS_HOME%\class\psGAuth.jar

An app server bounce and cache clear needs to be performed after adding the JAR file to the app server.

I will first discuss the defined Java methods that will be invoked from the PeopleCode.

• GetKey()

This method returns a random, 32 character, base 32 encoded string.  This is the secret key that will be shared between the PeopleSoft application and the client’s Google Authenticator application.  This method will be invoked for users that have net yet set up the Google Authenticator application.

• CheckCode (string SecretKey, integer Code, integer Timestamp)

This method is used to check if a given TOTP is valid for a particular user at a particular time. The SecretKey parameter is the shared secret key that was produced from the GetKey method during the user’s initial Google Authenticator setup.  The Code parameter is the TOTP (six digit number) generated by the user’s Google Authenticator application.  The Timestamp parameter is the PeopleSoft application’s Unix timestamp divided by 30.  This method will return a Boolean value that will signify if the user inputted TOTP is a valid one.

Now I will give a technical demonstration of how you can use the two-step verification process in your PeopleSoft applications.

The PeopleCode that will need to be written first is the code that is capable of creating a new Google Authenticator account in the system for a given user.  I put the code behind a push button on a setup page:

The code behind the button will call the GetKey method to create the shared secret key.

Once you obtain the secret key, you will need to generate a QR code so that the user can easily import the account information into their Google Authenticator app.  You do not necessarily have to create a QR code, it just makes it easier on the user from not having to manually type in the secret key into the app.  I make use of the Google Charts API to generate the QR code.

Once I have the URL to the QR code, I display it in an html area.

This QR code is displayed in a setup page for the user.

At this point, the user can open up their Google Authenticator app and scan the QR code (or manually input the account information) to add their new account.

After scanning the QR code, the application will start generating TOTPs immediately.

Now the user can input the generated TOTP into the prompt to ensure that their application is working correctly.

The code behind the “OK” button will call the CheckCode method to determine if the inputted code is correct.

If the CheckCode method returns true, then the user’s account information will be stored into the database.  In this demonstration, I am storing the User ID and the secret key value in the clear.  It would be a good idea to store the secret key in an encrypted state.

Now that you see how a new user gets set up with Google Authenticator, I would like to show you how you can present the two-step verification challenge in your application.  When a user attempts to access a resource that you would like to protect with two-step verification, you will need to ensure that you have a secret key stored in the database for the user.

If there is no secret key in the database for the user, then you will need to prompt the user to set up Google Authenticator as shown above.  Otherwise, you will need to prompt the user to input the current TOTP value that their Google Authenticator app has generated.

The code behind the “OK” button is similar to the code above except the SecretKey parameter of the CheckCode method will be pulled from the database rather than being obtained from the GetKey method since the user already has an account setup.

If the user inputs the correct TOTP into the prompt, then you should redirect the user to the protected resource that they were originally trying to access.  You might want to consider storing a session cookie (or create a session variable) that will signify that the user has performed two-step verification for the session.  Tracking if the users have already performed two-step verification for the session will allow you to provide your users with a better experience by not making them perform two-step verification more than once a session.

Some important things to note:

Ensure that the time on your server is correct and that the client’s time is in sync with your server.   There is room for about a minute difference in time, but anything more than that will cause the TOTPs to fail.

---

The two-step verification process with Google Authenticator can be enforced anywhere you want in your PeopleSoft application.  One use case would be to do two-step verification at the login page.  You can simply add an additional field for the TOTP on the login page and validate the inputted value in the sign on PeopleCode.  While this may cause a negative impact on the user experience, there is nothing stopping you from doing this from a technical perspective.  Another use case would be to do the two-step verification at the component-level in PeopleSoft with event mapping as I did in this video demonstration.

Future Plan #1:

I am currently polishing up (with plans of releasing) a solution to enforce the Google Authenticator challenge at the field-level in PeopleSoft.  This involved writing code on the web server to mask sensitive values and wrap the values in a clickable link. I previously demoed a (rough) version of this functionality in this post, but below is screenshot of what I am referring to.

Clicking the lock icon will invoke a modal prompt to ask for a Google Authenticator TOTP.  If the user inputs a correct TOTP, then the sensitive value will be revealed.  I believe that enforcing the two-step verification in this manner is the most desirable way with respect to providing a good user experience.  However, implementing this particular solution is very challenging from a technical perspective.  Read this post to learn how to achieve this type of field-level data masking solution.

Future Plan #2:

I am currently looking into leveraging the PeopleSoft Pluggable Encryption Technology (PET) to implement the TOTP algorithm natively within PeopleCode.  This way I will not have to rely on the Java code on the app server.

 

If you have any questions, remarks, or problems with using Google Authenticator in your PeopleSoft applications, then feel free to leave me a comment and I will be more than glad to help you out.