Important things you need to know about OAuth
OAuth is something every developer must know about. If you are making a standalone application or a third-party application that integrates with some other HTTP service, you need to know how OAuth works to provide your users an easy-to-use and well-integrated service.
The idea is to allow client applications a limited access to user information without ever sharing user credentials or password. OAuth framework is responsible for the exchanges that are required before an application gets your information.
Suppose you want to sign up for Dev.to (which is a great place for developers to exchange ideas) they let you sign up using your GitHub account. How does that happen? How would they know you own the GitHub account, that you are signing up with?
More importantly, how do you ensure that Dev.to is not overstepping its boundaries when it comes to the your information stored with GitHub?
We will stick to the example of Atom editor’s GitHub plugin which allows developers to push code to GitHub directly using the Atom interface. The reason for this as an example is because GitHub doesn’t hide away the details behind the scene and you get to see what’s going under the hood.
Before we get into the minutiae of OAuth’s working. Let’s set the stage by recognizing all the participants in the exchange:
- Resource Owner or User: This user is the one whose account information needs to be accessed (read and/or write) in order to make it work with an application.
- Client: This is the application that is seeking your permission to access your information from a different service. In our example, Atom editor is the client.
- Resource: Resource is your actual information sitting in the servers in some remote location. This can be accessed via an API if the client is granted appropriate permissions.
- Authorization Server: Also interfaced with via an API. This server is maintained by the service provider (GitHub in our example). Both the authorization server and the resource server are referred to as the API because they are managed by one entity, in this case GitHub, and exposed as an API to the client developer.
The process starts when the Client application is being developed. You can go to the resource provider and sign up with their developer’s portal or the API section of the website. You will also have to provide a callback URL where the user would be redirected after accepting or rejecting to give the app necessary permissions.
For example, if you go to GitHub→ Settings → Developer Settings and click on “Register a New Application”. This would provide you with a Client ID which can be made public and a Client Secret which, the developer organization must keep…well a secret.
After the Client ID and secret are provided to you, the developer, you must keep them safe and secure as they won’t be shown by the Authorization server again. The same goes for any other tokens that would be tossed around (More on tokens later).
OAuth 2 Workflow
You have registered your application. It has been developed and tested and now the users are ready to use it. A new user when registering with your service would be shown the option of “Sign in with GitHub”. This is the first step.
Step 1: Authorization request
The authorization request is the part where a new window (or a similar prompt) opens up with the resource webpage and asks users to login. If you are already logged in,on that device, then this step is skipped and you are simply asked by GitHub if you want to give access to Atom client app. This is much more transparent in case of Atom because they ask you to manually go to GitHub website and grant them the permission.
On visiting the URL, you are asked for the permission.
Notice the URL which shows this is a secure (HTTPS) webpage by GitHub.Inc. Now you, the user, can be certain that you are directly interacting with GitHub. Atom is simply waiting, quite out-of-the-way.
Unlike Atom, most client apps automatically load up the login or permissions page. While this is very convenient it can also be misused, if the client app decides to open up a phishing link. To avoid this, you must always check the URL to which you are redirected to, and make sure that it is correct URL and is using the HTTPS protocol.
Step 2: Getting the Authorization Grant
To notify the Atom client, you are given a token (an authorization grant) which is then submitted to the Atom client.
Once the user does this, the user’s job is done. (In fact, a typical user is not even aware about the exchange of authorization grant. GitHub’s example was chosen to show that this is what happens).
Step 3: Getting the access token
The authorization grant is still not the entity that gives the client access to user information. That is obtained by using something called an access token. Which the client app will try to get in this step.
To do this, the client will now have to provide the authorization grant to the authorization server along with a proof of its own identity. The identity is verified using the Client ID and Client secret that were given to the client app earlier.
The identity verification is done to ensure that the user is not tricked into using a nefarious app which is pretending to be a legit app. For example, if someone decides to name their executable as Atom with the same name, logo and functionality user might get tricked into giving access to a client which can misuse your information. They can snoop or even act without your consent. The authorization server ensures that the client is indeed what it appears to its users.
Once the identity is verified and the authorization grant is accepted, the authorization server throws a token to the client app. Think of the token as a combination of both username and password which can be given to the resource server to access a particular protected resource that the resource owner permitted you to access.
Finally, using this token the app can now gain access to the required user information and other resources from the resource server.
Notice, how in this entire exchange the actual username and password where never shared with the client? That’s the beauty of OAuth. Instead of giving username and passwords which would grant the app all the access to the resource, it uses tokens instead. And a token can gain only a limited access to the resource.
Suppose you lose access to your device which had the authorized client app in it. You can log in to GitHub and go to Settings → Applications → Authorized OAuth Apps to revoke the authorization grant and access token. I will be doing the same, since, in the above screenshots the Authorization grant was publically shown.
Now that you have a bird-eye view of how OAuth 2.You can read more about the authorization grants and other finer details of the protocol and how the API calls are made over here.