Authentication
++Auth needs to be pluggable.
+— Jacob Kaplan-Moss, "REST worst practices"
+
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.
Authentication will run the first time either the request.user or request.auth properties are accessed, and determines how those properties are initialized.
UserBasicAuthentication
This policy uses HTTP Basic Authentication, 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.
request.userwill be adjango.contrib.auth.models.Userinstance.request.authwill beNone.
TokenAuthentication
-This policy uses HTTP Authentication 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.
request.userwill be adjango.contrib.auth.models.Userinstance.
@@ -179,7 +187,7 @@ def example_view(request, format=None):
request.authwill beNone.
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.