# Upgrading from 1.1.0-rc.15 to 1.1.0-rc.16

This release adds revocation checking and per-realm trust anchors for mutual-TLS client authentication
([FAPI 2.0 & mutual TLS](../integration/fapi2.md)) and sender-constrained, revocable workload identity tokens
([Workload identity federation](../integration/workload-identity.md)). Check the behaviour changes below before you
upgrade; the first ones apply to an existing installation without any configuration change.

## Before you upgrade (summary)

- **Migrations V200 and V201** are catalog-only (no table rewrite, no backfill). V200 creates two tables:
  `realm_mtls_settings` (per realm: `revocation_checking`, default `HARD_FAIL`; `server_trust_anchors`, default
  `FALLBACK`; a realm without a row has these defaults) and `realm_mtls_trust_anchor` (a realm's own CA certificates),
  both with the config-cache triggers. V201 adds two columns to `workload_identity_credential`: `sender_constraint`
  (nullable; empty means no token binding, as before) and `token_generation` (constant default 0).
- **`tls_client_auth`: a client certificate without an OCSP URL or CRL distribution point is refused (breaking for
  such CAs).** The new default `HARD_FAIL` refuses a certificate (or any intermediate below the trust anchor) whose
  revocation status cannot be determined, with `invalid_client`. The CA must publish OCSP (AIA) or a CRL that
  HelixIAM can reach, so the server needs network egress to it (in Helm: egress to port 80, usually, through
  `networkPolicy`, and an allowlist entry for an internal CA host; private addresses are refused otherwise). Until the
  CA does, set the realm's revocation checking to `SOFT_FAIL` (accepts and logs) or `OFF` (needs a confirmation) in
  *Realm settings → Security → Mutual TLS* or `/admin/realms/{realm}/settings/mtls`. `self_signed_tls_client_auth` is
  not affected (no CA).
- **A realm's own trust anchors replace the server-wide ones by default.** `serverTrustAnchors` is `FALLBACK`: the
  server-wide `HELIX_FAPI_MTLS_TRUST_ANCHORS` apply only while the realm has no anchors of its own. A realm that adds
  a CA no longer trusts the server-wide CAs; set `INCLUDE` to keep both, `EXCLUDE` to never use the server-wide ones.
  Realms without anchors of their own are unchanged. Discovery advertises `tls_client_auth` for a realm only while it
  has a usable anchor.
- **Wallet: the name constraints and path length constraint of a trust anchor are now enforced.** A configured issuer
  anchor or a trusted-list service certificate carrying `nameConstraints` or `pathLenConstraint` limits the issuer
  chains below it; an issuer certificate outside them is refused (`ISSUER_UNTRUSTED`, "certificate outside the trust
  anchor's constraints"). The JDK ignored these on an anchor. Anchors without these extensions are unchanged. The
  wallet's OCSP requests also carry a nonce (RFC 8954): a "good" answer echoing a different nonce is no status, so the
  CRL is tried next, and under `HARD_FAIL` a login fails with `certificate revocation status unavailable` if none
  answers.
- **`helix.workload-identity.token-lifetime-seconds` above 3600 stops start-up.** The value must be between 1 and 3600
  (one hour; default 900). Lower it before you upgrade.
- **A requested workload scope outside the credential is `invalid_scope`.** A `scope` on the workload identity token
  exchange that the credential does not allow was dropped; it is now refused (RFC 6749 §5.2). A request without
  `scope` gets every scope of the credential, and the token carries exactly the scope granted.

## Other behaviour changes

- Disabling, deleting or rebinding a workload identity credential now ends the tokens exchanged under it
  (introspection `active: false`, admin API 401); the credential is read at most every 5 seconds per replica, and a
  token is refused when it cannot be read. A workload token is now a machine token of the bound client (introspection,
  revocation by the client, accepted as a Bearer token by the admin API as the bound service account; a DPoP-bound one
  never as Bearer).
- A workload identity credential has a *Token binding* (`none`, `dpop`, `mtls`). In a FAPI 2.0 realm the exchange is
  no longer refused; `none` cannot be saved there, and the realm security profile lists credentials without a binding
  as non-compliant before you switch.
- A `PUT` of a workload identity credential that leaves out `senderConstraint` keeps the stored binding (it was reset
  to `none`).