ACL Middleware API

Public Middleware API

ACL middleware.

aiohttp_auth.acl.acl.setup(app, groups_callback)

Setup middleware in aiohttp fashion.

Parameters:
  • app – aiohttp Application object.
  • groups_callback – This is a callable which takes a user_id (as returned from the auth.get_auth function), and expects a sequence of permitted ACL groups to be returned. This can be a empty tuple to represent no explicit permissions, or None to explicitly forbid this particular user_id. Note that the user_id passed may be None if no authenticated user exists.
aiohttp_auth.acl.acl.acl_middleware(callback)

Return ACL middleware factory.

The middleware is for use by the aiohttp application object.

Parameters:callback – This is a callable which takes a user_id (as returned from the auth.get_auth function), and expects a sequence of permitted ACL groups to be returned. This can be a empty tuple to represent no explicit permissions, or None to explicitly forbid this particular user_id. Note that the user_id passed may be None if no authenticated user exists.
Returns:A aiohttp middleware factory.
aiohttp_auth.acl.acl.get_permitted(request, permission, context)

Check permission for the given request with the given context.

Return True if the one of the groups in the request has the requested permission.

The function takes a request, a permission to check for and a context. A context is a sequence of ACL tuples which consist of a Allow/Deny action, a group, and a sequence of permissions for that ACL group. For example:

context = [(Permission.Allow, 'view_group', ('view',)),
           (Permission.Allow, 'edit_group', ('view', 'edit')),]

ACL tuple sequences are checked in order, with the first tuple that matches the group the user is a member of, and includes the permission passed to the function, to be the matching ACL group. If no ACL group is found, the function returns False.

Groups and permissions need only be immutable objects, so can be strings, numbers, enumerations, or other immutable objects.

Parameters:
  • request – aiohttp Request object.
  • permission – The specific permission requested.
  • context – A sequence of ACL tuples.
Returns:

The function gets the groups by calling get_user_groups() and returns true if the groups are Allowed the requested permission, false otherwise.

Raises:

RuntimeError – If the ACL middleware is not installed.

aiohttp_auth.acl.acl.get_user_groups(request)

Return the groups that the user in this request has access to.

This function gets the user id from the auth.get_auth function, and passes it to the ACL callback function to get the groups.

Parameters:request – aiohttp Request object.
Returns:If the ACL callback function returns None, this function returns None. Otherwise this function returns the sequence of group permissions provided by the callback, plus the Everyone group. If user_id is not None, the AuthnticatedUser group is added to the groups returned by the function.
Raises:RuntimeError – If the ACL middleware is not installed.
aiohttp_auth.acl.acl.extend_user_groups(user_id, groups)

Extend user groups with specific Groups.

Parameters:
  • user_id – User identity from get_auth.
  • groups – User groups.
Returns:

If groups is None, this function returns None. Otherwise this function extends groups with the Everyone group. If user_id is not None, the AuthnticatedUser group is added to the groups returned by the function.

aiohttp_auth.acl.acl.get_groups_permitted(groups, permission, context)

Check if one of the groups has the requested permission.

Parameters:
  • groups – A set of ACL groups.
  • permission – The specific permission requested.
  • context – A sequence of ACL tuples.
Returns:

True if the groups are Allowed the requested permission, False otherwise.

Decorators

ACL middleware decorators.

aiohttp_auth.acl.decorators.acl_required(permission, context)

Create decorator to check given permission with given context.

Return a decorator that checks if a user has the requested permission from the passed acl context.

This function constructs a decorator that can be used to check a aiohttp’s view for authorization before calling it. It uses the get_permission() function to check the request against the passed permission and context. If the user does not have the correct permission to run this function, it raises web.HTTPForbidden.

Parameters:
  • permission – The specific permission requested.
  • context – Either a sequence of ACL tuples, or a callable that returns a sequence of ACL tuples. For more information on ACL tuples, see get_permission().
Returns:

A decorator which will check the request passed has the permission for the given context. The decorator will raise HTTPForbidden if the user does not have the correct permissions to access the view.

AbstractACLGroupsCallback Class

class aiohttp_auth.acl.abc.AbstractACLGroupsCallback

Abstract base class for acl_groups_callback callabel.

User should create class deriving from this one, override acl_groups method and register object of that class with setup function as acl_groups_callback.

Usage example:

class ACLGroupsCallback(AbstractACLGroupsCallback):

    def __init__(self, cache):
        # store some kind of cache
        self.cache = cache

    async def acl_groups(self, user_id):
        # implement logic to return user's groups.
        user = await self.cache.get(user_id)
        return user.groups()


def init(loop):
    app = web.Application(loop=loop)
    ...
    cache = ...
    acl_groups_callback = ACLGroupsCallback(cache)

    acl.setup(app, acl_groups_callback)
    ...
acl_groups(user_id)

Return ACL groups for given user identity.

Note that the ACL groups returned by this method will be modified by the acl_middleware to also include the Group.Everyone group (if the value returned is not None), and also the Group.AuthenticatedUser if the user_id is not None.

Parameters:user_id – User identity (as returned from the auth.get_auth function). Note that the user_id passed may be None if no authenticated user exists.
Returns:A sequence of permitted ACL groups. This can be a empty tuple to represent no explicit permissions, or None to explicitly forbid this particular user_id.