CodamAIDocs
Topicdone

The admin interface

The pages for users, tenants, roles, groups, registrations and email templates, and which CIAS flows they trigger.

Variants
UsersTenantsRolesGroupsRegistrationsEmail templateswithout the platform administrator roleaccount without a tenant

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.

A click on “Suspend” in the user list
  1. Frontend
    Menu
    Does the session have the role platform-admin?
    ↳ no Area “Access” is missing from the menu
  2. BFF
    BFF route
    Valid access token and role platform-admin among all of the person's roles?
    ↳ no 401 or 403 “role missing”, CIAS is not asked
  3. CIAS
    Admin API
    Is the person a platform administrator?
    ↳ no 403
  4. CIAS
    Business rule
    Is the step allowed in the current state?
    ↳ no 409 with an error key, the page shows the matching text
  5. 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”
nonoControl and administration, no area “Access”. Typing an /access/… address shows the error message “role missing”
noyesAll 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

What each page does

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

ButtonBFF routeCIAS call
ListGET /api/hub/identity/tenantsGET /cias/admin/tenants
Create tenantPOST /api/hub/identity/tenantsPOST /cias/admin/tenants, with validity followed by POST …/{id}/validity
Activate, suspend, closePUT …/tenants/{key}/statusPOST /cias/admin/tenants/{id}/activate (for a suspended tenant /resume), /suspend, /close
Save validityPUT …/tenants/{key}/validityPOST /cias/admin/tenants/{id}/validity
Provision againPUT …/tenants/{key}/provisioningPOST /cias/admin/tenants/{id}/retry-provisioning
Detail pageGET …/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

ButtonCIAS call
ListGET /cias/admin/users/page (page by page until all are loaded) and the people’s groups
Adopt from IAMPOST /cias/admin/users/import
ActivatePOST /cias/admin/users/{id}/reactivate
Suspend, closePOST /cias/admin/users/{id}/suspend, /close, each with reason
Edit: display namePOST /cias/admin/users/{id}/rename
Edit: home tenantPOST /cias/admin/users/{id}/tenant
Edit: groupsPOST /cias/admin/groups/{key}/members and …/members/remove, only for the changes
Edit: project accessPOST /cias/admin/users/{id}/profile-attributes with projects
Detail: grant rolePOST /cias/admin/role-assignments
Detail: revokePOST /cias/admin/role-assignments/{id}/revoke with reason
Detail: save attributesPOST /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

PageButtonCIAS call
RegistrationsListGET /cias/admin/registrations?state=…
Approve, rejectPOST /cias/admin/registrations/{id}/approve, /reject with reason
Set up againPOST /cias/admin/registrations/{id}/retry
ActivatePOST /cias/admin/registrations/{id}/activate
DiscardPOST /cias/admin/registrations/{id}/discard
Email templatesList, save, reset, deleteGET, POST /cias/notification/templates, POST …/{id}/reset, DELETE …/{id}
GroupsList, create, change, deleteGET, POST /cias/admin/groups, PUT, DELETE …/{key}
MembersGET, POST …/{key}/members, POST …/{key}/members/remove
Adopt, reconcilePOST /cias/admin/groups/import, POST /cias/admin/groups/reconcile
RolesCatalogGET /cias/admin/roles, for pickers GET /cias/admin/roles/page
Reconcile with the modulesPOST /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.

Pitfalls

Next

Sources in the code and the knowledge base
  • hub-frontend – app/layouts/default.vue (navSections), app/composables/usePermissions.ts, shared/constants/roles.ts (PLATFORM_ADMIN_ROLE, FRONTEND_ROLES), app/middleware/auth.global.ts
  • hub-frontend – app/pages/access/** (users, tenants, groups, roles, registrations.vue, mail-templates.vue), app/components/access/*Dialog.vue, RoleCatalogue.vue
  • hub-frontend – server/api/hub/identity/**, server/api/hub/admin/registrations/**, server/api/hub/notification/templates/**, server/api/hub/me/tenant.get.ts, server/api/hub/identity/me/locale.*.ts
  • hub-frontend – server/utils/requireRole.ts, effectiveRoles.ts, ciasFetch.ts, mapUser.ts, mapTenant.ts, mapGroup.ts, mapRole.ts
  • CIAS – UserAdminController, TenantAdminController, GroupAdminController, RoleAdminController, RegistrationAdminController, MailTemplateAdminController, UserSelfController
  • CIAS/cias-frontend – app/layouts/default.vue
Search