1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
.. meta::
:description: Understand the concepts in OAuth 2.0, the authorization flow,
grant types, roles, authentication methods and etc.
:image: https://user-images.githubusercontent.com/290496/48670041-e5803e00-eb53-11e8-91a9-3776276d6bf6.png
.. _intro_oauth2:
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`_:
.. _very simple OAuth 2.0 flow: https://user-images.githubusercontent.com/290496/48670041-e5803e00-eb53-11e8-91a9-3776276d6bf6.png
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
-----------
.. module:: authlib.oauth2.rfc6749.grants
:noindex:
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:
- :class:`AuthorizationCodeGrant`
- :class:`ImplicitGrant`
- :class:`ResourceOwnerPasswordCredentialsGrant`
- :class:`ClientCredentialsGrant`
- :class:`RefreshTokenGrant`
- :class:`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:
.. code-block:: http
:emphasize-lines: 3,6
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_auth_methods:
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
.. code-block:: http
:emphasize-lines: 6
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
.. code-block:: http
:emphasize-lines: 6
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
.. code-block:: http
:emphasize-lines: 3
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 :ref:`jwt_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:
- :ref:`Token Revocation Endpoint <specs/rfc7009>`
- :ref:`Dynamic Client Registration Endpoint <specs/rfc7591>`
- :ref:`Token Introspection Endpoint <specs/rfc7662>`
|
