For our customers, multi-party data sharing means many participants transacting with each other in real time. While this sounds simple enough, the reality is getting participants to agree to collaborate can be a challenge. Many of these participants (often separate organizations) have grown accustomed to under-sharing their data, either because of the cost and complexity or because of insufficient access controls to truly share with trust.
A core tenet of Vendia Share is sharing with control. That tenet is the basis for a number of features that allow participants to gain trust in the Vendia Share platform and with each other. Those features, among many others, make Vendia Share the best platform to consider when building multi-party, real-time data sharing solutions. It’s these same features that bring the cost and complexity of building real-time data sharing solutions down significantly. Because sharing with control is a core tenet, it’s not surprising that access controls have been built into multiple levels of the Vendia Share architecture.
In this blog post, we’ll explore Vendia Share’s access control mechanisms, their relationships, and their purpose and placement within the overall Vendia Share architecture.
- User Management Access Controls – Protect Vendia Share user account management operations
- Uni Management Access Controls – Protect Vendia Share Uni management operations
- Node Access Controls – Protects a node’s GraphQL API
- Data Access Controls – Protects the data stored in a Uni
The Share architecture can be thought of at a high level as a Control Plane and a Data Plane. The Control Plane manages user accounts, Unis, and nodes (i.e. the metadata needed for the Share platform). The Data Plane spans the nodes that collectively act on the data in a Uni (i.e. the actual data shared by participants).
As captured in Figure 1, the user and Uni access controls protect the Vendia Share control plane and the node and data access controls protect the Vendia Share data plane. You can differentiate control and data plane access controls by considering whether the access control protects the Vendia Share platform (if so, it’s a control plane protection) or a Uni or node (if so, it’s a data plane protection). The most important point is that multiple access controls exist in each plane of the Vendia Share architecture. In addition to providing defense-in-depth, the numerous available access controls offer each participant in a Uni the flexibility and control they often need to willingly share data with others.
Now let’s examine each access control in depth.
User access controls
Purpose
User access controls protect the user account management operations provided by Vendia Share. This prevents unauthorized access to user management functions and enables features like self-service user management within an organization.
Approach
The Vendia Share control plane is where Vendia Share user accounts are stored. Authorization to specific user account management operations that act on user accounts is granted through a Role Based Access Control (RBAC) mechanism.
Before going further, it’s important to define a few key RBAC terms, as they relate to user access controls.
Key terminology
- Action – the right to call one or more of Share’s user account management operations
- Resource – the user account against which an Action can be performed
- Capability – a mapping of Action to Resource, linking the “right to call” (an operation) with the “right to manage” (a user account)
- Role – a named collection of Capabilities and used to determine if a user management operation is authorized
There are a set of Actions relevant to user account management. These are a subset of the ActionEnum defined in the Vendia Share control plane API. Each Action defined corresponds to a user management query or mutation available through the API.
| Action | GraphQL Query or Mutation Operation |
| USER_GET | getUser |
| USER_CREATE | createUser |
| USER_DELETE | deleteUser |
| USER_SET_EMAIL | setUserEmail |
| USER_SET_ROLE | setUserRole |
| USER_DELETE_ROLE | deleteUserRole |
| USER_INVITE | invite |
There are also a specific set of Resource formats that are permitted for user account management purposes. The allowable formats in some way describe one or more Vendia Share user accounts. These are the accounts against which an Action from above can be executed.
A Vendia Share user can use either a default role or a custom role when attempting to invoke one of the user management operations made available through Vendia Share’s control plane API. The Vendia Share Command Line Interface (CLI) provides a quick and easy way to invoke these operations but those same interactions can also be achieved using a GraphQL client of your choice.
Examples
We’ve created a set of examples to demonstrate how user controls can be viewed and managed and the implications of their settings on user account management operations. These include invocation of control plane APIs using the Vendia Share CLI and a GraphQL client.
Enterprise-only features
More advanced user controls scenarios and self-service features are available for our Enterprise customers. While we won’t cover those in detail here, the permission necessary originates from the creation of an administrator role. An administrator can then invoke otherwise unauthorized API operations (e.g., createUser) or grant escalated privileges to other accounts within the administrator’s organization (i.e., setUserRole).
Uni access controls
Uni access controls protect the Uni management operations provided by Vendia Share. Authorization to specific Uni management operations is granted through an RBAC mechanism, very similar to the RBAC mechanism that protects user controls.
Approach
In addition to storing user accounts, Vendia Share’s control plane also stores information about all Unis and nodes deployed across the platform. Authorization to specific Uni management operations that act on Uni and node configuration is granted through an RBAC mechanism.
We can slightly modify the RBAC terms from the previous section to make them specific to Uni management.
Key terminology
- Action – the right to call one or more of Share’s Uni management operations
- Resource – the Uni or node against which an Action can be performed
- Capability – a mapping of Action to Resource, linking the “right to call” (an operation) with the “right to manage” (a Uni or node)
- Role – a named collection of Capabilities and used to determine if a Uni management operation is authorized
There are a set of Actions relevant to Uni management. You’ll notice these are a subset of the ActionEnum defined in the Vendia Share control plane API. Further, you’ll notice that each Action defined corresponds to a user-specific query or mutation available through the API.
| Action | GraphQL Query or Mutation Operation |
| UNI_CREATE | register |
| UNI_DELETE | destroy |
| UNI_RESET | reset |
| UNI_JOIN | join |
| UNI_INVITE | invite |
| UNI_DELETE_NODE | NA |
| UNI_GET | getUni, listUnis, getNode |
| UNI_EVOLVE_SCHEMA | evolve |
| UNI_QUERY | NA – future use |
| UNI_MUTATE | NA – future use |
There are a different set of Resource formats that are permitted for Uni management purposes. The formats can be used to describe one or more Unis in a single statement. These are the Unis against which an Action from above can act upon.
Examples
We’ve created a set of examples to demonstrate how Uni Controls can be viewed and managed and the implications of their settings on Uni management operations. These include invocation of control plane APIs using the Vendia Share CLI and a GraphQL client.
Node access controls
Purpose
Node Access Controls authorize requests to a specific node’s GraphQL API. They can be thought of as the “coarse-grained” authorization to the GraphQL API. They act as an enforcement point, permitting or denying every request. Whether that authorization mechanism is direct (e.g. performed by Vendia Share) or indirect (e.g. delegated to another authorization service), the Node Access Controls are responsible for preventing unauthorized API access.
Approach
A Vendia Share Uni contains one or more nodes. Each node maintains its own authentication and authorization configuration, allowing authorization approaches across nodes to differ while still retaining a shared source of truth across nodes in the form of a serverless distributed ledger.
The GraphQL API that provides access to the serverless distributed ledger available on a node is protected by the Node Access Control configured when a node is created. Each participant in a Uni can select a different authorization scheme, depending on their authorization preferences.
Figure 4 depicts a two-node Uni, each with different authorization settings configured. This Uni topology is common within a single organization and across organizations.
Within a single organization, it may be preferable to create a two-node Uni to isolate internal (i.e. private) and external (i.e. public) interfaces to Share. For example, the internal node might use the IAM authorization setting, permitting cross-account access between their existing AWS account and the Vendia Share account created to host their node. The external node might instead use COGNITO to leverage an existing user pool for their external user accounts.
Across organizations, each participant is likely to have a unique set of authorization requirements and existing solutions. Giving each participant the ability to use their existing solutions without impacting the other is one of the key benefits of a decentralized platform like Vendia Share.
Examples
We’ve created a set of examples to demonstrate how Node Access Controls can be configured and the implications of their settings on clients interfacing with a node’s GraphQL API.
Data access controls
Purpose
Data Access Controls allow a data writer to dictate access rights to the data they’ve written to a Uni. They can be thought of as the “fine-grained” authorization to the data. These controls take the form of an Access Control List (ACL), and can be applied to either at the object (e.g., a PurchaseOrder) or property (e.g., just the price field within a PurchaseOrder) level of a data structure.
Approach
Unlike centralized architectures, where a single data owner dictates the data access permissions of all participants, Vendia Share’s decentralized architecture empowers every data writer with the ability to control data access (i.e., to act as a data owner). Data access controls protect the ability to read and the ability to modify. While Node Access Controls may permit a GraphQL query to be received by a node, Data Access Controls may restrict the data values returned to the caller. Likewise, while Node Access Controls may permit a GraphQL mutation to be received by a node, Data Access Controls may restrict data modification if the caller is not permitted to do so because of an existing ACL.
Figure 5 depicts a two-node Uni, each with data access controls applied to data stored in the ledger. This allows the writer of any record to dictate the read and write permissions of other nodes, at the record or field level.
Key terminology
- Object – An entity that can written to Vendia Share, consisting of one or more properties, including an optional
aclproperty - Path – An optional path to a specific property within the object being protected by an ACL
- Principal – A node in the Uni, against which an ACL will be applied
- Operation – An action a Principal can take (e.g.
READ) on the object or property specified - ACL – The combination of Principal, Operation, and (optionally) Path, with an association to a specific Object
Data Access Controls are a very important and deep topic. Check out the docs for more information and this blog post for a concrete scenario that will help you better understand the full set of capabilities they enable.
Examples of how data access controls can be configured
We’ve also created a set of examples to demonstrate how Data Access Controls can be configured and the implications on the ability for other participants to read and write data using their node’s GraphQL API.
Learn more about multi-party data sharing with control
Using the access controls outlined above, participants will quickly grow comfortable sharing more data, with more fellow participants, with confidence. Increasing data sharing can unlock the participants’ ability to optimize their collective operations, explore new business models, and maximize the value of their real-time data. Vendia Share’s existing controls allow for a rich set of protections to be established before, during, and after a Uni is created to encourage secure data sharing. These controls are often a key element to participants becoming comfortable with the notion of sharing with control.
Explore our FAQs and take a closer look at real-time data sharing use cases.