Skip to content

Upgrading

How to move a HelixIAM installation to a newer release, and the breaking changes that need you to act.

How the schema is migrated

HelixIAM manages its database schema one of two ways:

  • Versioned Flyway migrations (default) — in the app, the container image and the Helm chart alike. Versioned migration scripts are applied on startup, giving you an auditable, ordered migration history.
  • Legacy idempotent bootstrap — the older schema.sql path, kept for existing installs that never adopted Flyway:
HELIX_MIGRATIONS_ENABLED=false
HELIX_SQL_INIT_MODE=always

When an install that used the legacy bootstrap adopts Flyway, set HELIX_FLYWAY_BASELINE_VERSION to that schema's version.

Migrations are additive and backward-compatible unless a breaking change below says otherwise: a new release runs against the previous schema, and the previous release tolerates the new schema. This is what makes rolling upgrades safe.

Never edit a released migration

Once a migration has shipped and been applied anywhere, it is immutable. To change the schema, add a new migration. Editing an applied migration breaks checksum validation and corrupts the migration history.

How to upgrade

  1. Read the breaking changes. Work through every entry in Breaking changes between the release you run and the one you move to. Some need a step before you roll out.
  2. Back up. Take a fresh database backup (pg_dump, see Backup & disaster recovery) and keep DB_ENCRYPTION with it. Rolling back across a migration means restoring this backup.
  3. Roll out helix-iam-server. The first pod to start applies any pending migrations. Because migrations are backward-compatible, the old pods keep working against the same schema during the rollout. Session and token state lives in PostgreSQL (and Redis, if configured), not in any one pod, so a rolling replacement keeps signed-in sessions. Where a breaking change says old and new pods must not run side by side, use --set strategy.type=Recreate or scale to zero first.
  4. Roll out the console (a separate Deployment when console.enabled).
  5. Verify the running version and readiness (below).

With Helm, upgrade with --reset-then-reuse-values (Helm 3.14 or later), not --reuse-values: it keeps the values you set and adds the defaults of sections a newer chart introduced. With --reuse-values those sections are missing and the chart refuses to render (values section "..." is missing).

helm upgrade helixiam oci://ghcr.io/melmarzgioui/helixiam/charts/helixiam --version 1.1.0-rc.33 --reset-then-reuse-values

With Docker Compose, set the new HELIX_VERSION in .env, then docker compose pull && docker compose up -d.

The chart's update strategy is the Helm value strategy (default Kubernetes' RollingUpdate, 25% / 25%).

Verify the upgrade

/actuator/info is not exposed, so read the version from what you deployed — the image tag:

kubectl get deploy helixiam -o jsonpath='{.spec.template.spec.containers[0].image}'   # Helm
docker compose images server                                                          # Docker Compose

Then confirm readiness. It is anonymous — no session or token — so it works from any host that can reach the server (see Authenticating to the API for $HELIX_URL):

curl -s "$HELIX_URL/actuator/health/readiness"
{"status":"UP"}

With Flyway enabled, helix-iam-server logs the applied versions on startup, and flyway_schema_history in the database records every applied migration and its checksum. A readiness of UP after the restart confirms the schema reached the shape the new release expects. Then check one sign-in and one refresh of a token issued before the upgrade. See Observability & health.

Breaking changes

Only changes that need an operator to act are listed, newest first. Each group applies when you upgrade from a release before the one named. Releases not listed need no action.

Before 1.1.0-rc.33

No migration. The export format is unchanged (formatVersion 2), and files from earlier releases still import, with the exceptions below.

  • LDAP and Active Directory sign-in refuse an empty password (security). Upgrade if you use either. An empty password is refused before the directory is contacted, with the same "invalid credentials" answer as a wrong password. An LDAP provider whose service account has no password no longer searches the directory anonymously: give it a password.
  • An uploaded realm import never reads the server's environment. This covers POST /admin/realms/{realm}/import (JSON, archive and Keycloak). A ${NAME} placeholder in a secret field leaves that secret as it is: an existing secret is kept, a new client gets a generated secret, other new secrets stay unset. The import result lists them in secretsNotProvided, and the console shows that list as a warning. A placeholder in any other field refuses that entry: it is listed in failed with the field name, and the response is 422. In a Keycloak import, a ${vault.<key>} reference in a secret field is treated the same way. If a pipeline relied on the server's environment to fill secrets, do one of these: put the secret values in the uploaded document (they are stored, never returned), set them afterwards in the console or admin API, or move the file to the realm-config folder.
  • The realm-config folder fills placeholders in secret fields only. A placeholder in any other field, such as clientId or a messaging provider's host, now fails that entry, and the error names the field. Write those settings as values. A secret whose variable is not set is left as it is and listed in the log; with HELIX_REALMS_REQUIRE_ENV=true the entry fails.
  • Earlier exports with a placeholder in tokenEndpoint are refused for that provider. Earlier releases wrote an OIDC provider's tokenEndpoint, and a wallet's credentials, credentialSets, credentialFormats and customCredentialQueries, as placeholders. Importing such a file now refuses that provider and names the field. Put the real value back in the file, or export again from this release.
  • New placeholders in exports. Confidential clients that use a secret are exported with ${HELIX_<REALM>_CLIENT_<CLIENTID>_SECRET}, and an organization's own identity providers with ${HELIX_<REALM>_IDP_<ALIAS>_<KEY>}. All are listed in requiredEnv. For a realm-config folder import, set these variables to keep the same secrets on the target. Without them a client gets a new secret and an organization provider has none.
  • Colliding placeholder names get a suffix. When two secrets of one export would get the same variable name (for example clients web-app and web_app), both names now end in _ and 8 hex digits. Names that did not collide are unchanged. Set the new variables listed in requiredEnv.
  • A realm with the key-store policy sovereign can be imported into a new realm. Add keyCustody.backendId, the id of a key custody backend of the target server, to the exported file. See Realm key custody. Re-importing a realm's own export needs no backendId.
  • A realm import with workload identities can be refused with 403. The import now checks, as the admin API does, that the importing administrator may act on each workload identity's "acts as" client. A delegated administrator who lacks the permissions that client's service account holds gets 403, and nothing is imported. Import such a file as a realm administrator who holds those permissions.

Before 1.1.0-rc.32

  • Some button labels are shorter. A button label on the server pages no longer breaks over two lines, so long labels were shortened (English and Dutch): "Send reset link" is Send, "I have verified my email address — continue" I've verified it, "Send the link again" Resend link, "Verify my email address" Verify email, "Confirm my email address" Confirm email, "I have done this, continue" Continue, "Sign in to accept" Sign in and "Accept invitation" Accept. Update browser tests or scripts that find these buttons by their text; ids and names are unchanged.

Before 1.1.0-rc.31

  • Server pages have a new layout. Every page in a sign-in flow (password reset, registration, e-mail verification, required actions, consent, MFA setup, errors, signed out) now uses the sign-in page's split layout, and sizes, radii and spacing follow helixiam.com on every realm. A realm with no theme of its own gets the helixiam.com look; a realm's own colours, fonts, logo and favicon are kept. The images /img/logo.svg, /img/helix-mark.svg, /img/helix-favicon.svg and /img/favicon.avif are removed. If a realm has custom CSS (Login theme → Advanced → Custom CSS), open its pages after upgrading, in light and dark and on a phone, and adjust selectors or sizes that changed. Custom CSS that points at a removed image must use the realm's own logo or /img/favicon.svg.

Before 1.1.0-rc.30

  • Users in groups get the groups' roles. Until 1.1.0-rc.30 a role on a group reached none of its members. From 1.1.0-rc.30 every member of a group, and of every group under it, holds the group's roles in tokens, SAML assertions and the console. A group that holds admin makes its members administrators of the realm. Before you upgrade, review each realm's Groups: the roles of each group and its members, including child groups. Remove what should not grant access.
  • A realm keeps its last administrator. An administrator cannot delete their own account, and the last enabled administrator cannot be deleted, disabled or lose the admin role (409 lastRealmAdmin). Scripts that remove administrators must leave one in place, or run as a master administrator.

Before 1.1.0-rc.29

  • Generic SAML connections sign their requests. Every existing connection to an external SAML identity provider starts signing its authentication and logout requests with the realm's SAML signing key. An identity provider that refuses signed requests it has no certificate for rejects the sign-in. Before you upgrade, register the connection's SP metadata with the identity provider again (download it from the connection screen, or from /realms/{realm}/broker/{alias}/saml/metadata), or set Sign authentication requests off on the connection (signAuthnRequests=false).
  • SAML connections created with the wizard before 1.1.0-rc.29 did not work. Open each one, import the identity provider's metadata again and save.
  • Importing into an existing realm keeps what the document leaves out. Settings the document omits or gives as null keep their current value; before, they were reset to 0 or off. Give a setting explicitly if a script relied on the reset. To clear the organization blocked-domain list, give "".
  • eIDAS needs an https IDP_BASE_URL. The entity ID is IDP_BASE_URL + /realms/{realm}/broker/{alias}/eidas/metadata. With plain http on any host other than localhost, a connection cannot be saved.

Before 1.1.0-rc.20 (Organizations v2)

  • Roll out with Recreate. Once a new pod has migrated (V207–V215), an older pod cannot read organizations and refuses user tokens. Use --set strategy.type=Recreate or scale to zero; one replica under a rolling update is not enough. V215 waits at most 5 seconds for its lock on organization: run it when no long transaction holds that table, and start again if it failed. Rolling back needs the pre-upgrade backup.
  • The organizations claim needs the scope organizations. Allow the client scope on each relying party that reads it and add it to the scope parameter, or read the always-present organization (active organization) instead. See Organizations in tokens.
  • A member's free-text role becomes organization roles with no permissions. Every organization gets a built-in Org admin role, granted to nobody: appoint organization admins after the upgrade (PUT .../organizations/{org}/members/{user} with roleIds), and update clients that read role.
  • Domains must be verified. Existing domains start pending and route nothing. Add the TXT record _helixiam-challenge.<domain> shown on the organization's Domains tab, then verify.
  • require_membership applies without the organization parameter, whenever the active organization is known. Check that the people of a verified domain who sign in are members, or switch it off.
  • Email linking through an identity provider needs a verified local address. Have accounts created without one verify it before their users first sign in through a provider.
  • SCIM is rate limited per token (600 a minute by default, helix.scim.rate-limit.per-token-per-minute). Raise it first if a provisioning client syncs faster.
  • Importing an older realm export in overwrite mode clears organizationBlockedDomains. Set it again afterwards.
  • Customer admins on a restricted console need their host in config.adminExtraAllowedHosts (Install).

See Organizations (B2B).

Before 1.1.0-rc.19

  • Every caller administers only its own realm. A realm admin or delegated admin gets 403 on any other realm, a service account acts only in its token's realm, and fine-grained admin grants match only <role>_<realm>. Move cross-realm automation to master-realm admins on the master host.

Before 1.1.0-rc.18 (audit and logs collected, never pushed)

  • Export audit_log first. Migration V205 drops the table, so history you did not export is deleted:

    psql "$DATABASE_URL" -c "\copy (SELECT * FROM audit_log) TO 'audit_log.csv' CSV HEADER"
    
  • Set up a log collector before you upgrade. Audit HTTP forwarding (helix.audit.http.*) and realm webhooks are removed; each audit event is one JSON line on stdout. The audit writer metrics and alerts, helix.audit.write.*, the audit retention setting, the console event search and the admin events search endpoint are gone. See Observability & health.

Before 1.1.0-rc.17 (eHerkenning KV1.13, DigiD and eIDAS)

Check every eID connection before you upgrade. Setup is in eHerkenning and DigiD and eIDAS; settings and reason codes in eID operations.

  • PKIoverheid checks are on by default. Every enabled eHerkenning connection, of any version, needs the broker's metadata imported and its signer confirmed; pasted certificates alone no longer log in. A YAML eHerkenning entry or a YAML CombiConnect DigiD entry stops the server at startup: move it to the console or admin API. HELIX_EID_PKIO_TRUST_BUNDLE=none is for test systems only.
  • Broker metadata refresh is off by default. Without config.eidMetadataRefreshInterval (for example PT6H), logins fail after a broker renews its certificates until an admin re-imports its metadata.
  • The Artifact Resolution server's certificate status is checked (hard-fail). Allow egress to its OCSP and CRL URLs; if you narrowed egress, cover that server's chain too.
  • The chart opens egress on port 80 to public addresses (networkPolicy.allowRevocationEgress, default true). Set it to false and add your own NetworkPolicy to narrow it.
  • Plain http that carries a token, personal data or a secret is refused (SCIM targets, OIDC upstreams, back-channel logout, HTTP SMS/email, workload identity discovery) unless the host is in HELIX_EGRESS_ALLOWED_PRIVATE_HOSTS. Use https://.
  • The chart refuses ingress.mtls.enabled without config.trustedProxies.
  • eHerkenning links of non-BSN identities are re-keyed (kvknr:<number>) with no migration. An existing company user's next sign-in creates a new account without roles. Per user, unlink the old link (POST .../federated-identities/{alias}/unlink) and give the new account the old one's roles, then remove the old account.
  • eID sessions are stricter. eHerkenning company, chain and DigiD Machtigen sessions get 403 on /account, /admin, /mfa, /authenticator and similar pages. Where the realm asks for a second factor, a sign-in below DigiD Substantieel or EH3 is refused (eidLevelTooLow): raise the connection's minimumLoa. Machtigen and chain sessions serve one client that has the eid scope, with no roles.
  • The eid scope is an administrator's to grant. Dynamic client registration refuses it; review clients that registered with it.
  • DigiD connections need a minimumLoa, must not set subjectAttribute, and, to be saved or imported enabled, need bsnEntitlementCategory and bsnLegalBasis (add them to older exports before restoring).
  • eIDAS connections need public or private (spType) at their next enabled save. Connections created through the API without subjectAttribute then match on the PersonIdentifier, not the NameID: plan to relink those accounts. Responses must be signed with RSASSA-PSS or ECDSA and assertions encrypted.

Before 1.1.0-rc.16 (mutual TLS revocation, workload tokens)

  • tls_client_auth refuses a client certificate whose revocation status cannot be determined (HARD_FAIL). The CA must publish OCSP or a CRL the server can reach; until then set the realm's revocation checking to SOFT_FAIL in Realm settings → Security → Mutual TLS.
  • A realm's own trust anchors replace the server-wide ones (serverTrustAnchors=FALLBACK). Set INCLUDE to keep both.
  • helix.workload-identity.token-lifetime-seconds above 3600 stops startup. Lower it first. A requested workload scope outside the credential is now invalid_scope.

See FAPI 2.0 & mutual TLS and Workload identity.

Before 1.1.0-rc.15 (FAPI 2.0)

  • Forwarded client certificates are off by default. If a proxy terminates mutual TLS, set HELIX_FAPI_CLIENT_CERT_HEADER and HELIX_FAPI_CLIENT_CERT_TRUSTED_PROXIES (Helm fapi.clientCertTrustedProxies: the ingress controller, never the console pods).
  • Clients that send DPoP proofs get DPoP-bound tokens and must present them with Authorization: DPoP and a proof.
  • Authorization responses carry iss (RFC 9207). Relying parties must accept the extra parameter.

Before 1.1.0-rc.14 (OpenID Connect conformance)

  • Tokens carry profile, email, address and phone claims only for the scopes granted. Make each relying party request the scopes whose claims it uses (typically openid profile email).
  • Userinfo returns end-user claims only. Read sid, auth_time, acr and amr from the ID token, and exp, scope and client_id from introspection.
  • Standard claims use their JSON types: updated_at is a number, phone_number_verified a boolean, address one object.
  • Implicit and hybrid flows need a larger proxy response-header buffer (ingress-nginx proxy-buffer-size: "32k") before you turn them on. See OIDC flows.

Before 1.1.0-rc.13 (key custody, data-key rotation)

  • Five secret columns are widened to text. Each ALTER takes a short exclusive lock: run the upgrade outside a burst of sign-ins.
  • Finish the rollout on every pod before you start a data-key rotation. Once a rotation has started, rolling back to an older release is not supported. See Key custody.
  • A custody factory built against the internal package must be rebuilt as a plugin against io.helixiam.custody.spi (Key custody plugins). A plugin image of your own must be pinned by digest with each jar's SHA-256.
  • The KMIP client key must not be world-readable (mode 0440 with the pod's fsGroup is accepted).

Before 1.1.0-rc.2 (console image, admin host)

  • The CSRF cookie is __Host-XSRF-TOKEN with secure cookies. A custom client that echoes the cookie must read that name (falling back to XSRF-TOKEN only on a development server).
  • Before setting adminAllowedHosts, point admin tools, Terraform, CI jobs and scripts at the admin host: on every other host /admin and the master realm answer 404. See Install.
  • The chart's default image is ghcr.io/melmarzgioui/helixiam/helix-iam-server with tag v<appVersion>. Check it if you set only one of image.repository / image.tag.
  • Account profile edits need a recent sign-in, and impersonated edits are refused. Support staff use the admin API or console.

Before 1.1.0-rc.1 (wallet extensions)

  • Client assertions are single use. Every private_key_jwt / client_secret_jwt assertion needs jti and exp, lives at most 5 minutes and is accepted once. A client that reuses one assertion must stop.
  • Typed mappers on wallet connections now run. Review each EUDI Wallet connection's Mappers tab, especially role mappers.
  • Credential issuance needs IDP_BASE_URL set to the public base URL.
  • Existing profile attributes count as untrusted for wallet attribute matching until an administrator, SCIM or an import writes them again.
  • A wallet connection may not trust this deployment's own issuers for the PID; such a connection is skipped at startup.
  • Verify-only assurance_level is high, not the LoA URI. A refused trusted-list presentation is audited as TRUST_LIST_UNAVAILABLE: update SIEM rules.

Before 1.0.0-rc.13

  • Disabling a realm takes effect. Before upgrading, check SELECT realm_id FROM realm_config WHERE NOT enabled; and switch back on any realm still in use.
  • Set DB_ENCRYPTION. The BSN is stored encrypted, and DigiD sign-in does not work without the key.
  • preferred_username never carries a BSN. DigiD usernames change. A relying party that used it as the BSN needs the bsn claim, opted in by a realm admin with a legal basis (PUT /admin/realms/{r}/bsn-release).
  • In-progress push, QR, transaction-signing, enrolment and CIBA flows are lost at the upgrade. A custom store bean must implement the new replace method.
  • Federated links of administrators are checked. After the upgrade, review the PRIVILEGED_LEGACY_LINK and PRIVILEGED_AMBIGUOUS_LINK entries of the startup report in your audit tool, confirm the links that are right and revoke trust in any you do not recognise (Users → (user) → Linked identities). See Admin roles (RBAC).
  • More actions need realm-admin: realm key writes, signing settings, admin grants, sign-in clients and flows, messaging and MFA policy. Give it to the people who do them.
  • Activate an ES256 realm key only once every replica runs the new release. A client asking for an ID-token algorithm with no active key must be changed. See Realm keys.

Before 1.0.0-rc.11

  • Wallet rolling upgrades: upgrade every replica in one step, drain wallet transactions, or set dcql.trustedAuthorities to Off for the roll.
  • Set signer-expiry-grace-days for EU trusted-list sources (it now defaults to 0). See Trusted lists.
  • Turn on the flow engine before binding an eudi-wallet-verify step.
  • The auditor role gains view-identity-providers. Review it if it must not read federation settings.
  • Spring Jackson properties are spring.jackson.* again (spring.jackson2.* is no longer read).

Before 1.0.0-rc.9 (Spring Boot 4)

  • Do not run old and new pods side by side. The older release cannot read sessions and tokens the new one writes. Upgrade with --set strategy.type=Recreate (with Helm 4, add --server-side=false once) or scale to zero first. Rolling back signs users out; with Redis, delete spring:session:* (and helix:authz:* with the Redis token store) before you roll back.
  • Rename roles named FACTOR_… (any case) first: the prefix is reserved and such roles grant nothing. The query is in Security hardening.
  • Spring properties set directly are renamed: server.error.* → spring.web.error.*, spring.session.redis.* → spring.session.data.redis.*, spring.dao.exceptiontranslation.enabled → spring.persistence.exceptiontranslation.enabled. HELIX_* settings and Helm values are unchanged.
  • Behind a proxy, set HELIX_TRUSTED_PROXIES; list every other host name clients use in HELIX_ALLOWED_HOSTS (with host:port for another port). X-Real-IP is not read: proxies must append to X-Forwarded-For. See Security hardening.
  • Allow internal SMTP relays and LDAP directories in HELIX_EGRESS_ALLOWED_PRIVATE_HOSTS (and HELIX_MESSAGING_SMTP_ALLOWED_PORTS) and HELIX_FEDERATION_LDAP_ALLOWED_HOSTS. See Configuration.
  • Client JWKS URLs must be https. A private_key_jwt client with an http JWKS URL can no longer authenticate.
  • Identity-provider secrets are write-only in the admin API; tools that read them back must stop.
  • Unknown eID minimum levels are refused. Check each connection's minimumLoa against the accepted values.
  • The generated admin password is not logged; read it from HELIX_ADMIN_PASSWORD_FILE.
  • The wallet transaction store needs PostgreSQL or Redis; wallet issuer revocation defaults to HARD_FAIL. actor_token on /oauth2/token is refused: use /agent/delegation/token. helix.outbound.fetch.login.* is split into login-admin and login-client.
  • Adding DB_ENCRYPTION to an install that ran without it needs the time-boxed plaintext migration window (HELIX_DB_ENCRYPTION_MIGRATE_PLAINTEXT, HELIX_DB_ENCRYPTION_MIGRATE_UNTIL). See Configuration.

See also