Skip to main content

Identity and Secrets

This page covers the three identity layers a platform administrator configures: the workload identities that services use to reach Vault, the secrets themselves and their rotation, and the user identities that Keycloak issues.

Workload identities: serviceAccounts.mode​

global:
serviceAccounts:
mode: split # split | legacy

Why split exists​

Before 1.3, each tenant had a single Kubernetes ServiceAccount, tenant-service-account-<tenant>, shared by every workload in the namespace — and that one identity was bound to all four of the tenant's Vault roles. The consequence is worth stating plainly: the carefully separated Vault policies collapsed into their union. Any pod holding that ServiceAccount could obtain any of the four policies, including the one that reads the Keycloak master credential.

In split mode the identity is divided into four purpose-scoped ServiceAccounts, each bound to exactly one Vault role, with bound_service_account_names naming precisely one account — so Vault rejects a login presenting any other identity.

ServiceAccountPurposeVault roleGrantsToken TTL
tenant-service-account-<tenant>Application / default tenant identityshared-secrets-role-<tenant>Read/write across the tenant secret space; read-only on infrastructure and identity secrets; explicit deny on vault-client-token15 min (max 1 h)
tenant-vso-sa-<tenant>Vault Secrets Operator syncvso-sync-role-<tenant>Read and list only1 h
tenant-infra-sa-<tenant>Infrastructure bootstraptenant-infra-role-<tenant>Create/update/read on exactly two paths: couchdb-credentials, seaweedfs-credentials15 min
tenant-keycloak-sa-<tenant>Keycloak onboardingkeycloak-onboard-role-<tenant>Read the Keycloak master credential; manage the two tenant identity secrets; write auth/jwt-<tenant>/config with every security-relevant parameter pinned15 min

A fifth role, token-issuer-role-<tenant>, binds only the Vault Secrets Operator's own ServiceAccount and is not part of the tenant identity set.

What split mode achieves​

  • The policy separation becomes enforceable rather than merely intended.
  • The Keycloak master credential is contained — reachable only by the realm-import job, where previously every CouchDB, SeaweedFS and application pod in the namespace had a path to it.
  • Blast radius is bounded per workload. Compromising the CouchDB bootstrap job now yields two storage credentials instead of the full tenant secret space plus Keycloak realm administration.
  • Workload identities have no Kubernetes API rights. The RoleBinding names only the human rbac.adminUser. The workload ServiceAccounts are deliberately unbound — they authenticate to Vault, not to the Kubernetes API. create pods was removed from the Role and secrets narrowed to read-only, which removes the privilege-escalation primitive entirely.
  • Tokens are not mounted by default. All four set automountServiceAccountToken: false. A pod that genuinely needs a Vault login opts back in explicitly in its own pod spec, so any new workload landing on one of these identities gets no token unless someone deliberately grants it.
  • Shorter-lived credentials. The main tenant role dropped from 1 h / 24 h to 15 min / 1 h.
legacy mode

legacy reproduces the pre-1.3 single shared ServiceAccount. It exists for compatibility during a migration and should not be used in a new deployment. In legacy mode the Vault policy separation is nominal, not enforced.

The tenant administrator Role​

In split mode the namespace Role governs the human rbac.adminUser only. The hardened default is read-only on pods and secrets, with no pod creation and no secret mutation:

rbac:
adminUser: "someone@example.com"
role:
rules:
- apiGroups: ['']
resources: ['pods', 'services', 'configmaps', 'secrets']
verbs: ['get', 'list']
- apiGroups: ['']
resources: ['services', 'configmaps']
verbs: ['create', 'update', 'delete']

Widen it only for what your administrators actually do.

Where secrets live​

HashiCorp Vault is the central store for credentials, API keys, certificates and tokens. Microservices authenticate to Vault using the requesting user's JWT, so Vault evaluates the user's identity, tenant context and roles against configured authentication roles and access policies — rather than the application deciding for itself what it is entitled to read.

global:
vault:
namespace: 'oli-hashicorp-vault'
serviceName: 'oli-vault'
port: 8200
scheme: 'http'
keycloakVaultPath: keycloak/oli-keycloak-credentials

keycloakVaultPath is relative to the KV mount. The chart refuses to render if it repeats the mount or contains a data/ segment, and the error message tells you the correct value.

Infrastructure secrets and application secrets no longer share a path, a role or a policy, which closes the escalation route from the Editor into infrastructure credentials.

Kubernetes Secrets: know what is authoritative​

Vault is the source of truth for tenant secrets and most infrastructure secrets, but a smaller set exists as conventional Kubernetes Secrets. The operationally important question is not whether a Secret exists in etcd but where its authoritative copy lives, because that determines whether deleting it is harmless, self-healing, or destructive:

How it got thereAuthoritative copyWhat happens if it disappears
Helm renders itThe Helm releaseMay regenerate with a different value
Vault Secrets Operator mirrors itVaultSelf-heals within the refresh interval
A bootstrap job writes itetcd — nothing reconciles itLost. Applies to vault-init-keys and vault-root-token
An operator owns itThe operator (cert-manager, CloudNativePG)Do not touch

Keep this inventory current for your installation. It is a prerequisite for any credible recovery procedure.

Rotating storage credentials​

CouchDB and SeaweedFS credentials are generated and stored in Vault. rotationId is the switch that asks for a new one:

couchdb:
credentials:
rotationId: '2026.09.04'

seaweedfs:
credentials:
rotationId: '2026.09.04'

Change the string to any new value — a date, a ticket ID, a counter — and on the next sync the rotation job sees a rotationId different from the one stored, generates new credentials, and writes them to Vault; the StatefulSet's pod annotation carries the same rotationId, so the pods roll onto the new credentials. Leaving the value unchanged leaves the credentials alone.

Use a date or a ticket ID rather than an incrementing number, so the value tells you when and why it was rotated.

For the full inventory of infrastructure secrets and how each one is rotated — organised by mechanism, since they do not all rotate the same way — see Secrets Rotation.

User identities: Keycloak​

OLIVE uses Keycloak for identity and access management, OAuth2 Proxy to run the OpenID Connect flow, and the ingress gateway to ensure only authenticated requests reach the services. Each microservice then validates the JWT again independently — signature, issuer, audience, expiry — rather than trusting that the edge did it. In a microservice architecture where services call each other directly, internal traffic must not be treated as inherently trusted.

global:
keycloakBaseURL: 'https://auth.develop.olive-team.com'
jwtIssuer:
rootPath: https://auth.develop.olive-team.com/realms/
additionalRootPaths: []

Issuers are compared exactly — no wildcards, no suffix matching — so each entry in additionalRootPaths widens trust by precisely one issuer. Entries must be https.

What you configure in the realm​

These are Keycloak settings, not chart values:

SettingRecommendation
Multi-factor authenticationEnforce for administrative roles at minimum. MFA is a native Keycloak capability, configurable per realm and enforceable per role — no product change is needed to mandate it.
Brute-force detectionEnabled.
Session lifetimesSet an absolute maximum that covers the paths OLIVE uses. Verify that removing a user actually terminates their sessions rather than leaving a valid token in circulation.
Audit loggingCapture is on in a newly onboarded realm — user events with a 30-day expiration from the realm import, admin events re-enforced on every sync. Emission is separate: Keycloak writes successes at DEBUG, so set global.audit.successLevel: info and logFormat: json or a correctly capturing realm emits nothing. A realm onboarded before user events became the default still has them off — realm import only reaches new realms.

For operator-level administrators who authenticate against the cluster operator's identity infrastructure rather than a tenant realm, MFA is that operator's responsibility.

OLIVE roles: user, editor, admin​

OLIVE distinguishes three levels of access, and from 1.3 they are genuinely different permissions rather than three names for the same thing — the mapping to Vault roles reflects the distinction, and requireRoleCheck is the single enforcement point. It emits a security event on both success and denial for privileged operations (OLIAUTHZ1–OLIAUTHZ3).

LevelRealm roleMay
usernoneExecute connectivity, read what they are entitled to
editoreditorAdditionally create and change connectivity definitions
adminadminAdministrative functions — but not ordinary editing functions

Only two roles are therefore assigned. "User" is the absence of both: a person with no role assignment is an ordinary user. The tenant realm also defines a tenant-user role and a /users group that grants it, but nothing in OLIVE reads it — see Tenant Administrators → Roles and Permissions.

Do not give an admin account the editor role

Our recommendation is that an account holding admin does not also hold editor. OLIVE does not forbid the combination — forbidding it in the product would make development and small-team deployments impractical — so it is your policy decision, enforced through role assignment.

The reason is specific rather than general hygiene, and it is set out under Administrative accounts are not for daily use: connectivity executes with the privileges of whoever runs it. An account that both authors connectivity and holds administrative rights is the account through which an administrative action can be obtained by someone who cannot hold the role themselves.

Note that the tenant realm's shipped /admins group grants both roles. It is a convenience for development; in a production tenant, assign the roles directly or build two groups of your own, and give a person who needs both capabilities two accounts with one role each.

Administrative accounts are not for daily use​

Connectivity executes with the permissions of the user who runs it, not those of the user who wrote it. A connector containing a privileged datapoint — clearing data, changing log settings, any admin-only operation — fails the role check for an ordinary user and succeeds for an administrator.

That makes an administrator who uses their admin account for ordinary work into a lever: someone who cannot obtain the admin role can still get administrative actions performed, simply by writing a connector and getting an administrator to execute it. They never need the role; they need the click.

Make this an explicit rule for your deployment, because the platform cannot enforce it for you:

  • An admin account is used for administrative tasks only — never for executing or testing connectivity, and never for everyday work.
  • Issue separate accounts where a person needs both. One person, two accounts, one role each. Do not solve it by adding the admin role to a working account.
  • Enforce MFA on the administrative accounts, and treat a sign-in to one as a deliberate act rather than a default.
  • An administrator should not execute connectivity on someone else's behalf without reading the whole definition first, including every element it calls.

Every administrative action that is performed emits OLIAUTHZ1 with the acting user, and an attempt without the role emits OLIAUTHZ2. Reviewing OLIAUTHZ1 events is how you would notice this pattern after the fact — an admin account performing privileged operations during ordinary connectivity execution is the signature to look for. See Security Logging.