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.