Skip to main content

Managing Users — Procedures

Everything on this page happens in the Keycloak admin console, in your tenant's own realm. User and Access Management explains the model — the realm, the three roles, the clients, the session lifetimes. This page is the set of tasks.

Which realm, and how to reach it

Your tenant has its own realm, named after the tenant, created when the tenant was onboarded. A user in your realm has no presence in any other tenant's.

Go straight to your realm's own console:

https://<your-keycloak-host>/admin/<tenant>/console/

That URL opens your realm directly and is the form worth bookmarking. The general console at https://<your-keycloak-host>/admin opens the master realm view, with the realm selector at the top left of the left-hand menu — if you enter through it, check the selector before every change, because a role assignment made in the wrong realm appears to succeed and grants nothing.

Your account is <tenant>_admin, and the password your platform administrator gives you is a one-time one: Keycloak asks you to set your own at first sign-in. Nothing records the password you choose, so treat it accordingly — if it is lost, your platform administrator has to reset the account.

Your platform administrator provides the Keycloak host name and your administrator credentials — and, separately, your tenant's OLIVE address, which is where your users sign in. It follows the pattern https://<tenant>.<cluster>.<domain>. Record it: it is not discoverable from the Keycloak console, and it is the one thing every new user needs from you.

Keycloak's console changes between releases

The paths below are for Keycloak 26, which is what OLIVE 1.3 ships against. If a menu does not match, the authority is Keycloak's own Server Administration Guide rather than this page — the OLIVE-specific part is which role, group or client to pick, and that does not change.


Add a user​

  1. Users → Add user.
  2. Enter the username. It is the only required field, and it cannot be changed afterwards unless the realm allows it — agree a convention before you start.
  3. Fill in email, first name and last name. Set Email verified only if you have verified it yourself.
  4. Create.

A user created this way has no credentials, so they cannot sign in yet. That is the one thing you must still do; a role is optional.

Give them a way to sign in​

Prefer letting the user set their own password:

  1. On the user → Credentials → Credential reset.
  2. Set Reset actions to Update Password, and send the email.
This needs email, and the shipped realm has none configured

The realm OLIVE creates has no SMTP server set, so sending the email fails until one is. Configure it once, under Realm settings → Email — host, port, the from address and credentials — using a relay your organisation provides. Your platform administrator does not supply one; whoever runs your mail infrastructure does.

Until that is in place, use the direct route below.

Or set one directly — Credentials → Set password — and leave Temporary on, so they must change it at first sign-in. A permanent password you chose and transmitted is a credential two people know.

Decide whether they need a role​

An ordinary user needs no role — they can sign in and execute connectivity as soon as they have credentials. Only editor and admin are granted, and only to people who need them. See Assign a role below.

Then tell them where to go​

Send them your tenant's OLIVE address, not the Keycloak console — Keycloak is where you administer accounts, not where users work. Signing in there succeeds and shows them nothing useful.


Assign a role​

OLIVE reads two realm roles. The mapping between them and what a person can do is in Roles and Permissions.

Realm roleGives
editorCreating and changing connectivity
adminAdministrative functions, and importing or exporting bundles
An ordinary user needs no role at all

Assign nothing and the person is an ordinary user — they can sign in and execute the connectivity they are entitled to. "User" is the absence of editor and admin, not a role you grant.

The realm does contain a tenant-user role, and the shipped /users group grants it, but OLIVE does not check it. Assigning it is harmless and does nothing; leaving it off costs nothing. If you want a group to put ordinary users in for your own bookkeeping, /users serves that purpose — just do not expect it to be what makes them work.

So the only role decisions you actually make are: does this person edit connectivity (editor), and does this person administer the tenant (admin).

Directly, to one user:

  1. Users → select the user → Role mapping → Assign role.
  2. Switch the filter to Filter by realm roles — the default view shows client roles, and OLIVE's roles are realm roles.
  3. Select the role → Assign.

Through a group, which is easier to audit at any scale:

  1. Users → select the user → Groups → Join Group.
  2. Pick the group → Join.
The shipped /admins group grants admin and editor

Our recommendation is that an account holding admin does not also hold editor — see the warning under Roles and Permissions. /admins is a convenience for development and small teams.

For a production tenant, either assign the two roles directly, or build two groups of your own:

  1. Groups → Create group → name it, for example olive-editors.
  2. Open it → Role mapping → Assign role → Filter by realm roles → editor → Assign.
  3. Repeat for olive-admins with admin only.

Then give a person who needs both capabilities two accounts, one in each group. Do not add admin to a working account.

A role change takes effect on the user's next token, not immediately — an access token already issued keeps the claims it was signed with for up to its lifespan (five minutes by default). To make a change take effect at once, sign the user's sessions out as well.


Remove access​

Three different things, with three different effects. Pick deliberately.

Remove a role​

Users → the user → Role mapping → select the row → Unassign. They keep their account and their session; their next token no longer carries the role.

Disable the account​

Users → the user → Details → turn Enabled off → Save.

They cannot sign in again. Existing sessions and already-issued tokens are not revoked by this — sign them out as well if the point is to cut access now.

Delete the account​

Users → the user → the Action menu (top right) → Delete.

Verify that deletion actually ends their access

Deleting a user does not necessarily invalidate tokens already in circulation, and OLIVE's services validate a JWT by signature and expiry without calling back to Keycloak. A token issued seconds before the deletion stays valid until it expires.

Treat the sequence as: sign out all sessions, then disable or delete. And confirm on your realm that removing a user does terminate their sessions — this is one of the realm settings the platform administrator is asked to verify, and it is worth testing with a throwaway account rather than assuming.

Sign out one user's sessions​

Users → the user → Sessions → Sign out all active sessions (or log out a single session from its row).

This ends the OLIVE session too, because the session is held by OAuth2 Proxy against Keycloak's. The user has to sign in again.

Sign out everyone in the realm​

Sessions (left-hand menu) → the Action menu → Sign out all active sessions.

Use this after a credential incident. Everyone in your tenant has to sign in again.


Enforce multi-factor authentication​

MFA is a Keycloak capability, and the realm already ships an OTP policy. What you decide is who has to use it. At minimum, enforce it for every account holding admin.

For everyone in the realm​

  1. Authentication → Required actions.
  2. Turn Configure OTP on — set Enabled, and set Set as default action so it applies to users created from now on.

Every user is then asked to enrol an authenticator at their next sign-in. Simple, and it applies to everyone.

For one user​

Users → the user → Details → Required user actions → add Configure OTP → Save. They enrol at their next sign-in.

For holders of a role only​

This is the arrangement to aim for if you do not want MFA for ordinary users. It needs a conditional authentication flow:

  1. Authentication → Flows → open browser → the Action menu → Duplicate. Name it, for example browser-mfa-for-admins.
  2. In the copy, on the browser forms sub-flow, choose Add step → Add sub-flow, name it admin-otp, and set its requirement to Conditional.
  3. Inside admin-otp, Add condition → Condition - user role → configure it with the role admin → requirement Required.
  4. Inside admin-otp, Add step → OTP Form → requirement Required.
  5. Back on Authentication → Flows, open the Action menu on your new flow → Bind flow → Browser flow.

Users holding admin are now prompted for a second factor; everyone else is not.

Test this with a second account before you sign out

A misconfigured browser flow can lock every administrator out of the realm, including you. Keep a second session open in another browser while you bind the flow, verify a sign-in works, and only then close it. If you are locked out, rebinding the original browser flow needs realm-level access you no longer have — recovery goes through your platform administrator.


Rotate the realm's client secrets​

Your tenant's realm carries four confidential clients whose secrets are, in effect, administrative credentials: anyone holding one can obtain tokens with that client's service-account roles without a login. Treat them the way you treat passwords.

Which client you are rotating decides whether you can finish the job yourself — read the table before you touch anything, because two of the four take the tenant's sign-in down if regenerated here alone:

ClientWho completes the rotation
olive-gatewayYour platform administrator — its secret is mirrored in Vault
olive-session-purgeYour platform administrator — same
olive-gateway-userYou. Keycloak only, no Vault copy
olive-gateway-adminYou. Keycloak only, no Vault copy — and this is the one whose secret grants admin, so it is the one most worth rotating on a schedule
Do not regenerate these without your platform administrator

The olive-gateway and olive-session-purge secrets are not only held in Keycloak. OLIVE mirrors them into HashiCorp Vault, and the workloads that consume them read the value at pod start. Regenerating one of those two in Keycloak alone leaves Keycloak and Vault disagreeing, and the symptom is a tenant whose users cannot sign in.

Completing the rotation requires a re-sync of the keycloak-setup Helm release and a restart of the consuming workloads — both of which need cluster access you do not have.

Raise it with your platform administrator and have them run it. The procedure is Secrets Rotation → the tenant's auth-proxy credentials.

For the two you can rotate yourself, the control is Clients → the client → Credentials → Regenerate.

Note also that rotating the session cookie secret signs every user in the tenant out, so it is an announced, off-peak operation rather than routine maintenance.


Turn on login event capture​

A newly onboarded realm records both admin events (configuration changes, which OLIVE's session-purge job depends on) and user events (logins, logouts, failed logins), the latter with a 30-day expiration.

A realm onboarded before user events became the default still has them off, and re-syncing the platform will not turn them on — the realm import that sets them applies only when a realm is created. Check yours: Realm settings → the Events tab → User events config. If Save events is off, this is the switch:

  1. Realm settings → the Events tab → User events config.
  2. Turn Save events on.
  3. Set an expiration, so the table does not grow without bound.
  4. Save.
Capturing is not the same as shipping

With this on, events land in Keycloak's own database. Getting them into your log platform is the platform administrator's half — Keycloak writes successful events at DEBUG by default, so a correctly configured realm can still emit nothing to stdout. Ask them to set global.audit.successLevel: info and logFormat: json.

Expect one log line per user event; on a busy realm, token refreshes dominate. Keeping only failures (warn) is a reasonable compromise and still covers intrusion detection.

Review who has access​

Worth doing on a schedule, and the first thing an auditor asks for.

QuestionWhere
Who holds admin?Realm roles → admin → Users in role
Who holds editor?Realm roles → editor → Users in role
Who is in a group?Groups → the group → Members
Which roles does one person hold, including inherited ones?Users → the user → Role mapping, with Hide inherited roles turned off
Who is signed in right now?Sessions
Which accounts are disabled but still present?Users → the user → Details, where Enabled is a toggle

Two things to look for beyond the obvious:

  • An account holding both admin and editor.
  • A service account holding admin — a client's service account is an identity too, and it does not appear in a list of people.
Your own account is the exception to the first rule

The administrator account created at onboarding holds admin, editor and Keycloak's realm-admin — it has to, because it is the account that sets the realm up. It is the one account where the combination is expected.

Use it for realm administration, and create separate working accounts for yourself: one with editor for building connectivity, one with admin if you also administer tenant assets. That way the account with realm-level power is not the one you work in day to day.


What you cannot do from here​

These need your platform administrator:

  • Creating or removing a tenant
  • Changing which clients exist in your realm, or completing a client-secret rotation
  • Anything in the cluster: storage, scaling, network policy, the platform's security configuration
  • Registering an internal destination for connectivity to reach — see Connectivity Applications
  • Reading the platform's security event log — the OLIAUTHZ* and OLIFETCH* codes are emitted into the cluster's log pipeline, which you cannot reach

One thing that is yours: the access token lifespan. You hold realm-level rights, so you can raise it — but it applies to every session in the tenant, so agree it before you change it. See Long-Running Orchestrations.