OAuth for Dummies

If you've ever accessed a website using your Facebook or Google credentials, then you've encountered OAuth. OAuth is a authorisation web protocol for granting websites access to some of your personal information or access rights to some system. The analogy usually given is that of a valet key, which makes no sense to me, as I own a rusty VW Beetle, but let's not worry about that.

If you're building such a website, you'll want to register it with the OAuth provider (Google or whatever). They will give you an application id and secret. This secret allows you to speak OAuth to the provider.

So, much later, Joe Bloggs comes along and wants to access your website. Your website sends a request to the OAuth provider (with your application id and secret) and gets given a conversation token.

Then, you redirect the user to the OAuth provider (but include the conversation token and a callback URL, which will have been included when you registered your app). The OAuth checks the conversation token and URL, and then works out who the user is (e.g. asking you to log in) and then presents a consent screen: "Do you want to allow application X to access your Y?" You check out the Y list and say OK (or not). The OAuth provider then sends an HTTP post via the browser back to your website, with two tokens:

• an access token (the valet key), which allows you to ask the OAuth provider for Y things
• a refresh token (for when the access token expires, which will be frequently)

Hang on a minute! What about these Y things? How does the OAuth provider know what the website wants rights for?

OAuth calls that "scopes". A scope is a name of a user "thing" that you're allowed access to. It could be a user name, email, or a set of access rights. When the website does OAuth, it adds a some scopes to the OAuth request, and if they are in the permitted list, they get presented to the user.

And that is basically it. There are some other nuances and stuff, but my car's broken down again and I need to run.