Manage groups and members

What this is about

You manage groups through the admin API under /cias/admin/groups. The user interfaces for this call exactly these endpoints, see The admin interface.

The endpoints

Lists always come in pages: items, page, size, total, hasMore. Without a value you get 50 rows, at most 500. If you ask for more, you get 400 instead of silently fewer rows.

The checks

The 403 looks exactly like every other refusal of the permission check. CIAS writes the exact reason to the log.

Create a group

POST /cias/admin/groups
Authorization: Bearer <token of a platform administrator>
{
  "key": "support",
  "name": "Support 1st Level",
  "description": "Everyone in phone support",
  "roles": [
    { "client": null, "key": "user" },
    { "client": "cdms-backend", "key": "customer-read" },
    { "client": "crms-backend", "key": "ticket-edit" }
  ],
  "defaultGroup": false
}

HTTP 200
{
  "key": "support",
  "name": "Support 1st Level",
  "description": "Everyone in phone support",
  "roles": [
    { "client": null, "key": "user", "displayName": "User",
      "scope": "PLATFORM", "effectiveInEveryTenant": true },
    { "client": "cdms-backend", "key": "customer-read", "displayName": "Read customers",
      "scope": "PLATFORM", "effectiveInEveryTenant": false },
    { "client": "crms-backend", "key": "ticket-edit", "displayName": "Edit tickets",
      "scope": "TENANT", "effectiveInEveryTenant": false }
  ],
  "memberCount": 0,
  "defaultGroup": false,
  "syncState": "SYNCHRONIZED"
}

A freshly created group has no members yet. So it does not give anyone anything yet.

The six variants

Changing roles means: send the whole list

There is no “add role” and no “remove role”. With PUT you always send the complete list. You remove a role by sending the list without it. Whatever you leave out goes away, in Keycloak too, even if it was the last role of a module.

The key cannot be changed. If a group should be called something else, change name.

Members are user records

userIds are the IDs of the user records in CIAS, not the Keycloak sub. How to find them is described in The user record. The list must not be empty, otherwise 400. You can add or remove several people at once, just like ticking boxes in an interface.

Take over existing Keycloak groups

A realm that existed before CIAS often contains groups that someone created in the Keycloak console. They carry no cias-managed mark, so CIAS does not touch them. With the import, CIAS takes them over.

POST /cias/admin/groups/import

HTTP 200
{
  "found": 4,
  "adopted": 2,
  "alreadyKnown": 1,
  "skipped": [
    { "group": "buchhaltung",
      "reason": "it carries 1 role(s) the CIAS catalogue does not know (erp:invoice-approve) — their module has to declare them first, or the next reconciliation would take them off the group" }
  ]
}

A group is taken over completely or not at all. Why so strict? Whatever CIAS manages, the reconciliation later writes back to Keycloak. If CIAS simply left out an unknown role, the next reconciliation would take it away from the group. If CIAS left out an unknown member, that person would be thrown out of the group. So: first have the module declare the missing roles and import the missing accounts, then repeat the import.

The import can safely be repeated. Groups that were taken over carry the mark and no longer show up in the next run. An interrupted run is finished the next time. alreadyKnown counts Keycloak groups without the mark whose name CIAS already uses for a group of its own. They stay untouched. The import does not take over subgroups, only the top level.

Errors at a glance

Pitfalls

Next

• The default group
• Reconciliation with Keycloak
• What a group is