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.sqlpath, kept for existing installs that never adopted Flyway:
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¶
- 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.
- Back up. Take a fresh database backup (
pg_dump, see Backup & disaster recovery) and keepDB_ENCRYPTIONwith it. Rolling back across a migration means restoring this backup. - 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=Recreateor scale to zero first. - Roll out the console (a separate Deployment when
console.enabled). - 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):
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 insecretsNotProvided, and the console shows that list as a warning. A placeholder in any other field refuses that entry: it is listed infailedwith the field name, and the response is422. 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
clientIdor a messaging provider'shost, 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; withHELIX_REALMS_REQUIRE_ENV=truethe entry fails. - Earlier exports with a placeholder in
tokenEndpointare refused for that provider. Earlier releases wrote an OIDC provider'stokenEndpoint, and a wallet'scredentials,credentialSets,credentialFormatsandcustomCredentialQueries, 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 inrequiredEnv. 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-appandweb_app), both names now end in_and 8 hex digits. Names that did not collide are unchanged. Set the new variables listed inrequiredEnv. - A realm with the key-store policy
sovereigncan be imported into a new realm. AddkeyCustody.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 nobackendId. - 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 gets403, 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.svgand/img/favicon.avifare 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
adminmakes 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
nullkeep 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 isIDP_BASE_URL+/realms/{realm}/broker/{alias}/eidas/metadata. With plain http on any host other thanlocalhost, 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=Recreateor scale to zero; one replica under a rolling update is not enough. V215 waits at most 5 seconds for its lock onorganization: run it when no long transaction holds that table, and start again if it failed. Rolling back needs the pre-upgrade backup. - The
organizationsclaim needs the scopeorganizations. Allow the client scope on each relying party that reads it and add it to thescopeparameter, or read the always-presentorganization(active organization) instead. See Organizations in tokens. - A member's free-text
rolebecomes 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}withroleIds), and update clients that readrole. - Domains must be verified. Existing domains start
pendingand route nothing. Add the TXT record_helixiam-challenge.<domain>shown on the organization's Domains tab, then verify. require_membershipapplies without theorganizationparameter, 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
403on 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_logfirst. Migration V205 drops the table, so history you did not export is deleted: -
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=noneis for test systems only. - Broker metadata refresh is off by default. Without
config.eidMetadataRefreshInterval(for examplePT6H), 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, defaulttrue). Set it tofalseand add your own NetworkPolicy to narrow it. - Plain
httpthat 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 inHELIX_EGRESS_ALLOWED_PRIVATE_HOSTS. Usehttps://. - The chart refuses
ingress.mtls.enabledwithoutconfig.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
403on/account,/admin,/mfa,/authenticatorand similar pages. Where the realm asks for a second factor, a sign-in below DigiD Substantieel or EH3 is refused (eidLevelTooLow): raise the connection'sminimumLoa. Machtigen and chain sessions serve one client that has theeidscope, with no roles. - The
eidscope is an administrator's to grant. Dynamic client registration refuses it; review clients that registered with it. - DigiD connections need a
minimumLoa, must not setsubjectAttribute, and, to be saved or imported enabled, needbsnEntitlementCategoryandbsnLegalBasis(add them to older exports before restoring). - eIDAS connections need public or private (
spType) at their next enabled save. Connections created through the API withoutsubjectAttributethen 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_authrefuses 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 toSOFT_FAILin Realm settings → Security → Mutual TLS.- A realm's own trust anchors replace the server-wide ones (
serverTrustAnchors=FALLBACK). SetINCLUDEto keep both. helix.workload-identity.token-lifetime-secondsabove 3600 stops startup. Lower it first. A requested workload scope outside the credential is nowinvalid_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_HEADERandHELIX_FAPI_CLIENT_CERT_TRUSTED_PROXIES(Helmfapi.clientCertTrustedProxies: the ingress controller, never the console pods). - Clients that send DPoP proofs get DPoP-bound tokens and must present them with
Authorization: DPoPand 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,acrandamrfrom the ID token, andexp,scopeandclient_idfrom introspection. - Standard claims use their JSON types:
updated_atis a number,phone_number_verifieda boolean,addressone 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. EachALTERtakes 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
fsGroupis accepted).
Before 1.1.0-rc.2 (console image, admin host)¶
- The CSRF cookie is
__Host-XSRF-TOKENwith secure cookies. A custom client that echoes the cookie must read that name (falling back toXSRF-TOKENonly on a development server). - Before setting
adminAllowedHosts, point admin tools, Terraform, CI jobs and scripts at the admin host: on every other host/adminand the master realm answer404. See Install. - The chart's default image is
ghcr.io/melmarzgioui/helixiam/helix-iam-serverwith tagv<appVersion>. Check it if you set only one ofimage.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_jwtassertion needsjtiandexp, 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_URLset 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_levelishigh, not the LoA URI. A refused trusted-list presentation is audited asTRUST_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_usernamenever carries a BSN. DigiD usernames change. A relying party that used it as the BSN needs thebsnclaim, 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
replacemethod.
Before 1.0.0-rc.12¶
- Federated links of administrators are checked. After the upgrade, review the
PRIVILEGED_LEGACY_LINKandPRIVILEGED_AMBIGUOUS_LINKentries 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.trustedAuthoritiesto Off for the roll. - Set
signer-expiry-grace-daysfor EU trusted-list sources (it now defaults to 0). See Trusted lists. - Turn on the flow engine before binding an
eudi-wallet-verifystep. - The
auditorrole gainsview-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=falseonce) or scale to zero first. Rolling back signs users out; with Redis, deletespring:session:*(andhelix: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 inHELIX_ALLOWED_HOSTS(withhost:portfor another port).X-Real-IPis not read: proxies must append toX-Forwarded-For. See Security hardening. - Allow internal SMTP relays and LDAP directories in
HELIX_EGRESS_ALLOWED_PRIVATE_HOSTS(andHELIX_MESSAGING_SMTP_ALLOWED_PORTS) andHELIX_FEDERATION_LDAP_ALLOWED_HOSTS. See Configuration. - Client JWKS URLs must be
https. Aprivate_key_jwtclient with anhttpJWKS 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
minimumLoaagainst 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_tokenon/oauth2/tokenis refused: use/agent/delegation/token.helix.outbound.fetch.login.*is split intologin-adminandlogin-client. - Adding
DB_ENCRYPTIONto 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.