Introduce OAuth 2.0

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

This section will help developers understand the concepts in OAuth 2.0, but not in deep of OAuth 2.0. Here is an overview of a very simple OAuth 2.0 flow:

OAuth 2.0 Flow

OAuth 2.0 Roles

There are usually four roles in an OAuth 2.0 flow. Let’s take GitHub as an example, you are building an application to analyze one’s code on GitHub:

  • Client: a client is a third-party application, in this case, it is your application.

  • Resource Owner: the users and orgs on GitHub are the resource owners, since they own their source code (resources).

  • Resource Server: The API servers of GitHub. Your client will make requests to the resource server to fetch source code. The server serves resources.

  • Authorization Server: The server for client to obtain an access token.

OAuth 2.0 Flow

The above image is a simplified version of an OAuth 2.0 authorization. Let’s take GitHub as an example. A user wants to use your application to analyze his/her source code on GitHub.

It usually takes these steps:

  1. Your application (client) prompts the user to log in.

  2. The user clicks the login button, your application will redirect to GitHub’s authorize page (Authorization Server).

  3. The user (he/she is a GitHub user, which means he/she is a Resource Owner) clicks the allow button to tell GitHub that he/she granted the access.

  4. The Authorization Server issues an access token to your application. (This step can contain several sub-steps)

  5. Your application uses the access token to fetch source code from GitHub’s Resource Server, analyze the source code and return the result to your application user.

But there are more details inside the flow. The most important thing in OAuth 2.0 is the authorization. A client obtains an access token from the authorization server with the grant of the resource owner.

Grant Types

Authorization server MAY supports several grant types during the authorization, step 1 and 2. A grant type defines a way of how the authorization server will verify the request and issue the token.

There are lots of built-in grant types in Authlib, including:

Take authorization_code as an example, in step 2, when the resource owner granted the access, Authorization Server will return a code to the client. The client can use this code to exchange an access token:

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

Client Authentication Methods

In the above code, there is an Authorization header; it contains the information of the client. A client MUST provide its client information to obtain an access token. There are several ways to provide this data, for instance:

  • none: The client is a public client which means it has no client_secret

    POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&client_id=s6BhdRkqt3

  • client_secret_post: The client uses the HTTP POST parameters

    POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&client_id=s6BhdRkqt3&client_secret=gX1fBat3bV

  • client_secret_basic: The client uses HTTP Basic Authorization

    POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

There are more client authentication methods defined by OAuth 2.0 extensions, including client_secret_jwt, private_key_jwt. They can be found in section Using JWTs for Client Authentication.

Token Scopes

Scope is a very important concept in OAuth 2.0. An access token is usually issued with limited scopes.

For instance, your “source code analyzer” application MAY only have access to the public repositories of a GitHub user.

Endpoints

The above example only shows one endpoint, which is token endpoint. There are more endpoints in OAuth 2.0. For example: