What this is about
CIAS manages a handful of objects: users, tenants, roles and so on. For each object there are two questions:
- Who owns it? Who decides what it means, and where does the authoritative version live?
- What does Keycloak keep of it? Many objects also exist in Keycloak, but only as a copy that CIAS wrote.
The exception is login data such as password and MFA. It exists only in Keycloak.
The object diagram
flowchart TB
MOD["Module<br/>e.g. CDMS"] -- "registers" --> R["Role<br/>(client, key)"]
MOD -- "registers" --> AT["Attribute<br/>catalog entry"]
U["User"] -- "belongs to" --> M["Tenant"]
RV["Role grant<br/>from–until, state"] -- "who" --> U
RV -- "what" --> R
RV -. "where (optional)" .-> M
G["Group"] -- "bundles" --> R
U -- "member of" --> G
U -- "has values for" --> AT
Read it like this: a module registers roles and attributes. A role grant connects a user with a role, optionally in a tenant. A group bundles roles, and whoever is a member gets all of them.
The table
| Object | What it is | Owned by | Counterpart in Keycloak |
|---|---|---|---|
| User | a person with email, display name, status and home tenant | CIAS (business), Keycloak (login) | the account, with password, MFA and sessions |
| Tenant | a customer unit whose data is separated from others | CIAS | for a dynamic tenant an organization, for a static one nothing |
| Role | a named permission of a module, such as model-editor | the module decides the meaning, CIAS keeps the catalog | a realm role or client role |
| Role grant | “person X has role Y, from when, until when, in which tenant” | CIAS | a role mapping on the account, or membership in a group inside the organization |
| Group | a bundle of roles, also across modules | CIAS | a group in the realm, marked as managed by CIAS |
| User attribute | a business note about the person | CIAS | none |
| Profile attribute | a value on the account that goes into the token, such as projects | the module registers it, CIAS writes | entry in the realm’s user profile, plus a mapper into the token |
| Module | a building block that needs roles and attributes, such as CDMS or CRMS | the installation assigns the name | none. Keycloak only knows the deployment’s client |
In Keycloak, a realm is a closed area with its own accounts and roles. A client there is the entry for a program that requests or checks tokens.
Each object in detail
When: A person should use the application.
CIAS keeps email, display name, status (PENDING, ACTIVE, SUSPENDED, CLOSED) and the home tenant. The email address is the account: there is one person per address. The CIAS record and the Keycloak account are linked through the account's ID in Keycloak. Password, MFA and session exist only in Keycloak. CIAS does not keep tenants other than the home tenant on the user. They live in Keycloak, as membership in an organization or in the attribute allowedTenants, and arrive through the token. More: The user record.
When: A customer gets their own separated data area.
CIAS keeps key, name, type (STATIC or DYNAMIC), business status, provisioning state and a validity from–until. A dynamic tenant has an organization in Keycloak; CIAS only remembers its ID as a reference. A static tenant has no counterpart in Keycloak; the assignment is then in the attribute tenant on the account. More: Static and dynamic tenants.
When: A module needs a permission that it wants to have granted.
A role always has a two-part name: client and key, for example cdms-backend and model-editor. CIAS also keeps the scope (PLATFORM or TENANT), the module that registered it, and the delegation: who may pass it on. When a module stops registering a role, the role is retired, not deleted. More: The role catalog.
When: A person gets a role.
CIAS stores every grant as its own record: who, which role, in which tenant, from when until when, by whom and why. The state is SCHEDULED (starts later), ACTIVE, EXPIRED or REVOKED. In Keycloak a global grant becomes a role mapping on the account. A grant in a tenant becomes membership in a group inside the organization that carries exactly this role. More: Granting a role and Time-limited roles.
When: Many people should get the same roles.
CIAS keeps key, name, the roles and the members. A group may carry roles of several modules at once, but only roles that are in the catalog. A group can be the default group: every new account joins it. Keycloak gets a copy of every group, marked with cias-managed=true. CIAS never touches groups without this mark. More: What a group is.
When: The business wants to remember something about the person.
A free key-value pair on the person's CIAS record. It stays in CIAS, does not go to Keycloak and ends up in no token. Login data never belongs here. More: Maintaining a person's attributes.
When: A module needs to know something about the person, for example for an attribute filter.
The module registers the attribute. CIAS takes it into its attribute catalog, adds it to the realm's user profile and creates the mapper that puts it into the token. The value itself is stored on the account in Keycloak. If the attribute is registered per tenant, the value lives in CIAS instead, per person and tenant, and replaces the token's value on every request. More: Two origins of attributes and One value per person or per tenant.
When: A building block such as CDMS, CRMS or CIAS itself runs in a deployment.
A module is not a record you create. It registers itself with its roles and attributes at startup. The installation assigns its name, which must be unique and stable. Keycloak does not know the module, only the deployment's client. If CDMS, CIAS and CRMS run in one program, they share one client. More: Modules register their roles.
Who owns what, at a glance
- password
- MFA
- session
- link to external login services
- roles
- role grants
- groups and members
- attributes in the profile
- organization of a dynamic tenant
- tenant status and validity
- time limit and reason of a grant
- delegation
- user attributes
- attribute values per tenant
- registrations
Write order: revoke first, grant last
Because every object lives in two places, a write can fail halfway. CIAS therefore writes in a fixed order:
| Operation | Order | What remains after a failure in between |
|---|---|---|
| grant something (add role, group, member) | CIAS first, then Keycloak | CIAS knows it, the token does not carry it yet |
| revoke something (remove role, remove member, delete group) | Keycloak first, then CIAS | the permission is gone, the record still exists |
In both cases the person ends up with fewer permissions, never more. The reconciliation at startup or on demand repairs the rest. More under The write order.