If you work in the web or mobile industry and have ever had to integrate with an API, there’s a decent chance you’ve heard of OAuth2. Google, Facebook, Github, Jira and a whole lot of people use it as a way to secure and limit third-party access to user data. I’ve heard it described as complicated. The base standard clocks in at 76 pages, and has about a dozen connected standards. OpenID Connect, which is not an IETF standard, slaps another dozen new standards on top of OAuth2’s. Calling it “light reading” would be a hilarious euphemism.
In order to make OAuth2 easier to understand for neophytes, I’ve had a weird but (I think) appropriate idea: Why not write a play? Plays are fun, right? “To be or not to be” hugely disappointed by how this turns out, “that is the question” that I’m about to answer.
Glenda Tables, a mother. She designs IoT janitorial space robots.
In our play, Glenda is what OAuth2 refers to as a “Resource Owner”. The things in the fridge are usually hers (in software parlance, those things are usually data, entities, stuff you want to control access to).
Steve Tables, stay at home android father and failed musician He is definitely not a deadbeat.
Steve is going to be our Authorization Server. Glenda trusts him to gate the access to the fridge while she’s away.
Robert Tables aka “Little Bobby Tables”, their 10-year-old son. He asks for things a lot.
In our play, Robert will be an OAuth2 “client”. Put simply, he negotiates access to the fridge with mom & dad.
ACT I: Client Password Grant
We’re in the kitchen of the Tables family. There is a fridge, and it is locked by a complicated-looking electronic device. Steve is seated in a lazy-boy, with a crude cardboard VR set taped to his face. Robert is sitting at the table.
ROBERT: Hey, dad, I want to eat the sandwich that I made for myself yesterday. Would you mind giving me an access token to the fridge?
STEVE: Bleep bloop. If you really are ROBERT TABLES, you’ll rephrase your request to provide me with your client_id and client_secret. Bloop bleep!
ROBERT, throwing his hands in the air as he stands up abruptly: UUUGH, so annoying! You’re my dad for crying out loud. My client_id is “0x31337” and my client_secret is “I have arachnophobia” and I would like an access token for the fridge to eat my sandwich.
STEVE: Bleep bloop, bloop. Hello, SON, congratulations for SUCCESSFUL_IDENTIFICATION Here is your ACCESS_TOKEN so that you can EAT_A_SANDWICH. Bleep!
Robert proceeds to gather the token from his father and insert it in the fridge’s device. Only a small compartment is unlocked, the one containing only Robert’s stuff. He grabs his half-eaten sandwich and goes back to the table to eat it.
What was that?
In a client credentials grant, the client (Robert) asks the Authorization Server (Steve) for an access token to a resource (the sandwich in the fridge) that is ultimately owned by Robert, and so, access is granted.
ACT II: Authorization Code Grant
Robert is still at the table and Steve still doing God-knows-what with the VR stuff. Glenda enters. Glenda is shuffling papers around inside her attache-case. She is pulling some out and putting some new ones in, apparently in a hurry.
ROBERT: Hey mom, could I have one of your juice cans to go with my sandwich? My fridge access token only gave me access to my sandwich.
GLENDA: UGH, that system is so, SO annoying. I am never buying a smart fridge again. Steve, give him some juice. Robert’s client_id is “0x31337”.
STEVE: Bleep. Hi, honey, if that’s really who you are! Please provide me with your username and password. Bloop bleep!
GLENDA: Seriously? Three times today - ugh. Username is “honey1983” and password is “ILoveChrisHemsworth”.
STEVE: I really wish you changed that password. It’s hurtful. Hand this Authentication Code to Bobby. Sad bleep.
Steve passes a small cube to Glenda who in turn passes it to Robert.
GLENDA: Okay, I’m gonna be late. Be nice!
Glenda exits in a storm of shuffling papers. Robert goes to his father with the small cube.
ROBERT: Here, dad. Here’s the code. My client_id is “0x31337”. Gimme another token please.
STEVE, as he eats the cube: Bleep. Sure, son, here you go. Bloop.
Robert takes a new token and goes to the fridge. This time only Glenda’s juice compartment opens. Robert grabs the juice and goes back to the table.
What was that?
In the Authorization Code Grant, the third-party client (Robert) has to ask the resource owner (Glenda) for access. Assuming Glenda is okay with this, she’ll be redirected to the authorization server to confirm her identity. I cheated a bit. Technically Robert doesn’t necessarily know that he’s asking for juice from his mom. Whether or not the third-party client knows who the resource owner is isn’t part of the spec.
Once that authorization step is done, the authorization server redirects the resource owner back to the client with a special code that the client will use to get an access token. Steve handing Robert that access token enables Little Bobby Tables to access his mom’s juice stash, but nothing else (that’s kind of the whole point).
ACT III: Resource Owner Password Grant (a.k.a. Robert is Hungry, Part Two:, Robert is STILL Hungry)
ROBERT: Ah, shoot. I forgot to ask mom if I could have the leftover fried chicken. Hey dad, any chance of getting a token for that chicken?
STEVE: Bleep! Look, sir, sorry. I’m not even sure if you’re my son, mostly on account of you not giving me anything to identify you with. Bloop. Also, that chicken is your mom’s, so unless you have a token for the chicken, no dice. The fridge won’t budge.
Robert goes to the fridge and tries his old juice token. Sure enough, the juice compartment pops open, but he can’t get the fried chicken door to move an inch.
Robert calls Glenda from the family’s rotary phone.
GLENDA: Who dis?
ROBERT: It’s me, I’m trying to get to the fried chicken but dad is not being helpful.
GLENDA: UUUUUUUGH. Okay you know what? Just grab my username and password. I’m in a meeting and I’ve got no time for this now. Username is “honey1983”, password is “ILoveChrisHemsworth”.
ROBERT: MOM, EWW. Also, it’s really insecure to hand me those outright.
GLENDA: I know, but I’m not driving back for fried chicken and whatever else you decide you need to eat in five minutes. Love you, I’ll be back for dinner.
Robert hangs up the receiver and turns to Steve, a menacing grin on his face.
ROBERT: My client_id is “0x31337”, my client_secret is “I have arachnophobia”, mom’s username is “honey1983”, her password is “ILoveChrisHemsworth” and I would like an access token for all of her things in the fridge.
STEVE, pulls up his VR goggles, incredulous: Are you sure? That’s a whole lot of stuff. I’m not sure she really meant to give you access to all of this.
ROBERT: Well, she wouldn’t have handed me her username and password otherwise, now, would she? Token, please!
Steve complies, an expression of fear in his face. As Robert heads towards the fridge, thunder can be heard. A storm brews. Robert inserts his token in the fridge. All of Glenda’s compartments clack open loudly. Robert starts laughing like an evil genius. He grabs the soda, the fried chicken, pie and ice cream, then proceeds back to the table with his haul. The curtain falls to Robert laughing as he gorges himself on his loot. The sound of the n storm rages outside.
Okay that last one was weird
Yeah. Essentially, this flow gives a third party access to a user’s credentials. Unless you’re absolutely mega-certain that it’s okay it is almost certainly not okay. Please avoid this flow.
THERE IS NO ACT 4
I’m missing the implicit grant here, but it’s essentially the same thing as authorization code flow except the token ends up in the hands of the end-user. To be fair, both the Implicit Grant and the Resource Owner Password Grant are considered legacy and are not recommended for implementation anymore.
This is by no means an exhaustive explanation of how OAuth2 works; there are already copious amounts of tutorials out there and the standards are there for you to read if you really want to know how it works. The goal here was to make the actors and the flows a bit easier to understand through a humorous format.
A parting note: I’ve found that people who encounter problems understanding OAuth2 usually get confused about the “roles” part, sometimes coalescing a few roles together. Understanding which role is supposed to do what and have access to which things is key to implementing OAuth2 correctly. Needless to say, it is critical to implement OAuth2 correctly should you decide to implement it at all. Godspeed.