Sign-in and people

One account signs in to every application on the server. Accounts live in Keycloak, the sign-in service at auth.yourdomain.com, in a single realm named vps. The groups an account belongs to decide which applications it can open.

In Settings > Sign-in requirements, What signing in requires offers:

Option	Effect
Password only	The default.
Password and an authenticator app	Every account must set up an authenticator app.

The setting applies to every account, existing ones included: each person is asked to set up an authenticator app at the next sign-in and cannot skip it. It covers the administrators of Keycloak’s own console too, described below. The section ends with Save and apply; the sign-in service restarts briefly.

While the setting is on Password only, a notice at the top of every admin page recommends the authenticator app. Dismiss hides it for good, and selecting Password and an authenticator app hides it too.

The realm also keeps these rules on every configuration run: self-registration is off, the email address is the username, duplicate emails are refused, usernames cannot be edited, and brute-force protection is on. An application’s refusal of an account outside its groups is not a failed sign-in for that protection (see Groups).

Groups

Access is decided by Keycloak groups.

Group	Meaning
`admin`	Whoever runs the server. Opens every application and the admin panel. Assigned deliberately, never by default.
`staff`	Employees. Departments are subgroups of `staff` (for example `accounting`), giving finer-grained access.
`client`	External users such as customers or partners. New accounts land here.
`visitor`	A keyword in an application’s access setting meaning “anyone, signed in or not”. It is never a real group and never appears in a sign-in token.

An application lists the groups allowed to open it; admin is always allowed. An application opened to a department subgroup admits only that department. See Configure an app for Catena for the labels that set this.

An application that signs in by itself refuses an account outside its groups. This holds for an account that signs in through an identity provider added in Keycloak, including an organization’s. The refusal never counts toward the account’s lockout (see Sign-in requirements).

A change of group takes effect the next time the person signs in.

Manage people in Keycloak (every edition)

You manage everyone by signing in to auth.yourdomain.com (realm vps) with an admin account. From the administration console:

Add a person: create the user with username and email, put the account in the right group, and either set a password or leave it blank and send an invitation (this needs Outgoing email).
Change access: add or remove the account in a group.
Remove someone: disable the account to block sign-in at once across every application while keeping its record, or delete it.
Lost second factor: you clear it on the account in Keycloak, and the person sets it up again.

People can reset their own password from the sign-in page, edit their profile and set up their own authenticator app without any request.

Keycloak’s own administration console

The top-level console at auth.yourdomain.com/admin (the master realm) has its own admin account, separate from the people above.

At your first sign-in there, Keycloak asks you to set up a one-time code in an authenticator app. It asks for that code at every sign-in after.
With Password and an authenticator app selected in Settings, every other account holding the admin role in that console, such as a recovery account you created, is asked to set up a one-time code at its next sign-in too. The configuration run that Save and apply starts asks for it; an account that already has a code is left alone. The automation account the server uses to configure Keycloak is not a person’s account and is not asked.
After repeated wrong passwords the account locks for a pause that grows with each failure, up to 15 minutes.

If you switch the vps realm off in Keycloak, it stays off. Updates and configuration runs never switch it back on, and apps that sign in through it show as waiting on the Apps tab until you switch it on again.

The name on the sign-in page follows the server’s domain: after a domain change it takes the new domain. A name you set yourself in the realm settings stays.

People panel (Catena Pro)

The People panel in the menu manages accounts and groups from the admin panel. The editions are compared at catena.run.

It shows Groups, with the applications each one opens, and People, with username, email and a “disabled” marker for disabled accounts. It can create, rename and delete groups, add people to groups and disable accounts.

Before a group is renamed or deleted, the panel shows “What this change affects”: the “Applications gated on this group” and the “People currently in this group”. Applications left with no group would be open to administrators only: “These applications would be left open to administrators only. They keep running, and quietly stop admitting everyone else.” Confirming applies exactly the change that was shown; if the list changed in the meantime, the panel asks you to read it again.

Every change is recorded in the administrative log.

If the panel reports “This server has no directory credential yet, so the list of people cannot be read. It arrives with the next configuration run.”, run Bring this server up to date in Server settings to provide it.

Troubleshooting

A person reaches an application they should not: check their groups in Keycloak, then the groups the application lists.
An application admits no one but admins: its group was deleted or renamed. The impact preview in the People panel shows this beforehand.
No reset email: see Outgoing email.