Platform Roles
What this screen is for
A tenant's roles screen lets a tenant administrator compose custom roles out of permissions they already hold, and shows the built-in roles locked.
This screen, opened by the Roles entry of the platform sidebar under the title Role Management, is where the built-in roles themselves are defined: the nine System roles of the installation — PLATFORM_SUPER_ADMIN, PLATFORM_OPERATOR, PLATFORM_AUDITOR, PLATFORM_VIEWER, TENANT_ADMINISTRATOR, TENANT_ACCESS_ADMINISTRATOR, TENANT_KEY_MANAGER, TENANT_AUDITOR and TENANT_VIEWER — each listed with its category, its description and how many permissions it carries.
What a platform role can do that a tenant role cannot is therefore not a matter of scope count. A change made here to TENANT_ADMINISTRATOR changes what every tenant administrator on the installation may do, in every tenant, at once. Nothing composed on a tenant's roles screen reaches beyond that tenant. Custom roles never appear here.
What must exist first
This is a platform screen: opening it while you are working inside a tenant sends you to that tenant's dashboard. Before you work here:
- The permission to list roles, which shows the sidebar entry and the list, and the permission to read the scope catalog, which fills the checklist behind each role. The built-in platform administrator, operator, auditor and viewer roles hold both, so the whole page is readable to them.
- The permission to update platform roles, held by the built-in platform administrator only, for Save and Reset. Without it the same checklist renders disabled and the drawer says so; the write controls are absent rather than greyed.
Decisions you make here
Reading a role
Clicking a row opens the role's drawer: every permission of the catalog as a checkbox, ticked when the role grants it, with a filter by name or description and a category selector, and a line counting how many of the catalog's permissions the role grants. The catalog offered is the set of permissions a person can hold; permissions reserved for service-to-service calls, and permissions declared but enforced by no operation, are left out.
Changing what a built-in role grants
With the update permission, tick and untick, then Save replaces the role's permission set with exactly what is ticked; Reset returns the drawer to the set it loaded. Saving a set identical to the current one changes nothing and records nothing. If another administrator saved the same role while your drawer was open, the save is refused as Role was modified by another admin, your ticks are kept, and Retry reloads the role so you can apply them to the current version.
Three things the platform refuses in a set: a permission it does not know, a permission reserved for service-to-service calls — the refusal deliberately does not name it — and a permission that is declared but enforced by nowhere. Nothing here checks planes: a permission the platform reserves for its own plane can be ticked into a tenant role and is accepted. Whether it then unlocks anything depends on the operation, and many platform operations also require the caller to be on the platform plane.
The drawer's description says that a change takes effect on the next sign-in and that active sessions keep their original permissions until then. That is not what the platform does.
A person's session carries role names, and each request expands them to permissions through a cache the save invalidates, so every holder has the new set on their next request once that invalidation reaches them — immediately in the usual case, and within a minute otherwise. That is true in both directions: a permission you remove is gone from a holder's next request, and nobody is signed out.
Cryptographic actors are not affected either way: an actor's permissions are the role names it holds, never a role's expanded set.
PLATFORM_SUPER_ADMIN itself is never saved: its permissions are the platform catalogue's, and a save of it is refused even when nothing changed. To give a platform administrator fewer permissions, assign them another platform role.
Read the consequence before you save. Removing a permission from another platform role removes it from every platform administrator holding it; removing one from a tenant role removes it from every person holding that role in every tenant. Adding one to a tenant role grants it to all of them.
What this screen does not do
It creates no role and deletes none: the nine built-in roles are the whole list, and a role composed by a tenant is edited and deleted only on that tenant's roles screen. It assigns nothing: who holds a platform role is decided on the platform users screen, and who holds a tenant role inside each tenant.
How it relates to other screens
Platform roles are assigned to people on the platform users screen, and the four built-in platform roles are also the only ones that can enter a tenant:
A tenant's administrator composes custom roles, bounded by their own permissions, on the tenant roles screen, and sees the built-in ones read-only there: