The key terms in pictures

What this is about

The same nine words come up again and again on this learning site. Here each one gets one sentence and one small picture. The details are on the page each section links to.

The map

This is how the nine terms fit together:

flowchart LR
    U["User"] -- "belongs to" --> M["Tenant"]
    U -- "member of" --> G["Group"]
    G -- "bundles" --> R["Role"]
    U -- "has" --> R
    U -- "has values for" --> A["Attribute"]
    M --> T(["Token"])
    R --> T
    A --> T
    T -- "with every request" --> D["CDMS"]
    D -- "role allows operation on" --> Mo["Model"]
    Mo -- "calls" --> H["Hook"]
    Mo -- "records" --> Rv["Revision"]

The left half belongs to CIAS and Keycloak: Who is the person, where do they belong, what may they do? The right half belongs to CDMS: Which data exists, and what happens to it? The token is the bridge between the two.

Token

A token is a signed pass that Keycloak issues after login and that the client sends along with every request.

flowchart LR
    K["Keycloak<br/>issues, signs"] --> T(["Token<br/>who, tenant,<br/>roles, attributes"])
    T --> F["Filter chain<br/>checks, reads"]
    F --> RC["RequestContext<br/>valid for one request"]

The CIAS filter chain checks the signature and expiry itself, without asking Keycloak. It then puts the result into the RequestContext, and from then on CDMS reads only from there. What is in the token applies until it expires. A revoked permission therefore disappears only with the next token.

More: What happens to the token on every request, What is read from the token, Why revoking a permission takes effect with a delay

Tenant

A tenant is a customer whose data stays separate from the data of every other customer.

flowchart LR
    A(["Request in<br/>tenant nordbau"]) --> DA[("Database<br/>nordbau")]
    A -. "never" .-> DB[("Database<br/>suedlogistik")]

CIAS manages the tenants. Which tenant applies to a request comes from the token: for a dynamic tenant from the organization in Keycloak, for a static one from the attribute tenant. After that the tenant gate asks CIAS whether this tenant is currently being served. In operating mode MULTI every tenant has its own database. In SINGLE there are no tenants.

More: Tenant, organization, group, Admitting the tenant (tenant gate), SINGLE and MULTI

User

A user is a person who has an account in Keycloak for logging in and a record in CIAS with their business meaning.

flowchart LR
    C["CIAS record<br/>status, home tenant"] -- "points to" --> K["Keycloak account<br/>password, MFA"]
    K -- "ID as sub<br/>in the token" --> D["CDMS<br/>_userId, history"]

Both halves hang on the ID of the Keycloak account. In the token it is sub. CDMS knows only this ID and the name from the token. It stores the ID in _userId, for example, and in the history.

More: The user record, The life of a user

Role

A role is a named permission like hr-employee-read that sits in the token and that CDMS compares with the roles of a model.

flowchart LR
    M["Module<br/>declares"] --> C["CIAS<br/>catalog, grant"]
    C --> K["Keycloak"]
    K --> T(["Token"])
    T --> D["CDMS<br/>check model role"]

A module declares its roles, CIAS keeps them in the role catalog, grants them and writes them to Keycloak. CDMS does not simply check the roles in the token, but the effective roles the filter chain builds from them: if the person has their own roles in their active, dynamic tenant, these replace the globally granted client roles. Realm roles always apply.

More: The role catalog, Effective roles: global or in the tenant, Model roles, How a role gets from the code into the token

Group

A group is a bundle of roles, and every member gets all roles of the group.

flowchart LR
    A["Anna"] -- "member" --> G["Group<br/>support"]
    B["Ben"] -- "member" --> G
    G --> R1["customer-read"]
    G --> R2["order-edit"]

A group applies platform-wide and belongs to no tenant. Being a member means: the same roles. It does not mean that you see the data of the other members. CIAS manages the group, Keycloak holds a copy so the roles get into the token.

More: What a group is, Group roles under dynamic tenants

Attribute

An attribute is a named value on a person, for example projects = alpha, beta, that CDMS uses to limit the visible rows.

flowchart LR
    V(["projects =<br/>alpha, beta"]) --> F["Attribute filter<br/>in CDMS"]
    F --> W["only rows with<br/>project IN (alpha, beta)"]

An attribute applies either per person (USER): then the value comes through the token. Or it applies per person and tenant (USER_IN_TENANT): then CIAS fetches the value for the active tenant on every request and replaces the value from the token with it. In the attribute filter a * lifts the restriction, and a missing attribute makes the request fail.

More: Two sources of attributes, One value per person or per tenant, Attribute filter

Model

A model describes a thing in your subject area, for example Customer, with fields, relations, endpoints, roles and filters.

flowchart LR
    H["Hub<br/>model Customer"] --> B["Build<br/>generator"]
    B --> A["table, endpoints,<br/>roles, filters"]

You describe the model in the hub, and the build generates the code from it. The level of the model (system, tenant or user) decides which database its data lives in and who sees which rows.

More: Modeling in the hub, Model levels: system, tenant, user, Which endpoints a model has

Hook

A hook is a class in your project that CDMS calls at fixed points of a standard flow, so you can plug in your own business logic.

flowchart LR
    A(["PATCH"]) --> BH["before hook<br/>may still change"]
    BH --> DB[("Database")]
    DB --> AH["after hook"]
    AH --> R(["Response"])

A hook belongs to one model. It runs before the database change (before) or after it (after), and when reading only after. Both run in the transaction of the request. Registration in CIAS has its own hooks too, which a project uses to adapt the flow.

More: Hooks: kinds and points in time, The order within a write, Custom logic: hooks and events

Revision

A revision is a saved state of an object after a change, with a number, a point in time and the person who acted.

flowchart LR
    R1["17 · ADD"] --> R2["42 · MOD"]
    R2 --> R3["58 · MOD<br/>rollback to 17"]
    R3 --> R4["63 · DEL"]

Revisions exist only for audited models. All revisions of an object together are its history. A rollback writes the old state as a new revision; the history is never rewritten. The numbers count per database, so per tenant.

More: What is audited, What a revision records, Rolling back to an old state

All terms in one table

Pitfalls

Next

• The CodamAI modules
• Who takes part in a request
• Who decides what?