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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
============================
OAuth 2: Creating a Provider
============================
Note that OAuth 2 provider is still very much a work in progress, consider it a
preview of a near future =)
**1. Which framework are you using?**
OAuthLib is a dependency free library that may be used with any web
framework. That said, there are framework specific helper decorator classes
to make your life easier. The one we will be using in this example is for
Django. For others, and information on how to create one, check out
:doc:`decorators`.
The main purpose of these decoraters is to help marshall between the
framework specific request object and framework agnostic url, headers, body
and http method parameters. They may also be useful for making sure common
best security practices are followed.
Their purpose is not to be a full solution to all your needs as a provider,
for that you will want to seek out framework specific extensions building
upon OAuthLib. See the section on :doc:`decorators` for a list of
extensions.
Relevant sections include:
.. toctree::
:maxdepth: 1
decorators
**2. Create your datastore models**
These models will represent various OAuth specific concepts. There are a few
important links between them that the security of OAuth is based on. Below
is a suggestion for models and why you need certain properties. There is
also example Django model fields which should be straightforward to
translate to other ORMs such as SQLAlchemy and the Appengine Datastore.
**User (or Resource Owner)**
The user of your site which resources might be access by clients upon
authorization from the user. In our example we will re-use the User
model provided in django.contrib.auth.models. How the user authenticates
is orthogonal from OAuth and may be any way you prefer::
from django.contrib.auth.models import User
**Client (or Consumer)**
The client interested in accessing protected resources.
**Client Identifier**:
Required. The identifier the client will use during the OAuth
workflow. Structure is up to you and may be a simple UUID::
client_id = django.db.models.CharField(max_length=100, unique=True)
**User**:
Recommended. It is common practice to link each client with one of
your existing users. Whether you do associate clients and users or
not, ensure you are able to protect yourself against malicious
clients::
user = django.db.models.ForeignKey(User)
**Grant Type**:
Required. The grant type the client may utilize. This should only be
one per client as each grant type has different security properties
and it is best to keep them separate to avoid mistakes::
# max_length and choices depend on which grants you support
grant_type = django.db.models.CharField(max_length=18,
choices=[('authorization_code', 'Authorization code')])
**Response Type**:
Required, if using a grant type with an associated response type
(eg. Authorization Code Grant) or using a grant which only utilizes
response types (eg. Implicit Grant)::
# max_length and choices depend on which response types you support
response_type = django.db.models.CharField(max_length=4,
choices=[('code', 'Authorization code')])
**Scopes**:
Required. The list of scopes the client may request access to. If
you allow multiple types of grants this will vary related to their
different security properties. For example, the Implicit Grant might
only allow read-only scopes but the Authorization Grant also allow
writes::
# You could represent it either as a list of keys or by serializing
# the scopes into a string.
scopes = django.db.models.TextField()
# You might also want to mark a certain set of scopes as default
# scopes in case the client does not specify any in the authorization
default_scopes = django.db.models.TextField()
**Redirect URIs**:
These are the absolute URIs that a client may use to redirect to after
authorization. You should never allow a client to redirect to a URI
that has not previously been registered::
# You could represent the URIs either as a list of keys or by
# serializing them into a string.
redirect_uris = django.db.models.TextField()
# You might also want to mark a certain URI as default in case the
# client does not specify any in the authorization
default_redirect_uri = django.db.models.TextField()
**Bearer Token (OAuth 2 Standard Token)**
The most common type of OAuth 2 token. Through the documentation this
will be considered an object with several properties, such as token type
and expiration date, and distinct from the access token it contains.
Think of OAuth 2 tokens as containers and access tokens and refresh
tokens as text.
**Client**:
Association with the client to whom the token was given::
client = django.db.models.ForeignKey(Client)
**User**:
Association with the user to which protected resources this token
grants access::
user = django.db.models.ForeignKey(User)
**Scopes**:
Scopes to which the token is bound. Attempt to access protected
resources outside these scopes will be denied::
# You could represent it either as a list of keys or by serializing
# the scopes into a string.
scopes = django.db.models.TextField()
**Access Token**:
An unguessable unique string of characters::
access_token = django.db.models.CharField(max_length=100, unique=True)
**Refresh Token**:
An unguessable unique string of characters. This token is only
supplied to confidential clients. For example the Authorization Code
Grant or the Resource Owner Password Credentials Grant::
refresh_token = django.db.models.CharField(max_length=100, unique=True)
**Expiration time**:
Exact time of expiration. Commonly this is one hour after creation::
expires_at = django.db.models.DateTimeField()
**Authorization Code**
This is specific to the Authorization Code grant and represent the
temporary credential granted to the client upon successful
authorization. It will later be exchanged for an access token, when that
is done it should cease to exist. It should have a limited life time,
less than ten minutes. This model is similar to the Bearer Token as it
mainly acts a temporary storage of properties to later be transferred to
the token.
**Client**:
Association with the client to whom the token was given::
client = django.db.models.ForeignKey(Client)
**User**:
Association with the user to which protected resources this token
grants access::
user = django.db.models.ForeignKey(User)
**Scopes**:
Scopes to which the token is bound. Attempt to access protected
resources outside these scopes will be denied::
# You could represent it either as a list of keys or by serializing
# the scopes into a string.
scopes = django.db.models.TextField()
**Authorization Code**:
An unguessable unique string of characters::
code = django.db.models.CharField(max_length=100, unique=True)
**Expiration time**:
Exact time of expiration. Commonly this is under ten minutes after
creation::
expires_at = django.db.models.DateTimeField()
**3. Implement a validator**
The majority of the work involved in implementing an OAuth 2 provider
relates to mapping various validation and persistence methods to a storage
backend. The not very accurately named interface you will need to implement
is called a :doc:`RequestValidator <validator>` (name suggestions welcome).
An example of a very basic implementation of the validate_client_id method
can be seen below::
from oauthlib.oauth2 import RequestValidator
# From the previous section on models
from my_models import Client
class MyRequestValidator(RequestValidator):
def validate_client_id(self, client_id, request):
try:
Client.objects.get(client_id=client_id)
return True
except Client.DoesNotExist:
return False
The full API you will need to implement is available in the
:doc:`RequestValidator <validator>` section. You might not need to implement
all methods depending on which grant types you wish to support. A skeleton
validator listing the methods required for the WebApplicationServer is
available in the `examples`_ folder on GitHub.
.. _`examples`: https://github.com/idan/oauthlib/blob/master/examples/skeleton_oauth2_web_application_server.py
Relevant sections include:
.. toctree::
:maxdepth: 1
validator
security
**4. Create your composite endpoint**
Each of the endpoints can function independently from each other, however
for this example it is easier to consider them as one unit. An example of a
pre-configured all-in-one Authorization Code Grant endpoint is given below::
# From the previous section on validators
from my_validator import MyRequestValidator
from oauthlib.oauth2 import WebApplicationServer
from oauthlib.oauth2.ext.django import OAuth2ProviderDecorator
validator = MyRequestValidator()
server = WebApplicationServer(validator)
provider = OAuth2ProviderDecorator('/error', server) # See next section
Relevant sections include:
.. toctree::
:maxdepth: 1
preconfigured_servers
**5. Decorate your endpoint views**
We are implementing support for the Authorization Code Grant and will
therefore need two views for the authorization, pre- and post-authorization
together with the token view. We also include an error page to redirect
users to if the client supplied invalid credentials in their redirection,
for example an invalid redirect URI::
@login_required
@provider.pre_authorization_view
def authorize(request, client_id=None, scopes=None, state=None,
redirect_uri=None, response_type=None):
# This is the traditional authorization page
# Scopes will be the list of scopes client requested access too
# You will want to present them in a nice form where the user can
# select which scopes they allow the client to access.
return render(request, 'authorize.html', {'scopes': scopes})
@login_required
@provider.post_authorization_view
def authorization_response(request):
# This is where the form submitted from authorize should end up
# Which scopes user authorized access to + extra credentials you want
# appended to the request object passed into the validator methods.
# In almost every case, you will want to include the current
# user in these extra credentials in order to associate the user with
# the authorization code or bearer token.
return request.POST.getlist['scopes'], {'user': request.user}
@provider.access_token_view
def token_response(request):
# Not much too do here for you, return a dict with extra credentials
# you want appended to request.credentials passed to the save_bearer_token
# method of the validator.
return {'extra': 'creds'}
def error(request):
# The /error page users will be redirected to if there was something
# wrong with the credentials the client included when redirecting the
# user to the authorization form. Mainly if the client was invalid or
# included a malformed / invalid redirect url.
# Error and description can be found in
# GET['error'] and GET['error_description']
return HttpResponse('Bad client! Warn user!')
**6. Protect your APIs using scopes**
At this point you are ready to protect your API views with OAuth. Take some
time to come up with a good set of scopes as they can be very powerful in
controlling access::
@provider.protected_resource_view(scopes=['images'])
def i_am_protected(request, client, resource_owner, **kwargs):
# One of your many OAuth 2 protected resource views
# Returns whatever you fancy
# May be bound to various scopes of your choosing
return HttpResponse('pictures of cats')
The set of scopes that protects a view may also be dynamically configured
at runtime by a function, rather then by a list::
def dynamic_scopes(request):
# Place code here to dynamically determine the scopes
# and return as a list
return ['images']
@provider.protected_resource_view(scopes=dynamic_scopes)
def i_am_also_protected(request, client, resource_owner, **kwargs)
# A view that has its views functionally set.
return HttpResponse('pictures of cats')
**7. Let us know how it went!**
Drop a line in our `G+ community`_ or open a `GitHub issue`_ =)
.. _`G+ community`: https://plus.google.com/communities/101889017375384052571
.. _`GitHub issue`: https://github.com/idan/oauthlib/issues/new
If you run into issues it can be helpful to enable debug logging::
import logging
log = logging.getLogger('oauthlib')
log.addHandler(logging.StreamHandler(sys.stdout))
log.setLevel(logging.DEBUG)
|