From dac4cb9e8bf107f407ed8754bbef0ce97e79beb2 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 12 Sep 2012 13:11:26 +0100 Subject: [PATCH 1/3] GitHub link in toolbar --- docs/api-guide/exceptions.md | 6 +++--- docs/api-guide/permissions.md | 19 ++++++++++++++++--- docs/static/css/drf-styles.css | 7 +++++++ docs/template.html | 1 + 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index c8ccb08bb..c22d6d8bb 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -8,7 +8,7 @@ ## Exception handling in REST framework views -REST framework's views handle various exceptions, and deal with returning appropriate error responses for you. +REST framework's views handle various exceptions, and deal with returning appropriate error responses. The handled exceptions are: @@ -16,9 +16,9 @@ The handled exceptions are: * Django's `Http404` exception. * Django's `PermissionDenied` exception. -In each case, REST framework will return a response, rendering it to an appropriate content-type. +In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error. -By default all error messages will include a key `details` in the body of the response, but other keys may also be included. +By default all error responses will include a key `details` in the body of the response, but other keys may also be included. For example, the following request: diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index be22eefe9..e0f3583fc 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -12,7 +12,7 @@ Permission checks are always run at the very start of the view, before any other ## How permissions are determined -Permissions in REST framework are always defined as a list of permission classes. Before running the main body of the view, each permission in the list is checked. +Permissions in REST framework are always defined as a list of permission classes. Before running the main body of the view each permission in the list is checked. If any permission check fails an `exceptions.PermissionDenied` exception will be raised, and the main body of the view will not run. @@ -73,7 +73,18 @@ This permission is suitable if you want to your API to allow read permissions to ## DjangoModelPermissions -This permission class ties into Django's standard `django.contrib.auth` model permissions. When applied to a view that has a `.model` property, permission will only be granted if the user +This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth]. When applied to a view that has a `.model` property, authorization will only be granted if the user has the relevant model permissions assigned. + +* `POST` requests require the user to have the `add` permission on the model. +* `PUT` and `PATCH` requests require the user to have the `change` permission on the model. +* `DELETE` requests require the user to have the `delete` permission on the model. + +The default behaviour can also be overridden to support custom model permissions. For example, you might want to include a `view` model permission for `GET` requests. + +To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property. Refer to the source code for details. + +The `DjangoModelPermissions` class also supports object-level permissions. Third-party authorization backends such as [django-guardian][guardian] should work just fine with `DjangoModelPermissions` without any custom configuration required. + ## Custom permissions @@ -84,4 +95,6 @@ The method should return `True` if the request should be granted access, and `Fa [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html [authentication]: authentication.md -[throttling]: throttling.md \ No newline at end of file +[throttling]: throttling.md +[contribauth]: https://docs.djangoproject.com/en/1.0/topics/auth/#permissions +[guardian]: https://github.com/lukaszb/django-guardian \ No newline at end of file diff --git a/docs/static/css/drf-styles.css b/docs/static/css/drf-styles.css index a5f0b97a2..7ad9d717f 100644 --- a/docs/static/css/drf-styles.css +++ b/docs/static/css/drf-styles.css @@ -22,6 +22,13 @@ pre { display: block; } +/* Header link to GitHub */ +.repo-link { + float: right; + margin-right: 10px; + margin-top: 7px; +} + /* GitHub 'Star' badge */ body.index #main-content iframe { float: right; diff --git a/docs/template.html b/docs/template.html index f20aabac7..936b6d935 100644 --- a/docs/template.html +++ b/docs/template.html @@ -21,6 +21,7 @@
+ GitHub From 003a65f0e094e59b5462fcd0607bf290d80cc5aa Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 12 Sep 2012 20:39:22 +0100 Subject: [PATCH 2/3] Tweaks to Token auth --- djangorestframework/authentication.py | 50 ++++++------- djangorestframework/authtoken/__init__.py | 0 .../authtoken/migrations/0001_initial.py | 72 +++++++++++++++++++ .../authtoken/migrations/__init__.py | 0 djangorestframework/authtoken/models.py | 23 ++++++ djangorestframework/authtoken/views.py | 0 djangorestframework/runtests/settings.py | 2 +- djangorestframework/tests/authentication.py | 12 ++-- djangorestframework/tokenauth/models.py | 29 ++++++-- docs/api-guide/authentication.md | 27 ++++--- docs/api-guide/permissions.md | 3 +- .../css/{drf-styles.css => default.css} | 2 +- docs/template.html | 2 +- 13 files changed, 167 insertions(+), 55 deletions(-) create mode 100644 djangorestframework/authtoken/__init__.py create mode 100644 djangorestframework/authtoken/migrations/0001_initial.py create mode 100644 djangorestframework/authtoken/migrations/__init__.py create mode 100644 djangorestframework/authtoken/models.py create mode 100644 djangorestframework/authtoken/views.py rename docs/static/css/{drf-styles.css => default.css} (99%) diff --git a/djangorestframework/authentication.py b/djangorestframework/authentication.py index 2446fbbdd..a66343921 100644 --- a/djangorestframework/authentication.py +++ b/djangorestframework/authentication.py @@ -6,14 +6,9 @@ Authentication behavior is provided by mixing the :class:`mixins.RequestMixin` c from django.contrib.auth import authenticate from djangorestframework.compat import CsrfViewMiddleware +from djangorestframework.authtoken.models import Token import base64 -__all__ = ( - 'BaseAuthentication', - 'BasicAuthentication', - 'SessionAuthentication' -) - class BaseAuthentication(object): """ @@ -105,36 +100,33 @@ class SessionAuthentication(BaseAuthentication): class TokenAuthentication(BaseAuthentication): """ - Use a token model for authentication. + Simple token based authentication. - A custom token model may be used here, but must have the following minimum - properties: + Clients should authenticate by passing the token key in the "Authorization" + HTTP header, prepended with the string "Token ". For example: + + Authorization: Token 401f7ac837da42b97f613d789819ff93537bee6a + """ + + model = Token + """ + A custom token model may be used, but must have the following properties. * key -- The string identifying the token * user -- The user to which the token belongs - * revoked -- The status of the token - - The token key should be passed in as a string to the "Authorization" HTTP - header. For example: - - Authorization: 0123456789abcdef0123456789abcdef - """ - model = None def authenticate(self, request): - key = request.META.get('HTTP_AUTHORIZATION', '').strip() + auth = request.META.get('HTTP_AUTHORIZATION', '').split() - if self.model is None: - from djangorestframework.tokenauth.models import BasicToken - self.model = BasicToken + if len(auth) == 2 and auth[0].lower() == "token": + key = auth[1] + try: + token = self.model.objects.get(key=key) + except self.model.DoesNotExist: + return None - try: - token = self.model.objects.get(key=key) - except self.model.DoesNotExist: - return None + if token.user.is_active and not getattr(token, 'revoked', False): + return (token.user, token) - if token.user.is_active and not token.revoked: - return (token.user, token) - -# TODO: DigestAuthentication, OAuthAuthentication +# TODO: OAuthAuthentication diff --git a/djangorestframework/authtoken/__init__.py b/djangorestframework/authtoken/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/djangorestframework/authtoken/migrations/0001_initial.py b/djangorestframework/authtoken/migrations/0001_initial.py new file mode 100644 index 000000000..a91006b00 --- /dev/null +++ b/djangorestframework/authtoken/migrations/0001_initial.py @@ -0,0 +1,72 @@ +# -*- coding: utf-8 -*- +import datetime +from south.db import db +from south.v2 import SchemaMigration +from django.db import models + + +class Migration(SchemaMigration): + + def forwards(self, orm): + # Adding model 'Token' + db.create_table('authtoken_token', ( + ('key', self.gf('django.db.models.fields.CharField')(max_length=40, primary_key=True)), + ('user', self.gf('django.db.models.fields.related.ForeignKey')(to=orm['auth.User'])), + ('revoked', self.gf('django.db.models.fields.BooleanField')(default=False)), + ('created', self.gf('django.db.models.fields.DateTimeField')(auto_now_add=True, blank=True)), + )) + db.send_create_signal('authtoken', ['Token']) + + + def backwards(self, orm): + # Deleting model 'Token' + db.delete_table('authtoken_token') + + + models = { + 'auth.group': { + 'Meta': {'object_name': 'Group'}, + 'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}), + 'name': ('django.db.models.fields.CharField', [], {'unique': 'True', 'max_length': '80'}), + 'permissions': ('django.db.models.fields.related.ManyToManyField', [], {'to': "orm['auth.Permission']", 'symmetrical': 'False', 'blank': 'True'}) + }, + 'auth.permission': { + 'Meta': {'ordering': "('content_type__app_label', 'content_type__model', 'codename')", 'unique_together': "(('content_type', 'codename'),)", 'object_name': 'Permission'}, + 'codename': ('django.db.models.fields.CharField', [], {'max_length': '100'}), + 'content_type': ('django.db.models.fields.related.ForeignKey', [], {'to': "orm['contenttypes.ContentType']"}), + 'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}), + 'name': ('django.db.models.fields.CharField', [], {'max_length': '50'}) + }, + 'auth.user': { + 'Meta': {'object_name': 'User'}, + 'date_joined': ('django.db.models.fields.DateTimeField', [], {'default': 'datetime.datetime.now'}), + 'email': ('django.db.models.fields.EmailField', [], {'max_length': '75', 'blank': 'True'}), + 'first_name': ('django.db.models.fields.CharField', [], {'max_length': '30', 'blank': 'True'}), + 'groups': ('django.db.models.fields.related.ManyToManyField', [], {'to': "orm['auth.Group']", 'symmetrical': 'False', 'blank': 'True'}), + 'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}), + 'is_active': ('django.db.models.fields.BooleanField', [], {'default': 'True'}), + 'is_staff': ('django.db.models.fields.BooleanField', [], {'default': 'False'}), + 'is_superuser': ('django.db.models.fields.BooleanField', [], {'default': 'False'}), + 'last_login': ('django.db.models.fields.DateTimeField', [], {'default': 'datetime.datetime.now'}), + 'last_name': ('django.db.models.fields.CharField', [], {'max_length': '30', 'blank': 'True'}), + 'password': ('django.db.models.fields.CharField', [], {'max_length': '128'}), + 'user_permissions': ('django.db.models.fields.related.ManyToManyField', [], {'to': "orm['auth.Permission']", 'symmetrical': 'False', 'blank': 'True'}), + 'username': ('django.db.models.fields.CharField', [], {'unique': 'True', 'max_length': '30'}) + }, + 'authtoken.token': { + 'Meta': {'object_name': 'Token'}, + 'created': ('django.db.models.fields.DateTimeField', [], {'auto_now_add': 'True', 'blank': 'True'}), + 'key': ('django.db.models.fields.CharField', [], {'max_length': '40', 'primary_key': 'True'}), + 'revoked': ('django.db.models.fields.BooleanField', [], {'default': 'False'}), + 'user': ('django.db.models.fields.related.ForeignKey', [], {'to': "orm['auth.User']"}) + }, + 'contenttypes.contenttype': { + 'Meta': {'ordering': "('name',)", 'unique_together': "(('app_label', 'model'),)", 'object_name': 'ContentType', 'db_table': "'django_content_type'"}, + 'app_label': ('django.db.models.fields.CharField', [], {'max_length': '100'}), + 'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}), + 'model': ('django.db.models.fields.CharField', [], {'max_length': '100'}), + 'name': ('django.db.models.fields.CharField', [], {'max_length': '100'}) + } + } + + complete_apps = ['authtoken'] \ No newline at end of file diff --git a/djangorestframework/authtoken/migrations/__init__.py b/djangorestframework/authtoken/migrations/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/djangorestframework/authtoken/models.py b/djangorestframework/authtoken/models.py new file mode 100644 index 000000000..fd47e6c72 --- /dev/null +++ b/djangorestframework/authtoken/models.py @@ -0,0 +1,23 @@ +import uuid +import hmac +from hashlib import sha1 +from django.db import models + + +class Token(models.Model): + """ + The default authorization token model. + """ + key = models.CharField(max_length=40, primary_key=True) + user = models.ForeignKey('auth.User') + revoked = models.BooleanField(default=False) + created = models.DateTimeField(auto_now_add=True) + + def save(self, *args, **kwargs): + if not self.key: + self.key = self.generate_key() + return super(Token, self).save(*args, **kwargs) + + def generate_key(self): + unique = str(uuid.uuid4()) + return hmac.new(unique, digestmod=sha1).hexdigest() diff --git a/djangorestframework/authtoken/views.py b/djangorestframework/authtoken/views.py new file mode 100644 index 000000000..e69de29bb diff --git a/djangorestframework/runtests/settings.py b/djangorestframework/runtests/settings.py index 1fc6b47b0..da2ae5b8f 100644 --- a/djangorestframework/runtests/settings.py +++ b/djangorestframework/runtests/settings.py @@ -90,7 +90,7 @@ INSTALLED_APPS = ( # Uncomment the next line to enable admin documentation: # 'django.contrib.admindocs', 'djangorestframework', - 'djangorestframework.tokenauth', + 'djangorestframework.authtoken', ) STATIC_URL = '/static/' diff --git a/djangorestframework/tests/authentication.py b/djangorestframework/tests/authentication.py index dab06b97c..ddbee4b65 100644 --- a/djangorestframework/tests/authentication.py +++ b/djangorestframework/tests/authentication.py @@ -8,7 +8,7 @@ from django.http import HttpResponse from djangorestframework.views import APIView from djangorestframework import permissions -from djangorestframework.tokenauth.models import BasicToken +from djangorestframework.authtoken.models import Token from djangorestframework.authentication import TokenAuthentication import base64 @@ -123,17 +123,17 @@ class TokenAuthTests(TestCase): self.user = User.objects.create_user(self.username, self.email, self.password) self.key = 'abcd1234' - self.token = BasicToken.objects.create(key=self.key, user=self.user) + self.token = Token.objects.create(key=self.key, user=self.user) def test_post_form_passing_token_auth(self): """Ensure POSTing json over token auth with correct credentials passes and does not require CSRF""" - auth = self.key + auth = "Token " + self.key response = self.csrf_client.post('/', {'example': 'example'}, HTTP_AUTHORIZATION=auth) self.assertEqual(response.status_code, 200) def test_post_json_passing_token_auth(self): """Ensure POSTing form over token auth with correct credentials passes and does not require CSRF""" - auth = self.key + auth = "Token " + self.key response = self.csrf_client.post('/', json.dumps({'example': 'example'}), 'application/json', HTTP_AUTHORIZATION=auth) self.assertEqual(response.status_code, 200) @@ -149,5 +149,5 @@ class TokenAuthTests(TestCase): def test_token_has_auto_assigned_key_if_none_provided(self): """Ensure creating a token with no key will auto-assign a key""" - token = BasicToken.objects.create(user=self.user) - self.assertEqual(len(token.key), 32) + token = Token.objects.create(user=self.user) + self.assertTrue(bool(token.key)) diff --git a/djangorestframework/tokenauth/models.py b/djangorestframework/tokenauth/models.py index f289b0fd5..e8886112b 100644 --- a/djangorestframework/tokenauth/models.py +++ b/djangorestframework/tokenauth/models.py @@ -1,15 +1,34 @@ import uuid +import hmac +from hashlib import sha1 from django.db import models -class BasicToken(models.Model): + +class TokenManager(models.Manager): """ - The default authorization token model class. + Manager class to provide `Token.objects.create_token(user=user)`. """ - key = models.CharField(max_length=32, primary_key=True, blank=True) + def create_token(self, user): + token = Token(user=user) + token.save() + return token + + +class Token(models.Model): + """ + The default authorization token model. + """ + key = models.CharField(max_length=40, primary_key=True) user = models.ForeignKey('auth.User') revoked = models.BooleanField(default=False) + created = models.DateTimeField(auto_now_add=True) + objects = TokenManager() def save(self, *args, **kwargs): if not self.key: - self.key = uuid.uuid4().hex - return super(BasicToken, self).save(*args, **kwargs) + self.key = self.generate_key() + return super(Token, self).save(*args, **kwargs) + + def generate_key(self): + unique = str(uuid.uuid4()) + return hmac.new(unique, digestmod=sha1).hexdigest() diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index f2878f193..777106e8b 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -60,33 +60,40 @@ Or, if you're using the `@api_view` decorator with function based views. } return Response(content) -## UserBasicAuthentication +## BasicAuthentication -This policy uses [HTTP Basic Authentication][basicauth], signed against a user's username and password. User basic authentication is generally only appropriate for testing. +This policy uses [HTTP Basic Authentication][basicauth], signed against a user's username and password. Basic authentication is generally only appropriate for testing. -**Note:** If you run `UserBasicAuthentication` in production your API should be `https` only. You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage. - -If successfully authenticated, `UserBasicAuthentication` provides the following credentials. +If successfully authenticated, `BasicAuthentication` provides the following credentials. * `request.user` will be a `django.contrib.auth.models.User` instance. * `request.auth` will be `None`. +**Note:** If you use `BasicAuthentication` in production you must ensure that your API is only available over `https` only. You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage. + ## TokenAuthentication -This policy uses simple token-based HTTP Authentication. Token basic authentication is appropriate for client-server setups, such as native desktop and mobile clients. +This policy uses a simple token-based HTTP Authentication scheme. Token authentication is appropriate for client-server setups, such as native desktop and mobile clients. -The token key should be passed in as a string to the "Authorization" HTTP header. For example: +To use the `TokenAuthentication` policy, include `djangorestframework.authtoken` in your `INSTALLED_APPS` setting. - curl http://my.api.org/ -X POST -H "Authorization: 0123456789abcdef0123456789abcdef" +You'll also need to create tokens for your users. -**Note:** If you run `TokenAuthentication` in production your API should be `https` only. + from djangorestframework.authtoken.models import Token + + token = Token.objects.create(user=...) + print token.key + +For clients to authenticate, the token key should be included in the `Authorization` HTTP header. The key should be prefixed by the string literal "Token", with whitespace seperating the two strings. For example: + + Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b If successfully authenticated, `TokenAuthentication` provides the following credentials. * `request.user` will be a `django.contrib.auth.models.User` instance. * `request.auth` will be a `djangorestframework.tokenauth.models.BasicToken` instance. -To use the `TokenAuthentication` policy, you must have a token model. Django REST Framework comes with a minimal default token model. To use it, include `djangorestframework.tokenauth` in your installed applications and sync your database. To use your own token model, subclass the `djangorestframework.tokenauth.TokenAuthentication` class and specify a `model` attribute that references your custom token model. The token model must provide `user`, `key`, and `revoked` attributes. Refer to the `djangorestframework.tokenauth.models.BasicToken` model as an example. +**Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. ## OAuthAuthentication diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index e0f3583fc..bd1074628 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -83,8 +83,7 @@ The default behaviour can also be overridden to support custom model permissions To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property. Refer to the source code for details. -The `DjangoModelPermissions` class also supports object-level permissions. Third-party authorization backends such as [django-guardian][guardian] should work just fine with `DjangoModelPermissions` without any custom configuration required. - +The `DjangoModelPermissions` class also supports object-level permissions. Third-party authorization backends such as [django-guardian][guardian] that provide object-level permissions should work just fine with `DjangoModelPermissions` without any custom configuration required. ## Custom permissions diff --git a/docs/static/css/drf-styles.css b/docs/static/css/default.css similarity index 99% rename from docs/static/css/drf-styles.css rename to docs/static/css/default.css index 7ad9d717f..8e0490d32 100644 --- a/docs/static/css/drf-styles.css +++ b/docs/static/css/default.css @@ -26,7 +26,7 @@ pre { .repo-link { float: right; margin-right: 10px; - margin-top: 7px; + margin-top: 9px; } /* GitHub 'Star' badge */ diff --git a/docs/template.html b/docs/template.html index 936b6d935..e6c9078a7 100644 --- a/docs/template.html +++ b/docs/template.html @@ -10,7 +10,7 @@ - +