diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 76aaba8a1..0a144a94a 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -1,9 +1,88 @@ # Authentication +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. -## BasicAuthentication +Authentication will run the first time either the `request.user` or `request.auth` properties are accessed, and determines how those properties are initialized. + +## Setting the authentication policy + +The default authentication policy may be set globally, using the `DEFAULT_AUTHENTICATION_CLASSES` setting. For example. + + API_SETTINGS = { + 'DEFAULT_AUTHENTICATION_CLASSES': ( + 'djangorestframework.authentication.SessionAuthentication', + ) + } + +You can also set the authentication policy on a per-view basis, using the `APIView` class based views. + + class ExampleView(APIView): + authentication_classes = (SessionAuthentication,) + + def get(self, request, format=None): + content = { + 'user': unicode(request.user), # `django.contrib.auth.User` instance. + 'auth': unicode(request.auth), # None + } + return Response(content) + +Or, if you're using the `@api_view` decorator with function based views. + + @api_view(allowed=('GET',), authentication_classes=(SessionAuthentication,)) + def example_view(request, format=None): + content = { + 'user': unicode(request.user), # `django.contrib.auth.User` instance. + 'auth': unicode(request.auth), # None + } + return Response(content) + +## UserBasicAuthentication + +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. + +If successfully authenticated, `UserBasicAuthentication` provides the following credentials. + +* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.auth` will be `None`. ## TokenBasicAuthentication +This policy uses [HTTP Basic Authentication][basicauth], signed against a token key and secret. Token basic authentication is appropriate for client-server setups, such as native desktop and mobile clients. + +**Note:** If you run `TokenBasicAuthentication` in production your API must be `https` only, or it will be completely insecure. + +If successfully authenticated, `TokenBasicAuthentication` provides the following credentials. + +* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.auth` will be a `djangorestframework.models.BasicToken` instance. + +## OAuthAuthentication + +This policy uses the [OAuth 2.0][oauth] protocol to authenticate requests. OAuth is appropriate for server-server setups, such as when you want to allow a third-party service to access your API on a user's behalf. + +If successfully authenticated, `OAuthAuthentication` provides the following credentials. + +* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.auth` will be a `djangorestframework.models.OAuthToken` instance. + ## SessionAuthentication + +This policy uses Django's default session backend for authentication. Session authentication is appropriate for AJAX clients that are running in the same session context as your website. + +If successfully authenticated, `SessionAuthentication` provides the following credentials. + +* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.auth` will be `None`. + +## 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. + +[basicauth]: http://tools.ietf.org/html/rfc2617 +[oauth]: http://oauth.net/2/ +[permission]: permissions.md +[throttling]: throttling.md \ No newline at end of file diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index c7bae30d1..af8c4ec90 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -5,27 +5,89 @@ For example your project's `settings.py` file might look like this: API_SETTINGS = { 'DEFAULT_RENDERERS': ( - 'djangorestframework.renderers.JSONRenderer', 'djangorestframework.renderers.YAMLRenderer', ) 'DEFAULT_PARSERS': ( - 'djangorestframework.parsers.JSONParser', 'djangorestframework.parsers.YAMLParser', ) } ## DEFAULT_RENDERERS -A list or tuple of renderer classes. +A list or tuple of renderer classes, that determines the default set of renderers that may be used when returning a `Response` object. Default: ( - 'djangorestframework.renderers.JSONRenderer', - 'djangorestframework.renderers.DocumentingHTMLRenderer')` + 'djangorestframework.renderers.JSONRenderer', + 'djangorestframework.renderers.DocumentingHTMLRenderer' + 'djangorestframework.renderers.TemplateHTMLRenderer' + ) ## DEFAULT_PARSERS -A list or tuple of parser classes. +A list or tuple of parser classes, that determines the default set of parsers used when accessing the `request.DATA` property. + +Default: + + ( + 'djangorestframework.parsers.JSONParser', + 'djangorestframework.parsers.FormParser' + ) + +## DEFAULT_AUTHENTICATION + +A list or tuple of authentication classes, that determines the default set of authenticators used when accessing the `request.user` or `request.auth` properties. + +Default if `DEBUG` is `True`: + + ( + 'djangorestframework.authentication.SessionAuthentication', + 'djangorestframework.authentication.UserBasicAuthentication' + ) + +Default if `DEBUG` is `False`: + + ( + 'djangorestframework.authentication.SessionAuthentication', + ) + +## DEFAULT_PERMISSIONS Default: `()` + +## DEFAULT_THROTTLES + +Default: `()` + +## DEFAULT_MODEL_SERIALIZER + +Default: `djangorestframework.serializers.ModelSerializer` + +## DEFAULT_PAGINATION_SERIALIZER + +Default: `djangorestframework.pagination.PaginationSerializer` + +## FORMAT_SUFFIX_KWARG + +Default: `format` + +## UNAUTHENTICATED_USER_CLASS + +Default: `django.contrib.auth.models.AnonymousUser` + +## FORM_METHOD_OVERRIDE + +Default: `_method` + +## FORM_CONTENT_OVERRIDE + +Default: `_content` + +## FORM_CONTENTTYPE_OVERRIDE + +Default: `_content_type` + +## URL_ACCEPT_OVERRIDE + +Default: `_accept` diff --git a/docs/index.md b/docs/index.md index 125efa791..72e247eef 100644 --- a/docs/index.md +++ b/docs/index.md @@ -91,6 +91,7 @@ General guides to using REST framework. * [CSRF][csrf] * [Form overloading][formoverloading] +* [Contributing to REST framework][contributing] * [Credits][credits] ## Development @@ -151,10 +152,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [permissions]: api-guide/permissions.md [throttling]: api-guide/throttling.md [exceptions]: api-guide/exceptions.md -[status]: api-guide/status.md +[status]: api-guide/status-codes.md [reverse]: api-guide/reverse.md [settings]: api-guide/settings.md [csrf]: topics/csrf.md [formoverloading]: topics/formoverloading.md +[contributing]: topics/contributing.md [credits]: topics/credits.md diff --git a/docs/template.html b/docs/template.html index 2c3572e17..20b0afd45 100644 --- a/docs/template.html +++ b/docs/template.html @@ -103,6 +103,7 @@ margin-top: 5px; diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md new file mode 100644 index 000000000..cbb41f2a2 --- /dev/null +++ b/docs/topics/contributing.md @@ -0,0 +1,12 @@ +# Contributing to REST framework + +## Accessing settings + +**Describe api_settings** + +## Managing compatibility issues + +**Describe compat module** + +## Running the tests +