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 --- 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 +- 5 files changed, 153 insertions(+), 147 deletions(-) create mode 100644 docs/static/css/default.css delete mode 100644 docs/static/css/drf-styles.css (limited to 'docs') 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 @@ - +