From c85f799ade0710dd27838e8bfc78989c80213d6a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 12 Sep 2012 10:12:13 +0100 Subject: Updating docs --- docs/api-guide/authentication.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) (limited to 'docs/api-guide/authentication.md') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index ca29bc4d..f2878f19 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -2,6 +2,10 @@ # Authentication +> Auth needs to be pluggable. +> +> — Jacob Kaplan-Moss, ["REST worst practices"][cite] + Authentication is the mechanism of associating an incoming request with a set of identifying credentials, such as the user the request came from, or the token that it was signed with. The [permission] and [throttling] policies can then use those credentials to determine if the request should be permitted. REST framework provides a number of authentication policies out of the box, and also allows you to implement custom policies. @@ -60,7 +64,7 @@ Or, if you're using the `@api_view` decorator with function based views. This policy uses [HTTP Basic Authentication][basicauth], signed against a user's username and password. User basic authentication is generally only appropriate for testing. -**Note:** If you run `UserBasicAuthentication` in production your API must be `https` only, or it will be completely insecure. 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. +**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. @@ -69,11 +73,13 @@ If successfully authenticated, `UserBasicAuthentication` provides the following ## TokenAuthentication -This policy uses [HTTP Authentication][basicauth] with no authentication scheme. Token basic 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: +This policy uses simple token-based HTTP Authentication. Token basic 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: curl http://my.api.org/ -X POST -H "Authorization: 0123456789abcdef0123456789abcdef" -**Note:** If you run `TokenAuthentication` in production your API must be `https` only, or it will be completely insecure. +**Note:** If you run `TokenAuthentication` in production your API should be `https` only. If successfully authenticated, `TokenAuthentication` provides the following credentials. @@ -102,8 +108,9 @@ If successfully authenticated, `SessionAuthentication` provides the following cr ## Custom authentication policies -To implement a custom authentication policy, subclass `BaseAuthentication` and override the `authenticate(self, request)` method. The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise. +To implement a custom authentication policy, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method. The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise. +[cite]: http://jacobian.org/writing/rest-worst-practices/ [basicauth]: http://tools.ietf.org/html/rfc2617 [oauth]: http://oauth.net/2/ [permission]: permissions.md -- cgit v1.2.3