Skip to main content

Tenant Onboarding and Offboarding

Platform administrators provision new tenants and retire them safely—including identity setup in Keycloak, platform resources, and coordination with tenant administrators.

Onboarding a Tenant​

Onboarding a new tenant involves the following steps:

  1. Add entry to infrastructure repository: Create a new entry for the tenant in the infrastructure Git repository.
  2. Add chart from template: Add the OLIVE Platform Helm chart for the tenant using the template provided in the template Git repository.
  3. Configure values.yaml: Customize the values.yaml file for the new tenant with appropriate configuration values.
  4. Import connectivity bundle: Import the foundational OLIVE connectivity bundle for the corresponding platform version. This bundle provides the base connectivity and integration capabilities required for the tenant.
  5. Automatic deployment: Once changes are checked in and ArgoCD is correctly configured, the new tenant is automatically deployed to the platform.
Identity and secrets are created by the sync, not by you — but they are yours to verify

Nothing in the list above sets up Keycloak or Vault by hand. Two charts in the tenant's deployment do it on every sync:

ChartWhat it creates for the tenant
keycloak-setupThe tenant's Keycloak realm, named after the tenant: its four confidential clients, the realm roles, the groups and the administrator account. It also mirrors two client secrets into Vault.
vault-secrets-setupThe tenant's Vault policies, Kubernetes auth roles and KV paths, and the ServiceAccount bindings the pods authenticate with.

Both run as Jobs, and both are idempotent — a re-sync reconciles rather than recreates. What that means for you is that a tenant whose realm or Vault entries are missing is a failed Job, not a missing step: check the Jobs in the tenant's namespace and in the Vault namespace before adding anything manually.

Three things to confirm before handing the tenant over:

  1. The realm exists and you can sign in to it — see Verify the Deployment.
  2. The tenant's <tenant>-oauth2-proxy-secret entry exists in Vault with all five values; without it, users cannot sign in.
  3. The tenant administrator has what they need: the Keycloak host, their realm administrator credentials, and the tenant's OLIVE address. Reusing a tenant name whose Vault and Keycloak state was never cleaned up is the usual cause of an onboarding that half-succeeds — see Uninstall and Teardown.

The tenant administrator account and its initial password​

The keycloak-setup Job creates one administrator account in the new realm, and the realm is named after the tenant:

Username<tenant>_admin
Realm<tenant>
Realm rolesadmin, editor
Keycloak permissionsrealm-management: realm-admin — full administration of this realm, and no access to any other
PasswordGenerated by the Job, 24 random characters, flagged temporary

The generated password is written to Vault, which is where you retrieve it in order to hand it over:

kubectl exec -it <vault-pod> -n <vault-namespace> -- \
vault kv get secret/shared-secrets-<tenant>/keycloak-credentials-<tenant>

The entry holds two fields, username and password.

It is a one-time password, and Vault is not kept in step with Keycloak

The account is created with the required action Update Password, so the value from Vault works for exactly one sign-in and the tenant administrator then chooses their own. Nothing writes that new password back, so from the first sign-in onwards the Vault entry is a record of what was issued, not the current credential.

If a tenant administrator loses access later, the answer is a password reset in Keycloak — by you in the master console, or by another administrator of that realm — not a look in Vault.

If there is no credential in Vault

The Job generates and stores the password only when it imports the realm. A realm that was created by an earlier run, or by hand, can therefore exist with nothing at that Vault path — and the password cannot be reconstructed, because the realm stores only a hash. The Job says so in its log rather than failing the sync, so a tenant that is otherwise green can still be a tenant nobody can administer. Retrieve the credential as part of onboarding rather than when the tenant administrator first asks for it.

This is recoverable. As platform administrator you hold the Keycloak master administrator credential, which administers every realm on the server: sign in to the tenant's realm with it, reset the password of <tenant>_admin — leaving Temporary on, so the tenant administrator sets their own at first sign-in — and store the new value at the path above. The same route repairs anything else the realm needs after an unusual onboarding.

Keep it a recovery action rather than a habit:

  • The master credential is yours. It is never handed to a tenant administrator — their realm-admin rights in their own realm are what they need, and the master account would give them every other tenant as well.
  • Prefer a password reset over editing the realm by hand. The realm's clients, roles and groups are reconciled by the chart on every sync, so a manual change to them is either redundant or will be overwritten.
  • Interventions are recorded. Admin events are enabled on every realm by the onboarding Job, so what you change in a tenant realm is auditable — which is the point of using the account deliberately and rarely.

What to hand over to the tenant administrator​

Four things, none of which the tenant administrator can discover alone:

WhatValue
Their realm<tenant>
Keycloak realm consolehttps://<keycloak-host>/admin/<tenant>/console/
Initial credentials<tenant>_admin and the password from Vault, to be changed at first sign-in
The tenant's OLIVE addresshttps://<tenant>.<cluster>.<domain> — where their users sign in

The Keycloak host is global.keycloakBaseURL, or https://authenticate.<cluster>.<domain> when that value is not set.

Link them to Managing Users — Procedures, and point out that the realm has no SMTP server configured, so the credential-reset email they would normally send to a new user does not work until they configure one.

The administrator account is not an everyday account

<tenant>_admin holds admin and editor together, which is convenient for setting a tenant up and wrong for running it. Tell the tenant administrator to create separate accounts for daily work — see Administrative accounts are not for daily use.

Development vs. Production Deployments​

The deployment environment significantly impacts how tenants are configured and deployed:

Regardless of the deployment type, all tenants (both development and production) require the foundational OLIVE connectivity bundle for the corresponding platform version to be imported to ensure proper platform integration and functionality.

Removing a Tenant​

To remove a tenant from the platform:

  1. Remove infrastructure entry: Simply remove the tenant entry from the infrastructure Git repository.
  2. Data considerations: Export the tenant's content first — the storage goes with the namespace.
  3. Clean up what the deployment does not own: the tenant's Vault policies, auth roles and KV data, and its Keycloak realm, are not removed with the deployment. Reusing the tenant name without cleaning them up is the usual cause of a tenant that onboards halfway and then fails on every retry.

Uninstall and Teardown covers all of this in detail, including removing the whole platform.

Resource Scaling​

When adding or removing tenants, pay attention to monitoring infrastructure resources. Certain services may need to be scaled higher or lower based on the new tenant configuration:

  • Adding tenants may require scaling up services to accommodate increased demand
  • Removing tenants may allow you to scale down services if capacity is no longer needed

Refer to the Resource Scaling guide for detailed information on how to adjust resource allocations.