Part 3: Let’s Play on the OAuth 2.0 Playground!

This is part three of a tutorial blog series from Ben Finkel addressing the challenges, solutions, and implementation of sound authentication. By the end of this series, you will be confident in your ability to implement an authentication system — even with little-to-no background.

It's tough to wrap your head around the OAuth flow. There are URI calls and redirects, as well as three different tokens. A visual guide could be really helpful.

Google to the rescue. Let's use the OAuth 2.0 Playground app in your browser to walk through the OAuth 2.0 process. The app can be found at:  https://developers.google.com/oauthplayground/.

You'll see why I'm such a fan in just a moment, but first, let's establish our context.

For this exercise, the Provider will be Google, specifically the Google Calendar API. This means that you'll need a Google account. Use an existing account or sign up. It'll help to put a calendar item up for today's date so we have something to look up.

The Consumer (or Relying Party) will be OAuth 2.0 Playground. This is an app that Google created specifically to demonstrate the OAuth 2.0 process.

Finally, we will be the User>

1. Launch the Playground at the above URL and scroll down the list of APIs on the left-hand side, selecting "Calendar API" like you see in the screen shot above.

2. The two options listed below the Calendar API, which look like URLs, are actually the possible Scopes that we can choose from. That full string, http and all, will be passed into our Authentication request.

3. Note the other APIs that Google offers (there are a lot). Feel free to choose a different one from the Calendar API and see how they work. It's a playground after all, so play!

4. Select "https://www.googleapis.com/auth/calendar.readonly" and click "Authorize APIs."

a. If you have multiple Google accounts saved on this browser, you'll have to choose one here. b. If you're not already signed into the account, you'll have to enter your username and password. This is the Authentication process. c. If you only have one account and you're already signed in, then you'll jump to the next step.

5. Check it out!  This is the confirmation page for the OAuth 2.0 Playground. Let's break it down:

a. This is the name of the Consumer as registered with the Provider. Recall that every consumer has to get a Consumer Key from the Provider before this process can proceed. That way the Provider can inform the User about which App is trying to access their Resources. b. Here Google provides a short description of the Scope requested, while clicking the icon on the right will provide further details. We can use this to decide if we want to continue or not.

c. Finally, we have the option to Allow or Deny this request. Either choice will return control back to the Consumer application. Go ahead and try clicking Deny first, see how the OAuth Playground responds, and then re-attempt the Authorization and click Allow to continue.

6. We are returned to the OAuth Playground and we've got a code! You can see the code on the left-hand side of the page, called the "Authorization Code."  The string itself is meaningless gobbledygook, but the Provider will recognize it on the next step, and that's all that matters.

What I love about the Playground are the details on the right. There you can see the initial HTTP request that was sent along with the querystring parameters. For instance notice that "scope=https…" matches the scope we chose earlier. I realize it looks like a URL, and I don't know why Google chose to format their Scopes that way, but it's really just a string indicating the permissions being requested. You can also see the client_id and redirect_uri in the request.

Below that is the redirection that the Provider performed after we allowed access. It's very simply a GET call with the Authorization code in the querystring. You can see this matches the URL in the address bar of your browser.

7. We can now click the "Exchange" button and turn this code in for our two tokens, the Access and Refresh tokens. Go ahead and do that but take note, the Playground will automatically collapse the "Step 2" section and expand "Step 3." I'd recommend re-expanding Step 2 and taking a look at the new information there.

You now have an Access and Refresh token filled in, and a timer counting down the time until that access token expires. You can always manually refresh it by clicking the "Refresh access token" button. Go ahead and try that.

Again, on the right you have your HTTP Request and Response details. The Post at the top went to the token url ("/oauth2/v3/token") and passed the Authorization Code in the body of the message.

The response below came back with a JSON object in its payload, and you can see the two tokens and expiration timer in that object.

8. You can now use the interface to make API-specific calls. How to use a particular provider's API is outside the scope of this tutorial, but click "List Possible Operations" and check out what you can perform with the Calendar API. To see items on a Calendar, first call the "List CalendarList" method, find the ID value in the JSON response, and then call the "List Events" method pasting that ID over the {calendarId} token in the Request URI.

Hopefully, this helps make the OAuth 2.0 flow clear. I know it helped me immensely the first time I worked with this. You should feel free to play with the Playground as much as you'd like. Before I sign off though, let's take a quick look at how we can Revoke the access we just granted.

1. Browse to https://myaccount.google.com/intro/security. If you have multiple accounts, make sure you're signed in with the correct account. Just click your account icon in the upper right to choose.

2. Select "Connected app & sites" on the left-hand navigation pane, or scroll down the main page to reach that section. Click "Manage Apps."

3. You'll see a list of all Consumer Apps you've granted access to your Google account, along with what Scope they were granted. You will probably recognize most of these apps, but you might be surprised at what you see there. On that list you should find an entry for "Google OAuth 2.0 Playground," indicating that it has access to Google Calendar.

4. If you expand that entry you can see more details about the access you granted, and a big blue "Revoke" button appears. Clicking that button will revoke the access and effectively expire all of the codes and tokens immediately.

Every OAuth provider has some mechanism for performing this same process, although the details of how you do it will vary from Provider to Provider. It's good to understand that Users can always revoke access because we'll want to write our Consumer app to degrade gracefully at every step if it finds it has been denied access.

In our next installment we'll create a basic (free) Google App Engine application and start our Authentication framework.

You can read the full tutorial series in these weekly installments:

Part 1: Authentication for the Modern Web

Part 2: Delegating Authentication

Part 3: Let's Play on the OAuth 2.0 Playground

Part 4: Let's Start Running Code

Part 5: Authorization Grant, Our First OAuth Dance Steps

Part 6: Authorization Request, An OAuth "State" of Mind

Part 7: Authorization Grant, Final OAuth Dance Steps 

Part 8: Expanding Our Service with GitHub

Part 9: OAuth 2.0: Authorization, Not Authentication

The series will conclude in April 2016.