flask-oso API Reference

class flask_oso.FlaskOso(oso: Optional[Oso] = None, app: Optional[Flask] = None)

oso flask plugin

This plugin must be initialized with a flask app, either using the app parameter in the constructor, or by calling init_app() after construction.

The plugin must be initialized with an oso.Oso instance before use, either by passing one to the constructor or calling set_oso().

Authorization

  • FlaskOso.authorize(): Check whether an actor, action and resource is authorized. Integrates with flask to provide defaults for actor & action.

Configuration

authorize(resource: Any, *, actor: Optional[Any] = None, action: Optional[str] = None) → None

Check whether the current request should be allowed.

Calls oso.Oso.is_allowed() to check authorization. If a request is unauthorized, raises a werkzeug.exceptions.Forbidden exception. This behavior can be controlled with set_unauthorized_action().

Parameters:

  • actor – The actor to authorize. Defaults to flask.g.current_user. Use set_get_actor() to override.

  • action – The action to authorize. Defaults to flask.request.method.

  • resource – The resource to authorize. The flask request object (flask.request) can be passed to authorize a request based on route path or other request properties.

See also: flask_oso.authorize() for a route decorator version.

init_app(app: Flask) → None

Initialize app for use with this instance of FlaskOso.

Must be called if app isn’t provided to the constructor.

perform_route_authorization(app: Optional[Flask] = None) → None

Perform route authorization before every request.

Route authorization will call oso.Oso.is_allowed() with the current request (from flask.request) as the resource and the method (from flask.request.method) as the action.

Parameters:

app – The app to require authorization for. Can be omitted if the app parameter was used in the FlaskOso constructor.

require_authorization(app: Optional[Flask] = None) → None

Enforce authorization on every request to app.

Parameters:

app – The app to require authorization for. Can be omitted if the app parameter was used in the FlaskOso constructor.

If FlaskOso.authorize() is not called during the request processing, raises an oso.OsoError.

Call FlaskOso.skip_authorization() to skip this check for a particular request.

set_get_actor(func: Callable[[], Any]) → None

Provide a function that oso will use to get the current actor.

Parameters:

func – A function to call with no parameters to get the actor if it is not provided to FlaskOso.authorize(). The return value is used as the actor.

set_oso(oso: Oso) → None

Set the oso instance to use for authorization

Must be called if oso is not provided to the constructor.

set_unauthorized_action(func: Callable[[], Any]) → None

Set a function that will be called to handle an authorization failure.

The default behavior is to raise a Forbidden exception, returning a 403 response.

Parameters:

func – A function to call with no parameters when a request is not authorized.

skip_authorization(reason: Optional[str] = None) → None

Opt-out of authorization for the current request.

Will prevent require_authorization from causing an error.

See also: flask_oso.skip_authorization() for a route decorator version.

flask_oso.authorize(func=None, resource=None, actor=None, action=None)

Flask route decorator. Calls FlaskOso.authorize() before the route.

Parameters are the same as FlaskOso.authorize().

Warning

This decorator must come after the route decorator as shown below, otherwise authorization will not be checked.

For example:

@app.route("/")
@authorize(resource=flask.request)
def route():
    return "authorized"
flask_oso.skip_authorization(func=None, reason=None)

Decorator to mark route as not requiring authorization.

Warning

This decorator must come after the route decorator.

Causes use in conjunction with FlaskOso.require_authorization() to silence errors on routes that do not need to be authorized.