Role-based Authorization

Authorization is the process of specifying and enforcing access rights of users to resources.

Flask-User offers role-based authorization through the use of the @roles_required decorator.


If a view function is decorated with the @roles_required decorator, the user:

  • must be logged in, and
  • must be associated with the specified role names.

If any of these conditions is not met, an ‘Unauthorized access’ error message will be shown and the user will be redirected to the USER_UNAUTHORIZED_ENDPOINT.

In the example below the current user is required to be logged in and to be associated with the role named ‘Admin’:

from flask_user import roles_required

@route('/admin/dashboard')    # @route() must always be the outer-most decorator
def admin_dashboard():
    # render the admin dashboard

Note: Comparison of role names is case sensitive, so 'Admin' will NOT match 'admin'.

Simple AND/OR operations

The @roles_required decorator accepts one or more role names. At the decorator level, if multiple role names are specified here, the user must have all the specified roles. This is the AND operation.

At the argument level, each item may be a role name or a list or role names. If a list of role names is specified here, the user mast have any one of the specified roles to gain access. This is the OR operation.

In the example below, the user must always have the 'Starving' role, AND either the 'Artist' role OR the 'Programmer' role:

# Ensures that the user is ('Starving' AND (an 'Artist' OR a 'Programmer'))
@roles_required('Starving', ['Artist', 'Programmer'])

Note: The nesting level only goes as deep as this example shows.

Required Role and UserRoles data-models

The @roles_required decorator depends the Role and UserRoles data-models (in addition to the User data-model).

See the docs on Role and UserRoles data-models.

Example App

The Basic App demonstrates the use of the @roles_required decorator.