Handling permissions

Principals

A principal, is an entity that can be authenticated by a computer system. It is the actor who does the action. [1]

It could either be someone, a computer, a service or a group of any of such things. This is conceptually wider than the classical "user id*".

Permissions are then associated to these principals.

For instance, a user is identified in an unique way when he connects to the authentication system, which role is to define a list of principals for the authenticating user.

The difference between a role and a group

From scratch, it's not easy to precisely define the difference between these two concepts which allow to associate permissions to a group of principals. [2]

The difference is mainly semantic, but we can see a difference in the "direction" of the relationship between these two concepts.

• A role is a list of permissions associated to a principal;
• A group is a list of principals we can associate to a permission.

The difference between permission, ACL and ACE

An ACL is a list of Access Control Entry (ACE) enabling or disabling acces rights to a person or a group.

—https://en.wikipedia.org/wiki/Access_Control_List

I would even say, in our case, "to a principal". For instance:

create_record: alexis,remy,tarek

This ACE gives the create permission on the record object to the users Tarek, Rémy and Alexis.

Manipulated objects

To handle permissions, we identified the following objects:

To define ACLs, there is a hierarchy: objects inherit the ACLs from their parents.

           +---------------+
           | Bucket        |
           +---------------+
    +----->+ - id          +<---+
    |      | - permissions |    |
    |      +---------------+    |
    |                           |
    |                           |
    |                           |
    |                           |
    |                           |
+---+-----------+        +------+---------+
| Collection    |        | Group          |
+---------------+        +----------------+
| - id          |        |  - id          |
| - permissions |        |  - members     |
+------+--------+        |  - permissions |
       ^                 +----------------+
       |
       |
+------+---------+
| Record         |
+----------------+
|  - id          |
|  - data        |
|  - permissions |
+----------------+

Permissions

For all of these objects, we identified the following permissions:

To each specified permission on an object is associated a list of principals.

For the create permission, we are forced to specify which child the permission applies to since an object can have different kind of child nodes. For instance: collections:create, groups:create.

We don't have a delete and update permission so far, because we don't have any use case which needs them. Whoever with the write permission can also delete a record.

Permissions from an object are inherited from its parent. For instance, a record created in a collection available to anyone will also be available to anyone.

Said differently, it's not possible that an object has a more restrictive permission that its parent.

Here is a complete list of permissions:

principals

Actors connecting to the storage service can authenticate themselves.

They then receive a list of principals:

• Everyone: the principal given to all actors (authenticated or not);
• Authenticated: the principal given to all authenticated actors;
• A principal identifying the actor, for instance fxa:32aa95a474c984d41d395e2d0b614aa2

In order to avoid identifiers collisions, the actor principal is built from the authentication type used (system, basic, ipaddr, hawk, fxa) and the identifier.

Depending the bucket on which the action is taking place, the groups the user is a member of are also added to her list of principals (e.g. group:moderators)

So, if Bob connects with his Firefox Account on the servicedenuages_blog bucket, on which he is a member of the moderators group, he would have the following list of principals: Everyone, Authenticated, fxa:32aa95a474c984d41d395e2d0b614aa2, group:moderators

It's then possible to assign a permission to Bob by using one of these principals.

A few examples

Blog

Wiki

Polls

Collaborative maps

Platforms

Of course, there are many ways to modelize common use cases. For instance, it's possible to imagine a wiki platform (ala wikia.com) where wikis are private by default and some pages can be published:

The HTTP API

During the creation of an object, the user is given the write permission on the object:

PUT /v1/buckets/servicedenuages_blog HTTP/1.1
Authorization: Bearer 0b9c2625dc21ef05f6ad4ddf47c5f203837aa32ca42fced54c2625dc21efac32
Accept: application/json

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "id": "servicedenuages_blog",
    "permissions": {
        "write": ["fxa:49d02d55ad10973b7b9d0dc9eba7fdf0"]
    }
}

It's possible to add permissions using the PATCH HTTP method.

PATCH /v1/buckets/servicedenuages_blog/collections/articles HTTP/1.1
Authorization: Bearer 0b9c2625dc21ef05f6ad4ddf47c5f203837aa32ca42fced54c2625dc21efac32
Accept: application/json

{
    "permissions": {
        "read": ["+system.Everyone"]
    }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "id": "servicedenuages_blog",
    "permissions": {
        "write": ["fxa:49d02d55ad10973b7b9d0dc9eba7fdf0"],
        "read": ["system.Everyone"]
    }
}

For PATCH, we are thinking about using a syntax prefixed with a + or a - to add or remove principals on an ACL.

It is also possible to do a PUT to reset the ACLs, knowing that the PUT will then add the current user to the list. It's possible to use a PATCH to remove herself from the list. Adding the current user allows to avoid situations where nobody has access to the data anymore.

The specific case of user data

One of the current feature of Kinto is to handle record collections by user.

On *nix systems, it's possible, for an application, to save configuration for the current user in her personal folder, without bothering about its specific location, using ~.

In our case, if an application want to save contacts for a user, it can use a shortcut to reference the personal bucket of the user: /buckets/personal/collections/contacts.

This URL will return a HTTP 307 to the current user bucket.

POST /v1/buckets/personal/collections/contacts/records HTTP/1.1

{
   "name": "Rémy",
   "emails": ["remy@example.com"],
   "phones": ["+330820800800"]
}

HTTP/1.1 307 Temporary Redirect
Location: /v1/buckets/fxa:49d02d55ad10973b7b9d0dc9eba7fdf0/collections/contacts/records

Like so, it's possible for Alice to share her contacts with Bob. She just have to give the read permission to Bob on her collection and give him the complete URL: /v1/buckets/fxa:49d02d55ad10973b7b9d0dc9eba7fdf0/collections/contacts/records.

Permissions delegation

In Kinto, we defined a format to restrict permissions using OAuth2 scopes: storage:<bucket_id>:<collection_id>:<permissions_list>.

Taking back the previous tasks example, it is possible for Bob to create a specific OAuth2 token with the following scopes: profile storage:todolist:tasks:write storage:personal:contacts:read+records:create

Like so, even if Bob has the write permission on his contacts, the application using this token will only be able to read the existing contacts and add new ones.

One part of the complexity is to manage presenting these scopes in a readable way to the user, so she or he is able to chose which permissions to give to the applications acting on her behalf.

So, here is where we're at with our thinking!

If you have things to add or discuss with this proposal, don't hesitate to interrupt us while it's still possible!