Skip to main content

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 to true to tell the webhook that the user has successfully validated
  • expirationSeconds is number property on how long the authentication session is valid for before a refresh is required.
  • userID is a string which identifies the the userID. 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 can read or write

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

  1. write to documents in the "books" collection where the _id.title value endsWith('Potter').
  2. write to any document in the "newspapers" collection. We use a single value of true
  3. read to documents in the "books" collection where the _id.title value endsWith('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.