Skip to content

Upgrading from 1.1.0-rc.1 to 1.1.0-rc.2

This page lists what you must change, and what behaves differently, when you move a HelixIAM install from v1.1.0-rc.1 to v1.1.0-rc.2. The source is the v1.1.0-rc.2 release notes and upgrade notes.

The release ships the admin console as its own signed image and Helm Deployment, can keep the admin API on the console's host only, and gives every admin-configurable feature a console screen (Login theming, organization branding, realm archives, the token-exchange allow-list, the realm switches, user actions and the wallet's Advanced settings). There are no new Flyway migrations.

Before you upgrade: checklist

# Do this Applies if
1 Make custom clients read the __Host-XSRF-TOKEN cookie a script, test harness or proxy rule reads the CSRF cookie
2 Run production over HTTPS with secure cookies you set HELIX_COOKIE_SECURE=false
3 Point admin tools at the admin host before setting adminAllowedHosts you restrict the admin API to the console host
4 Check the default image your install pulls you set only one of image.repository / image.tag
5 Optionally move the console to its own Deployment you run the console
6 Tell support staff about profile edits users or support edit profiles through the account console

Upgrade with helm upgrade --reset-then-reuse-values as usual: plain --reuse-values from an older chart is refused, because the new console section is missing.

1. The CSRF cookie is __Host-XSRF-TOKEN in production

What changed. With secure cookies (helix.security.cookie-secure=true, the default) the server's JavaScript-readable CSRF cookie is now called __Host-XSRF-TOKEN (Secure, Path=/, no Domain, SameSite=Lax), so a sibling subdomain cannot plant one. Only a plain-HTTP development server still uses XSRF-TOKEN. The header stays X-XSRF-TOKEN, and server-rendered forms (_csrf) are unaffected. The cookie is always at path / now (it used to follow /realms/<realm> on realm URLs, which made account-console saves from a page at / fail with 403).

What you must do.

  • The admin console and the account SPA read the new name; nothing to change for them.

  • A custom client that reads the cookie to echo it (a script, a test harness, a reverse-proxy rule) must read __Host-XSRF-TOKEN, falling back to XSRF-TOKEN only for a development server. Of several cookies with the name, use the last whose value starts with r1.. The examples on this site do that:

    CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

  • Old XSRF-TOKEN cookies are ignored in production and replaced on a development server. A form opened before the upgrade may need one reload.

2. Plain HTTP is not for production

With HELIX_COOKIE_SECURE=false (helix.security.cookie-secure=false, Helm config.cookieSecure: false: plain HTTP for a demo or development) the cookie is XSRF-TOKEN without Secure or the __Host- prefix, and anything on the network path or a sibling host can set cookies for it: cookie injection is possible by nature there. Run production over HTTPS with secure cookies, the default.

3. Admin API only on the admin host

What changed. New setting helix.admin.allowed-hosts (HELIX_ADMIN_ALLOWED_HOSTS, Helm config.adminAllowedHosts). When set, the admin REST API (/admin/**, with /v3/api-docs/**, /swagger-ui/** and /swagger-ui.html) answers 404 on every other host, and so does the master realm (/realms/master/** and its well-known documents) unless config.adminRestrictMasterRealm (HELIX_ADMIN_RESTRICT_MASTER_REALM) is false. Only a trusted proxy's X-Forwarded-Host counts. Other realms are unaffected. Empty, the default, changes nothing. The municipality profile sets it to the beheer host.

What you must do before setting it. Admin tools, Terraform, CI jobs and scripts that call /admin (or /v3/api-docs, /swagger-ui) or get master-realm tokens through the public host get 404 once it is set. Point them at the admin (beheer) host, or at an in-cluster name you also list in adminAllowedHosts (for example helixiam.identity.svc). For the Terraform provider, both the token issuer and the admin API origin move:

provider "helix" {
  issuer   = "https://beheer.example.nl/realms/master" # master-realm token endpoint, on an admin host
  base_url = "https://beheer.example.nl"               # admin API origin (HELIX_BASE_URL); defaults to the issuer origin
  # client_id / client_secret unchanged
}

The same applies to HELIX_ISSUER / HELIX_BASE_URL, the provisioning service account's token URL, and any OpenID discovery of /realms/master by such tools. See Install.

4. The chart's default image can be pulled

What changed. The chart's default image.repository was ghcr.io/melmarzgioui/helix-iam-server and its default tag 1.0.0-SNAPSHOT; neither is published, so an install that relied on the defaults could not pull the server image. The defaults are now ghcr.io/melmarzgioui/helixiam/helix-iam-server (where releases are pushed) and the tag v<appVersion>. The chart's appVersion and version are now 1.1.0-rc.2, the release that publishes both images; the console image follows the same rule.

What you must do. Nothing if you set image.repository and image.tag explicitly. If you set only the tag, the repository now changes to the published one; if you set only the repository, the default tag is now v<appVersion>.

5. The admin console image and Deployment

What changed. The admin console is released as its own signed multi-arch image, ghcr.io/melmarzgioui/helixiam/helix-dashboard (same tag as the server), and the chart can run it as a second Deployment with its own replica count, HPA, PodDisruptionBudget, Ingress host and NetworkPolicy. Nothing changes for an existing install: the new console section is off by default, and the server Deployment, Service, selectors and replicaCount are untouched. See Architecture and Install.

To move an install whose console host was routed to the server (for example a beheer host listed under ingress.hosts):

  1. Remove the console host from ingress.hosts / ingress.tls (the server keeps its sign-in host).
  2. Set console.enabled=true, console.ingress.hosts[0].host=<that host> with its TLS secret, and console.networkPolicy.ingressNamespaceSelectors to the ingress controller's namespace.
  3. Keep config.spBaseUrl equal to https://<that host>, or leave it empty so the chart derives it from the console host. With the console enabled the chart also sets HELIX_CONSOLE_BASE_URL to it, so the built-in helix-console client's redirect URI becomes <spBaseUrl>/console/callback on the next server start (it was http://localhost:8180 when unset).
  4. Make config.trustedProxies cover the console pods too (usually the cluster pod CIDR), so the server honours the https scheme and host the console forwards.
  5. Optionally set config.adminAllowedHosts to that host (item 3).

The console's ingress must overwrite client-sent X-Forwarded-* headers, and the console Service must never be exposed directly. Two Deployments then roll out side by side; the server keeps its replicaCount and the console its console.replicaCount (typically 1–2).

6. Account profile edits need a recent sign-in

What changed. One rule now covers profile changes in the server-rendered account console (Edit details, new) and PUT /realms/{realm}/account/profile alike:

  • the sign-in must be recent: the API answers 403 {"error":"step_up_required","reauth":...} and the account SPA links to signing in again;
  • an administrator's impersonation is refused (403, audited). There is no rule for support edits through the account console: support staff use the admin API or console instead.

Before, the API accepted both. Users can edit only the attributes the realm lists as self-editable (Realm settings → Account console); a form that names any other attribute or a reserved claim writes nothing. See Account console.

See also