What this is about
CIAS has an admin API under /cias/admin/…. The user interface people use to operate it is the Access area in the hub (hub-frontend), at the addresses /access/…. There you create tenants, suspend people, grant roles, maintain groups, work through open registrations and adjust mail texts.
The CIAS portal (cias-frontend) has no admin pages of its own. Its navigation lists further areas only greyed out. You operate the administration in the hub. What the portal shows is described in The CIAS portal.
The page map
flowchart LR
NAV["Hub<br/>area “Access”"] --> T["/access/tenants<br/>Tenants"]
NAV --> U["/access/users<br/>Users"]
NAV --> R["/access/registrations<br/>Registrations"]
NAV --> M["/access/mail-templates<br/>Email templates"]
NAV --> G["/access/groups<br/>Groups"]
NAV --> RO["/access/roles<br/>Roles"]
T --> TD["/access/tenants/{key}<br/>one tenant"]
U --> UD["/access/users/{id}<br/>one person"]
TD -. "users of the tenant" .-> U
/access on its own redirects to the user list. The order in the menu is tenants, users, registrations, email templates, groups, roles.
The path of a click
Between the browser and CIAS sits the hub’s BFF, the server part of the user interface (see Session in the BFF and cookies). Every admin page calls a route under /api/hub/…, and that route calls CIAS.
-
FrontendMenuDoes the session have the role
platform-admin?↳ no Area “Access” is missing from the menu -
BFFBFF routeValid access token and role
platform-adminamong all of the person's roles?↳ no 401 or 403 “role missing”, CIAS is not asked -
CIASAdmin APIIs the person a platform administrator?↳ no 403
-
CIASBusiness ruleIs the step allowed in the current state?↳ no 409 with an error key, the page shows the matching text
- CIAS suspends, the list reloads
The BFF sends the session’s access token as Authorization: Bearer …. For its own check it reads the realm roles from the token and the client roles from Keycloak’s userinfo endpoint. If it cannot determine the roles, it answers 502, not 403.
Who sees what
| Account needs a tenant and has none? | Role platform-admin? | What the person sees in the hub |
|---|---|---|
| yes | – | Empty menu, only settings and sign-out. Notice “No tenant assigned” |
| no | no | Control and administration, no area “Access”. Typing an /access/… address shows the error message “role missing” |
| no | yes | All pages under “Access” |
The first row comes from GET /cias/me/tenant, see Self-service information. If the installation requires a tenant and the request has none, CIAS would refuse almost every page. So the hub shows the notice right away instead of a page full of errors.
The hub checks for the role platform-admin. Which roles CIAS accepts as platform administrator is set by the installation in codamai.cias.platform-administrator-roles. See The platform’s realm roles.
The pages
When: /access/tenants and /access/tenants/{key}
The list shows every tenant with its business standing, provisioning, validity and the number of people with this home tenant. Create tenant asks for name, key, type (“Organization” = dynamic, “Static”), for “Organization” the organization in the identity provider (prefilled with the key), and the validity. Edit changes only the validity. The detail page shows all four standings side by side. Activating is only possible after provisioning has finished. For a suspended tenant, the same button resumes it. Closing asks first.
Result: See Creating and provisioning a tenant and Suspending, closing, validity.
When: /access/users and /access/users/{id}
The list shows all people across all tenants, with filters for tenant and status. Buttons per row: Activate, Suspend and Close (both with a reason), Edit (display name, home tenant, groups, project access). Adopt from IAM fetches accounts from Keycloak that CIAS does not know yet. The detail page shows directly granted roles and roles inherited through groups, Grant role (with tenant for tenant roles, end date, reason), Revoke (with reason) and the CIAS attributes. There is no “Create user” button.
Result: See Suspend, unsuspend, close, Granting a role.
When: /access/registrations
By default the queue shows the open attempts: Awaiting approval, Awaiting verification and Failed. “All” shows every state. The buttons depend on the state: Approve and Reject (with reason) for “Awaiting approval”; Set up again and Discard for “Failed”; Activate and Discard for “Awaiting verification”.
Result: See Approval by an administrator and Cleaning up abandoned registrations.
When: /access/mail-templates
The page lists the seven registration mails per language (German, English) with their default, as “Shipped” or “Own version”, and below them the wording of individual tenants. Edit opens an editor with subject, text, an HTML switch, the mail's placeholders (plus application and flow) and an optional tenant. The page marks unknown placeholders before saving. Reset gives a default the shipped text again; a tenant's wording is deleted, after which the default applies to it.
Result: See Editing templates.
When: /access/groups
The list is searched in CIAS and loaded page by page. Create group and Edit ask for name, key (fixed after creation), description, roles from the catalog and whether it is the default group. You add or remove members through a person search. On top there are Delete, Adopt from IAM and Reconcile with IAM. Groups with module roles get a notice that these roles do not apply in dynamic tenants.
Result: See Managing groups and members and Group roles under dynamic tenants.
When: /access/roles
The role catalog, read only, organized by the module that declared the role, with search and filters by origin and scope. Roles for the context switch are in a separate notice box. Reconcile with the modules starts the reconciliation and shows the report per module.
Result: See The role catalog and Reconciliation with Keycloak.
When: A signed-in person without platform-admin.
The area “Access” is missing from the menu. If the person opens a page by its address, the BFF already refuses, and the page shows “Missing permission – the role “platform-admin” is required”.
Result: No data, no calls to CIAS.
When: The installation requires a tenant, and the request has none.
The menu is empty. Above every page it says “No tenant assigned” with the signed-in name. Only the settings and sign-out stay reachable.
Result: An administrator assigns the account to a tenant, then a new sign-in is enough.
Which button triggers which call
Tenants
| Button | BFF route | CIAS call |
|---|---|---|
| List | GET /api/hub/identity/tenants | GET /cias/admin/tenants |
| Create tenant | POST /api/hub/identity/tenants | POST /cias/admin/tenants, with validity followed by POST …/{id}/validity |
| Activate, suspend, close | PUT …/tenants/{key}/status | POST /cias/admin/tenants/{id}/activate (for a suspended tenant /resume), /suspend, /close |
| Save validity | PUT …/tenants/{key}/validity | POST /cias/admin/tenants/{id}/validity |
| Provision again | PUT …/tenants/{key}/provisioning | POST /cias/admin/tenants/{id}/retry-provisioning |
| Detail page | GET …/tenants/{key} | GET /cias/admin/tenants/by-key?key=…, GET /cias/admin/users?tenantKey=… |
The pages work with the tenant’s key. CIAS addresses tenants by their ID, so the BFF reads the tenant via by-key before every change.
Users
| Button | CIAS call |
|---|---|
| List | GET /cias/admin/users/page (page by page until all are loaded) and the people’s groups |
| Adopt from IAM | POST /cias/admin/users/import |
| Activate | POST /cias/admin/users/{id}/reactivate |
| Suspend, close | POST /cias/admin/users/{id}/suspend, /close, each with reason |
| Edit: display name | POST /cias/admin/users/{id}/rename |
| Edit: home tenant | POST /cias/admin/users/{id}/tenant |
| Edit: groups | POST /cias/admin/groups/{key}/members and …/members/remove, only for the changes |
| Edit: project access | POST /cias/admin/users/{id}/profile-attributes with projects |
| Detail: grant role | POST /cias/admin/role-assignments |
| Detail: revoke | POST /cias/admin/role-assignments/{id}/revoke with reason |
| Detail: save attributes | POST /cias/admin/users/{id}/attributes, replaces the whole set |
The email address is shown in the dialog but cannot be changed. It is the sign-in and belongs to Keycloak. The steps in the dialog run one after the other and not in one transaction: if the second fails, the first is already saved. So the BFF reads the person again at the end and shows what is really there.
The project access ends up as the profile attribute projects in Keycloak, that is in the token. The attributes on the detail page are the free key-value pairs on the CIAS record. The difference is explained in Two origins of attributes.
Registrations, email templates, groups, roles
| Page | Button | CIAS call |
|---|---|---|
| Registrations | List | GET /cias/admin/registrations?state=… |
| Approve, reject | POST /cias/admin/registrations/{id}/approve, /reject with reason | |
| Set up again | POST /cias/admin/registrations/{id}/retry | |
| Activate | POST /cias/admin/registrations/{id}/activate | |
| Discard | POST /cias/admin/registrations/{id}/discard | |
| Email templates | List, save, reset, delete | GET, POST /cias/notification/templates, POST …/{id}/reset, DELETE …/{id} |
| Groups | List, create, change, delete | GET, POST /cias/admin/groups, PUT, DELETE …/{key} |
| Members | GET, POST …/{key}/members, POST …/{key}/members/remove | |
| Adopt, reconcile | POST /cias/admin/groups/import, POST /cias/admin/groups/reconcile | |
| Roles | Catalog | GET /cias/admin/roles, for pickers GET /cias/admin/roles/page |
| Reconcile with the modules | POST /cias/admin/roles/reconcile |
After Discard, the page tells you whether the address is free again. CIAS reports this with identityRemoved. If the account stayed in Keycloak, a new registration with this address runs onto it.
For every signed-in person
Two calls run for everyone, without an admin role:
- Language in the header and under settings:
PUT /cias/me/locale. The choice is stored on the account and also applies to mails. - Tenant notice:
GET /cias/me/tenant, see above.