Permissions and roles

A permission is the smallest thing that can be allowed. It is a name in the form <namespace>.<action>, with more segments if the product wants them.

• eidos.document.read
• eidos.document.sign
• eidos.folder.manage

The first segment is the namespace: the short name of the product that owns the permission. Only that product can define permissions in its own namespace, so one product cannot invent a permission that looks like another's.

Rules for a permission name:

• Lowercase letters, digits and underscores in each segment, each starting with a letter.
• Segments are separated by dots, at least two of them, up to 96 characters in all.
• Once defined, a permission's meaning never changes. A product that no longer wants one marks it deprecated. A deprecated permission still matches, so existing assignments keep working, but each use is recorded.

The names authz and identity are reserved for identity's own permissions.

What a permission declares#

When a product registers a permission, it also declares two properties.

A product sets a stricter value for a dangerous action, such as signing a document, than for a harmless one, such as reading.

A role may hold a pattern that ends in .*, which covers every permission under that prefix. eidos.* covers eidos.document.read and eidos.folder.manage. A wildcard needs at least one more segment after the prefix, so it never covers a bare namespace. A question always names a concrete permission, never a pattern.

The reserved namespaces are the exception. A wildcard never covers a permission in authz or identity. Those have to be given by name.

A role is a named bundle of permissions, defined by the product. A role might be editor or admin. Giving someone a role is shorter and safer than giving them every permission one by one.

A product's role names use lowercase letters, digits, underscores, dots and hyphens, start with a letter and run to at most 64 characters.

An organization can also write custom roles of its own. A custom role is a bundle of concrete permissions, never a pattern, each one a permission that exists, is not deprecated and belongs to a product installed in that organization or to the reserved identity namespace. Writing a custom role grants nothing by itself: it only becomes authority when someone is given it, and the usual limits below apply to that. If the organization later narrows what a product may do there, the permission stops working without the role being touched. An organization has a limited number of custom roles, and the platform's own organization has none.

A role is versioned. When a product changes what a role contains, the role gets a new version, and the people who hold the old version keep it until they are moved to the new one. Changing a role therefore never silently widens what someone holds.

There are two kinds of assignment, and both are limited to one organization. An assignment can be made to a person, to a group in the organization, or to a membership set, such as the guests of the organization. Group members hold what the group holds, and groups can nest. Adding someone to a group counts as giving them everything the group holds, so the person adding must be able to give all of it.

Every assignment has the following.

• A scope. Either the whole organization, or one resource. A resource scope covers that resource and everything inside it.
• An expiry. Optional. An assignment with no expiry lasts until it is revoked. One with an expiry stops being effective at that time.
• A delegation flag. Whether the holder may pass the authority on.
• A reason and a record. Who granted it, and when. Assignments are never edited. A change is a new assignment, and the old one is revoked, so the history is kept.

A guest is held to more. Authority for a guest is anchored to their sponsor, so it cannot exceed what the sponsor could give, it is never delegable, it ends no later than the guest membership, and a guest never holds a high-risk permission. A guest also cannot author an assignment to a group or membership set.

Membership comes first. A person with no active membership in an organization holds nothing in it, whatever assignments were made. See Memberships and invitations. Removing a membership also removes the assignments held in that organization.

Authority can be delegated, but it can only be narrowed. Whoever creates an assignment must hold the authority being given, and must hold it in a delegable form. They cannot create a delegable assignment from one that is not delegable. A delegated assignment is only effective while the one it came from is, and it cannot outlast it. If the original is revoked or expires, everything delegated from it falls away.

This is why an invitation that carries a role is assigned on the inviter's authority. If the inviter could not hand out that role, the invitee still joins but without it.

Products can also register resources, for example a document, and say what they sit inside, for example a folder in a workspace. Resources form a tree to a limited depth. An assignment scoped to a folder reaches the documents in it.

A product can also describe relations between a person and a resource, for example owner or viewer, and say which permissions each relation implies. A relation can include another, such as an editor also being a viewer, or be inherited from a parent. Relations can only add. Anything that says no is a policy. See Authorization.

A scope is what an application is allowed to ask to see for a person. A permission is what a person is allowed to do in a product. A product scope on the consent screen links the two: it lets an application use your permissions in a product, and never more than your role there allows. See Scopes and consent.

• Authorization
• Delegation and token exchange
• Organizations