Terminology
Permissions Blueprint
A Permissions Blueprint is schema representation of your permission model. This defines types of resource types, roles, and actions.
Resource Type
A type of resource that needs to be protected - typically this is a table name or a feature.
Resource {
Name: String,
Actions: []String,
Attributes: []String,
}
Vista allows defining attributes on Resource Types - think of these as columns on a table.
Resource ID
An instance of a resource in your application - also known as Resource ID.
Permission
A grouping of resource type, action, attribute, and ownership query (See Role).
Permission {
ResourceType: String,
Action: String,
Attribute: String | null,
OwnerId: String,
}
Role
A role is a grouping of permissions that can be granted to users/usersets. A role consists of a list of permissions - the resource IDs affected are determined by the OwnerId
, and its corresponding ownership query
. This ownership query
is evaluated against your database to generate a list of IDs that the permissions applies to - these are implicit grants, as you're not specifying the IDs yourself, but rather the query to retrieve them.
We provide $USERID
and $ORGID
as template variables.
Example: A manager can view all tickets that belong to their org, but only edit tickets that belong to their team.
The underlined portions express access through a form of ownership - we have defined the first as orgOwned
and the latter as teamOwned
.
Resource {
Name: "ticket",
Actions: ["view", "edit"],
Attributes: [],
}
Role {
ID: "Manager",
Grants: [{
Action: "view",
Resource: "ticket",
OwnerId: "orgOwned",
}, {
Action: "edit",
Resource: "ticket",
OwnerId: "teamOwned",
}],
Owners: {
orgOwned: "SELECT id FROM tickets WHERE tickets.companyId = $ORGID",
teamOwned: "SELECT id FROM tickets INNER JOIN users ON tickets.creator = users.id AND users.supervisor = $USERID",
}
}
client.users.grantRole('user1', 'manager')
If user1 is granted the Manager
role, to check if user1 can edit ticket5, we evaluate the appropriate queries.
Explicit Grants
To grant 1-off access (say a for a contractor
role), you can specify *
as OwnerId
, to only allow access to explicitly defined resource IDs.
client.users.grantRole('user1', 'contractor', 'ticket5', 'tickets')
Roles can be inherited, where a child role inherits permissions and ownership queries from the parent.
Role {
ID: String,
InheritsFrom: []String,
Grants: []{}String {
Action: String,
Resource: String,
Attribute: String | null,
OwnerId: String,
},
Owners: {
Id: String,
...
}
}
Userset
A group of users that can have permission grants. Usersets can also inherit from each other.
Userset {
ID: String,
OrgId: String,
Users: []String,
InheritsFrom: []String,
}
User
An instance of an end user. You can add a user to a userset (and inherit the permissions applied to that userset), or grant permissions directly to a user.
User {
ID: String,
OrgId: String,
}
Branch
Branches add version control to your permissions, and represent the state of your blueprint - this includes all Resource Types, Roles, as well as relationships between resource objects. Branches enable you to roll out changes to your permissions blueprint in an iterative way - read the Version Control Guide for more info.