What this is about
Most roles belong to a module and apply in a tenant. A few roles do not: they apply everywhere and are checked by the platform itself, not by a module. These are the platform’s realm roles. In Keycloak they live on the realm level, in the token under realm_access.roles.
The six roles at a glance
| Role | What for | Who checks it | In the role catalog | Granted by |
|---|---|---|---|---|
platform-admin | manages the platform: all tenants, all users, the catalog | CIAS on every management operation | yes, PLATFORM, delegation empty | only a platform administrator |
user | every person with an account; the floor, not a permission | – | yes, PLATFORM | platform administrator; registrations without a tenant grant it as an initial role |
mail-template-admin | change the wording of every mail: the defaults and every tenant’s | CIAS when mail templates are edited | yes, PLATFORM | platform administrator |
allowed-tenant-context-switch | switch into another tenant | filter chain on the header tenant | no | directly in Keycloak |
allowed-user-context-switch | work on behalf of another person who has consented | filter chain on the header user | no | directly in Keycloak |
declaration-reader | read a module’s declaration, GET /cias/fetch | the module, for example CDMS | no | directly in Keycloak, on the account CIAS reads with |
Each role in detail
When: Someone has to create tenants, define roles, manage users.
Which roles count as platform administrator is set by the installation in code, not in a setting with a default value. In the standalone CIAS, this is platform-admin. A platform administrator may grant any role and meets every ceiling. The role itself is never delegated: its delegation list is empty, so only another platform administrator grants it.
Result: The first person gets it on the first start if the installation is set up that way, see below.
When: Every person with an account.
Not a real permission, but the floor. The installation lists it as a realm role that is created at startup. A registration without a tenant grants it as an initial role.
Result: In the catalog as a platform role, can be granted by platform-admin.
When: Somebody should maintain the wording of the mails without administering the platform.
Whoever holds this role edits every mail template: the default of every mail and the wording of every tenant. Which roles may do so is set by the installation through CIAS_NOTIFICATION_EDITOR_ROLES; the default is platform-admin and mail-template-admin. Because the role reaches the wording of every tenant, it is a realm role and is never granted within a tenant.
Result: See Editing mail templates.
When: Support needs to look into a tenant they are not a member of.
The filter chain allows the privileged switch through the header tenant only with this role, and only into tenants from the list of allowed tenants. It is not in any catalog and is not granted through CIAS.
Result: See Switch between tenants.
When: Support needs to see what a specific person sees.
The filter chain applies the header user only with this role. Without it, a request with the header is refused, 403 cias.authentication.user-switch-denied. The role alone is not enough, though: the target person has to have consented to the switch, otherwise 403 cias.authentication.user-switch-not-consented. Whoever holds the role may also request a consent. The role is not in any catalog and is not granted through CIAS.
Result: See User switch by header.
When: CIAS reads the declaration of a module that runs as a separate service.
The module answers GET /cias/fetch only for tokens with one of its reader roles. In CDMS, the list is in codamai.cdms.cias.reader-roles, in the generated project with declaration-reader. An empty list means: nobody.
Result: See Modules register their roles.
Why the switch roles are realm roles
The two switch roles must follow the person everywhere. If allowed-tenant-context-switch were attached to a tenant, the person could switch once, would then be in the target tenant without the role, and could not get back. And an organization that could grant such roles would open access to other tenants for its administrators.
Where realm roles come from
-
1CIAS→Keycloakcreates the realm roles that the installation lists under
startup.realm-roles, for exampleuser -
2CIASenters the platform roles from the bootstrap configuration in the catalog, in the standalone CIAS
platform-admin,userandmail-template-admin, without an owner module -
3CIAS→Keycloakgives the platform administrator role to the account with the configured address, if setResult: The installation has a first platform administrator
The account for the first platform administrator must already exist in Keycloak. CIAS does not create accounts with a password. If the configuration names an address without an account, the application does not start, instead of silently skipping it.
Because the platform roles do not belong to any module, no reconciliation ever retires them.
Do not confuse: the roles of CIAS as a module
tenant-admin, tenant-owner and tenant-user sound like platform roles, but they are tenant roles. CIAS registers them like any other module, they live on the CIAS client and apply in a tenant.
| Role | Meaning | In the standalone CIAS, can be granted by |
|---|---|---|
tenant-admin | manages a tenant | tenant-owner, platform-admin |
tenant-owner | founded the tenant | platform-admin |
tenant-user | member of a tenant | tenant-admin, platform-admin |
So further administrators are appointed by the tenant’s owner, not by every administrator. Only a platform administrator can appoint another owner.