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:

NewUser

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

GetKey

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.

QRURL

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

DisplayQRCode

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

SetupGAuth

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.

PhoneScreen1

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

PhoneScreen2

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

InputCode

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

CheckCode

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.

GAuthTable

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.

CheckUser

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.

ChallengeUser

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.

FieldLevelChallenge

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.

21 thoughts on “Implementing Google Authenticator in PeopleSoft

  1. Ravi S says:

    Excellent article. We were planning to implement 2FA in our PeopleSoft instance and this article has pointed us in the right direction. Thanks

  2. Paul Van Lankvelt says:

    Hello Colton,
    Could you share this project with Lakeshore Technical College?
    Just zip it and send to me.
    We have test environment in tools 8.55.13 and would like to try this out in one.
    Thanks Paul Van Lankvelt

    • Colton Fischer says:

      Hi Paul,

      I do not mind sharing this project at all! I actually thought I provided a link to the source App Designer project in this post, but I was mistaken. I’ve created a separate post here that has a link to the app designer project with instructions on getting it up and running. I have only tested this project on 8.55.06 and 8.55.08 Tools, but it should work well (hopefully better) with the Tools that you are on. Please let me know your experiences with this project if you have a chance to play with it.

      Thanks,
      Colton

    • Colton Fischer says:

      Hi Kiran,

      This can be implemented on 8.53, but you will have to customize the delivered pre build events of the components that you want to enforce 2FA on. I suppose this is not too big of an issue if you plan on enforcing 2FA a few components, but anything more than that will create a lot of maintenance overhead. Your organization would really need to weigh the security benefits vs the overhead costs with implementing this solution. Once you get on 8.55 the overhead costs would no longer be a concern, because you will be able to leverage event mapping to implement this solution.

      If you are interested in implementing this in your 8.53 environment, then you can check out this post where I provide a code sample to get this solution working in pre-8.55 environments.

  3. Kiran says:

    Thanks Colton for the response.

    I was able to implement it but it errors because of timezone issues. My system is on PST, would you pls be able to recommend?

    Invalid Attempt. Ensure that the time on your device is in sync with the server time of: February 21, 2017 12:33 AM PST (0,0)

    • Colton Fischer says:

      I ran into this issue as well. You will need to navigate to: PeopleTools -> Utilities -> Administration-> PeopleTools Options. On this page you will need to change the “Base Time Zone” field to the correct timezone. I do not believe that this requires an app bounce, so the change should work immediately.

  4. Chris says:

    You should never use Google Authenticator – it is far too insecure – secret key revelation destroys all protection for all users – their entire TOTP concept is flawed.

    Use something modern instead.

    • Cris says:

      You didn’t understood a thing – secret key is user based not a general one…try to understand the whole before assuming or criticizing

Leave a Reply

Your email address will not be published.