Hierarchy, rights and authorization

Hierarchies help make information easier to find and understand. For example, most websites use breadcrumbs to show you where you are. Your computer probably has a bunch of drives and deeply nested folders that contain files. We generally use these hierarchical elements to keep data organized, and to keep a tighter grip on rights management. For example, sharing a specific folder with a team, but a different folder could be private.

Although you are free to use Atomic Data with your own custom authorization system, we have a standardized model that is currently being used by Atomic-Server.

Design goals

  • Fast. Authorization can sometimes be costly, but in this model we'll be considering performance.
  • Simple. Easy to understand, easy to implement.
  • Handles most basic use-cases. Should deal with basic read / write access control, calculating the size of a folder, rendering things in a tree.

Atomic Hierarchy Model

  • Every Resource SHOULD have a parent. There are some exceptions to this, which are discussed below.
  • Any Resource can be a parent of some other Resource, as long as both Resources exists on the same Atomic Server.
  • Grants / rights given in a parent also apply to all children, and their children.
  • There are few Classes that do not require parents:

Authorization

  • Any Resource might have read and write Atoms. These both contain a list of Agents. These Agents will be granted the rights to edit (using Commits) or read / use the Resources.
  • Rights are additive, which means that the rights add up. If a Resource itself has no write Atom containing your Agent, but it's parent does have one, you will still get the write right.
  • Rights cannot be removed by children or parents - they can only be added.
  • Commits can not be edited. They can be read if the Agent has rights to read the subject of the Commit.

Top-level resources

Some resources are special, as they do not require a parent:

  • Drives are top-level items in the hierarchy: they do not have a parent.
  • Agents are top-level items because they are not owned by anything. They can always read and write themselves.
  • Commits are immutable, so they should never be edited by anyone. That's why they don't have a place in the hierarchy. Their read rights are determined by their subject.

Authentication

Authentication is about proving who you are, which is often the first step for authorization. See authentication.

Current limitations of the Authorization model

The specification is growing (and please contribute in the docs repo), but the current specification lacks some features:

  • Rights can only be added, but not removed in the hierarchy. This means that you cannot have a secret folder inside a public folder.
  • No model for representing groups of Agents, or other runtime checks for authorization. (issue)
  • No way to limit delete access or invite rights separately from write rights (issue)
  • No way to request a set of rights for a Resource