User and Access Management
Tenant administrators control who can use their tenant and what those people are allowed to do, within the limits the platform administrator sets — identity provider configuration, platform-wide policies, and the role model.
Identity Provider Architecture
In a production multi-tenant deployment, Keycloak is the central identity provider for all OLIVE tenants and platform components. See Environment and Deployment Profiles for how the deployments differ.
What a Tenant Gets at Onboarding
- Its own Keycloak realm — an isolated identity namespace, named after the tenant
- A tenant admin user —
<tenant>_admin, created with full configuration rights in that realm, holdingadminandeditor. Your platform administrator hands over its initial password, which Keycloak requires you to change at first sign-in - Self-service management — the tenant administrator manages users, roles and realm settings without involving the platform administrator
The realm console is at https://<your-keycloak-host>/admin/<tenant>/console/.
Identity isolation is therefore realm-level: a user in one tenant's realm has no presence in another's.
Adding Users and Clients
Users are managed directly in Keycloak, in your own realm. Managing Users — Procedures has the task-by-task version: adding a user, assigning a role, removing access, enforcing MFA for admins, and reviewing who has what.
The clients are created by OLIVE's tenant onboarding and should not be added to or removed by hand.
Roles and Permissions
OLIVE recognises three levels of access, of which only two are roles you assign:
| Role | Capabilities | Realm role |
|---|---|---|
| Admin | Full privileges to configure and manage tenant assets, and to import and export OLIVE Connectivity Bundles. Administrative functions only — an admin is not an editor, and the two roles should be held by separate accounts | admin |
| Editor | Creating and managing connectivity: instantiating templates and editing connectivity instances | editor (introduced in 1.1.0) |
| User | Consuming and executing existing configurations | none — see the note below |
Three things are administrative even though they look like ordinary content in the editor, and all three moved from editor to admin in 1.3:
- Importing an OLIVE Connectivity Bundle — it writes into a live tenant and can overwrite what is there.
- Connectivity entries tagged
core— the entries delivered with the foundational package. They are hidden in the editor unless it is opened with the URL parameterdebug=true, and they define how OLIVE's own services behave, so changing one changes the platform underneath every solution in that tenant rather than changing a solution. In normal operation nobody edits them. - Deploying or changing a pilet (UI component) — a pilet runs inside an authenticated user's browser session, so it is treated as an administrative change. Connectivity engineers build and test pilets in a development deployment and hand them over for production.
A development deployment has no authentication and a single user who holds every permission, so all three are freely available there. The restriction only becomes visible when the same work moves to production.
The realm also ships two groups, which are the simplest way to assign these:
| Group | Grants |
|---|---|
/admins | admin and editor |
/users | tenant-user |
OLIVE checks for editor and admin. A person holding neither is an ordinary user — they sign in and execute the connectivity they are entitled to, with no role assignment at all.
The realm does define a tenant-user role, and the /users group grants it, but nothing in OLIVE reads it. It is harmless to assign and harmless to omit; /users is useful as a group to keep ordinary users in, not as something that grants them anything.
Roles can be assigned to a user directly or through group membership, and to service clients as well as people.
/admins grants both roles — the recommendation is not toThe shipped /admins group is a convenience for development and small-team deployments, and it grants editor alongside admin. We recommend that an account holding admin does not also hold editor.
The reason is the one in the warning below: connectivity runs with the privileges of whoever executes it, so an account that both edits connectivity and holds administrative rights is the account through which an administrative action can be performed by someone who does not hold the role. Keeping the two apart removes that path.
In a production tenant, prefer assigning roles directly, or build two groups of your own — one granting editor, one granting admin — and give a person who needs both two accounts, one in each. Do not add admin to a working account. See Platform Administrator → Identity and Secrets.
An admin account should be used for administration, and nothing else. Give each administrator an ordinary user account for everyday use and a separate account for administrative work.
The reason is specific rather than general hygiene. Connectivity runs with the privileges of whoever executes it. A connector can be built that reaches datapoints only an admin may call — clearing data, changing log settings — and it does nothing at all when an ordinary user runs it. It succeeds the moment an administrator runs it, while appearing to be a normal piece of connectivity. Not being signed in as an admin during routine work removes the opportunity entirely.
The same applies to reviewing connectivity you did not write: read what it calls before you run it.
Authentication Flows
OLIVE supports user-to-machine and machine-to-machine authentication over OIDC and OAuth 2.0.
The Clients
Each tenant realm carries four OLIVE confidential clients. Three come from the realm import; the fourth is created by the onboarding job. The Clients list also shows Keycloak's own built-ins — account, account-console, admin-cli, broker, realm-management, security-admin-console — which are normal and not OLIVE's. None of them is public, and direct access grants — username and password straight to the token endpoint — are disabled on all of them.
| Client | Purpose | Flow | Service account holds |
|---|---|---|---|
olive-gateway-user | The unprivileged gateway client | Authorization code | Nothing beyond the realm defaults |
olive-gateway | The client OAuth2 Proxy signs your users in with. Its secret is what the tenant's sign-in depends on | Authorization code | A composite client role editor, which includes the realm role editor |
olive-gateway-admin | Administrative operations | Authorization code | A composite client role admin, which includes the realm role admin |
olive-session-purge | Read-only access to the realm's admin event log, for the session-purge CronJob | Service account only — no interactive login | realm-management: view-events in this realm, and nothing else |
All four issue scoped JWT access tokens carrying the caller's authorization level.
olive-gateway-admin's service account resolves to the realm role admin. Anyone holding that client's secret can act as an administrator of your tenant without signing in, and without appearing in a list of users. Treat all four secrets as administrative credentials.
Two of them are held in both Keycloak and HashiCorp Vault, so rotating them is not something you can complete alone:
| Client | Secret also in Vault? | Rotation |
|---|---|---|
olive-gateway | Yes — reconciled into the tenant's oauth2-proxy entry on every sync | Needs your platform administrator; see the procedure |
olive-session-purge | Yes — same entry | Needs your platform administrator |
olive-gateway-user | No — Keycloak only | Regenerating it affects only what consumes it |
olive-gateway-admin | No — Keycloak only | Regenerating it affects only what consumes it |
Regenerating either of the first two in Keycloak alone leaves Keycloak and Vault disagreeing, and the symptom is a tenant whose users cannot sign in.
olive-session-purge exists so the purge job is not an administratorThe session-purge CronJob needs to read the realm's admin event log to notice that a user was disabled or deleted. Rather than giving it the Keycloak master administrator credential, onboarding creates this client with exactly one permission — view-events on this realm. It cannot read users, change anything, or see any other realm.
olive-gateway also drives the platform's own scheduled jobsSigning your users in is not the only thing this client does. Three internal CronJobs obtain a token for olive-gateway with the client-credentials grant and call OLIVE APIs with it:
| Job | What it does |
|---|---|
| Scheduler trigger | Executes every ScheduledTask in the tenant — scheduled DataPoints, Connectors and Workflows |
| Data-orchestrator cleanup | Deletes orchestrator entries whose TTL has passed |
| Session-memory cleanup | Deletes session-memory entries whose TTL has passed |
Each of those endpoints is guarded by the realm role editor, which olive-gateway holds through its composite client role. So in Keycloak:
- Do not rename or delete the client. The job looks it up by the exact id
olive-gateway. - Do not remove the
editorrole from it, and do not narrow the composite role that grants it. - Replacing it with a different client is not supported — the jobs read its secret from a platform-managed location, so another client's id would be sent with
olive-gateway's secret and rejected.
Any of those changes stops scheduled execution and TTL cleanup, and the failure is quiet: the jobs fail in the background with 401 responses, nothing in the OLIVE UI indicates it, and storage keeps growing. If scheduled tasks stop firing, this client is the first thing to check.
Authentication Proxy
All OIDC flows are mediated by OAuth2 Proxy, which handles redirects, logins and token validation, and enforces authentication before a request reaches OLIVE's APIs or UI. Authentication happens at the edge, which is why the ingress configuration and the identity provider have to agree — see Ingress Requirements.
Session and Token Lifetimes
Access tokens issued by Keycloak are JWTs, signed so that every service can verify them without calling back to Keycloak. They are short-lived by design: a stolen token is only useful until it expires.
The realm OLIVE ships sets:
| Setting | Default in the OLIVE realm | Where to change it |
|---|---|---|
| Access token lifespan | 5 minutes | Realm Settings → Tokens → Access Tokens → Access Token Lifespan |
| SSO session idle timeout | 8 hours | Realm Settings → Sessions → SSO Session Idle |
| SSO session max lifespan | 24 hours | Realm Settings → Sessions → SSO Session Max |
Keycloak also allows these to be overridden per client, under Clients → client → Advanced → Advanced Settings — but see the warning below before assuming that helps. Keycloak's own reference is Timeouts.
Session data itself is held in OLIVE's Session Memory service, isolated per tenant.
Long-Running Orchestrations
Keycloak issues refresh tokens, but data orchestration does not use them. An orchestration therefore runs on the access token it started with, and an operation that takes longer than the access token lifespan can outlive the token that authorized it.
There are two ways to deal with that, and the order matters:
- Shorten the operation. Break a long orchestration into steps, or run it through the workflow engine, which manages long-running executions as workflows rather than as one call held open. This keeps the default five-minute token, and it is the only option that costs nothing.
- Extend the access token lifespan, if the operation genuinely cannot be shortened. Set it to at least the expected duration — a two-hour orchestration needs tokens valid for at least two hours.
Keycloak does offer a per-client override, under Clients → the client → Advanced — but it does not solve this today. An orchestration can be triggered by a user, and it then runs on that user's token — not on a token issued to some dedicated long-running client. Raising the lifespan on one client therefore leaves the user-triggered case exactly as it was. The realm-level setting is currently the only one that works.
Keycloak Features Worth Using
These are Keycloak capabilities, available to you as the realm administrator:
- Multi-factor authentication — the realm ships a TOTP policy; enforcing a second factor is a realm or role-level setting you enable. Enforce it for anyone holding the
adminrole at minimum - Brute-force detection — enabled in the realm OLIVE ships. It locks accounts after repeated failed logins
- Session management — view and revoke active sessions
- Credential management — password policies, periodic changes, recovery options. The realm OLIVE ships sets no password policy at all, so whatever your organisation requires — length, complexity, history, expiry — is yours to set, under Authentication → Policies → Password policy. Worth doing before the first user is created
- Identity brokering — federate an external identity provider
- User consent and privacy — manage consent for data usage
For the step-by-step version of the ones you will use most, see Managing Users — Procedures; for everything else, the Keycloak Server Administration Guide. How Keycloak itself is operated, upgraded and secured is not an OLIVE responsibility.
Related
- Managing Users — Procedures — the tasks: users, roles, sessions, MFA, access review
- Connectivity Applications
- Identity and Secrets