# 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](theming.md), [organization branding](../manage/organizations.md#in-the-console), [realm archives](../integration/import-export.md#archives-with-theme-files), the [token-exchange allow-list](../manage/oidc-clients.md#common-tasks), the [realm switches](realm-settings.md#login), [user actions](../manage/users.md#in-the-console) and the [wallet's Advanced settings](../federation/eudi-wallet.md#in-the-console)). There are no new Flyway migrations.

## Before you upgrade: checklist

| # | Do this | Applies if |
| --- | --- | --- |
| 1 | Make custom clients read the [`__Host-XSRF-TOKEN` cookie](#1-the-csrf-cookie-is-__host-xsrf-token-in-production) | a script, test harness or proxy rule reads the CSRF cookie |
| 2 | Run production over HTTPS with [secure cookies](#2-plain-http-is-not-for-production) | you set `HELIX_COOKIE_SECURE=false` |
| 3 | Point admin tools at the admin host before setting [`adminAllowedHosts`](#3-admin-api-only-on-the-admin-host) | you restrict the admin API to the console host |
| 4 | Check the [default image](#4-the-charts-default-image-can-be-pulled) your install pulls | you set only one of `image.repository` / `image.tag` |
| 5 | Optionally move the console to [its own Deployment](#5-the-admin-console-image-and-deployment) | you run the console |
| 6 | Tell support staff about [profile edits](#6-account-profile-edits-need-a-recent-sign-in) | 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:

    ```bash
    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](municipality-hosting.md) 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](../integration/terraform.md), both the token issuer and the admin API origin move:

```hcl
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](../getting-started/install.md#admin-api-only-on-the-admin-host).

## 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](../getting-started/architecture.md) and [Install](../getting-started/install.md#the-admin-console-as-its-own-deployment).

**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](#3-admin-api-only-on-the-admin-host)).

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](realm-settings.md#account-console)); a form that names any other attribute or a reserved claim writes nothing. See [Account console](../integration/account-console.md).

## See also

- [Upgrades & migrations](upgrades.md) — the general procedure
- [Upgrading from rc.13 to 1.1.0-rc.1](upgrade-rc13-1.1.0-rc1.md)
- [Architecture](../getting-started/architecture.md)