Forem: Micah Silverman

Easy Single Sign-On with Spring Boot and OAuth 2.0

Micah Silverman — Thu, 02 May 2019 05:00:00 +0000

Single sign-on used to be the “Holy Grail” of enterprise size companies and was usually only available to companies that could afford it. Nowadays, we take SSO as a matter of course. For instance, you would think it's completely weird (and unpleasant) if you logged into Gmail and then had to log in again when you went to Google Docs.

But, what about building custom applications for developers? SSO was still in the domain of the enterprise with everything from proprietary solutions to SAML, which usually required complex configuration of on-premises solutions.

Now, with standards like OAuth 2.0 and OpenID Connect and service providers, like Okta, it’s a snap for developers to incorporate SSO into their apps, whether it’s a hobby project or an enterprise grade application.

In this post, I’ll introduce OpenID Connect - the key enabling technology for delegated authentication and SSO - and then jump into a code example with Spring Boot where you can see SSO in action across multiple applications.

Approaches to Single Sign-On with OAuth 2.0 and OpenID Connect

With OIDC, SSO is often accomplished by linking multiple applications through a single defined OpenID Connect application:

In the diagram above, you can see that you achieve SSO because you authenticate with Client App 1 via OIDC App 1 and Client App 2 is connected to the same OIDC App 1 application.

Let’s call this “Level 1” SSO.

“Level 2” is being able to connect multiple client applications to multiple OIDC applications and still accomplish SSO. Here’s what this looks like:

A successful interaction with OpenID Connect results in an ID Token (identity token) being passed back to the application.

In this case, you may have different requirements for the information included in the ID Token that comes back between OIDC App 1 and OIDC App 2. Each Spring Boot application gets its own ID Token and yet you only have to authenticate once.

Set Up Your App for Next Level Single Sign-On with OAuth and OpenID Connect

Head on over to developer.okta.com to create yourself a free-forever developer account. Look for the email to complete the initialization of your Okta org.

You’ll set up two OpenID Connect applications next.

Navigate to Applications in the admin console and click: Add Application. Choose Web and click Next.

Populate the fields with these values:

Field Name	Value
Name	OIDC App 1
Base URIs	http://localhost:8080
Login redirect URIs	http://localhost:8080/login/oauth2/code/okta

Click Done.

Scroll down and copy the Client ID and Client Secret. You’ll use those values shortly.

Create a second app in the same way with these values:

Field Name	Value
Name	OIDC App 2
Base URIs	http://localhost:8081
Login redirect URIs	http://localhost:8081/login/oauth2/code/okta

Copy the Client ID and Client Secret values here as well.

Next, you’ll set up some Authorization Servers with custom claims and access policies. This drives whether or not Okta will issue a token when one is requested.

Navigate to API > Authorization Servers. Click Add Authorization Server. Fill in the values according to this table:

Field Name	Value
Name	OIDC App 1
Audience	api://oidcapp1
Description	OIDC App 1

Click Done. Click the Claims tab. Click Add Claim. Fill in the fields with these values (leave those not mentioned as their defaults):

Field Name	Value
Name	appName
Include in token type	ID Token Always
Value	“OIDC App 1”

Note the double quotes (“) in the “OIDC App 1”.

Click the Access Policies tab. Click Add Policy. Enter: OIDC App 1, for the Name and Description fields. For the Assign to field, choose The following clients. Start typing: OIDC in the input area and click Add to the right of OIDC App 1. Click Create Policy. This binds the policy to your first OIDC app.

Click Add Rule. Enter: OIDC App 1 for the Name field. Deselect all the grant types except for Authorization Code. Click Create Rule. This ensures that the request must be the Authorization Code flow in order for Okta to create tokens (More on the Authorization Code Flow below).

Click the Settings tab and copy the Issuer URL. You’ll make use of this value shortly.

You’re now going to repeat everything for a second Authorization Server, only this time, it will be bound to your second OIDC App.

Navigate to API > Authorization Servers. Click Add Authorization Server. Fill in the values according to this table:

Field Name	Value
Name	OIDC App 2
Audience	api://oidcapp2
Description	OIDC App 2

Click Done. Click the Claims tab. Click Add Claim. Fill in the fields with these values (leave those not mentioned as their defaults):

Field Name	Value
Name	appName
Include in token type	ID Token Always
Value	“OIDC App 2”

Note the double quotes (“) in the “OIDC App 2”.

Click the Access Policies tab. Click Add Policy. Enter: OIDC App 2, for the Name and Description fields. For the Assign to field, choose The following clients. Start typing: OIDC in the input area and click Add to the right of OIDC App 2. Click Create Policy. This binds the policy to your second OIDC app.

Click Add Rule. Enter: OIDC App 2 for the Name field. Deselect all the grant types except for Authorization Code. Click Create Rule. This ensures that the request must be the Authorization Code flow in order for Okta to create tokens.

Click the Settings tab and copy the Issuer URL.

Use Spring Boot’s OAuth integration for Single Sign-On

Now that you have all the configuration in place, you can see “next level” single sign-on in action.

The github project includes a shell script to launch the app. This works on Mac and Linux. If you’re on another platform, simply examine the last line of the script to launch the application. Open up two terminal windows. Execute the following in the first:

./run_app.sh \
    --ci <client id, oidc app 1> \
    --cs <client secret, oidc app 1> \
    --is <issuer, oidc app 1> \
    --po 8080

Execute the following in the second terminal window:

./run_app.sh \
    --ci <client id, oidc app 2> \
    --cs <client secret, oidc app 2> \
    --is <issuer, oidc app 2> \
    --po 8081

Launch your browser and navigate to http://localhost:8080. You’ll immediately be redirected to authenticate. After you enter your username and password, you should see your name and the app’s name: OIDC App 1. If you don’t see the app name, then it’s likely you didn’t configure the custom claim correctly. You’ll also see the raw ID Token in JSON Web Token format. You can copy and paste the JWT to jsonwebtoken.io and see its contents, which includes the appName claim.

Open a second tab in your browser and navigate to http://localhost:8081.

You should NOT be required to authenticate again and you should see your name, the app’s name: OIDC App 2, and another JWT.

This is Single Sign-On in action. And, you’re using two separate spring boot apps, connecting to two different Authorization Servers, bound to two different OIDC apps. That’s next level SSO!

Spring Security with OAuth for Easy Java

It’s Okta’s cloud service for OIDC (which rides on top of OAuth) and SSO that makes this all work. Okta’s Spring Boot Starter combined with the latest version of Spring Security makes the code super simple.

There’s only three dependencies in the whole project: spring-boot-starter-web, spring-boot-starter-thymeleaf and okta-spring-boot-starter.

spring-boot-starter-web gives the application a Model-View-Controller framework. spring-boot-starter-thymeleaf is a templating engine that integrates with Spring and is the View part of the MVC framework. okta-spring-boot-starter brings in Spring Security, so you don’t have to define it as another dependency.

With the Okta Spring Boot Starter, you only need three bits of information to integrate with Okta: client id, client secret and issuer.

Spring Security requires authentication by default, so there’s no additional configuration needed in this example.

Take a look at the HomeController:

 @GetMapping("/")
 public ModelAndView home(@AuthenticationPrincipal OidcUser user) {
     ModelAndView mav = new ModelAndView();
     mav.addObject("user", user.getUserInfo());
     mav.addObject("idToken", user.getIdToken().getTokenValue());
     mav.setViewName("home");
     return mav;
 }

By the time this method is entered, Spring Security has already managed authentication via the Authorization Code flow. an OidcUser object is automatically passed into the method, which represents all of the parsed claims from the ID Token as well as the ID Token JWT itself. The user info and raw JWT are retrieved from the OidcUser and added to the model. The method then renders the view: home.html.

Take a look at the heart of home.html:

 <div th:if="${user.claims.containsKey('appName')}"
     class="alert alert-success text-center" role="alert"
 >
     <h2 th:text="${user.claims.appName}"></h2>
 </div>
 <p/>
 <div th:if="${user.claims.containsKey('name')}"
     class="alert alert-primary text-center" role="alert"
 >
     <h3 th:inline="text">Welcome [[${user.claims.name}]]!</h3>
 </div>
 <div class="alert alert-secondary text-center">
     <p th:inline="text" class="text-break" style="overflow-wrap: anywhere">
         [[${idToken}]]
     </p>
 </div>

The th:if in the first div is Thymeleaf templating to guard against you not having set the appName custom claim correctly. Assuming it exists, appName is rendered using user.claims.appName from the model that was passed into this view.

The second div shows the user’s name.

The third div shows the raw JWT that was added to the model in the controller above.

A Five-Minute Overview of OpenID Connect

With a new perspective on single sign-on and a working Spring Boot app under our belts, let’s dig into OIDC a little deeper.

OpenID Connect is an identity and authentication layer that rides on top of OAuth 2.0. In addition to “knowing” who you are, you can use OIDC for Single Sign-On. It’s especially easy with Spring Boot and Okta.

OIDC is built for web applications as well as native and mobile apps. It’s a modern approach to authentication that we developed by Microsoft, Google and others. It supports delegated authentication. This means that I can provide my credentials to my authentication provider of choice (like Okta) and then my custom application (like a Spring Boot app) gets an assertion in the form of an ID Token to prove that I successfully authenticated. The Spring Boot app never sees the username and password. This is a great approach for modern apps where you want to separate concerns, such as authentication, from the business logic of the application.

As a developer, I know that I need authentication. But, I’ve seen enough horror stories from breaches over the years that I am happy to not handle credentials directly.

OpenID Connect uses “flows” to accomplish delegated authentication. This is simply the steps taken to get from an unauthenticated state in the application to an authenticated state.

Let’s walk through a sequence diagram of what an OIDC flow looks like:

This flow is called the Authorization Code Flow and is the most secure flow for end users. It’s the one you’ve been using in the code example that goes along with this post. The goal of the flow is to get tokens over to the Spring Boot app as proof of identity.

You kick off the flow from the application in your browser. It sends a request to the Authorization Server (Okta) which includes a redirect_uri value. This is so that after you’ve authenticated, Okta can send you back to the right spot in your application with an Authorization Code.

The Spring Boot app can now exchange the Authorization Code for tokens from Okta.

Why this dance? Your Spring Boot app never sees the credentials. Notice on step 5, the credentials are submitted directly to Okta. The Authorization code is redirected back through the browser (where the request was initiated). But, we don’t want the browser to get the tokens directly. It’s safer for the application under your control - the Spring Boot application - to get the tokens from Okta. That’s why it’s the Spring Boot application that exchanges the code for the tokens.

To learn more about OAuth 2.0 and OIDC, check out these blog posts

Learn More About Secure Single Sign-on, OAuth 2.0, and Spring Boot

The Okta Spring Boot Starter enables you to integrate your Spring Boot apps with Okta with just a few lines of code and three configuration properties.

Along with our Spring Boot Starter, Okta’s OpenID Connect service not only conforms to the standard, but gives you a sophisticated Single Sign-On experience where the same user can access many different OIDC applications, each with their own set of requirements and configuration. Remember: OIDC rides on top of OAuth 2.0 - it’s not standalone. Whereas OAuth focuses exclusively on authorization, OIDC explicitly adds identity and authentication concerns.

If you’d like to learn more about OAuth and Spring Boot you might be interested in these other posts:

Like what you learned today? Follow us on Twitter, and subscribe to our YouTube channel for more awesome content!

Build a One-time Password Token for MFA with Okta

Micah Silverman — Thu, 30 Aug 2018 05:00:00 +0000

Okta has a great multi-factor authentication (MFA) service that you can use right away with a free developer account. It provides additional security by requiring a second factor after authentication and supports a variety of factor types including SMS, soft tokens like Google Authenticator, hard tokens like Yubikey and the Okta Verify soft token with push notification.

Google Authenticator and Okta Verify are a type of factor called time-based one-time password (TOTP) tokens. They use an algorithm based on a shared secret and a system clock with a high degree of precision. Okta adds an additional level of convenience without sacrificing security by supporting push notifications in the Okta Verify mobile app.

Okta Verify uses a QR Code to read in the shared secret when enrolling in MFA.

In this post, I use the shared secret in a less-convenient but fun way, while still keeping the same level of security. The ArduBoy project combines an Arduino microprocessor with a monochrome OLED screen and a set of buttons that look suspiciously like a classic Nintendo GameBoy. All this fits into a credit card size form-factor. This open-source programming platform makes for the perfect vehicle to use the TOTP standard to create a hardware and software based hybrid token for MFA.

Well, maybe not perfect. But, fun!

The biggest challenge is that when you turn off an ArduBoy, it’s really off. There’s no realtime clock that continues to run when the ArduBoy is off. We take this for granted on our computers or mobile devices that either have hardware to keep the clock running, have the ability to automatically set the time over a network on boot or both. Not so with the ArduBoy! In order to really use this as your go-to TOTP device, you need to keep it on and charge it before it dies.

What the application does to mitigate this is use the onboard EEPROM (Electrically Erasable Programmable Read-Only Memory) to (a) save the secret and (b) save the last date and time set. The next time you turn on the ArduBoy, it checks to see if a secret has been set. If so, it goes directly to setting the date and time. On the date and time setting screen, it starts with the last set date and time to make it easier to update.

This is a fun way to learn a little about TOTP and see it working against a real Okta organization.

In “real life”, you’ll want to use the Okta Verify mobile app (available on iOS and Android). There’s a lot less manual labor involved.

Get Up and Running with an Okta Verify Token

The source code (including a pre-built binary) can be found on the GitHub repository.

If you have an ArduBoy and want to see the app running, you can install the latest binary .hex file directly.

You can also drop the .hex file right onto the ProjectABE ArduBoy emulator site to see it in action without having an actual ArduBoy yourself.

NOTE: ProjectABE does not have the ability to save data to the EEPROM. So, if you restart the application there, you’ll need to re-set both the shared secret and the date and time.

The easiest way to install OktaArduToken onto an actual ArduBoy is to use the Arduino IDE. This allows you to both edit and upload the source as well as providing the command line tool, avrdude, to upload binaries.

Here’s an example install command using avrdude on Mac:

/Applications/Arduino.app/Contents/Java/hardware/tools/avr/bin/avrdude -v \
-C /Applications/Arduino.app/Contents/Java/hardware/tools/avr/etc/avrdude.conf \
-p atmega32u4 \
-c avr109 \
-P /dev/cu.usbmodem1411 \
-U flash:w:<path to OktaArduToken project>/OktaArduToken.hex

NOTE: The -p parameter specifies the ArduBoy part number and the -c parameter specifies the ArduBoy programmer type. The -P parameter will be different on your Mac. You can see the list of available serial ports by using this command:

ls -la /dev/cu.*

You’re looking for the entry that contains usbmodem in it.

Working with Source Code and Dependencies

If you want to work with the source code in the Arduino IDE, compile it, and upload it to your ArduBoy, you’ll need to install a few libraries. For each of these, navigate to: Sketch -> Include Library -> Manage Libraries.

You’ll need:

Arduboy2 - An alternative library for the Arduboy miniature game system
swRTC - A software real-time clock
TOTP-Arduino - Library to generate time-based one-time Passwords
Base32 - a library to encode strings into and decode strings from Base32

The Base32 library is the only one that you can’t install via the library manager in Arduino IDE. It’s easy enough to install by cloning the GitHub repository to your local Arduino IDE libraries folder. On Mac, it looks like this:

cd ~/Documents/Arduino/libraries/
git clone https://github.com/NetRat/Base32.git

If all your libraries are in place, you can navigate to: File -> Open... in the Arduino IDE and choose the OktaArduToken.ino file. You should then be able to navigate to: Sketch -> Verify/Compile to compile the code. If you get any errors, make sure that all the above libraries are installed.

Navigating around the OktaArduToken Interface

OktaArduToken is unique among TOTP examples for Arduino or ArduBoy in that it has an interface to set the shared secret and to set the date and time. Most examples require you to hardcode the secret into the source code before uploading.

With a total of 6 buttons, the interface to set the shared secret and the date and time may remind you of a ’90s era flip phone. ;)

Set the Shared Secret

When you first launch that app, you’ll see the shared secret setting screen:

Okta Verify uses a 16-byte Base32 encoded string for the shared secret. Initially, this is shown as 16 Ms. You can use the up and down buttons to navigate around the set of capital letters and the numbers from 0 - 9. You can use the left and right buttons to move positions within the available 16 characters.

The interface automatically wraps. That is, hitting the right button when you’re on the 16th character moves the cursor back to the 1st character. Hitting the left button when you’re on the 1st character moves the cursor to the 16th character. Likewise, hitting the up button when 9 is showing, will change that character to A. Hitting the down arrow when A is showing, will change that character to 9 (it goes A-Z and then 0-9).

When the shared secret is set, press the A button to move on to the date and time setting screen.

NOTE: See below for how to configure Okta for MFA and obtain the shared secret to program in.

Set the Date and Time

Once you’ve saved the shared secret, you’ll see the date and time setting screen:

You can use the up and down arrows to change the numbers for each part of the date and time. You can use the right and left buttons to change positions on the date and time interface. The interface will automatically skip over separators and will automatically wrap around in a similar way to the shared secret interface.

Once the date and time are set, press the A button to move on to the TOTP screen.

NOTE: Precision is important, so it is recommended that you set the time ahead by 10 seconds, watch a clock with a seconds counter and hit the A button the moment at which the times match. Also, the date and time that you set should always be GMT regardless of your current time zone. Also, There is currently NO error checking of any kind. That is, if you put in an invalid date and/or time, you will get unexpected results.

You can press the B button to return to the shared secret screen from here.

The TOTP Display

Once the shared secret and date and time are set, you see the TOTP screen. At the top of the screen, in a large font, you see the current passcode. This passcode changes every 30 seconds. Below the passcode, you see the full date and time which updates every second.

Press the A button to return to the set date and time screen. Press the B button to return to the set shared secret screen.

Configure Okta for Multi-factor Authentication

In Okta, there are two complimentary pieces to MFA: enrollment and enforcement. An MFA enrollment policy drives the conditions under which a user will be required to enroll in MFA and what configured factors they must enroll in. A Signon Policy can be configured to require a second factor after authentication. That’s the MFA enforcement part of the policy.

To get started, signup for a free Okta Developer org at https://developer.okta.com/signup/

Setup an Okta group and a new user to make testing the MFA policies easier.

Log into the admin console of your Okta org. Switch from the Developer Console to the Classic UI by selecting the dropdown in the upper left:

Next, choose: Directory > Groups from the top menu of the admin console. Click Add Group and enter mfaers for the Name field. Click Add Group.

Choose: Directory > People from the top menu of the admin console. Click Add Person and fill in the fields as follows:

field	value
First name	Jane
Last name	Doe
Username	jane.doe@mfaers.com
primary email	jane.doe@mfaers.com
Groups	mfaers
Password	Set by admin
User must change password on first login	(unchecked)

Enter a password of your choice. Click Save.

Configure an MFA Enrollment Policy

Select Security > Multifactor from the top menu of the admin console.

On the Factor Types tab, select Active next to Okta Verify.

Select the Factor Enrollment tab. Click Add Multifactor Policy , enter mfaers policy for Policy name and choose mfaers for Assign to groups. Select required from the dropdown next to Okta Verify. Click Create Policy.

In the Add Rule dialog, enter mfaers rule for Rule name and select the first time a user signs in in the dropdown next to Enroll in multi-factor. Click Create Rule.

That’s all that’s needed to configure MFA enrollment!

Configure an MFA Enforcement Policy

Select Security > Authentication from the top menu of the admin console. Click Sign On > Add New Okta Sign-on Policy.

Enter mfaers policy in Policy Name and choose mfaers in Assign to Groups.

Click Create Policy and Add Rule.

Enter mfaers rule for Rule Name and check Prompt for Factor. Select Every Time > Create Rule.

That’s all that’s needed to configure MFA enforcement.

Authenticate with Okta and the OktaArduToken

In a private browsing window, navigate to your okta org and login as jane.doe@mfaers.com.

You should see a screen to setup Okta Verify. Click Configure factor.

On the next screen select any device type (it doesn’t matter since we’ll be setting up our ArduBoy anyway). Click Next.

On the Setup Okta Verify screen, click Can’t scan?

You’ll then see the Secret Key Field. Turn on your ArduBoy (or use ProjectABE) and enter the shared secret value.

On the Arduboy, press the A button and enter in the correct date and time (GMT timezone). Press the A button. This will bring you to the TOTP screen.

Click Next on the Setup Okta Verify dialog. Enter in the code displayed on the ArduBoy and click Next.

If all goes well, you’ll see a screen asking for you to set a security question and answer to finish configuring your account.

You’ve now completed enrollment in Okta Verify using an ArduBoy as a hardware token! Pretty cool stuff.

You could logout and login again and you will be prompted to put in a code again which you would get from the ArduBoy.

NOTE: The clock component in ProjectABE is not very accurate and will get behind or ahead very quickly. You can always press the A button to set the time once again so that the passcode shown is correct.

You can also program in the value in the actual Okta Verify app on your mobile device and confirm that the passcode shown is the same as the passcode on the ArduBoy.

Here’s the OktaArduToken side-by-side with the Okta Verify mobile app:

A look at the TOTP Arduino Code

The code for OktaArduToken is in a single sketch file: OktaArduToken.ino. I am sure this is not best practice and would benefit from some C++ objectification, but it works for a quick little hobby project.

It all boils down to three lines of code in the ShowTotpCode() method, thanks to the TOTP and swRTC libraries:

TOTP totp = TOTP(hmacKey, 10);
long GMT = rtc.getTimestamp();
totpCode = totp.getCode(GMT);

It uses the hmacKey, which is the Base32 decoded value of the shared secret along with the current timestamp to compute the current totpCode. It is this 6-digit code that is displayed on the ArduBoy screen.

The other key enabling feature is the ability to write the shared secret and current time to EEPROM and to read those values back out.

void writeTotpInfo(TotpInfo totpInfo) {
  writeString(TOTP_SECRET_SAVE_ADDRESS, totpInfo.secret);
  writeInt(TOTP_SEC_SAVE_ADDRESS, totpInfo.sec);
  writeInt(TOTP_MIN_SAVE_ADDRESS, totpInfo.minu);
  writeInt(TOTP_HOUR_SAVE_ADDRESS, totpInfo.hour);
  writeInt(TOTP_DAY_SAVE_ADDRESS, totpInfo.day);
  writeInt(TOTP_MON_SAVE_ADDRESS, totpInfo.mon);
  writeInt(TOTP_YEAR_SAVE_ADDRESS, totpInfo.year);
  DEBUG_PRINTLN("Wrote totpInfo to eeprom.");
}

TotpInfo readTotpInfo() {
  TotpInfo ret = {};

  ret.secret = readString(TOTP_SECRET_SAVE_ADDRESS, 16);
  ret.sec = readInt(TOTP_SEC_SAVE_ADDRESS);
  ret.minu = readInt(TOTP_MIN_SAVE_ADDRESS);
  ret.hour = readInt(TOTP_HOUR_SAVE_ADDRESS);
  ret.day = readInt(TOTP_DAY_SAVE_ADDRESS);
  ret.mon = readInt(TOTP_MON_SAVE_ADDRESS);
  ret.year = readInt(TOTP_YEAR_SAVE_ADDRESS);

  return ret;
}

There’s a bunch of supporting methods to handle the input interfaces for the shared secret and date and time as well as displaying things in the right spot on the display.

Being a bit of a n00b to Arduino program, I am sure this code could be improved on. I <3 pull requests!

Learn More About Okta Verify and Multi-factor Authentication

I hope you enjoyed seeing how authentication with MFA using Okta Verify works along with alternate token devices. The requirements for creating your own token are a programmable microprocessor with a clock and a display

If you’d like to learn more about MFA with Okta, check out these posts:

Finally, please follow us on Twitter to find more great resources like this, request other topics for us to write about, and follow along with our new open source libraries and projects!

P.S. : If you liked this project and want to see the source code in one place, please go checkout and star its GitHub repository.

And… If you have any questions, please leave a comment below!