As described in the concepts section <concepts-permissions>
, permissions can be set on any object.
On each kind of object the set of permissions can be:
Permission | Description |
---|---|
read | Any listed principal can read the object. |
write | Any listed principal can write the object, which further implies read, update, and delete. |
create | Any listed principal can create a new child object. |
In the case of a creation, since an object can have several kinds of children, the permission is prefixed by the type of child (for instance group:create
, collection:create
on buckets). When a user is allowed to create a child, she is allowed to read the parent attributes as well as listing accessible objects via the plural endpoint.
The following table lists all permissions that can be associated to each kind of object.
Object | Associated permissions | Description |
---|---|---|
Configuration | bucket:create |
Create new buckets and list existing buckets. |
|
|
|
Collection |
|
|
Record |
|
|
Group |
|
|
Important
Every modification of an object (including the creation of new objects) grant the write
permission to their creator/editor.
Note
There is no delete
permission. Anyone with the write
permission on an object can delete it.
During the authentication phase, a set of principals
for the current authenticated user will be bound to to the request.
The main principal is considered the user ID and follows this formalism: {policy}:{identifier}
(e.g. with internal accounts <api-accounts>
: account:alice
). When a user is added to a group <groups>
, they receive a principal.
There are two special principals:
system.Authenticated
: All authenticated users.system.Everyone
: Anyone (authenticated or anonymous). Using this principal is useful when a rule should apply to all users.
Those principals are used in the permissions definitions. For example, to give the permission to read for everyone and to write for the friends group, the definition is read: ["system.Everyone"], write: ["/buckets/pictures/groups/friends"]
.
Note
A principal can also be another application (in order to provide service to service authentication).
The currently authenticated user ID can be obtained on the root URL.
$ http GET http://localhost:8888/v1/ --auth bob:my-secret
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length
Content-Length: 288
Content-Type: application/json; charset=UTF-8
Date: Thu, 16 Jul 2015 09:48:47 GMT
Server: waitress
{
"documentation": "https://kinto.readthedocs.io/",
"hello": "cloud storage",
"settings": {
"kinto.batch_max_requests": 25
},
"url": "http://localhost:8888/v1/",
"user": {
"bucket": "4399ed6c-802e-3278-5d01-44f261f0bab4",
"id": "account:bob",
"principals": [
"account:bob",
"system.Everyone",
"system.Authenticated"
]
}
"version": "1.4.0"
}
In this case the user ID is: account:bob
Note
If Alice wants to share objects with Bob, Bob will need to give Alice his user ID - this is an easy way to obtain that ID.
If the current user has the write
permission on the object, the permissions are returned in the permissions
attribute along the data
attribute in the JSON requests payloads.
Permissions can be replaced or modified independently from data.
permissions
is a JSON dict with the following structure:
"permissions": {<permission>: [<list_of_principals>]}
Where <permission>
is the permission name (e.g. read
, write
) and <list_of_principals>
should be replaced by an actual list of principals
.
Example:
{
"data": {
"title": "No Backend"
},
"permissions": {
"write": ["twitter:leplatrem", "group:ldap:42"],
"read": ["system.Authenticated"]
}
}
Note
When an object is created or modified, the current user id
is always added among the write
principals.
An object's permissions can be modified at the same time as the object itself, using the same PATCH <record-patch>
and PUT
<record-put>
methods discussed in the Records section
<records>
.
Note
The user ID that updates any permissions is always added to the write
permission list. This is in order to prevent accidental loss of ownership on an object.
Requires setting kinto.experimental_permissions_endpoint
to True
.
Important
The inherited objects are not expanded. This means that if the current user has some permissions on a bucket, the sub-objects like collections, groups and records won't be explicitly listed.
<prefix?><field name>
:filter <filtering>
by value(s)_sort
:order list <sorting>
_limit
:pagination max size <pagination>
_token
:pagination token <pagination>
_fields
:filter the fields of the records <selecting_fields>
Filtering, sorting, partial responses and paginating can all be combined together.
?_sort=-last_modified&_limit=100&_fields=title