e622ff1734f10b925cc84cbf6bc445ad468b5350
[twitter-api-cdsw] / oauthlib / oauth2 / rfc6749 / request_validator.py
1 # -*- coding: utf-8 -*-
2 """
3 oauthlib.oauth2.rfc6749.grant_types
4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 """
6 from __future__ import unicode_literals, absolute_import
7
8 import logging
9
10 log = logging.getLogger(__name__)
11
12
13 class RequestValidator(object):
14
15     def client_authentication_required(self, request, *args, **kwargs):
16         """Determine if client authentication is required for current request.
17
18         According to the rfc6749, client authentication is required in the following cases:
19             - Resource Owner Password Credentials Grant, when Client type is Confidential or when
20               Client was issued client credentials or whenever Client provided client
21               authentication, see `Section 4.3.2`_.
22             - Authorization Code Grant, when Client type is Confidential or when Client was issued
23               client credentials or whenever Client provided client authentication,
24               see `Section 4.1.3`_.
25             - Refresh Token Grant, when Client type is Confidential or when Client was issued
26               client credentials or whenever Client provided client authentication, see
27               `Section 6`_
28
29         :param request: oauthlib.common.Request
30         :rtype: True or False
31
32         Method is used by:
33             - Authorization Code Grant
34             - Resource Owner Password Credentials Grant
35             - Refresh Token Grant
36
37         .. _`Section 4.3.2`: http://tools.ietf.org/html/rfc6749#section-4.3.2
38         .. _`Section 4.1.3`: http://tools.ietf.org/html/rfc6749#section-4.1.3
39         .. _`Section 6`: http://tools.ietf.org/html/rfc6749#section-6
40         """
41         return True
42
43     def authenticate_client(self, request, *args, **kwargs):
44         """Authenticate client through means outside the OAuth 2 spec.
45
46         Means of authentication is negotiated beforehand and may for example
47         be `HTTP Basic Authentication Scheme`_ which utilizes the Authorization
48         header.
49
50         Headers may be accesses through request.headers and parameters found in
51         both body and query can be obtained by direct attribute access, i.e.
52         request.client_id for client_id in the URL query.
53
54         OBS! Certain grant types rely on this authentication, possibly with
55         other fallbacks, and for them to recognize this authorization please
56         set the client attribute on the request (request.client). Note that
57         preferably this client object should have a client_id attribute of
58         unicode type (request.client.client_id).
59
60         :param request: oauthlib.common.Request
61         :rtype: True or False
62
63         Method is used by:
64             - Authorization Code Grant
65             - Resource Owner Password Credentials Grant (may be disabled)
66             - Client Credentials Grant
67             - Refresh Token Grant
68
69         .. _`HTTP Basic Authentication Scheme`: http://tools.ietf.org/html/rfc1945#section-11.1
70         """
71         raise NotImplementedError('Subclasses must implement this method.')
72
73     def authenticate_client_id(self, client_id, request, *args, **kwargs):
74         """Ensure client_id belong to a non-confidential client.
75
76         A non-confidential client is one that is not required to authenticate
77         through other means, such as using HTTP Basic.
78
79         Note, while not strictly necessary it can often be very convenient
80         to set request.client to the client object associated with the
81         given client_id.
82
83         :param request: oauthlib.common.Request
84         :rtype: True or False
85
86         Method is used by:
87             - Authorization Code Grant
88         """
89         raise NotImplementedError('Subclasses must implement this method.')
90
91     def confirm_redirect_uri(self, client_id, code, redirect_uri, client,
92                              *args, **kwargs):
93         """Ensure client is authorized to redirect to the redirect_uri requested.
94
95         If the client specifies a redirect_uri when obtaining code then
96         that redirect URI must be bound to the code and verified equal
97         in this method.
98
99         All clients should register the absolute URIs of all URIs they intend
100         to redirect to. The registration is outside of the scope of oauthlib.
101
102         :param client_id: Unicode client identifier
103         :param code: Unicode authorization_code.
104         :param redirect_uri: Unicode absolute URI
105         :param client: Client object set by you, see authenticate_client.
106         :param request: The HTTP Request (oauthlib.common.Request)
107         :rtype: True or False
108
109         Method is used by:
110             - Authorization Code Grant (during token request)
111         """
112         raise NotImplementedError('Subclasses must implement this method.')
113
114     def get_default_redirect_uri(self, client_id, request, *args, **kwargs):
115         """Get the default redirect URI for the client.
116
117         :param client_id: Unicode client identifier
118         :param request: The HTTP Request (oauthlib.common.Request)
119         :rtype: The default redirect URI for the client
120
121         Method is used by:
122             - Authorization Code Grant
123             - Implicit Grant
124         """
125         raise NotImplementedError('Subclasses must implement this method.')
126
127     def get_default_scopes(self, client_id, request, *args, **kwargs):
128         """Get the default scopes for the client.
129
130         :param client_id: Unicode client identifier
131         :param request: The HTTP Request (oauthlib.common.Request)
132         :rtype: List of default scopes
133
134         Method is used by all core grant types:
135             - Authorization Code Grant
136             - Implicit Grant
137             - Resource Owner Password Credentials Grant
138             - Client Credentials grant
139         """
140         raise NotImplementedError('Subclasses must implement this method.')
141
142     def get_original_scopes(self, refresh_token, request, *args, **kwargs):
143         """Get the list of scopes associated with the refresh token.
144
145         :param refresh_token: Unicode refresh token
146         :param request: The HTTP Request (oauthlib.common.Request)
147         :rtype: List of scopes.
148
149         Method is used by:
150             - Refresh token grant
151         """
152         raise NotImplementedError('Subclasses must implement this method.')
153
154     def is_within_original_scope(self, request_scopes, refresh_token, request, *args, **kwargs):
155         """Check if requested scopes are within a scope of the refresh token.
156
157         When access tokens are refreshed the scope of the new token
158         needs to be within the scope of the original token. This is
159         ensured by checking that all requested scopes strings are on
160         the list returned by the get_original_scopes. If this check
161         fails, is_within_original_scope is called. The method can be
162         used in situations where returning all valid scopes from the
163         get_original_scopes is not practical.
164
165         :param request_scopes: A list of scopes that were requested by client
166         :param refresh_token: Unicode refresh_token
167         :param request: The HTTP Request (oauthlib.common.Request)
168         :rtype: True or False
169
170         Method is used by:
171             - Refresh token grant
172         """
173         return False
174
175     def invalidate_authorization_code(self, client_id, code, request, *args, **kwargs):
176         """Invalidate an authorization code after use.
177
178         :param client_id: Unicode client identifier
179         :param code: The authorization code grant (request.code).
180         :param request: The HTTP Request (oauthlib.common.Request)
181
182         Method is used by:
183             - Authorization Code Grant
184         """
185         raise NotImplementedError('Subclasses must implement this method.')
186
187     def revoke_token(self, token, token_type_hint, request, *args, **kwargs):
188         """Revoke an access or refresh token.
189
190         :param token: The token string.
191         :param token_type_hint: access_token or refresh_token.
192         :param request: The HTTP Request (oauthlib.common.Request)
193
194         Method is used by:
195             - Revocation Endpoint
196         """
197         raise NotImplementedError('Subclasses must implement this method.')
198
199     def rotate_refresh_token(self, request):
200         """Determine whether to rotate the refresh token. Default, yes.
201
202         When access tokens are refreshed the old refresh token can be kept
203         or replaced with a new one (rotated). Return True to rotate and
204         and False for keeping original.
205
206         :param request: oauthlib.common.Request
207         :rtype: True or False
208
209         Method is used by:
210             - Refresh Token Grant
211         """
212         return True
213
214     def save_authorization_code(self, client_id, code, request, *args, **kwargs):
215         """Persist the authorization_code.
216
217         The code should at minimum be associated with:
218             - a client and it's client_id
219             - the redirect URI used (request.redirect_uri)
220             - whether the redirect URI used is the client default or not
221             - a resource owner / user (request.user)
222             - authorized scopes (request.scopes)
223
224         The authorization code grant dict (code) holds at least the key 'code'::
225
226             {'code': 'sdf345jsdf0934f'}
227
228         :param client_id: Unicode client identifier
229         :param code: A dict of the authorization code grant.
230         :param request: The HTTP Request (oauthlib.common.Request)
231         :rtype: The default redirect URI for the client
232
233         Method is used by:
234             - Authorization Code Grant
235         """
236         raise NotImplementedError('Subclasses must implement this method.')
237
238     def save_bearer_token(self, token, request, *args, **kwargs):
239         """Persist the Bearer token.
240
241         The Bearer token should at minimum be associated with:
242             - a client and it's client_id, if available
243             - a resource owner / user (request.user)
244             - authorized scopes (request.scopes)
245             - an expiration time
246             - a refresh token, if issued
247
248         The Bearer token dict may hold a number of items::
249
250             {
251                 'token_type': 'Bearer',
252                 'access_token': 'askfjh234as9sd8',
253                 'expires_in': 3600,
254                 'scope': 'string of space separated authorized scopes',
255                 'refresh_token': '23sdf876234',  # if issued
256                 'state': 'given_by_client',  # if supplied by client
257             }
258
259         Note that while "scope" is a string-separated list of authorized scopes,
260         the original list is still available in request.scopes
261
262         :param client_id: Unicode client identifier
263         :param token: A Bearer token dict
264         :param request: The HTTP Request (oauthlib.common.Request)
265         :rtype: The default redirect URI for the client
266
267         Method is used by all core grant types issuing Bearer tokens:
268             - Authorization Code Grant
269             - Implicit Grant
270             - Resource Owner Password Credentials Grant (might not associate a client)
271             - Client Credentials grant
272         """
273         raise NotImplementedError('Subclasses must implement this method.')
274
275     def validate_bearer_token(self, token, scopes, request):
276         """Ensure the Bearer token is valid and authorized access to scopes.
277
278         :param token: A string of random characters.
279         :param scopes: A list of scopes associated with the protected resource.
280         :param request: The HTTP Request (oauthlib.common.Request)
281
282         A key to OAuth 2 security and restricting impact of leaked tokens is
283         the short expiration time of tokens, *always ensure the token has not
284         expired!*.
285
286         Two different approaches to scope validation:
287
288             1) all(scopes). The token must be authorized access to all scopes
289                             associated with the resource. For example, the
290                             token has access to ``read-only`` and ``images``,
291                             thus the client can view images but not upload new.
292                             Allows for fine grained access control through
293                             combining various scopes.
294
295             2) any(scopes). The token must be authorized access to one of the
296                             scopes associated with the resource. For example,
297                             token has access to ``read-only-images``.
298                             Allows for fine grained, although arguably less
299                             convenient, access control.
300
301         A powerful way to use scopes would mimic UNIX ACLs and see a scope
302         as a group with certain privileges. For a restful API these might
303         map to HTTP verbs instead of read, write and execute.
304
305         Note, the request.user attribute can be set to the resource owner
306         associated with this token. Similarly the request.client and
307         request.scopes attribute can be set to associated client object
308         and authorized scopes. If you then use a decorator such as the
309         one provided for django these attributes will be made available
310         in all protected views as keyword arguments.
311
312         :param token: Unicode Bearer token
313         :param scopes: List of scopes (defined by you)
314         :param request: The HTTP Request (oauthlib.common.Request)
315         :rtype: True or False
316
317         Method is indirectly used by all core Bearer token issuing grant types:
318             - Authorization Code Grant
319             - Implicit Grant
320             - Resource Owner Password Credentials Grant
321             - Client Credentials Grant
322         """
323         raise NotImplementedError('Subclasses must implement this method.')
324
325     def validate_client_id(self, client_id, request, *args, **kwargs):
326         """Ensure client_id belong to a valid and active client.
327
328         Note, while not strictly necessary it can often be very convenient
329         to set request.client to the client object associated with the
330         given client_id.
331
332         :param request: oauthlib.common.Request
333         :rtype: True or False
334
335         Method is used by:
336             - Authorization Code Grant
337             - Implicit Grant
338         """
339         raise NotImplementedError('Subclasses must implement this method.')
340
341     def validate_code(self, client_id, code, client, request, *args, **kwargs):
342         """Ensure the authorization_code is valid and assigned to client.
343
344         OBS! The request.user attribute should be set to the resource owner
345         associated with this authorization code. Similarly request.scopes and
346         request.state must also be set.
347
348         :param client_id: Unicode client identifier
349         :param code: Unicode authorization code
350         :param client: Client object set by you, see authenticate_client.
351         :param request: The HTTP Request (oauthlib.common.Request)
352         :rtype: True or False
353
354         Method is used by:
355             - Authorization Code Grant
356         """
357         raise NotImplementedError('Subclasses must implement this method.')
358
359     def validate_grant_type(self, client_id, grant_type, client, request, *args, **kwargs):
360         """Ensure client is authorized to use the grant_type requested.
361
362         :param client_id: Unicode client identifier
363         :param grant_type: Unicode grant type, i.e. authorization_code, password.
364         :param client: Client object set by you, see authenticate_client.
365         :param request: The HTTP Request (oauthlib.common.Request)
366         :rtype: True or False
367
368         Method is used by:
369             - Authorization Code Grant
370             - Resource Owner Password Credentials Grant
371             - Client Credentials Grant
372             - Refresh Token Grant
373         """
374         raise NotImplementedError('Subclasses must implement this method.')
375
376     def validate_redirect_uri(self, client_id, redirect_uri, request, *args, **kwargs):
377         """Ensure client is authorized to redirect to the redirect_uri requested.
378
379         All clients should register the absolute URIs of all URIs they intend
380         to redirect to. The registration is outside of the scope of oauthlib.
381
382         :param client_id: Unicode client identifier
383         :param redirect_uri: Unicode absolute URI
384         :param request: The HTTP Request (oauthlib.common.Request)
385         :rtype: True or False
386
387         Method is used by:
388             - Authorization Code Grant
389             - Implicit Grant
390         """
391         raise NotImplementedError('Subclasses must implement this method.')
392
393     def validate_refresh_token(self, refresh_token, client, request, *args, **kwargs):
394         """Ensure the Bearer token is valid and authorized access to scopes.
395
396         OBS! The request.user attribute should be set to the resource owner
397         associated with this refresh token.
398
399         :param refresh_token: Unicode refresh token
400         :param client: Client object set by you, see authenticate_client.
401         :param request: The HTTP Request (oauthlib.common.Request)
402         :rtype: True or False
403
404         Method is used by:
405             - Authorization Code Grant (indirectly by issuing refresh tokens)
406             - Resource Owner Password Credentials Grant (also indirectly)
407             - Refresh Token Grant
408         """
409         raise NotImplementedError('Subclasses must implement this method.')
410
411     def validate_response_type(self, client_id, response_type, client, request, *args, **kwargs):
412         """Ensure client is authorized to use the response_type requested.
413
414         :param client_id: Unicode client identifier
415         :param response_type: Unicode response type, i.e. code, token.
416         :param client: Client object set by you, see authenticate_client.
417         :param request: The HTTP Request (oauthlib.common.Request)
418         :rtype: True or False
419
420         Method is used by:
421             - Authorization Code Grant
422             - Implicit Grant
423         """
424         raise NotImplementedError('Subclasses must implement this method.')
425
426     def validate_scopes(self, client_id, scopes, client, request, *args, **kwargs):
427         """Ensure the client is authorized access to requested scopes.
428
429         :param client_id: Unicode client identifier
430         :param scopes: List of scopes (defined by you)
431         :param client: Client object set by you, see authenticate_client.
432         :param request: The HTTP Request (oauthlib.common.Request)
433         :rtype: True or False
434
435         Method is used by all core grant types:
436             - Authorization Code Grant
437             - Implicit Grant
438             - Resource Owner Password Credentials Grant
439             - Client Credentials Grant
440         """
441         raise NotImplementedError('Subclasses must implement this method.')
442
443     def validate_user(self, username, password, client, request, *args, **kwargs):
444         """Ensure the username and password is valid.
445
446         OBS! The validation should also set the user attribute of the request
447         to a valid resource owner, i.e. request.user = username or similar. If
448         not set you will be unable to associate a token with a user in the
449         persistance method used (commonly, save_bearer_token).
450
451         :param username: Unicode username
452         :param password: Unicode password
453         :param client: Client object set by you, see authenticate_client.
454         :param request: The HTTP Request (oauthlib.common.Request)
455         :rtype: True or False
456
457         Method is used by:
458             - Resource Owner Password Credentials Grant
459         """
460         raise NotImplementedError('Subclasses must implement this method.')

Benjamin Mako Hill || Want to submit a patch?