Access Control Permissions
You can describe permissions attributed using a JSON document. This JSON document is encoded within the certificate used by each device. Each peer verifies the cerificates of other peers, and accepts or rejects reads and writes based on these permissions.
You can issue each certificiate manually or with the Online with Authentication identity.
Rejecting a user
To reject a user from reading or writing at all, specify the JSON payload below.
{ "authenticate": false}
Accepting a user
To grant full read
& write
permissions to all collections and all documents:
{ "authenticate": true, "expirationSeconds": 28800, "userID": "123abc", "permissions": { "read": { "everything": true, "queriesByCollection": {} }, "write": { "everything": true, "queriesByCollection": {} } }}
authenticate
totrue
to tell the webhook that the user has successfully validatedexpirationSeconds
isnumber
property on how long the authentication session is valid for before a refresh is required.userID
is astring
which identifies the theuserID
. This should be unique across users within your app.permissions
which describes all the types of access control for collections and documents that this user canread
orwrite
Access Control Permissions
info
Currently, you can only specify a permission query on the _id
field of a
document. Mutable properties are currently not supported. We are working on
adding this feature.
To grant selective permissions on specific documents, add to the
queriesByCollection
property inside either the read
or write
property.
Each key inside queriesByCollection
is a reference to the collection. Each
value is an array of ditto queries describing which
documents the user can read or write.
Example
The following write permissions below describe that userID: "123abc"
can
write
to documents in the"books"
collection where the_id.title
valueendsWith('Potter')
.write
to any document in the"newspapers"
collection. We use a single value oftrue
read
to documents in the"books"
collection where the_id.title
valueendsWith('Potter')
.
{ "authenticate": true, "expirationSeconds": 28800, "userID": "123abc", "permissions": { "write": { "everything": false, // ensure that this is false "queriesByCollection": { // 1. "books": [ "endsWith(_id.title, 'Potter')" ], // 2. "newspapers": [ "true" ] } }, "read": { "everything": false, // ensure that this is false "queriesByCollection": { // 3. "books": [ "endsWith(_id.title, 'Potter')" ], } } }}
Here is a full example for a complex permissions query:
{ "authenticate": true, "identity": { "provider": "facebook", "id": true }, "expirationSeconds": 3600, "permissions": { "read": { "everything": false, "queriesByCollection": { "cars": ["_id == 'my-specific-id'", "_id == 'id1' || _id == 'id2"], "boats": ["_id > 100", "_id > -10 && _id < 10"], "foods": ["_id == false"], "books": ["endsWith(_id, 'Potter')"] } }, "write": { "everything": false, "queriesByCollection": { "cars": ["_id.price > 1500 && _id.currency == 'USD'", "_id.color == 'red"], "boats": ["regex(_id, '^Wave.*')"] } }, }}
App-level Security
The access rules contained in the identity are rigid, signed by the central certificate authority, and enforced by all participating devices. This offers the highest level of security. If a device is not allowed to access particular data, it will never be synced to their device. See Query Overlap Groups, for more details on multi-hopping through untrusted devices.
For apps with weaker security requirements, a developer may choose to relax the access rules inside the Ditto certificate, and instead restrict access in their application code.
One advantage is that the developer has more flexibility to change the access rules dynamically since they are not encoded in signed certificates. Another advantage is that all devices in the mesh can participate in syncing the data, which may help it propagate faster. If certain data is only accessible to a few privileged devices which are not often in range of each other, it will take longer for them to sync.
The disadvantage is that an unprivileged user does have a device containing privileged data. A technically savvy user or phone thief may be able to gain access to not only their regular data, but also the more privileged data that they were never intended to be able to view.
Therefore relaxed access rules - app-level security - are only suitable for environments where there is a degree of trust that the devices won't end up unlocked in the wrong hands.