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:
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:
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:
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.
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:
AuthorizationCodeGrant
ImplicitGrant
ResourceOwnerPasswordCredentialsGrant
ClientCredentialsGrant
RefreshTokenGrant
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=SplxlOBeZQQYbYS6WxSbIA
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 GiHub user.
The above example only shows one endpoint, which is token endpoint. There are more endpoints in OAuth 2.0. For example: