Introducing Vendor Authentication November 6, 2019

Starting 16.4, Gyroscope supports account management and access control for custom entities. What previous required a custom portal outside of a Gyroscope application can now be accomplished from within.

Before we dive into this new "vendor authentication" feature, let's look at some core user management concepts in Gyroscope:

Capability Vectors

Each user in Gyroscope is described with a list of capabilities, also known as "capability vectors" or "capability flags". For example, the permissions to view and delete records can be separately granted. Although conceptually, the users who can only view records belong to one group, and the ones who can both view and edit belong to another, organizing users in groups creates an unnecessary level of rigidity.

When designing capability flags, there are several factors to consider. First, the effects of each flag should not overlap. For example, "editor" and "super editor" are bad examples. A rule of thumb: describe the users by What they can do, not Who they are.

Also the capability flags must be additive. There shouldn't be a scenario where a user with two flags has less access than a user one only one flag. It is unfortunately a common practice to see some "contractor" flag that takes away the typical "admin" or "staff" level access. When provisioning a new user, one would check all the flags, with the intent of creating a super user, just to be surprised to see that the contractor permission is an "anti-permission".

When capability vectors are independent and additive, they make the description and enforcement of user permissions predictable and well defined.

Inheritance

A special type of permission is for creating new users. In general, a user can only replicate permissions they already have themselves. For example, a user who can only view cannot create a user that can both view and edit. Otherwise, this would have been a case of privilege escalation. Gyroscope allows fine control over which capability flags' inheritance is enforced. Exceptions can be made so that certain permissions can always be granted regardless of the creator's access.  

Multi-Tenant

Many cloud products use a multi-tenant architecture to host many accounts on the same server. Gyroscope implements multi-tenancy through virtual name spaces; each virtual space is known as a "GS", identified by a "GS ID". 

With the help of gsguard, users in a Gyroscope application can be placed in safely contained segments. A "seed user" is created when an organization-level account is provisioned. This user can then create more sub users. Both the initial user's permissions and their GS ID are inherited. This effectively contains new users in the same organization.

Vendor Authentication

So far we have examined ways to separate users' permissions by their capabilities and their organizations. Now consider a management system for a property maintenance company. Each "user" is an internal staff. Some users have access to unresolved maintenance issues, some can assign contractors to tickets, and some can even modify the contractor registry. However, a staff user is a staff user is a staff user. What if we want to give contractors access to the same Gyroscope application without creating a separate, say, "contractor portal"?

Before Gyroscope 16.4, the only two options were both sub optimal. One is to create a contractor flag that violates both the "independent" and "additive" principles in designing access control. Another way is to replicate the contractor id as a GS ID and separate the staff and contractors through multi-tenant containers. Such approach is not sustainable mainly because once multi-tenancy is repurposed, it can no longer be utilized for its originally intended purpose.

Vendor Authentication in 16.4 was designed to solve exactly this issue. In the above example, a contractor is a vendor. The internal staff and a contractor have different set of roles. Whether a staff can view or edit a maintenance ticket is irrelevant to a contractor, whose concerns are ticket acceptance, progress report and invoicing for example. The separate lists of capabilities for the staff and contractors define their respective "security realm".

Within each realm, the capability flags can be provisioned in an independent and additive manner. Gyroscope uses the same users table and user management interface for both main and vendor-specific accounts. This means that the same authentication infrastructure is applied to all types of users, avoiding security fragmentation and its associated problems.

From the staff's user management interface, a user can be linked to a specific vendor and thus activating the vendor's unique capability descriptors. Once a vendor signs in, he can only create other vendor accounts if he can create new accounts at all.

Gyroscope 16.4 comes with a new code generator that walks the developer through an extensive list of integration points. Keep in mind that the code gen only helps transform the authentication framework by extending user descriptors, linking vendor records and providing the vendor ID in the authentication context through the userinfo function. The enforcement of the vendor ID, as well as the implementation of vendor-specific modules are left to the programmer.