End-User Access
Many apps require access controls to manage end-user authorization for reading and writing specific data. For instance, junior staff members are limited to read-only access, while senior staff members have permission to both read and write documents.
You can issue each certificate manually or with the OnlinewithAuthentication digital identity.
To reject a user from reading or writing at all, specify the JSON payload:
To grant full read and write permissions to all collections and all documents:
- 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.
Currently, you can only specify a permission query on the _id field of a document. Permissions on mutable properties are currently not supported.
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.
Permissions must be written using the legacy query syntax and not DQL. For more see Query Syntax (Legacy)
The following write permissions describe that userID: "123abc" can:
- write to documents in the "books" collection where the _id.locationId == 'abcedef123456'.
- write to any document in the "newspapers" collection. We use a single value of true
- read to documents in the "books" collection where the _id.locationId == 'abcedef123456'
Threat modeling is a process used by software engineers to identify, analyze, and prioritize threats that could potentially impact an application. It helps engineers identify potential weak points in an application and take steps to mitigate those risks. Threat modeling involves identifying the assets that an application needs to protect, assessing the potential threats to those assets, and determining the best ways to protect them.
By identifying potential risks, engineers can ensure that the application is secure from malicious actors and that users' data is protected. Threat modeling can also help ensure that the application meets the company's security standards and regulations.
Threat modeling in peer-to-peer (P2P) networks is different than that in client-server networks due to the distributed nature of the P2P network. In a client-server network, there is a single server that all clients connect to, and thus all of the data and resources are centralized. This makes it easier to identify potential threats and vulnerabilities, but creates a entry that can be targeted by an attacker, making it easier to exploit the entire network at once.
Peer-to-peer (P2P) networks are networks that do not have a central server, but rather all nodes are equal, allowing clients to share resources with each other directly. As such, P2P networks have more restrictive permissions on synchronization than client-server authentication systems, as nodes are required to agree to any changes made by other peers. This is done to ensure that no node has an advantage over another and that all nodes remain secure.
Therefore, even though peers in Ditto may have overlapping subscriptions, Ditto peers are only able to synchronize data directly from a peer that has the authority to write that document. In other words, small peers are only able to trust writes from other peers that have the authority to make those writes. They cannot trust each other as a source of data that they aren't authorized to write to, since they can't tell the difference between an edit they made on their own and one which came from a further hop.
Because Ditto peers are only able to synchronize data directly from a peer that has the authority to write that document, a read-only security model comes with some caveats. This section covers how to best implement this security model and the trade-offs that exist in peer-to-peer networks.
Ditto provides a mechanism to specify which small peers can read documents in a collection without permission to write. This can be useful in situations where you have restrictive user roles, such as customer and employee.
To implement read-only documents, you should create restrictive write permissions that include the userId inside of the document _id. Ditto ensures that only those authorized to create documents with a particular document _id are able to synchronize those documents in a trustworthy manner throughout the system.
In this example, peers can read chat messages from other people, but cannot write to them. They can only write their own chat messages.
Imagine three peers, Peer A, B, and C. Peers A and B are connected, but Peer C only connected to peer B.
Every peer has similar permissions, where they can read everything but can only write to a collection with an _id that represents their userID. So, for example, Peer A has the following permissions:
Peer A writes a message and syncs that message to B.
However, Peer B cannot forward that message from A to C. This is because peer B does not have write permissions to create documents with userID=A.
Today Ditto enforces that data which has to propagate peer-to-peer must have mutual write permissions. If integrity is at risk, you have to sign the payloads yourself at the application level.
This is a credible attack vector, especially if Peer A represents an authority in the system, such as an administrative user. This design prevents a hacker from impersonating Peer A, because other peers will only synchronize documents from Peer A when they have a direct connection to Peer A, and can verify their certificate is valid.
A hacker attempts to write messages pretending to be peer A even though they are only allowed to read.
- Steal mobile phone that is authorized as Peer B
- Create documents pretending to be Peer A.
This is a credible attack vector, especially if Peer A represents an authority in the system, such as an administrative user. This design prevents a hacker from impersonating Peer A, because other peers will only synchronize documents from Peer A when they have a direct connection to Peer A, and can verify their certificate is valid.
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.
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.