OAuth 2.0 Explained by Visiting Grandma

After my last post, I realized that it might be kind of hard to understand if you didn’t already have a basic understanding of authentication online.  To that end, I came up with a different way to try to explain how OAuth 2.0 works, by using my Grandmother as an example.

Lets say I am going on a trip to visit Grandma, when I get to her house I would like to have access to it so that I can see her and talk with her a while, but I don’t have a key!  In order for me to get into Grandma’s house I need to ask for permission, this is where OAuth2 comes in.

In this case I ring the doorbell and wait for Grandma to ask “Who is it?”  I respond, “Your Grandson Christopher” to which she replies “I’m coming!”  This is similar to the way that OAuth2 works, when I (The application) try to access data (Grandma’s house) I first have to ask permission from the user (Grandma).  Here Grandma acknowledges that she will let me in and lets me know that she is on the way just like the OAuth2 sever returning me a code.  The application can use this code to complete activation.

When Grandma gets to the door she can tell it is me by looking through the peep-hole in the door.  In OAuth2, this is where I would send my secret key and the code the server gave me to the server so that it can verify who I am.  In Grandma’s case all she has to do is look out the window or door!

Once Grandma has confirmed my identity she lets me into the house just like in OAuth2, once the server has confirmed who I am it passes me a bearer token which I (the application) can use to access secured items on behalf of the user.

If you want to learn more about OAuth, I listed several resources in my previous post which details more of the technical side of how OAuth2 works.

OAuth2 and ArcGIS Online

For a while now ArcGIS Online has had the ability to allow a user to login, and create a Map, publish data, etc.  And of course there were APIs that allowed us developers to get access to that data created by the users.  However, there was a big problem: The app couldn’t access the data without the user logging in, and to do that the app basically had to ask for the user’s username and password, which is a big no-no in the security world, and a level of responsibility that you probably don’t want if you were the developer.

Around March of this year Esri released an update to AGOL that for the first time provided a new way to authenticate users, OAuth 2.0.  And to make things even better, they didn’t just make up some new protocol  they used an industry standard and accepted process for authenticating users.  If you have already done OAuth 2.0 in the past, you can probably stop readying here and jump over to developers.arcgis.com and check out the walk-throughs and examples that Esri provides.  If not then here we go!

In a nut shell OAuth 2.0 is a standards based authentication system that provides reasonable protection, yet is simple and easy to implement correctly and allows developers to authenticate users without ever knowing that user’s password.

OAuth 2.0 is all about the workflow!  And it looks something like this:

1. The Client or Application offers the user an option to login via AGOL.  This option is in the form of a link or button that directs the user to a web page hosted by AGOL.  Here the user has the option to login this providing the application access to his/her data. During the “redirect” to the AGOL login page the application identifies itself via a special ID, this allows AGOL to let the user know what application is requesting the login.
2. Once the client logs in, AGOL sends the user back to the application, and provides that application with a special code.  This code is an agreement between the server and the application to allow the application to complete the login process, however the code itself does not allow access to any secured data.
3. The application makes a POST request to AGOL that specifies the code, the application id and the application secret.  This secret is known only by the application and AGOL, not the user.  AGOL can then verify that these three pieces of information all match, if they do…
4. AGOL returns a bearer token to the application.  This bearer token provides access to data via any AGOL API call that accepts a “token.”
5. The application can now use the token from the server to request secured resources
6. The server uses the token to validate the user and apply any permissions to requested resources, and returns either an error condition stating the user does not have access, or the data back to the application.

And authentication is complete!  The client can now use the bearer token to requested secured services, as seen in parts E and F above.  It is a little bit complicated at first, but there is plenty of code out there to help get you started.

There are variations on OAuth 2.0 that I did not cover here in this post, if you would like more information check out these links for more info:

• The OAuth 2.0 Specification
• Esri’s Documentation on OAuth 2.0 (and example code!)
• Google’s Documentation on OAuth 2.0 (This is where I learned originally)