Upgrading from rc.13 to 1.1.0-rc.1¶

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

The release adds decentralised-identity features, all Preview and not yet tested with a real national wallet: wallet step-up and profile, credentials beyond the PID, credential issuance, verified data for applications, the verification API, transaction confirmation, DIDs, and automation for trusted lists. None of them is on until you configure it. The items below apply whether or not you use them.

Before you upgrade: checklist¶

#	Do this	Applies if
1	Make sure every `private_key_jwt` / `client_secret_jwt` client sends a fresh, short-lived assertion with `jti` and `exp`	any client authenticates with a signed assertion
2	Review the typed mappers on your wallet connections	you have EUDI Wallet connections with typed identity-provider mappers
3	Set `IDP_BASE_URL` to the public base URL	you will issue credentials
4	Re-write the profile attributes you will match wallets against	you will turn on wallet attribute matching
5	Move PID trust away from this deployment's own issuer	a wallet connection trusts this server's issuer for the PID, or a template uses a PID type
6	Let the Flyway migrations V90–V135 run	always
7	Read the other behaviour changes	you use verify-only wallet connections or trusted lists

Back up the database first, as for every upgrade, and keep DB_ENCRYPTION with the backup.

1. Client assertions are single use¶

What changed. Every client that authenticates with a signed assertion (private_key_jwt, client_secret_jwt) — at the token endpoint, PAR, introspection, revocation and the wallet verification API — must now:

send jti and exp in every assertion (an assertion without either is refused with invalid_client);
keep its lifetime at most 5 minutes (exp − iat, and exp at most 5 minutes after the server's clock, with 60 s of skew);
create a fresh assertion for every request: a jti is accepted once per client until the assertion expires (RFC 7523 §3), recorded in the shared PostgreSQL replay store (credential_attestation_jti), so a replay on any replica is refused.

Fail closed. When the replay store (the database) cannot record a jti, the assertion is refused, so these clients cannot authenticate during a database outage. Clients using client_secret_basic are not affected.

What you must do. Check your client libraries. Most (Nimbus, MSAL, Spring Security's NimbusJwtClientAuthenticationParametersConverter) already send a random jti and a short exp per request. A client that caches and reuses one assertion must stop doing so.

2. Wallet connections now run their typed mappers¶

What changed. Wallet logins now apply the typed identity-provider mappers like every other connection: at just-in-time provisioning every mapper applies (attribute importer, hardcoded attribute and role, claim-to-role), and at a later sign-in the FORCE mappers apply (attributes overwritten, mapper-assigned roles added and removed). Before, only the legacy mappers setting applied, and only at just-in-time provisioning. A typed mapper saved on a wallet connection earlier now runs. A mapper that cannot be applied refuses the sign-in.

What you must do. Before upgrading, open each EUDI Wallet connection's Mappers tab (or list GET /admin/realms/{realm}/identity-providers/{alias}/mappers) and review what it does, especially role mappers. Remove or change any you did not mean to run. See Credentials beyond the PID.

3. The credential issuer needs `IDP_BASE_URL`¶

What changed. A realm can now issue credentials over OpenID4VCI. The credential issuer identifier is {IDP_BASE_URL}/realms/{realm} (or the realm's own issuer setting), taken from configuration and never from the request's Host header, because it is signed into every credential, names the status lists and is the audience of every key proof.

What you must do. If you will issue credentials, set IDP_BASE_URL to the public base URL. Without it the realm cannot issue. Issuer keys also need DB_ENCRYPTION outside the dev profile. Nothing issues until an administrator enables the issuer settings of a realm. See Credential issuance.

A new admin permission, manage-credential-issuance, covers templates, offers and issued credentials; realm-admin includes it. See Admin roles.

4. Profile attributes record who set them¶

What changed. Flyway V123 adds user_profile_provenance: from this release on, every write of a profile attribute records its source — ADMIN (admin API and console), SCIM, IMPORT (user CSV import, realm import), SELF (account console), REGISTRATION (self sign-up), FEDERATION_MAPPER (identity-provider just-in-time provisioning and mappers) — with a keyed hash of the value. Only the opt-in wallet attribute matching reads it, and it trusts only ADMIN, SCIM and IMPORT values that have not changed since.

Existing attributes have no recorded source and count as untrusted (fail closed): attribute matching refuses them (UNTRUSTED_SOURCE) until an administrator, SCIM or an import writes them again. Re-running your SCIM sync or user import is enough. Nothing else changes for existing attributes. V120–V122 add the wallet step-up and profile tables; all those features are off by default.

5. Own issuers are never trusted for the PID¶

What changed. A wallet connection may no longer trust this deployment's own credential issuers (any realm's did:web, issuer key, issuer certificate or the CA that issued it) for the PID, and a credential template may no longer use a PID type or a claim the wallet subject is derived from (personal_administrative_number, issuing_country). See This deployment's own issuer.

What you must do. A stored wallet connection whose PID trusts an own issuer fails validation at start-up and is skipped (logged): move that trust to a credential besides the PID, or trust the real PID provider. A template with a PID type or a subject claim can no longer issue: give it its own type and drop those claims.

6. New Flyway migrations V90–V135¶

The migrations run on start-up. They only add tables, columns and indexes:

Migration	What it adds
`V90__trusted_list_rotation_and_pointers.sql`	trusted list sources: signer rotation, pointer depth, announced signers, retry backoff counter, load generation; per member: depth and signers
`V95__credential_issuance.sql`	the credential issuer: settings, issuer keys, the development CA, templates, offers, issuer access tokens, nonces, the `credential_attestation_jti` replay store (also used for client assertions), status lists, issued credentials
`V96__credential_issuance_hardening.sql`	issuer review round: wallet clients, offers served by reference, offers delivered to the user, DPoP binding of pre-authorized tokens
`V97__credential_token_configuration_use.sql`	a pre-authorized token used once per credential configuration
`V110__client_verified_claims.sql`	per-client `verified_claims` release policies (deleted with the client and the realm)
`V115__wallet_verification_api.sql`	the verification API opt-in on the policy, and per-client API settings
`V116__wallet_verification_template.sql`	verification templates
`V117__wallet_verification.sql`	verifications (status and names kept 7 days)
`V120__wallet_profile_settings.sql`	per verify-only connection: step-up lifetime, attribute matching and kept-attribute settings
`V121__user_verified_attribute.sql`	verified attributes kept on the profile, sealed
`V122__verified_claims_stored_attributes.sql`	`useStoredAttributes` on the verified-claims policy
`V123__user_profile_provenance.sql`	who set each profile attribute (above)
`V125__wallet_transaction_data.sql`	the encrypted `transaction_data` of a wallet transaction
`V130__did_support.sql`	`publish_did_web` on the issuer settings, `signing_method` on templates
`V135__credential_offer_user_index.sql`	an index for a user's open credential offers

7. Other behaviour changes¶

Step-up without the first factor. A signed-in user asked for acr_values by a client whose flow has a top-level REQUIRED wallet step is no longer sent to the sign-in page first: they go straight to the wallet step, keeping the session. See Wallet step-up and profile.
No credential offers to yourself. An administrator can no longer offer a credential to their own account (403).
No BSN through issued credentials. Every issued claim goes through the central BSN detector; BSN-like claim names and BSN-shaped const: values are refused when a template is saved.
Verify-only release value. The verified_claims of a verify-only connection now carry the IDA value "assurance_level": "high" instead of the LoA URI. acr is unchanged (http://eidas.europa.eu/LoA/high). A relying party that compared assurance_level with the URI must accept high.
Verify-only and a verified-claims policy. A client with an enabled verified-claims policy no longer gets the verify-only connection's verify.releasedClaims ID-token release; its policy governs. Clients without a policy are unchanged.
Trusted lists: no automatic integrity reset. A source whose stored trust state fails its integrity check now stays failed closed until an administrator runs Reset and reload; the automatic reset (TRUSTED_LIST_INTEGRITY_RESET) is gone. Removing a pinned signer needs resetFloors: true (the console asks). Sources stored by rc.13 keep their old integrity codes until their next successful load. See Trusted lists.
Trusted lists: failing closed with a clear code. A presentation refused because a trusted list gives no anchors is audited as TRUST_LIST_UNAVAILABLE, no longer ISSUER_UNTRUSTED. Update SIEM rules that match on the old reason.
Trusted lists: retry backoff. A failed refresh now waits 15, 30, 60, … minutes, up to helix.wallet.trusted-lists.max-retry-interval-minutes (360), instead of a fixed interval.
PID mapping. The PID mapping and the wallet subject read only the PID's credential queries.
Wallet mapper behaviour. See item 2: typed mappers on wallet connections now run, and a credential from an own issuer can never grant a role with an admin permission.