Skip to main content

What Are Roles?

Roles are what Devii uses for "groups" and "users". A role can describe either one login, group together a set of logins, or both. Every user of a Devii tenant schema will access data through a role, describing the capabilities of that role in terms of allowed operations, as well as determining access to data objects.

Roles have several attributes: aside from the standard ID, name, and creation time, a role has a passkey, a parent ID (can be null), creator ID (will be set to a special value for the "initial" role for a tenant), capabilities, and optionally, role classes. Each of these are explained below.

Capabilities​

Capabilities govern the "powers" a role has in the Devii system. A capability represents the ability to perform an operation or set of operations. Capabilities should govern operations that change the state of a tenant schema and its data; there is no need for capabilites to read data (that is governed by access controls). A role with no capabilities is "read-only", able only to access the data objects to which it has ACLs; the access controls for such a role are all treated as read-only, regardless of whether or not they grant modify or append rights.

The list of capabilities is as follows:

  • login: Ability to authenticate and receive login tokens

  • select: Query tables

  • insert: Add new rows

  • update: Update rows

  • delete: Delete rows.

  • upload: If multimedia package is enabled, upload files to file storage.

  • download: If multimedia package is enabled, download files from file storage.

  • create_role: Create new roles

  • update_role: Update roles

  • delete_role: Delete roles.

  • view_role: View role data (other than self and children)

  • create_class: Create new role classes

  • update_class: Update role classes

  • delete_class: Delete role classes

  • view_class: View role class data for non-member classes

  • admin: Tenant admin (bypasses rules within tenancy)

NB: Roles which have the capability to modify other roles can modify those other roles' capabilities if they are child roles, or if the role has the admin flag; however, no role is allowed to modify its own capabilities.

Hierarchies​

Roles can be, but do not need to be, nested. A given role can have at most one parent, but an arbitrary number of children, both directly and through intermediate roles.

When using hierarchical roles, role visibility is governed (mostly) by the role hierarchy: a role can only see its parent role and/or sibling roles (descended from the same parent) if allowed by the parent; roles can automatically see any child roles.

The ability to create, update, or delete roles is governed by policy rules; a given role must have the named capability, and must also be within the scope for a policy rule that allows the role to manipulate roles. The target for this rule must be "roles". The rule may be filtered, in which case only roles that match the filter may be operated on.

A role with the 'admin' capability bypasses this restriction, and is, in fact, the 'root' equivalent for the tenant; 'admin' roles must be treated specially, like the root account on a Unix system, and using them for normal work is not recommended.

Role Passwords​

roleid: Role identifier. Foreign key to the roles table.

salt: Randomly-generated salt for password.

hash: Hash value of password + salt. Hashed via SHA-512.

createtime: Timestamp password was created.

setby: RoleID of the role that set this password. Useful for detecting whether a password was system-generated and needs changing.

Role Attributes​

roleid: Role identifier. Integer. Unique within an installation.

login: Role login name. Restricted to valid characters for an email address, although it is not required to be an email address. Unique within schema.

name: Role name. This is a freeform name, and can be anything.

parentid: Role parent. Integer. ID of the parent role. Can be null, in which case this role has no parent.

creatorid: Role creator. Integer. ID of the role that created this role. May be 0, in which case the role was created by the system.

createtime: Timestamp for role creation. Timestamp appropriate to the database system.

capabilities: Role capability flags. Probably stored in a subtable. Capability flags will be character strings, strictly defined in a special table.

classes: Role classes. Subtable. This is a list of class identifiers. Each role class will be defined in a separate table.