Understanding OAuth2… with Horses!
If you’re integrating your software with a web service these days, chances are you have to use OAuth2 to authorize it. Here’s a little story about a horse which will (hopefully) help you understand the OAuth2 flow a little better.
Video transcript & code
Once upon a time there was beautiful chestnut stallion named Reese. Reese’s owner Ona loved him very much, but she lived in the city and didn’t have land on which to keep a horse. So Reese the Horse, or “Reese Horse” as Ona often called him, lived at a boarding stable in the countryside.
The name of the stable was the Circle Vertex Ranch, but most people who boarded horses there called it CirVer for short. Circle Vertex staff knew that the animals entrusted to them were precious to their owners. Everyone at CirVer prided themselves in not only their level of care, but also in their security practices.
One day Ona realized it was time for Reese Horse’s yearly dental checkup. So she called up Reese’s vet, Dr. Arthur Client, to schedule a visit. When Ona told Dr. Client where Reese was boarded, he said: “Ah yes, I have a several regular patients at CirVer! They already know who I am there, but as you probably know their security protocols are very particular. I’ll need you to get explicit authorization from them for me to visit Reese Horse.”
So Ona called the Circle Vertex Ranch, and asked them to authorize Client to visit Reese Horse. The stable administrator said she’d be happy to do so, but first she needed to verify that it was really Ona calling. After asking her some security questions, he said: “OK Ona, I’m placing an authorization grant on file for Dr. Client to have access to Reese the Horse. Please tell him to reference grant #1357 when he visits.”
So Ona called Dr. Client back, and told him about the grant file number. The next day, Dr. Client drove up to CirVer and checked in at the desk. He showed his identification, and presented the authorization number he received from Ona. The person working the desk looked up the grant, and said “Yep, that checks out. Here’s a key to Reese’s stall. By the way, you can keep that key for a full year, so you won’t have to check in with us every time.”
Dr. Client took the key, headed off to the barn, and a few minutes later he was examining Reese’s teeth. Later that day he cheerfully reported a perfect bill of health back to Ona. The End.
Oh right, this video was supposed to be about Oauth2.
Oauth2 is a broadly-adopted standard to enable users of online applications to grant other applications the right to access their stuff.
For instance, let’s say you use a cloud file storage application to hold photos of your beloved horse. In Oauth2 terms, the photos are resources, the file storage service is a resource server, and you are the resource owner.
Now let’s say you want to have physical prints made of one of your photos. You visit a third-party printing service website, create an account, and enable the cloud storage integration.
In Oauth2 terms, the printing service is called a client. This might be a little bit confusing, if you’re used to thinking of the word client in reference to a human user or their web browser. But for the purposes of Oauth2, the client is the third-party service that wants access to your stuff on a resource server.
When you ask the printing app to integrate with the file service, it redirects your browser to the file service’s authorization endpoint. This is similar to how Dr. Client redirected Ona to the boarding stable in order to get an authorization for him to see her horse.
The authorization endpoint verifies that you have an account, and asks you if you want to grant authorization to the photo printing service. When you confirm, it redirects your browser back to the the photo printing app. It attaches an authorization grant code as a query parameter in the redirect. This is like when Ona gave the boarding stable’s grant code to Dr. Client.
Now here’s the tricky bit about Oauth2. The grant code is not enough for the printing service to access your photos. A grant code is a short-lived representation of your agreement to give the client access to your stuff. It’s usually only valid for a period of minutes, just long enough to be exchanged for a longer-lived access token. That’s the key to Reese’s stall, in our horse story.
In order to get this token, the client must make an HTTP POST request to the file storage service’s token endpoint. Technically, it must make this post to the storage service’s authorization server. You can think of the authorization server as the “front desk” staff who gave Dr. Client a key.
In practice, the resource server and the authorization server are often the same thing, at least as far as clients are concerned. But within the file-storage service, these concerns may be separated.
The client supplies client credentials and the authorization grant code, and in return the authorization server gives it an access token. This is like when Dr. Client exchanged an authorization grant number for a key to Reese the Horse’s stall.
Once the printing service has an access token (which is just a string), it provides that token in every API request it makes to the file storage service on your behalf. So long as the token has not expired or been revoked, the file storage service will honor those requests.
This is the most common Oauth2 authorization workflow for integrating web applications. It’s a little convoluted, but once you understand it, you’ll be prepared to authorize your apps to access user resources on everything from social media, to file storage, to collaboration software. Happy hacking!