Access control

DevNote either provide a TL;DR changelog or link to a detailed changelog.

Corteza defines a RBAC access control facility. RBAC uses the roles of the given user to determine if they have access to the given resource.

Corteza’s RBAC facility uses a "flat design", which removes role hierarchy (two roles can not explicitly define a parent/child relationship).

Context role membership allows you to dynamically assign users to roles based on the defined set of rules.

While access control for specific records is supported, access control for particular fields of particular records is not.

You can bypass this limitation by using context role membership and module filed rules.

Access evaluation flow

If a user is a member of a bypass role, all operations are permitted without any restrictions.

When access is evaluated, the system collects all users' roles and RBAC rules (security context). The order of rule evaluation is based on role importance and resource specificity.

Access evaluation flow:

If any rule defines an explicit deny, the evaluation results with deny.
If at least one rule defines an explicit allow, the evaluation results with allow.
If the current level has no explicit allow or deny, the evaluation continues to the next set of rules based on role importance.
If the evaluation cannot find an explicit allow or deny, the evaluation results with deny.

Role importance

Role importance defines the order in which roles and their corresponding rules are evaluated.

Role importance for authenticated users:

bypass roles
context roles
common roles
authenticated roles

Role importance for authenticated users:

anonymous roles

Resource specificity

Resource specificity defines the order in which rules for the corresponding resources are evaluated. Resource specificity is defined based on "how specific is this rule to this resource".

As an example, a rule that allows users to create records on the account module in the CRM namespace is more specific than the rule just on the CRM namespace.

Such specificity allows you to deny access to all but one resource of the given type.

Role types

A list of bypass, authenticated, and anonymous roles is provided in the system configuration and can not be changed at runtime. Refer to DevOps guide for details on how this can be done

These roles can not be modified or renamed.

If you wish to alter the roles, you can either:

temporarily change the role list, edit the roles, revert the role list changes,
change the provision scripts to supply the required names at the initial Corteza run.

Bypass

Bypass roles allow their members unlimited access to Corteza with no permission checking.

Out of the box, Corteza defines the default bypass role named "Super administrator". Your system administrator can change the set of bypass roles in the .env file. The roles that are defined as authenticated have restricted editing options.

Common

Common roles are any additional roles defined in the administration panel, such as a CRM admin and application builder.

Contextual

You can not use contextual roles within auth clients, nor can they define an explicit member list. Contextual roles are assigned to users based on the operation and the context.

Contextual roles define a series of expressions, which determine when the role is assigned to the user based on the operations' context.

Each role can define an expression for each resource type. Each role can only use a resource type once.

Contextual roles are hidden from resource permission screens if the role does not define an expression for that resource. For example, a record specific role is not shown on the module permission screen.

An example use case would allow us to assign roles to resource owners, which would give them permissions that they shouldn’t have over other resources.

Refer to the ctx-role-evaluation for details.

Contextual roles are currently supported for:

records
workflows
auth clients

Authenticated

Authenticated roles are implicit, meaning that users can not explicitly be set as role members.

Out of the box, Corteza defines the default authenticated role named "Authenticated". Your system administrator can change the set of authenticated roles in the .env file. The roles that are defined as authenticated have restricted editing options.

If the user is authenticated with Corteza when they are accessing a resource, the system additionally assigns them authenticated roles.

Anonymous

Anonymous roles are implicit, meaning that users can not explicitly be set as role members.

Out of the box, Corteza defines the default anonymous role named "Anonymous". Your system administrator can change the set of anonymous roles in the .env file. The roles that are defined as anonymous have restricted editing options.

If the user is not authenticated with Corteza when they are accessing a resource, the system additionally assigns them anonymous roles.

Contextual role evaluation

Refer to Expressions for details on writing context role expressions.

If the expression returns true, the contextual role is applied.

Table 1. Common variables:
userID	The ID of the current user.

Records

resource.ID

The ID of the resource.

resource.recordID

The ID of the resource; same as resource.ID.

resource.moduleID

The ID of the related module.

resource.labels

The key-value pair of labels associated with this resource.

resource.namespaceID

The ID of the related namespace.

resource.ownedBy

The userID of the resource owner.

resource.createdAt

The timestamp of when the resource was created.

resource.createdBy

The userID of the user that created the resource.

resource.updatedAt

The timestamp of when the resource was last updated. The parameter is not defined if the resource has not yet been updated.

resource.updatedBy

The userID of the user that last updated the resource. The parameter will be 0 if the resource has not yet been updated.

resource.deletedAt

The timestamp of when the resource was deleted. The parameter is not defined if the resource has not been deleted.

resource.deletedBy

The userID of the user that deleted the resource. The parameter will be 0 if the resource has not been updated.

resource.values

A set of key-value pairs for the record values defined by the module fields.

If a module field is a multi-value, the corresponding key-value entry will be an array.

Workflows

Table 3. Workflows variables:
resource.ID	The ID of the resource.
resource.workflowID	The ID of the resource; same as resource.ID.
resource.labels	The key-value pair of labels associated with this resource.
resource.ownedBy	The userID of the resource owner.
resource.createdAt	The timestamp of when the resource was created.
resource.createdBy	The userID of the user that created the resource.
resource.updatedAt	The timestamp of when the resource was last updated. The parameter is not defined if the resource has not yet been updated.
resource.updatedBy	The userID of the user that last updated the resource. The parameter will be `0` if the resource has not yet been updated.
resource.deletedAt	The timestamp of when the resource was deleted. The parameter is not defined if the resource has not been deleted.
resource.deletedBy	The userID of the user that deleted the resource. The parameter will be `0` if the resource has not been updated.

Auth clients

Table 4. Auth clients variables:
resource.ID	The ID of the resource.
resource.labels	The key-value pair of labels associated with this resource.
resource.scope	The scope defined by the auth client.
resource.validGrant	The grant that is supported by the auth client.
resource.redirectURI	The redirect URI for the auth client.
resource.trusted	The trust setting of the auth client.
resource.enabled	The enabled setting for the auth client.
resource.validFrom	The timestamp denoting from when the auth client is valid from.
resource.expiresAt	The timestamp denoting when the auth client is no longer valid.
resource.ownedBy	The userID of the resource owner.
resource.createdAt	The timestamp of when the resource was created.
resource.createdBy	The userID of the user that created the resource.
resource.updatedAt	The timestamp of when the resource was last updated. The parameter is not defined if the resource has not yet been updated.
resource.updatedBy	The userID of the user that last updated the resource. The parameter will be `0` if the resource has not yet been updated.
resource.deletedAt	The timestamp of when the resource was deleted. The parameter is not defined if the resource has not been deleted.
resource.deletedBy	The userID of the user that deleted the resource. The parameter will be `0` if the resource has not been updated.

Important notes

System setup

Corteza defines a series of system role types: bypass, authenticated, and anonymous. System role types are defined on the server configuration level, and cannot be changed directly through the user interface.

If a role is assigned to one of the system role types, the editing is restricted. If the role was somehow removed or changed to the extent where the system can not identify it, the system would refuse to start.

The rationale behind such restrictions:

The configuration affects the RBAC facility and its setup process.
Systems that work with access tokens need to be aware of such changes.
The security model on this level rarely changes, and the change is drastic when it does.

Bypass RBAC roles

If a role is assigned as a bypass, it may not appear as any other role type (such as an authenticated or anonymous). In the case where this is not the case, the system will refuse to start.

Only members of the bypass role may manage the membership of the bypass role.

Bypass roles can be listed on auth clients as permitted or prohibited roles but are silently ignored when defined under forced roles.

Authenticated and anonymous

Authenticated and anonymous roles may not appear in any auth client security role lists (the allowed, denied, and forced roles) and are silently ignored.

Glossary

A user

A user is an entity that is accessing Corteza. A user can be a member of security roles and cannot get permissions directly without an assigned role.

A role

A role represents a set of users and a set of permissions over resources.

Corteza’s RBAC implementation defines a flat structure that removes role hierarchy (two roles can not explicitly specify a parent/child relationship).

Access

Defines if the rule permits (allow) or denies (deny).

A resource

A structured piece of information stored within Corteza that we may or may not control access to. Each resource belongs to a component and has a unique type.

A resource type

A resource type defines the structure of information within the Corteza component.

Operation

Defines what operation the given RBAC rule defines access to.

RBAC rule

A RBAC rule combines operation, role, access, and resource. It defines what someone can (or can not) do on one or more resources inside Corteza.

Security session

A security session is created when a user requests to access Corteza.