Permissions API

Last Updated: May 28, 2016

Permissions allow you to restrict access to certain features or content of your app. We recommend creating permissions for specific tasks or features of your app (e.g.: "Can view the map" or "Can delete projects") and then define groups of permissions to create the roles for you app.

Create Permissions and Permission Groups

Declare the permissions method in the app class and have it return a list or tuple of Permission and/or PermissionGroup objects. Permissions are synced everytime you start or restart the development server (i.e.: tethys manage start) or Apache server in production.

Once you have created permissions and permission groups for your app, they will be available for the Tethys Portal administrator to assign to users. See the Auth Token documentation for more details.

TethysAppBase.permissions()

Override this method to define permissions for your app.

Returns:

A list or tuple of Permission or PermissionGroup objects.

Return type:

iterable

Example:

python
from tethys_sdk.permissions import Permission, PermissionGroup

class MyFirstApp(TethysAppBase):

    def permissions(self):
        """
        Example permissions method.
        """
        # Viewer Permissions
        view_map = Permission(
            name='view_map',
            description='View map'
        )

        delete_projects = Permission(
            name='delete_projects',
            description='Delete projects'
        )

        create_projects = Permission(
            name='create_projects',
            description='Create projects'
        )

        admin = PermissionGroup(
            name='admin',
            permissions=(delete_projects, create_projects)
        )


        permissions = (admin, view_map)

        return permissions

Permission and Permission Group Objects

class tethys_sdk.permissions.Permission(name, description)

Defines an object that represents a permission for an app.

name

The code name for the permission. Only numbers, letters, and underscores allowed.

Type:

string

description

Short description of the permission for the admin interface.

Type:

string

Example:

python
from tethys_sdk.permissions import Permission

create_projects = Permission(
    name='create_projects',
    description='Create projects'
)
class tethys_sdk.permissions.PermissionGroup(name, permissions=None)

Defines an object that represents a permission group for an app.

name

The name for the group. Only numbers, letters, and underscores allowed.

Type:

string

permissions

A list or tuple of Permission objects.

Type:

iterable

Example:

python
from tethys_sdk.permissions import Permission, PermissionGroup

create_projects = Permission(
    name='create_projects',
    description='Create projects'
)

delete_projects = Permission(
    name='delete_projects',
    description='Delete projects'
)

admin = PermissionGroup(
    name='admin',
    permissions=(create_projects, delete_projects)
)

Check Permission

Use the has_permission method to check whether the user of the current request has a permission.

permissions.has_permission(perm, user=None)

Returns True if the user of the given request has the given permission for the app. If a user object is provided, it is tested instead of the request user. The Request object is still required to derive the app context of the permission check.

Parameters:
  • request (Request) -- The current request object.

  • perm (string) -- The name of the permission (e.g. 'create_things').

  • user (django.contrib.auth.models.User) -- A user object to test instead of the user provided in the request.

Example:

python
from tethys_sdk.permissions import has_permission

def my_controller(request):
    """
    Example controller
    """

    can_create_projects = has_permission(request, 'create_projects')

    if can_create_projects:
        ...

Controller Decorator

Use the permission_required decorator to enforce permissions for an entire controller.

permissions.permission_required(**kwargs)

Decorator for Tethys App controllers that checks whether a user has a permission.

Parameters:
  • *args -- Any number of permission names for the app (e.g. 'create_projects')

  • **kwargs -- Any of keyword arguments specified below.

Valid Kwargs:

  • message: (string): Override default message that is displayed to user when permission is denied. Default message is "We're sorry, but you are not allowed to perform this operation.".

  • raise_exception (bool): Raise 403 error if True. Defaults to False.

  • use_or (bool): When multiple permissions are provided and this is True, use OR comparison rather than AND comparison, which is default.

Example:

python
from tethys_sdk.permissions import permission_required

# Basic use
@permission_required('create_projects')
def my_controller(request):
    """
    Example controller
    """
    ...

# Custom message when permission is denied
@permission_required('create_projects', message="You do not have permission to create projects")
def my_controller(request):
    """
    Example controller
    """
    ...

# Multiple permissions with AND comparison (must pass both permissions tests)
@permission_required('create_projects', 'delete_projects')
def my_controller(request):
    """
    Example controller
    """
    ...

# Multiple permissions with OR comparison (must pass at least one permissions test)
@permission_required('create_projects', 'delete_projects', use_or=True)
def my_controller(request):
    """
    Example controller
    """
    ...

# Raise 403 exception rather than redirecting and displaying message (useful for REST controllers).
@permission_required('create_projects', raise_exception=True)
def my_controller(request):
    """
    Example controller
    """
    ...