Model roles

What this is about

Every model has roles. Before CDMS runs an operation, it checks whether the matching role is in the person’s token. If it is missing, CDMS answers with 403 missing-permission|<role>.

There are two kinds of model roles:

The base role is named like the model, e.g. audit-question. It allows every operation for which nothing stricter is set.
An action role appends the operation, e.g. audit-question-read. It only exists for operations you marked as requiring a role in the hub.

How the names are built is described in How role names are built.

Which operation requires which role

In the hub, on the Permissions tab, you mark the operations CREATE, READ, UPDATE and DELETE. Every marked operation gets its action role; all others require the base role.

Operation	Endpoint	Required role
Create	`POST /create`, upload on create	create role
Read	`POST /read/{id}`, `GET /read/{id}`	read role
Search	`POST /query`	read role
Replace	`PUT /update/{id}`	update role
Change	`PATCH /update/{id}`, upload on update	update role, because PATCH has no role of its own
Delete	`DELETE /delete/{id}`	delete role
Download	`GET /{id}/file`	first the read role (the object is read), then the download role
Read history	`POST /{id}/history`	read role and history role
Roll back	`POST /{id}/rollback/{revision}`	rollback role

Download, history and rollback cannot be marked on their own in the hub. That is why they require the base role.

Which role does READ require for model question in folder audit?

READ marked in the hub	endpoint with its own role	endpoint with publicAccess	Required role
no	no	no	`audit-question`
yes	no	no	`audit-question-read`
–	yes, e.g. `report-reader`	no	`report-reader`
–	–	yes	no role, any signed-in person

Variants

How a model sets its roles

Base role onlyAction roleEndpoint rolepublicAccess

When: no operation marked in the hub

1

Build
sets the base role audit-question for every operation
2

CDMS
checks the same role for every operation

Result: One role for everything. Simple, but with no difference between reading and writing.

When: e.g. READ marked in the hub

1

Build
sets audit-question-read for READ and keeps audit-question for all other operations
2

CDMS
checks only audit-question-read when reading and searching
3

CDMS
still checks audit-question when creating, changing and deleting

Result: Readers get audit-question-read; editors get audit-question and audit-question-read if they should also read.

When: model file (YAML): endpoint with roleRequired: <name>

1

Build
takes the name unchanged as the role for this operation
2

CDMS
checks exactly this name

Result: The custom name wins over base and action role. The hub does not have this setting.

When: model file (YAML): endpoint with publicAccess: true

1

Build
sets no role for this operation
2

CDMS
skips the role check

Result: Any person with a valid token may run the operation. It still does not work without a token, see Access without a token. The filters of the row level still apply.

Where the roles come from

A person’s roles are in their token. CIAS reads them on every request and builds the effective roles from them: if a person belongs to several tenants and the organization has its own roles, the roles of the active tenant apply. CDMS checks only against these effective roles. See Effective roles: global or in the tenant.

Abstract models

An abstract model forwards every request to its subtype. The roles checked are then those of the subtype:

Creating, reading, changing and deleting through /crm/kunde/… require the roles of privatkunde or firmenkunde, depending on which type is affected.
A search over the abstract model reads each hit through its subtype. The person needs the read role of every subtype that appears in the hits.
The roles of the abstract model itself apply when another model points to the abstract model through a relation.

See Abstract models and @type.

Pitfalls

Where to go next

How the names are built: How role names are built
Permissions that apply only through a relation: Permissions on relations (field roles)
What happens with a missing role without strict mode: Strict mode