Protocol documents are not necessarily easy to digest. They are often overstuffed with information, making them dry and difficult to understand. While the IETF is a good resource on protocols, their descriptions are often too pedantic and lack a “big picture” perspective. And if you’re like me, you need that big picture perspective before wading into the details.
I’ve been unable to find that big picture on OAuth 2.0, so I decided to write my own big picture, using what little I know about screenplay writing. I thought it would be fun to see how a conversation between three people could help understand the OAuth 2.0 protocol.
So here’s the setting for this Hollywood blockbuster movie: Ivan the Investor would like to purchase investment advice from Frank the Financial Wizard. To provide good advice, Frank needs to periodically get balance information from Ivan’s bank accounts. Frank will not withdraw any money, nor does he need to see any details about Ivan’s individual transactions; he just needs to know the balances every week so he can provide his best advice. Rather than bothering Ivan every week for balance information, he would prefer to go to Ivan’s bank and get the information directly. But Barbara the Banker doesn’t simply hand out balance information to just anyone that comes along. She needs to get permission from Ivan that allows Frank to check on his bank balances.
So the conversation between these three players goes something like this:
Scene One: An initial conversation between Ivan and Frank
Ivan: Hey Frank, I’m interested in purchasing your financial advice.
Frank: Great! Let’s get started! I’ll need to get access to your bank account balances every week.
Ivan: Hmmm … You mean you need to know all my balances every week?
Ivan: Sounds like a lot of trouble for me. I mean, I hardly check on the balances myself.
Frank: Don’t worry. I can get that information directly from your bank. That way I won’t need to bother you every week, unless there’s something important going on.
Ivan: You mean anyone can just get my balances from my bank anytime they want?
Frank: No way! That would violate about two dozen privacy laws. I just need you to get permission from your bank on my behalf. They know who I am. Just give them my business card. (Holds out a business card for Ivan)
Ivan: (Taking business card and examining it) Cool business card! What are all these funny numbers on the back?
Frank: (Pointing at the numbers) This is a special code that you need to present to the bank. It confirms my identity. Like I said, they already know me, and this special code confirms that you are asking them on my behalf.
Ivan: Okay, I’ll go to the bank. Then what happens?
Frank: Well, they’ll first look at my business card and then test the code on the back. Then they’ll ask you a question or two, and then give you some information to bring back to me. Then I’ll be able to get your balances.
Ivan: Okay. I’ll be back.
Scene Two: Ivan meets Barbara at the bank
Ivan: Hello Barbara. Frank the Financial Wizard sent me to see you. He needs to check on my account balances every week.
Barbara: Hello Ivan. Did Frank give you a special code?
Ivan: (Handing Frank’s business card to Barbara) Yes. It’s here, on the back of his business card.
Barbara: (Examining the card and the special code) Well, this is Frank’s business card all right. Let me run a check on the special code just to be sure. (Barbara pulls up a computer keyboard and enters Frank’s code. A few moments later, the computer beeps.) Okay. This looks legit.
Ivan: Great! Now what?
Barbara: I need to see your ID just to be sure you really are Ivan.
Ivan: (Shows his driver’s license to Barbara) Here you go.
Barbara: (Examines the license and is satisfied that Ivan is indeed who he says he is) Okay Ivan. I just have to formally ask one question.
Barbara: Am I to understand that you are granting Frank limited access to your accounts? More specifically, he will just have access to the balances and nothing more.
Ivan: Sounds good to me.
Barbara: Okay then. (Takes a business card from her desk and writes a special password on the back) Take this business card to Frank. He’ll know what to do with it.
Ivan: (Examining the card) Ah … more funny numbers on this card.
Barbara: Yes, it’s a special password that gives Frank permission to request a temporary password that will allow him to access your account for an hour at a time.
Ivan: Wait a minute. He said he needs access to the account every week. A one-hour password won’t do him any good.
Barbara: Not a problem. Whenever Frank needs access to your bank balances, he uses the password on this card to request another temporary password. Every time he does this, he’ll get a password that’s good for an hour. If he needs another hour, he just requests another temporary password.
Ivan: That’s crazy. Why don’t you just give him access for an unlimited time using the password on the back of this card? Why make him request temporary passwords?
Barbara: (Pauses and thinks for a time) Well, that might work, but the problem is that there are other people in Frank’s office that will probably access your account on his behalf during that hour. Frank doesn’t want all his employees to have unlimited access, so he just requests temporary passwords and lets his people use it for an hour.
Ivan: Ah … I see. (Points to the password on the back of Barbara’s business card) So Frank keeps this original password in his safe so that nobody can use it indefinitely, and then just issues the temporary passwords to his employees so they can get the job done.
Barbara: Precisely. You are trusting Frank, but you can’t necessarily trust anyone he hands out this password to.
Ivan: Got it. Cool idea. But what happens if Frank loses this card? How do I know some burglar won’t break into his safe and take the card?
Barbara: Good question. But it’s really no problem. When Frank requests a temporary password, he has to login to the system with his own private password. So even if a burglar gets the password on the back of my business card, it won’t do him any good because only Frank can unlock it with his own password and then use it to get a temporary password.
Ivan: Wow! You guys have thought of everything!
Scene Three: Ivan meets with Frank again
Ivan: Hello Frank!
Frank: Hey Ivan! Did you get a password from the bank?
Ivan: Sure did! I learned a lot about your protocol as well. (Hands Barbara’s business card to Frank.)
Frank: Yes indeed. It’s called OAuth 2.0. It works well. (Examines the card and notes the password on the back.) Just stand by a minute while I log into my account at the bank and verify that I received the proper password.
Ivan: Not a problem. I understand that only you can log in and use that password to get access to my account.
Frank: Indeed. (Taps on his computer keyboard for a time, then looks up) It works! I now have a one-hour temporary password that gives me balances on your bank accounts.
Frank: We can now do business together. But remember this: if you should decide to stop doing business with me, you need to tell Barbara, and she will disable the password she provided on the back of her business card.
Ivan: So then you’ll no longer be able to keep getting temporary passwords to my account.
So there you have it! The OAuth 2.0 protocol as told by our characters Ivan, Frank and Barbara. Now that you have the big picture, you’re ready to wade into the protocol documents and understand the details.