From 003a65f0e094e59b5462fcd0607bf290d80cc5aa Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Wed, 12 Sep 2012 20:39:22 +0100
Subject: 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 +-
docs/static/css/default.css | 134 +++++++++++++++++++++
docs/static/css/drf-styles.css | 134 ---------------------
docs/template.html | 2 +-
14 files changed, 300 insertions(+), 188 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
create mode 100644 docs/static/css/default.css
delete mode 100644 docs/static/css/drf-styles.css
diff --git a/djangorestframework/authentication.py b/djangorestframework/authentication.py
index 2446fbbd..a6634392 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:
- * 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: Token 401f7ac837da42b97f613d789819ff93537bee6a
+ """
- Authorization: 0123456789abcdef0123456789abcdef
+ 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
"""
- model = None
def authenticate(self, request):
- key = request.META.get('HTTP_AUTHORIZATION', '').strip()
-
- if self.model is None:
- from djangorestframework.tokenauth.models import BasicToken
- self.model = BasicToken
+ auth = request.META.get('HTTP_AUTHORIZATION', '').split()
- try:
- token = self.model.objects.get(key=key)
- except self.model.DoesNotExist:
- return None
+ 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
- if token.user.is_active and not token.revoked:
- return (token.user, token)
+ if token.user.is_active and not getattr(token, 'revoked', False):
+ 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 00000000..e69de29b
diff --git a/djangorestframework/authtoken/migrations/0001_initial.py b/djangorestframework/authtoken/migrations/0001_initial.py
new file mode 100644
index 00000000..a91006b0
--- /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 00000000..e69de29b
diff --git a/djangorestframework/authtoken/models.py b/djangorestframework/authtoken/models.py
new file mode 100644
index 00000000..fd47e6c7
--- /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 00000000..e69de29b
diff --git a/djangorestframework/runtests/settings.py b/djangorestframework/runtests/settings.py
index 1fc6b47b..da2ae5b8 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 dab06b97..ddbee4b6 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 f289b0fd..e8886112 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):
+ """
+ Manager class to provide `Token.objects.create_token(user=user)`.
+ """
+ def create_token(self, user):
+ token = Token(user=user)
+ token.save()
+ return token
+
+
+class Token(models.Model):
"""
- The default authorization token model class.
+ The default authorization token model.
"""
- key = models.CharField(max_length=32, primary_key=True, blank=True)
+ 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 f2878f19..777106e8 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.
+
+To use the `TokenAuthentication` policy, include `djangorestframework.authtoken` in your `INSTALLED_APPS` setting.
+
+You'll also need to create tokens for your users.
+
+ from djangorestframework.authtoken.models import Token
-The token key should be passed in as a string to the "Authorization" HTTP header. For example:
+ token = Token.objects.create(user=...)
+ print token.key
- curl http://my.api.org/ -X POST -H "Authorization: 0123456789abcdef0123456789abcdef"
+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:
-**Note:** If you run `TokenAuthentication` in production your API should be `https` only.
+ 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 e0f3583f..bd107462 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/default.css b/docs/static/css/default.css
new file mode 100644
index 00000000..8e0490d3
--- /dev/null
+++ b/docs/static/css/default.css
@@ -0,0 +1,134 @@
+/* Set the body padding-top when above 980px to push the content down from
+ below the navbar, which is fixed at >980px screen widths. */
+@media (min-width: 980px) {
+ body {
+ padding-top: 71px;
+ }
+}
+
+body {
+ padding-bottom: 40px;
+}
+
+pre {
+ font-size: 12px;
+}
+
+.dropdown .dropdown-menu {
+ display: none;
+}
+
+.dropdown.open .dropdown-menu {
+ display: block;
+}
+
+/* Header link to GitHub */
+.repo-link {
+ float: right;
+ margin-right: 10px;
+ margin-top: 9px;
+}
+
+/* GitHub 'Star' badge */
+body.index #main-content iframe {
+ float: right;
+ margin-top: -12px;
+ margin-right: -15px;
+}
+
+/* Travis CI badge */
+body.index #main-content p:first-of-type {
+ float: right;
+ margin-right: 8px;
+ margin-top: -14px;
+ margin-bottom: 0px;
+}
+
+/* Github source file badges */
+a.github {
+ float: right;
+ margin-top: -12px;
+ margin-right: 12px;
+}
+
+a.github:hover {
+ text-decoration: none;
+}
+
+/* Force TOC text to not overrun */
+#table-of-contents {
+ overflow: hidden;
+}
+
+/* Code blocks should scroll horizontally */
+pre {
+ overflow: auto;
+ word-wrap: normal;
+ white-space: pre;
+}
+
+/* Preserve the spacing of the navbar across different screen sizes. */
+.navbar-inner {
+ padding: 5px 0;
+}
+
+@media (max-width: 979px) {
+ .navbar .brand {
+ margin-left: 0;
+ padding-left: 0;
+ }
+ .navbar-inner .container-fluid {
+ padding-left: 15px;
+ }
+}
+
+.nav-list li.main {
+ font-weight: bold;
+}
+
+/* Set the table of contents to static so it flows back into the content when
+ viewed on tablets and smaller. */
+@media (max-width: 767px) {
+ #table-of-contents {
+ position: static;
+ }
+}
+
+/* When the page is in two-column layout, give the main content some room
+ to breath on the left. */
+@media (min-width: 768px) {
+ #main-content {
+ padding-left: 1em;
+ }
+}
+
+/* Cutesy quote styling */
+blockquote {
+ font-family: Georgia, serif;
+ font-size: 18px;
+ font-style: italic;
+ margin: 0.25em 0;
+ padding: 0.25em 40px;
+ line-height: 1.45;
+ position: relative;
+ color: #383838;
+ border-left: none;
+}
+
+blockquote:before {
+ display: block;
+ content: "\201C";
+ font-size: 80px;
+ position: absolute;
+ left: -10px;
+ top: -20px;
+ color: #7a7a7a;
+}
+
+blockquote p:last-child {
+ color: #999999;
+ font-size: 14px;
+ display: block;
+ margin-top: 5px;
+}
+
diff --git a/docs/static/css/drf-styles.css b/docs/static/css/drf-styles.css
deleted file mode 100644
index 7ad9d717..00000000
--- a/docs/static/css/drf-styles.css
+++ /dev/null
@@ -1,134 +0,0 @@
-/* Set the body padding-top when above 980px to push the content down from
- below the navbar, which is fixed at >980px screen widths. */
-@media (min-width: 980px) {
- body {
- padding-top: 71px;
- }
-}
-
-body {
- padding-bottom: 40px;
-}
-
-pre {
- font-size: 12px;
-}
-
-.dropdown .dropdown-menu {
- display: none;
-}
-
-.dropdown.open .dropdown-menu {
- 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;
- margin-top: -12px;
- margin-right: -15px;
-}
-
-/* Travis CI badge */
-body.index #main-content p:first-of-type {
- float: right;
- margin-right: 8px;
- margin-top: -14px;
- margin-bottom: 0px;
-}
-
-/* Github source file badges */
-a.github {
- float: right;
- margin-top: -12px;
- margin-right: 12px;
-}
-
-a.github:hover {
- text-decoration: none;
-}
-
-/* Force TOC text to not overrun */
-#table-of-contents {
- overflow: hidden;
-}
-
-/* Code blocks should scroll horizontally */
-pre {
- overflow: auto;
- word-wrap: normal;
- white-space: pre;
-}
-
-/* Preserve the spacing of the navbar across different screen sizes. */
-.navbar-inner {
- padding: 5px 0;
-}
-
-@media (max-width: 979px) {
- .navbar .brand {
- margin-left: 0;
- padding-left: 0;
- }
- .navbar-inner .container-fluid {
- padding-left: 15px;
- }
-}
-
-.nav-list li.main {
- font-weight: bold;
-}
-
-/* Set the table of contents to static so it flows back into the content when
- viewed on tablets and smaller. */
-@media (max-width: 767px) {
- #table-of-contents {
- position: static;
- }
-}
-
-/* When the page is in two-column layout, give the main content some room
- to breath on the left. */
-@media (min-width: 768px) {
- #main-content {
- padding-left: 1em;
- }
-}
-
-/* Cutesy quote styling */
-blockquote {
- font-family: Georgia, serif;
- font-size: 18px;
- font-style: italic;
- margin: 0.25em 0;
- padding: 0.25em 40px;
- line-height: 1.45;
- position: relative;
- color: #383838;
- border-left: none;
-}
-
-blockquote:before {
- display: block;
- content: "\201C";
- font-size: 80px;
- position: absolute;
- left: -10px;
- top: -20px;
- color: #7a7a7a;
-}
-
-blockquote p:last-child {
- color: #999999;
- font-size: 14px;
- display: block;
- margin-top: 5px;
-}
-
diff --git a/docs/template.html b/docs/template.html
index 936b6d93..e6c9078a 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -10,7 +10,7 @@
-
+