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.

  • resource owner
      An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
  • resource server
      The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.
  • client
      An application making protected resource requests on behalf of the resource owner and with its authorization. The term "client" does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other  devices).
  • authorization server
      The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

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:

  • A user-agent of resource owner(typically a web browser) must be used in this flow
  • Client need to be capable of receiving the access token via redirection from authorization server.

The advantage of Authorization Code Grant includes:

  • Client has no chance to get user’s credential, the authorization is done at the authorization server side.
  • The access token isn’t exposed to Resource Owner and User-agent.