> For the complete documentation index, see [llms.txt](https://docs.planetcrust.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetcrust.com/platform-administration-console/security-model-rbac/security-model-introduction.md).
# Security Model Introduction
### Overview
{% hint style="success" %}
The Users, Roles and User Groups settings can be found in the Platform Admin Area, towards the top of the left menu bar.
{% endhint %}
@Human defines a [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control) access control facility. RBAC uses the Roles of the given User to determine whether they have access to a given Resource.
{% hint style="info" %}
Most of the @Human resources allow you to define which Roles are allowed to access the Resource. Locate the permissions button in the user interface in order to manage the resource.
{% endhint %}
Refer to [Resource Operation Reference](#user-content-fn-1)[^1] for the complete reference of available RBAC rules.
{% hint style="info" %}
@Human also has User Groups, which you can use to implement hierarchical access.
{% endhint %}
{% hint style="danger" %}
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 contextual role membership and module field rules.
{% endhint %}
### Access Evaluation
{% hint style="warning" %}
If a user is a member of a bypass role, **all operations are permitted** without any restrictions.
{% endhint %}
Resulting access is based on two components:
* Access evaluation based on the organization tree.
* Access evaluation based on user-assigned roles and contextual roles.
{% hint style="danger" %}
The two components are merged using the following check-list.
1. If user-assigned roles result in explicit deny, the result is deny.
2. If user-assigned roles result in explicit allow, the result is allow.
3. If user group hierarchy result in explicit allow, the result is allow.
4. If user group hierarchy result in explicit deny, the result is deny.
5. The result is inherit.
{% endhint %}
#### Role evaluation
Access evaluation flow:
1. If any rule defines an explicit **deny**, the evaluation results with **deny**.
2. If at least one rule defines an explicit **allow**, the evaluation results with **allow**.
3. If there are no explicit allow or deny rules on the current level, the evaluation continues to the next set of rules based on role importance.
4. If the evaluation cannot find an explicit allow or deny rules, 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:
1. bypass roles,
2. context roles,
3. common roles,
4. authenticated roles.
Role importance for unauthenticated users:
1. 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 this rule is to this resource*.
As an example, a rule that allows users to create records on Module in a Namespace is more specific than the rule just on the Namespace.
{% hint style="success" %}
Such specificity allows you to deny access to all but one resource of the given type. For example, you could deny access to all namespaces and allow access to just one namespace.
{% endhint %}
### Role Types
{% hint style="info" %}
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](#user-content-fn-2)[^2] 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 @Human run.
{% endhint %}
#### Bypass
Bypass roles allow their members unlimited access to @Human with no permission checking.
Out of the box, @Human defines the default bypass role named "Super administrator". Your system administrator can [change the set of Bypass roles](#user-content-fn-3)[^3] in the `.env` file. The roles that are defined as authenticated have restricted editing options.
#### Common Roles
Common roles are any additional roles defined in the administration panel, such as application builder.
#### Contextual Roles
{% hint style="info" %}
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.
{% endhint %}
Contextual roles define a series of expressions[^1], 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.
{% hint style="danger" %}
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.
{% endhint %}
For example, a certain case of use would allow us to use contextual roles to permit resources owners to perform operations they normally wouldn’t have, such as editing and deleting said resources.
Refer to the [Contextual Role Evaluation](#user-content-fn-1)[^1] 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.
@Human defines the default authenticated role named "Authenticated". Your system administrator can [change the set of authenticated roles ](#user-content-fn-1)[^1]in the `.env` file. The roles that are defined as authenticated have restricted editing options.
If the user is authenticated with @Human 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.
@Human defines the default anonymous role named "Anonymous". Your system administrator can [change the set of anonymous roles](#user-content-fn-1)[^1] in the `.env` file. The roles that are defined as anonymous have restricted editing options.
If the user is **not** authenticated with @Human when they are accessing a resource, the system additionally assigns them anonymous roles.
### 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 is somehow removed or changed to the extent where the system can not identify it, the system should 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. In the occasion where this is not the case, the system will refuse to start.
{% hint style="danger" %}
Only members of the bypass role may manage the membership of the bypass role.
{% endhint %}
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
| User | A user is an entity that is accessing @Human. A user can be a member of security roles and cannot get permissions directly without an assigned role. |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Role |
A role represents a set of users and a set of permissions over resources.
@Human’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`). |
| Resource | A structured piece of information stored within @Human that we may or may not control access to. Each resource belongs to a component and has a unique type. |
| Resource Type | A resource type defines the structure of information within the @Human 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 @Human. |
| Security Session | A security session is created when a user requests to access @Human. |
[^1]: Add link
[^2]: Add URL and change name
[^3]:
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.planetcrust.com/platform-administration-console/security-model-rbac/security-model-introduction.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.