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.
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.
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
- Users → Add user.
- 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.
- Fill in email, first name and last name. Set Email verified only if you have verified it yourself.
- 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:
- On the user → Credentials → Credential reset.
- Set Reset actions to Update Password, and send the email.
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 role | Gives |
|---|---|
editor | Creating and changing connectivity |
admin | Administrative functions, and importing or exporting bundles |
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:
- Users → select the user → Role mapping → Assign role.
- Switch the filter to Filter by realm roles — the default view shows client roles, and OLIVE's roles are realm roles.
- Select the role → Assign.
Through a group, which is easier to audit at any scale:
- Users → select the user → Groups → Join Group.
- Pick the group → Join.
/admins group grants admin and editorOur 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:
- Groups → Create group → name it, for example
olive-editors. - Open it → Role mapping → Assign role → Filter by realm roles →
editor→ Assign. - Repeat for
olive-adminswithadminonly.
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.
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
- Authentication → Required actions.
- 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:
- Authentication → Flows → open browser → the Action menu → Duplicate. Name it, for example
browser-mfa-for-admins. - 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. - Inside
admin-otp, Add condition → Condition - user role → configure it with the roleadmin→ requirement Required. - Inside
admin-otp, Add step → OTP Form → requirement Required. - 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.
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:
| Client | Who completes the rotation |
|---|---|
olive-gateway | Your platform administrator — its secret is mirrored in Vault |
olive-session-purge | Your platform administrator — same |
olive-gateway-user | You. Keycloak only, no Vault copy |
olive-gateway-admin | You. 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 |
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:
- Realm settings → the Events tab → User events config.
- Turn Save events on.
- Set an expiration, so the table does not grow without bound.
- Save.
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.
| Question | Where |
|---|---|
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
adminandeditor. - A service account holding
admin— a client's service account is an identity too, and it does not appear in a list of people.
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*andOLIFETCH*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.
Related
- User and Access Management — the model: realm, roles, clients, sessions and tokens
- Connectivity Applications — templates, the workbench, and import/export
- Keycloak Server Administration Guide — the authority for anything about the console itself