How a role gets from the code into the token

What this is about

A role passes through several stations before it allows a request. Each station has its own topic in this chapter. This page shows the whole path with one example: the role order-edit from a CDMS model should allow Ben to edit orders in tenant nordbau.

The whole path

sequenceDiagram
    participant M as CDMS module
    participant C as CIAS
    participant K as Keycloak
    participant A as Anna (Admin)
    participant B as Ben
    participant F as Filter chain
    Note over M: Build: generator writes order-edit into the declaration
    C->>M: Read declaration (bean or GET /cias/fetch)
    M-->>C: roles: order-edit
    C->>K: Create client role order-edit on cdms-backend
    C->>C: Catalog: cdms-backend/order-edit, TENANT, owner cdms
    A->>C: POST /cias/admin/role-assignments (Ben, order-edit, nordbau)
    C->>C: Check delegation, tenant, ceiling, store grant
    C->>K: Ben into group cdms-backend:order-edit of organization nordbau
    B->>K: Sign in or renew token
    K-->>B: Token with organization.nordbau.resource_access.cdms-backend.roles = [order-edit]
    B->>F: Request with token
    F->>F: Tenant nordbau, effective roles: order-edit
    F-->>M: RequestContext with order-edit
    M->>M: Check model role: editing allowed

The stations

The stations of a role

1

Generator
at build time, writes the role order-edit from the model into the module's declaration
2

CIAS→Keycloak
Reconciliation: reads the declaration and creates the client role on cdms-backend
3

CIAS
Catalog: enters it, scope TENANT, owner cdms, delegation from the installation
4

Admin→CIAS
Grant: Anna grants order-edit to Ben in nordbau
5

CIAS→Keycloak
Entry: Ben becomes a member of the group cdms-backend:order-edit in the organization nordbau
6

Keycloak
Token: on the next sign-in or renewal, the role is in the organization claim
7

Filter chain
Read out: for nordbau, takes the roles of its own client from the claim

Result: order-edit is in the RequestContext, CDMS allows editing

Station	What can go wrong	Topic
Declaration	module not readable, declaration rejected	Modules register their roles
Reconciliation	Keycloak not reachable → catalog stays unchanged	Reconciliation with Keycloak
Catalog	role retired → no new grant	The role catalog
Grant	no delegation, wrong tenant, ceiling, tenant without organization	Grant a role
Token	old token does not carry the role yet	Renew the token
Read out	role of another client, or request runs in another tenant	Effective roles: global or in the tenant

Other ways into the token

Not every role comes through a grant

Tenant role by grantRole through a groupInitial role of a registration

When: the path above

Grant in CIAS, group in the organization, organization claim in the token.

Result: The role has a grant with an ID, can be time-limited and revoked.

When: Ben is a member of the CIAS group sachbearbeitung, which carries order-edit.

CIAS keeps the group and creates it in Keycloak as a group in the realm. The role is attached to the group, Ben is a member. In the token it appears as a global client role.

Result: No grant per person. Whoever leaves the group loses the role. See What a group is.

When: Ben founds a tenant with the registration.

The registration enters the initial roles, for example tenant-owner, directly in Keycloak, in the registration's tenant. Afterwards CIAS records them as grants, with registration as the grantor. This applies if the tenant has an organization; without one, the registration grants globally and it stays with the role in Keycloak.

Result: With an organization: a grant like any other, listed, revocable and counted for the ceiling. See Initial roles as a rule set.

Pitfalls

Realm role, client role, organization role
Grant a role
How CDMS checks the role: Model roles

What this is about

The whole path

The stations

Other ways into the token

Pitfalls

Next