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 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.
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:
Your application (client) prompts the user to log in.
The user clicks the login button, your application will redirect to GitHub’s authorize page (Authorization Server).
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.
The Authorization Server issues an access token to your application. (This step can contain several sub-steps)
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:
JWTBearerGrant
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=SplxlOBeZQQYbYS6WxSbIAClient 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.
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:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4