What this is about
A person who registers needs a few roles from the start, otherwise they cannot do anything after the first sign-in. Which roles these are is not fixed in code but set by a rule set. It knows three situations:
| Situation | applies when | Default |
|---|---|---|
TENANT_FOUNDER | the registration founds a new tenant (CREATE_NEW) | tenant-owner, tenant-admin, tenant-user (client roles) |
TENANT_MEMBER | the person joins an existing tenant | tenant-user (client role) |
TENANTLESS | the registration has no tenant (NONE) | user (realm role) |
The situation depends only on the tenant assignment, not on the variant. So an invitation by a tenant administrator is TENANT_MEMBER, and a self-registration with CREATE_NEW is TENANT_FOUNDER.
Where the roles come from
-
CIASTenant ruleIs there a rule for this tenant and this situation? Then only that rule applies
-
CIASInstallation ruleOtherwise: is there a rule without a tenant for this situation?
-
CIASDefaultOtherwise: the
RegistrationRolesbean - The initial roles are fixed. After that, hooks may still change them
The three levels
When: No stored rule matches.
The RegistrationRoles bean in the application's code. cias-runtime and the hub ship it: founder tenant-owner, tenant-admin and tenant-user, member tenant-user, without tenant user. The founder gets all three so that she can run her tenant without a platform administrator: inviting requires tenant-admin, and she can only pass on what she holds herself. If registration is switched on and the bean is missing, the application does not start. There is no built-in standard set.
When: A platform administrator writes a rule without a tenant.
PUT /cias/admin/registration-rules/{situation} with { "roles": [ { "key": "…", "level": "MODULE" } ] }. Each role must be in the role catalog and must not be retired. The rule applies to all tenants that have no rule of their own.
When: A tenant administrator wants different initial roles for their tenant.
The same endpoint, called with a token that carries a tenant. The rule applies only to this tenant. Each role must be tenant-scoped, and all roles must be delegated through one role that the author holds themselves. They must also hold each role themselves (ceiling). CIAS remembers through which role the rule was written.
Result: The rule replaces the installation rule for this tenant.
level is MODULE for a client role of your own client or REALM for a realm role. It is required.
Why replace instead of add?
If the tenant rule only added to the installation rule, a tenant could only ever grant more, never less. “New members first get read access only” would then not be possible. That is why: if the tenant has a rule, only that rule counts.
Installation, TENANT_MEMBER: tenant-user, report-read
Tenant nordbau, TENANT_MEMBER: report-readNew member in nordbau: report-read
New member in suedlogistik: tenant-user, report-readTwo authorities
| Installation rule | Tenant rule | |
|---|---|---|
| Who writes it | platform administrator | tenant administration, as delegated |
| Who it applies to | all tenants without their own rule | only this tenant |
| Which roles | all from the catalog | only tenant-scoped, delegated, held by the author |
| Checked when applied | no | yes, the delegation |
Delegation when applied
A tenant rule is checked not only when it is written, but on every registration that applies it. CIAS then asks the catalog: may the role through which the rule was written still pass on these roles?
If the installation has withdrawn the delegation in the meantime, CIAS does not apply the rule and does not grant a reduced set either. The registration is not completed, and the log says which rule is no longer covered. The tenant administration then rewrites the rule or deletes it.
Hooks and ceiling
After the rule set, a hook with onAssignInitialRoles may still change the set. CIAS then only checks that each role exists. What the rule set grants is granted by the installation, not by a single person. That is why the ceiling applies when a rule is written, not when roles are granted.