What this is about
CRMS does not manage roles. It gets from CIAS who is asking and then only checks: is the required role in this person’s list? Which role is needed for what, you set per project in the hub.
How CRMS knows the person
On every request, CRMS asks CIAS for the caller, meaning the person behind the request. CIAS returns four things, all from the checked token:
| Field | Meaning |
|---|---|
| authenticated | whether there is a person at all. Without one, CRMS answers 401 crms-authentication-required |
| person | who is asking, as the identity provider names them. CRMS records them on every revision, approval and document |
| tenant | the person’s tenant, or none |
| roles | the realm roles and the client’s roles together in one list |
A platform administrator role only counts if it is in the token as a realm role. Nobody can get it through a tenant’s organization. More on this in Effective roles and The realm roles of the platform.
When: CRMS runs in the application's process
-
1User→Clientsends a request with their token
-
2CIASchecks the token and determines person, tenant and roles
-
3CRMSreads the caller from CIAS. The client roles are those of the application's client
When: CRMS runs as a separate service, the application uses crms-client
-
1Client→CRMSpasses the person's token on unchanged
-
2CIASexchanges the token in the CRMS service for one for its own client
-
3CRMSreads the caller. The client roles are those the person holds on the CRMS service's client
How the exchange works is described in Token exchange.
All roles at a glance
| What | Field in the hub | Variable | Default | How many |
|---|---|---|---|---|
write your own templates (scope USER) | templateRoleUser | CODAMAI_CRMS_TEMPLATE_ROLES_USER | crms-template-personal | exactly one |
write the tenant’s templates (scope TENANT) | templateRoleTenant | CODAMAI_CRMS_TEMPLATE_ROLES_TENANT | crms-template-author | exactly one |
write system templates (scope SYSTEM) | – | – | the platform administrator roles from CIAS | those of CIAS |
| approve or reject an approval stage | role of a stage in approvalStages | – | – | one per stage |
| list, read, verify documents | documentRoleRead | CODAMAI_CRMS_REST_DOCUMENT_ROLES_READ | crms-document-reader | list |
| set and release a legal hold | documentRoleHold | CODAMAI_CRMS_REST_DOCUMENT_ROLES_HOLD | crms-document-custodian | list |
| erase documents | documentRoleErase | CODAMAI_CRMS_REST_DOCUMENT_ROLES_ERASE | crms-document-eraser | list |
The hub writes your values into the configuration as the default during the build. The variable can override it in an environment. For the document roles it is a comma-separated list, and one matching role is enough. An empty list admits nobody. Where you find the fields is described in The CRMS module in the hub.
Rendering needs no role. Every signed-in person may render, with every template they can see.
See: which templates a person finds
A template belongs to a scope: the system, a tenant or a single person in a tenant. Whether you see it depends only on who it belongs to. No role is needed for that.
| Scope of the edition | Does it belong to you? | Do you see it? |
|---|---|---|
| SYSTEM | – | yes, every signed-in person |
| TENANT | your tenant | yes |
| TENANT | another tenant | no, 404 template-not-found |
| USER | you yourself in the same tenant | yes |
| USER | another person | no, 404. Exception when approving, see below |
Write: editions, drafts, submitting
Writing means: creating an edition or variant, reading and saving the draft, submitting, rolling back and retiring. For this, CRMS checks three things in a row:
-
1CRMSCan you see the edition? Otherwise 404
template-not-found -
2CRMSIs its scope admitted in this installation? Otherwise 422
template-scope-not-admitted -
3CRMSDo you have the write role of this scope? Otherwise 403
template-write-denied -
4CRMSThe change is carried out and written into the chain with your name
A new edition in scope TENANT also needs a tenant in the token, otherwise 422 template-tenant-required.
System templates are written by the platform administrators that CIAS names for the installation. CRMS has no role of its own for this. If scope SYSTEM is admitted and CIAS names no administrator role, the application does not start.
Approve: the role of the stage
A submitted revision goes through the approval stages of its scope. Each stage names a role. Only someone with the role of the current stage may approve or reject. The write role is not needed for this.
| Check | Otherwise |
|---|---|
| You can see the edition, or it is the personal template of a person in your tenant | 404 template-not-found |
| The revision is waiting for approval | 409 template-revision-not-in-review |
| You have not approved this revision yet | 409 approval-already-given |
| You have the role of the current stage | 403 approval-role-missing |
| The stage does not exclude the author, or you are not the author | 403 approval-author-excluded |
The exception in the first row is on purpose: personal templates are reviewed by the tenant’s reviewers. What stages, the minimum number of reviewers and the meaning of an approval look like is described in Approval.
Documents: three roles instead of one
Someone who reads audit reports is not automatically the person who freezes them for a court. And not the one who erases a data subject’s documents either. That is why there are three roles.
- The archive itself checks the role before it looks anything up. This holds the same whether your application calls it embedded, whether the request comes through
/crms/documentsor throughcrms-clientat the CRMS service. A refusal (403document-access-denied) does not reveal whether the document exists. - After that, the archive only works in the person’s tenant. A document of another tenant does not exist for them: 404
document-not-found. - A platform administrator has no document role just because they are an administrator.