Skip to main content

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.