Identity concepts

Users, groups, roles, privileges and permissions on objects, and how Kyvernon decides what a user may do.

Kyvernon decides every request in one place, whether it arrives through the console, the CLI, the native API, the gRPC API or the vSphere endpoints. The decision uses the user, the groups of the user, the object the request is about and the roles that are granted on that object or above it. Administrators manage these parts in the console under Administration, in the area that the user menu opens.

Users

A user is a local account or a federated account. A local account has a password that Kyvernon stores as an Argon2id hash; the Users screen (Users) creates and manages them. A federated account is created at the first sign-in through an identity provider and has no password in Kyvernon. Its user name is the preferred user name of the provider, in lower case, and the column Source shows Local or Single sign-on.

Three kinds of account have a special purpose:

The first administrator, created when the controller starts for the first time. It must change its password at the first sign-in.
The break-glass account, named breakglass by default, for use when the identity provider is down. It carries the badge Break glass, its sessions last at most one hour, and its password must be changed after every use.
Service accounts, marked with Service account. They are for automation and sign in with API tokens, not in the console.

A user can be disabled, which ends its sessions, and a user is locked after repeated failed sign-ins. The lock ends by itself, or an administrator lifts it.

Groups

A group is a named collection of users and of other groups. A local user is added to groups on the Groups screen (Groups), and a federated user gets the groups from the groups claim of the identity provider at every sign-in. A permission can name a group instead of a user, so that a role follows the membership. Local groups, with their nesting, and the password and lockout policies are kept in the replicated store, so every controller shares them. On the first start of this version, a controller moves the group file of an earlier version into the store and renames the file to <name>.migrated. It also writes the policy files of an earlier version into the store once.

Roles and privileges

A privilege is one permitted operation, such as VirtualMachine.Interact.PowerOn or Network.Config. A role is a named set of privileges. Kyvernon has nine built-in roles that you cannot change or delete, and you can create your own on the Roles screen (Roles). The built-in roles are Administrator, Read-only, No access, Virtual machine power user, Virtual machine user, Backup operator, Tenant administrator, Tenant user and Tenant service principal. The pages Built-in roles and Privileges list what each one holds.

Permissions on objects

A permission links a principal (a user or a group), a role and an object of the inventory. It can propagate to the children of the object. The Permissions screen (Permissions) and the tab Permissions of every object show and change them.

To decide whether a user holds a privilege on an object, Kyvernon walks from the object up to the root:

A permission that does not propagate counts only on the object itself.
At the nearest object that has a permission for the user, that permission decides. A permission for the user itself wins over permissions for its groups. Several group permissions on the same object are combined.
Nothing above that object is consulted. A permission with the role No access on a child therefore blocks a role that is granted higher up.
The privilege is granted when one of the effective roles holds it.

Tenant users are confined further: their privileges apply only inside the folders and resource groups of their tenant. A role with a provider-only firewall privilege cannot be granted inside a tenant.

Sessions, tokens and the audit log

A session starts at sign-in and ends by sign-out, by an idle timeout, by its absolute lifetime or when an administrator ends it on the Sessions screen (Sessions). An API token (API tokens) is a long-lived credential for automation that cannot answer a verification code. Every change of users, roles, permissions, tokens and sessions is written to the audit log (Audit log), together with failed and refused sign-ins.