Explained OAuth 2 by Example - Part I

OAuth 2 Introduction

Authorization system is a very fundamental component for most websites or applications, we must login first before we can access the resources we own. I believe you still remember about 10 years ago, you need to create your account for every website, you have a Google account, a Yahoo account, and a MySpace account. What is changed right now, obviously, you can login many websites with your Google account or Facebook account, you don’t need to create new account any more. The hero behind is OAuth 2, a protocol enable third-party application obtain limited access to an HTTP service.

As a web developer, we may often meet OAuth 2. For example, the most familiar case is that you want to integrate your website to other famous platforms, to enable your users can use your service without registration. Or more complicated, you are building a social network, and you want other developers to create third-party applications for you, so you must implement a OAuth 2 service within your open platform. Of course, besides the examples described above, there are many different adoptions of OAuth 2. In this article, I plan to list several usual scenarios by an example.

Imagine I was developing a project in the past year. The project is very simple, to clone Twitter. Ok, it’s not simple. The project name is GuaJi. GuaJi is a micro-blogging platform, users can post messages and read the messages of their followers. So we must create the account system at first to enable users to register and login. Two days later, I finished the account system, I’m a productive programmer, two days more, I can implement all the features of GuaJi.

Login with GuaJi

Actually, I spent one week to finish all the features. After GuaJi was running for a month, there were tens of users using my service. One day, a user emailed to me, he said my service is very great, he intended to use GuaJi’s account to login into his website. Ok, I didn’t want to disappoint him, I started to build my authorization server to support OAuth 2. It was not hard to me, I replied him five days later, and said GuaJi supported OAuth 2 now, you can go ahead to create your client and integrate to your websites. You will get a client_id and secret after you create a new client, the two keys are used in the OAuth 2 authorization.

Several days later, I saw the service usage report, some users used GuaJi to sign in. Awesome, GuaJi became a open platform. I think it’s best to explain more for the login with GuaJi. Here is the flow.

  1. The resource owner(user) visit http://guaji.com/oauth2/authorize?response_type=code&client_id=s6BhdRkqt3&redirect_uri=http://guaji.com/callback via a browser.
  2. User-agent(browser) send this request to authorization server.
  3. Authorization server response an authorization code to browser, by redirecting to specified redirect_uri with the code.
  4. Browser visit the redirect_uri, then pass the authorization code to client, the client here is a web server of third-party application.
  5. Client send a POST request to authorization server with url http://guaji.com/oauth2/token?grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=http://guaji.com/callback to get access token.
  6. Client get the access token from authorization server.
  7. Client use access token returned to obtain the resource in resource server.


According to the diagram and steps above, we can see there are four roles participated, I list all of them here, and the definitions are from RFC6749.

Authorization Code Grant

The example above described one flow of OAuth 2 - Authorization Code Grant, which is the commonest use case. Because this is a redirection-based flow, so there are two requirements:

The advantage of Authorization Code Grant includes: