Role-based Access Controls
Vendia Share provides comprehensive role-based access controls (RBAC) to enable administrators to control the actions users are permitted to take and the resources on which they can operate.
Vendia's RBAC system is designed to be both simple to use and highly secure. It enables system administrators to easily limit who can access their corporate data and code, constrain employee and business partner activities, and secure critical systems from accidental mishandling. Developers using Vendia Share's free tier, however, can largely ignore RBAC while learning the system, because default role permissions and automatic permission boundary management automates away most of the need for explicit permissions management in typical usage scenarios.
RBAC modulates the interaction between Vendia Share users and Vendia Share APIs and resources. RBAC does not impact the visibility of data in a Uni. RBAC may be used to determine whether a Vendia Share user is permitted to access the data in a Uni. In addition, each Uni node possesses its own user identity and authorization mechanisms, which are outside the scope of RBAC.
Actions: Actions express the right to call one or more Vendia Share APIs. For example,
USER_GETexpresses the right to call the
getUserGraphQL query in the Vendia Share API. For convenience, actions such as
UNI_ALLmay be used to convey, "all user-related APIs" and "all Uni-related APIs", respectively.
Capabilities: A capability is a mapping from actions to sets of resources. For example, the default role for a user includes capabilities to create unis in the default Uni namespace and perform operations on unis in which the caller has at least one node.
Default Role: Each Vendia user is assigned a default role, which will be used to determine their capabilities for any API call not provided with an explicit role.
Resources: Resources determine the object(s) to which an action can be applied. (There may be more than one resource listed per action.) For example, an action such as
UNI_GETmight have two resources,
test2.unis.vendia.net, permitting the owner of that role to access information about either the
Roles: Roles are named sets of capabilities. When a call is made to any Vendia Share API, the caller's role is used to determine if the action is legal, i.e. whether the caller is authorized to perform it. A role can be provided explicitly; if no role is provided, the caller's default role will be used instead.
Vendia Share supports the following actions on user accounts:
USER_GET: Permits calling getUser to retrieve user account details.
USER_GETalso determines which users are included when listing users.
USER_CREATE: Permits calling createUser, allowing the owner to make new accounts on the Vendia Share system.
USER_DELETE: Permits calling deleteUser, allowing the owner to remove existing accounts from the Vendia Share system.
USER_SET_EMAIL: Permits calling setUserEmail.
USER_SET_ROLE: Permits calling setUserRole, allowing the caller to assign new roles or replace existing roles for themselves or other users.
USER_DELETE_ROLE: Permits calling deleteUserRole, allowing the caller to remove roles from themselves or other users.
USER_INVITE: Permits the owner to invite users to join an existing Uni. Note that inviting a new node to join an existing uni requires two types of permission:
- The right to call invite for the uni in question
- The right to invite the user (owner) of the new node.
USER_ALL: Convenience setting - permits all of the user actions listed above.
USER_INVITE, user actions are typically reserved for administrators.
To comply with GDPR, CCPA, and similar regulations, every user on the Vendia
system is automatically granted
for themselves; these rights cannot be removed.
Vendia Share supports the following actions on Unis:
UNI_GET: Permits calling getUni to retrieve user account details.
UNI_GETalso determines which unis are included when listing unis.
UNI_CREATE: Permits calling
registerto create new unis.
UNI_DELETE: Permits calling
destroyto delete existing unis.
UNI_RESET: Permits calling
reseton an existing uni to reset it to its state immediately after initial deployment.
UNI_JOIN: Permits calling
jointo create a new node in an existing uni.
UNI_INVITE: Permits calling
inviteon an existing uni. Note that inviting a new node to join an existing uni requires two types of permission: the right to call invite for the uni in question and the right to invite the user (owner) of the new node.
UNI_DELETE_NODE: Permits calling
leaveon an existing uni. (Normally this is performed by the owner of the node, but RBAC can express the right to remove nodes owned by others.)
UNI_QUERY: Grants access to call queries in the uni's data API.
UNI_MUTATE: Grants access to call mutations in the uni's data API.
UNI_ALL: Convenience setting - permits all of the uni actions listed above.
Vendia Share users are identified by the current email address associated with their Vendia account. '*' may be used as a wildcard, or to indicate that no subdomain is required. Examples:
firstname.lastname@example.org: user Mary in the
*@acme.com: any user in the
*@*.acme.com: same as the above
*@unis.domain.com: any user in the
*@*.*.*: any user in any domain
All user commands (getuser, userSetEmail, etc.) require resources using name formats.
Uni commands can take one of several forms:
- Name Format: using a name format where a uni resource is expected has the meaning of "this user is an owner of at least one node in the Uni"
<UNI_NAME>.<SUBDOMAIN>.<DOMAIN>.<EXT>: the Uni's fully qualified name; '*' may be used as a wildcard for any portion of the name.
<UNI_NAME>.<SUBDOMAIN>.<DOMAIN>.<EXT>#<NODE_NAME>: a specific node in a Uni
email@example.com: any Uni where
firstname.lastname@example.org at least one node
test.unis.acme.com: a Uni named
testin the namespace operated by
acme.comin the subdomain
foo.*.acme.com#bar: the node
barin the uni
fooin the namespace owned by
Acme.com. The subdomain may be present or absent; either way it is ignored.
*.acme.com: every uni in the namespace owned by
Vendia Share's RBAC system includes a built-in permission boundary
feature that prevents escalation of privileges. Permission boundaries
impact administrative features, such as
USER_SET_ROLE. Without a
permission boundary, any Vendia account with administrative privileges
USER_SET_ROLE could "mint" unlimited privileges for
themselves or others by setting
To prevent this from happening, the effect of calling
is required to be a subset of the role of the caller. In other
words, users cannot create or alter roles to be more powerful than
themselves. As an example, an administrator with
*.*.acme.com rights would be allowed to
test1.*.acme.com to another user (or themselves),
but could not grant
test1.*.other_domain.com to any user.
Permission boundaries are enforced automatically - no user action is required.
Often, Vendia Share users are referred to as "normal" or
"administrator" depending on their privileges. However, the
privileges of individual users may vary from company to company
and even among accounts. For instance, an administrator for acme.com
may decide that its users should not be permitted to call
reset, because these actions potentially cause loss
of data. Other companies may grant their users both privileges, or
grant it only for unis in a development subdomain but not in the
Default users operating in the Vendia Share free tier have access to
only the default namespace,
*.unis.vendia.com. Up to the
available (per-user) limits, they can create new Unis and nodes in this
namespace and have access to call any API on the Unis in which they own at least
one node. Free tier users do not possess any user privileges except for the "built-in" right to view and update their own user account information and invite other free tier users to join their Unis.
The privileges of a default user operating under an enterprise
agreement varies depending on the setup requested by the company's
Vendia account administrator. The initial user account created for enterprise
agreements is typically an administrator account, with full permission to
create new users and roles in one or more corporate-owned namespaces. For more
information on enterprise configuration, contact Vendia sales or