diff options
Diffstat (limited to 'api-guide/permissions/index.html')
| -rw-r--r-- | api-guide/permissions/index.html | 13 |
1 files changed, 11 insertions, 2 deletions
diff --git a/api-guide/permissions/index.html b/api-guide/permissions/index.html index a8a8ecd3..893d3957 100644 --- a/api-guide/permissions/index.html +++ b/api-guide/permissions/index.html @@ -459,10 +459,19 @@ </blockquote> <p>Together with <a href="../authentication">authentication</a> and <a href="../throttling">throttling</a>, permissions determine whether a request should be granted or denied access.</p> <p>Permission checks are always run at the very start of the view, before any other code is allowed to proceed. Permission checks will typically use the authentication information in the <code>request.user</code> and <code>request.auth</code> properties to determine if the incoming request should be permitted.</p> +<p>Permissions are used to grant or deny access different classes of users to different parts of the API.</p> +<p>The simplest style of permission would be to allow access to any authenticated user, and deny access to any unauthenticated user. This corresponds the <code>IsAuthenticated</code> class in REST framework.</p> +<p>A slightly less strict style of permission would be to allow full access to authenticated users, but allow read-only access to unauthenticated users. This corresponds to the <code>IsAuthenticatedOrReadOnly</code> class in REST framework.</p> <h2 id="how-permissions-are-determined">How permissions are determined</h2> <p>Permissions in REST framework are always defined as a list of permission classes.</p> <p>Before running the main body of the view each permission in the list is checked. -If any permission check fails an <code>exceptions.PermissionDenied</code> exception will be raised, and the main body of the view will not run.</p> +If any permission check fails an <code>exceptions.PermissionDenied</code> or <code>exceptions.NotAuthenticated</code> exception will be raised, and the main body of the view will not run.</p> +<p>When the permissions checks fail either a "403 Forbidden" or a "401 Unauthorized" response will be returned, according to the following rules:</p> +<ul> +<li>The request was successfully authenticated, but permission was denied. <em>— An HTTP 403 Forbidden response will be returned.</em></li> +<li>The request was not successfully authenticated, and the highest priority authentication class <em>does not</em> use <code>WWW-Authenticate</code> headers. <em>— An HTTP 403 Forbidden response will be returned.</em></li> +<li>The request was not successfully authenticated, and the highest priority authentication class <em>does</em> use <code>WWW-Authenticate</code> headers. <em>— An HTTP 401 Unauthorized response, with an appropriate <code>WWW-Authenticate</code> header will be returned.</em></li> +</ul> <h2 id="object-level-permissions">Object level permissions</h2> <p>REST framework permissions also support object-level permissioning. Object level permissions are used to determine if a user should be allowed to act on a particular object, which will typically be a model instance.</p> <p>Object level permissions are run by REST framework's generic views when <code>.get_object()</code> is called. @@ -526,7 +535,7 @@ def example_view(request, format=None): <p>This permission is suitable if you want your API to only be accessible to registered users.</p> <h2 id="isadminuser">IsAdminUser</h2> <p>The <code>IsAdminUser</code> permission class will deny permission to any user, unless <code>user.is_staff</code> is <code>True</code> in which case permission will be allowed.</p> -<p>This permission is suitable is you want your API to only be accessible to a subset of trusted administrators.</p> +<p>This permission is suitable if you want your API to only be accessible to a subset of trusted administrators.</p> <h2 id="isauthenticatedorreadonly">IsAuthenticatedOrReadOnly</h2> <p>The <code>IsAuthenticatedOrReadOnly</code> will allow authenticated users to perform any request. Requests for unauthorised users will only be permitted if the request method is one of the "safe" methods; <code>GET</code>, <code>HEAD</code> or <code>OPTIONS</code>.</p> <p>This permission is suitable if you want to your API to allow read permissions to anonymous users, and only allow write permissions to authenticated users.</p> |