django-oso API Reference

Authorization

django_oso.auth.authorize(request, resource, *, actor=None, action=None)

Authorize request for resource, actor and action.

Calls oso.Oso.is_allowed() with the corresponding arguments. If authorization fails, raises a django.core.exceptions.PermissionDenied exception.

Parameters
  • actor – The actor making the request. Defaults to request.user.

  • action – The action to authorize the actor to perform. Defaults to request.method.

  • resource – The resource to authorize the actor to access.

Raises

django.core.exceptions.PermissionDenied – If the request is not authorized.

See django_oso.decorators.authorize() for view decorator version of this function.

django_oso.auth.skip_authorization(request)

Mark request as not requiring authorization.

Use with the django_oso.middleware.RequireAuthorization() middleware to silence missing authorization errors.

See django_oso.decorators.skip_authorization() for view decorator version of this function.

Middleware

class django_oso.middleware.ReloadPolicyMiddleware(get_response)

Reloads all oso policies on every request when in DEBUG mode

class django_oso.middleware.RequireAuthorization(get_response)

Check that authorize was called during the request.

Raises

oso.OsoError – If authorize was not called during request processing.

Warning

This check is performed at the end of request processing before returning a response. If any database modifications are committed during the request, but it was not authorized, an OsoError will be raised, but the database modifications will not be rolled back.

class django_oso.middleware.RouteAuthorization(get_response)

Perform route authorization on every request.

A call to authorize() will be made before view functions are called with the parameters actor=request.user, action=request.method, resource=request.

Rules in oso policies can be written over requests using the HttpRequest specializer:

allow(actor, action, resource: HttpRequest) if
    # Access request properties to perform authorization
    request.path = "/";

Note

If the view returns a 4**, or 5** HTTP status, this will be returned to the end user even if authorization was not performed.

View Decorators

django_oso.decorators.authorize(view_func=None, resource=None, actor=None, action=None)

Authorize view for resource, actor, and action.

All three parameters must be constant for this decorator to be used. If actor or action are omitted, the defaults from django_oso.auth.authorize(). are used.

django_oso.decorators.authorize_request(view_func=None, actor=None, action=None)

Authorize the view function, using the request as the resource.

This performs route authorization, similarly to RouteAuthorization, but on a single view.

django_oso.decorators.skip_authorization(view_func)

View-decorator that marks a view as not requiring authorization.

Use in combination with django_oso.middleware.RequireAuthorization(). Some views will not require authorization. This decorator marks those views so that the middleware can skip the check.

List endpoint authorization

The oso Django integration includes list filtering support for Django models.

Note

These features are in preview and will be stabilized in a future release. Please join our Slack to provide feedback or discuss with the engineering team.

Usage

See the list filtering usage guide for more information.

API Reference

django_oso.auth.authorize_model(request, model, *, actor=None, action=None)django.db.models.query_utils.Q

Authorize request for django model model, actor, and action.

Warning

This feature is currently in preview.

Partially evaluates the Polar rule allow(actor, action, Variable(model)). If authorization fails, raises a django.core.exceptions.PermissionDenied exception.

Otherwise, returns a django Q object representing a filter that must be applied to model. This object can be applied to filter query results to only contain authorized objects.

For example:

post_filter = authorize_model(request, Post)
authorized_posts = Post.objects.filter(post_filter)

See also:

Parameters
  • actor – The actor making the request. Defaults to request.user.

  • action – The action to authorize the actor to perform. Defaults to request.method.

  • model – The model to authorize access for.

Raises

django.core.exceptions.PermissionDenied – If the request is not authorized.

Returns

A django Q object representing the authorization filter.

class django_oso.models.AuthorizedModel(*args, **kwargs)

Use a manager based on AuthorizedQuerySet, allowing the authorize() method to be used.

Warning

This feature is currently in preview.

class django_oso.models.AuthorizedQuerySet(model=None, query=None, using=None, hints=None)

QuerySet with authorize() method.

Oso

django_oso.oso.Oso = <oso.oso.Oso object>

Singleton oso.Oso instance.

Use for loading policy files and registering classes.