Skip to main content

Key Concepts

Authentication vs. Authorization#

The term "auth" is often thrown around the security world, representing either authentication or authorization - clarifying the distinction is imperitive to building a secure platform.

Authentication answers the question of "who are you?" and is central to establishing user identity.

Authorization answers the question of "what can you do?" and focuses on access management. Unlike authentication, authorization must happen each time an action is performed on a protected resource. We aim to solve this, with our API-first approach.

Blueprint vs. Objects#

Your Permissions Blueprint is a representation of the types of relationships that can exist within your system. This schema describes Resource Types, what actions can be taken on them, and the roles that can perform those actions.

This is an example of what a (simple) Blueprint might look like:


This Blueprint is then applied to your users and individual resource objects via the API.

This templatized approach allows you to reuse basic permissions models across different sets of users. If you have the same organizational structure across different usersets, you can simply reuse the blueprint and assign permissions for new objects.

More importantly, Blueprints help us enforce correctness, compute permission checks quickly, and prevent any accidental access grants.

Implicit vs. Explict Grants#

In order enforce access, you must first grant access.

Implicit grants are permission grants that are evaluated via an ownership query. Explicit grants are done via the API - usually to grant 1-off access.


There are many ways to model permissions - one such popular model is known as RBAC (role-based access control).

According to the EnterpriseReady SaaS Feature Guide, RBAC is one of 11 key differentiating features for B2B SaaS companies to scale and build for enterprise customers.

In traditional RBAC permissioning systems, users are assigned roles, which map to specific permissions across resources. Although this works well in many basic cases, often certain users will require access to resources that don't align exactly to the defined roles - leading to creating more roles. You must also explicitly define which resources are affected by that role - leading to constant updates when new resources are created. These issues around granularity can pose threats to security without diligent maintenance.

We believe these issues with RBAC can be solved by representing permissions as relationships between entities - a model known as ReBAC (relationship-based access control). Modeled after Google Zanzibar, Google’s tried and true internal authorization platform, Vista permissioning follows these principles of ReBAC.

Beyond simply expressing policies in the form of subject-action-object, ReBAC also allows us to easily define role-role and resource-resource relationships. This allows us to define permissions based on relationships, as well as enable role inheritance.

Example 1: There are a number of documents that are related to a folder. You can define rules such that "document" inherits certain permissions from "folder". When "new_document" is added to "folder" those that can read "folder" can also read "new_document". With ReBAC, this is all managed by existing relationships, while with RBAC, one would have to update every role with the permission "read:new_document".

Example 2: If there is an "admin" role that inherits from a "manager" role, new permissions granted to "manager" will automatically be inherited by "admin". This is not possible in traditional RBAC.