API Docs

Invenio module for common role based access control.

class invenio_access.ext.InvenioAccess(app=None, **kwargs)

Invenio Access extension.

Extension initialization.

Parameters:app – The Flask application. (Default: None)

init_app(app, entry_point_actions='invenio_access.actions', entry_point_system_roles='invenio_access.system_roles', **kwargs)

Flask application initialization.

Parameters:

• app – The Flask application.
• entry_point_actions – The entrypoint for actions extensions. (Default: 'invenio_access.actions')
• entry_point_system_roles – The entrypoint for system roles extensions. (Default: 'invenio_access.system_roles')
• cache – The cache system. (Default: None)

init_config(app)

Initialize configuration.

Parameters:app – The Flask application.

Action factory

Factory method for creating new action needs.

invenio_access.factory.action_factory(name, parameter=False)

Factory method for creating new actions (w/wo parameters).

Parameters:

• name – Name of the action (prefix with your module name).
• parameter – Determines if action should take parameters or not. Default is False.

Permissions

class invenio_access.permissions.Permission(*needs)

Represents a set of required needs.

Extends Flask-Principal’s flask_principal.Permission with support for loading action grants from the database including caching support.

Essentially the class works as a translation layer that expands action needs into a list of user/roles needs. For instance, take the following permission:

Permission(ActionNeed('my-action'))

Once the permission is checked with an identity, the class will fetch a list of all users and roles that have been granted/denied access to the action, and expand the permission into something similar to (depending on the state of the database):

Permission(UserNeed('1'), RoleNeed('admin'))

The expansion is cached until the action is modified (e.g. a user is granted access to the action). The alternative approach to expanding the action need like this class is doing, would be to load the list of allowed actions for a user on login and cache the result. However retrieving all allowed actions for a user could results in very large lists, where as caching allowed users/roles for an action would usually yield smaller lists (especially if roles are used).

Initialize permission.

Parameters:*needs – The needs for this permission.

allow_by_default = False

If enabled, all permissions are granted when they are not assigned to anybody. Disabled by default.

excludes

Return denied permissions from database.

Returns:A list of need instances.

needs

Return allowed permissions from database.

Returns:A list of need instances.

Needs

invenio_access.permissions.ParameterizedActionNeed = <functools.partial object>

A need having the method preset to “action” and a parameter.

If it is called with argument=None then this need is equivalent to ActionNeed.

invenio_access.permissions.SystemRoleNeed = <functools.partial object>

A need with the method preset to “system_role”.

System roles

invenio_access.permissions.any_user = Need(method='system_role', value='any_user')

Any user system role.

This role is used to assign all possible users (authenticated and guests) to an action.

invenio_access.permissions.authenticated_user = Need(method='system_role', value='authenticated_user')

Authenticated user system role.

This role is used to assign all authenticated users to an action.

invenio_access.loaders.load_permissions_on_identity_loaded = <function load_permissions_on_identity_loaded>

Add system roles “Needs” to users’ identities.

Every user gets the any_user Need. Authenticated users get in addition the authenticated_user Need.

Actions

invenio_access.permissions.superuser_access = Need(method='action', value='superuser-access')

Superuser access aciton which allow access to everything.

Models

Database models for access module.

class invenio_access.models.ActionNeedMixin

Define common attributes for Action needs.

action = Column(None, String(length=80), table=None)

Name of the action.

classmethod allow(action, **kwargs)

Allow the given action need.

Parameters:action – The action to allow. Returns:A invenio_access.models.ActionNeedMixin instance.

argument = Column(None, String(length=255), table=None)

Action argument.

classmethod create(action, **kwargs)

Create new database row using the provided action need.

Parameters:

• action – An object containing a method equal to 'action' and a value.
• argument – The action argument. If this parameter is not passed, then the action.argument will be used instead. If the action.argument does not exist, None will be set as argument for the new action need.

Returns:

An invenio_access.models.ActionNeedMixin instance.

classmethod deny(action, **kwargs)

Deny the given action need.

Parameters:action – The action to deny. Returns:A invenio_access.models.ActionNeedMixin instance.

exclude = Column(None, Boolean(name='exclude'), table=None, nullable=False, default=ColumnDefault(False), server_default=DefaultClause('0', for_update=False))

If set to True, deny the action, otherwise allow it.

id = Column(None, Integer(), table=None, primary_key=True, nullable=False)

Primary key. It allows the other fields to be nullable.

need

Return the need corresponding to this model instance.

This is an abstract method and will raise NotImplementedError.

classmethod query_by_action(action, argument=None)

Prepare query object with filtered action.

Parameters:

• action – The action to deny.
• argument – The action argument. If it’s None then, if exists, the action.argument will be taken. In the worst case will be set as None. (Default: None)

Returns:

A query object.

class invenio_access.models.ActionRoles(**kwargs)

ActionRoles data model.

It relates an allowed action with a role.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

need

Return RoleNeed instance.

class invenio_access.models.ActionSystemRoles(**kwargs)

ActionSystemRoles data model.

It relates an allowed action with a predefined role. Example: “any user”

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

classmethod create(action, **kwargs)

Create new database row using the provided action need.

need

Return the corresponding Need instance.

validate_role_name(key, role_name)

Checks that the role name has been registered.

class invenio_access.models.ActionUsers(**kwargs)

ActionUsers data model.

It relates an allowed action with a user.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

need

Return UserNeed instance.

invenio_access.models.changed_action(mapper, connection, target)

Remove the action from cache when an item is updated.

invenio_access.models.get_action_cache_key(name, argument)

Get an action cache key string.

invenio_access.models.removed_or_inserted_action(mapper, connection, target)

Remove the action from cache when an item is inserted or deleted.

Utils

Utility functions for Invenio-Access.

invenio_access.utils.get_identity(user)

Create an identity for a given user instance.

Primarily useful for testing.

Proxies

Helper proxy to the state object.

invenio_access.proxies.current_access = <LocalProxy unbound>

Helper proxy to access state object.

CLI

Command line interface for Invenio-Access.

invenio_access.cli.lazy_result(f)

Decorate function to return LazyProxy.

invenio_access.cli.process_action(ctx, param, value)

Return an action if exists.

invenio_access.cli.process_allow_action(*args, **kwargs)

Process allow action.

invenio_access.cli.process_deny_action(*args, **kwargs)

Process deny action.

invenio_access.cli.process_email(ctx, param, value)

Return an user if it exists.

invenio_access.cli.process_remove_action(*args, **kwargs)

Process action removals.

invenio_access.cli.process_role(ctx, param, value)

Return a role if it exists.

invenio_access.cli.allow_action = <Group allow>

Allow action.

invenio_access.cli.deny_action = <Group deny>

Deny actions.

invenio_access.cli.list_actions = <Command list>

List all registered actions.