The default group

What this is about

Some roles simply everyone needs, such as the realm role user or the permission to read your own profile. Instead of adding every new person to a group by hand, you mark the group as a default group. Then every new account automatically becomes a member.

Why? Otherwise a single checkbox on a screen would change at once what thousands of existing people may do, and no screen could show beforehand who is affected.

Make a group a default group

You set "defaultGroup": true when you create or change the group, see Manage groups and members. There can be several default groups. A new account then becomes a member of all of them.

Request

PUT /cias/admin/groups/grundrechte
{
  "key": "grundrechte",
  "name": "Basic rights",
  "roles": [ { "client": null, "key": "user" } ],
  "defaultGroup": true
}

Response

HTTP 200
{ "key": "grundrechte", "memberCount": 0, "defaultGroup": true, "syncState": "SYNCHRONIZED", … }

memberCount stays 0. The response shows both side by side: memberCount is what the group is now, defaultGroup is what it will be.

Two halves, both needed

A default group lives in two places:

Half	What it does	For whom
CIAS	adds the person to the group after a completed registration and stores the membership	everyone who comes through a CIAS registration
Keycloak	CIAS puts the group on the realm’s list of default groups. Keycloak itself puts every newly created account into it	every account newly created in Keycloak

The CIAS half makes sure CIAS knows the membership: the member list, memberCount and the reconciliation see it. The Keycloak half makes sure a new account has the roles right from its first token.

The flow for a registration

A registration is completed

1

CIAS
sets up the account: tenant, membership, initial roles
2

Hook
creates the user record in CIAS
3

Hook
looks up all default groups. None? Then it stops here
4

CIAS
saves the membership in every default group
5

CIAS→Keycloak
adds the person to each of these groups

Result: The person is a member, in CIAS and in Keycloak

This step runs after the user record is created, because members are user records. It runs as a hook inside the registration: if CIAS cannot save the membership, the registration fails. An account that silently stayed without its default group would fail on its first request, and nobody would know why. More on hooks in Your own logic: hooks and events.

The variants

Who becomes a member when

registration completedexisting account registersaccount is created directly in Keycloakgroup becomes a default groupgroup is no longer a default groupKeycloak unreachable

When: Self-registration, invitation or creation by the platform administrator, and the registration is finished.

CIAS adds the person to all default groups, first in CIAS, then in Keycloak.

Result: member of all default groups

When: A person with an existing account registers for another tenant.

This registration also ends with the same hook. The person becomes a member of the default groups they are not in yet. If they already were a member, it stays one membership.

Result: member of all default groups

When: Someone creates an account in the Keycloak console or through Keycloak's own registration page.

Keycloak itself puts the account into the default groups. CIAS learns nothing about it and does not manage this membership. The next reconciliation brings the members in Keycloak in line with CIAS and removes the person again.

Result: member only until the next reconciliation. For a lasting membership: import the account and add it in CIAS

When: defaultGroup changes from false to true.

CIAS registers the group as a default group in Keycloak. Nobody is added after the fact.

Result: applies from the next new account on

When: defaultGroup changes from true to false.

CIAS first removes the group from Keycloak's list, then changes its own record. All members stay members.

Result: no new members any more, existing ones stay

When: Keycloak does not answer when the person is added after the registration.

The membership is in CIAS, the group becomes PENDING. The registration does not fail: nobody should lose their account because Keycloak was briefly away. The next reconciliation catches up the membership in Keycloak.

Result: registration finished, roles in the token only after the reconciliation

The decision

Does this person become a member of the default group?

How is the account created?	Was the group already a default group then?	Result
through a CIAS registration	yes	yes, in CIAS and Keycloak
directly in Keycloak	yes	only in Keycloak, until the next reconciliation
the account already exists	–	no, unless the person registers anew for a tenant
–	no	no, not even afterwards

The default group

What this is about

Make a group a default group

Two halves, both needed

The flow for a registration

The variants

The decision

Pitfalls

Next