> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/installation/rpm/rpm-upgrade/release-specific-steps.md).

# Release-specific steps

Releases that need more than the standard procedure — a database to provision, a service to deploy, an Oracle grant to make, or Groovy imports to update.

## What this is

Most upgrades need nothing beyond the procedure on the [minor](https://docs.openiam.com/installation/rpm/rpm-upgrade/minor-upgrade.md) or [major](https://docs.openiam.com/installation/rpm/rpm-upgrade/major-upgrade.md) page. Some releases add a database that must exist before you start, and a service to deploy once you are on it — neither of which the upgrade can create for you.

**Work out which releases you are passing through, then open the tab for each of them and take its steps.** Passing through counts even if you are not stopping there: going from 2026.4.2 straight to 2026.8.2 crosses `pbac` and `privacy`, and needs both.

## The databases each release adds

4.2.1.x ran on two databases: `openiam` and `activiti`. By 2026.10.1 there are nine.

<table><thead><tr><th width="126">Release</th><th width="144.39996337890625">Database</th><th>Service</th><th>Carries data forward?</th></tr></thead><tbody><tr><td><strong>4.2.2</strong></td><td><code>groovy</code></td><td><code>groovy-manager</code></td><td>Yes — see <a href="https://docs.openiam.com/installation/rpm/rpm-upgrade/after-a-major-upgrade.md"><em>After a major upgrade</em></a></td></tr><tr><td><strong>2026.3.1</strong></td><td><code>auditlog</code></td><td><code>audit-log-manager</code></td><td>—</td></tr><tr><td><strong>2026.5.2</strong></td><td><code>batchtasks</code></td><td><code>batch-task-manager</code></td><td>Yes, on a one-shot flag</td></tr><tr><td><strong>2026.6.1</strong></td><td><code>certification</code></td><td><code>certification-manager</code></td><td>Yes, on a one-shot flag</td></tr><tr><td><strong>2026.7.1</strong></td><td><code>pbac</code></td><td><code>pbac-manager</code></td><td>—</td></tr><tr><td><strong>2026.8.1</strong></td><td><code>privacy</code></td><td><code>privacy-manager</code></td><td>New capability, no legacy data</td></tr><tr><td><strong>2026.10.1</strong></td><td><code>reporting</code></td><td><code>report-manager</code></td><td>New capability, no legacy data — but reads the other databases, see below</td></tr></tbody></table>

Nothing new arrives with 2026.8.2 or 2026.9.2 — they extend what is already there. 2026.10.1 adds `reporting`, and with it the one grant an Oracle installation has to make by hand (below). A [major upgrade](https://docs.openiam.com/installation/rpm/rpm-upgrade/major-upgrade.md) from 4.2.1.x to 2026.10.1 crosses **all seven** rows above.

{% hint style="danger" %}
**Each new database is one more thing your backup has to cover.** A backup routine written against 4.2.1.x captures two databases out of nine. It will still complete, still report success, and no longer be a rollback position.
{% endhint %}

## Provisioning a new database

The shape is the same for every one of them. Substitute the database name from the table above.

{% stepper %}
{% step %}

### Create the database

**Before upgrading**, create the database or schema on your existing database server — MySQL, MariaDB, MSSQL, Oracle or PostgreSQL. Each service applies its own migrations on first start, so it needs the database to exist but not to be populated.
{% endstep %}

{% step %}

### Add the two properties

In `datasource.properties`, alongside the entries already there for `openiam` and `activiti`:

{% code overflow="wrap" %}

```properties
<name>.databaseSchema.name=<name>
jdbc.<name>.url=jdbc:mysql://${jdbc.host}:${jdbc.port}/<name>?autoReconnect=true&useUnicode=true&characterEncoding=utf8&connectionCollation=utf8_general_ci&serverTimezone=UTC
```

{% endcode %}

The file ships with commented blocks for Oracle, PostgreSQL and MSSQL — take the URL form from the block matching your database rather than adapting the MariaDB one.

{% hint style="warning" %}
**The new database also needs credentials, and how they are supplied is not documented.** Ask OpenIAM support how your deployment should hold them — treat any instruction to put a username and password directly into `datasource.properties` with suspicion, since the shipped file holds neither for the databases already in use.
{% endhint %}
{% endstep %}

{% step %}

### Deploy the service

Deploy it alongside `openiam-esb`. On first start it applies its own schema.
{% endstep %}
{% endstepper %}

Two of the seven then need a one-off data migration, and the newest needs a grant, below.

## Steps by release

Each tab holds the steps for one release. **Open every tab from the release after the one you are on through to your target** — the steps are cumulative, not alternatives.

{% tabs %}
{% tab title="2026.5.2" %}

### The batch task manager

The batch task subsystem — schedulers, initializers, the `BATCH_CONFIG` and `BATCH_SCHEDULE` tables, and the Groovy task runners — moved out of `openiam-esb` into a standalone service. It scales independently, and a batch job failing no longer affects API traffic.

After provisioning `batchtasks` and deploying `batch-task-manager`, its first start applies the schema and copies existing `openiam.BATCH_CONFIG` rows across. The runner short-circuits once the target table has rows, so restarts are no-ops.

**`BATCH_SCHEDULE` is deliberately not migrated.** The scheduler rebuilds future runs from each task's cron expression, and historical schedule rows have no operational value after cutover.
{% endtab %}

{% tab title="2026.6.1" %}

### The certification manager

Certification — the configurations, campaigns, review items, and the campaign compute — moved out of `openiam-esb` into a standalone service with its own database. The Activiti review workflow stays in the `workflow` service; its certification steps delegate the compute over RabbitMQ.

To carry existing certification data forward, start `certification-manager` once with:

{% code overflow="wrap" %}

```properties
org.openiam.certification.migrate-from-openiam=true
```

{% endcode %}

On that first start the migrations create the `certification` tables, then the runner copies the data out of `openiam` **preserving primary keys** — in-flight Activiti workflows hold reviewer and campaign ids as process variables, so the ids must not change. `ACCESS_CERTIFICATION*` becomes `CERTIFICATION*`, and the `CERTIFICATION`-typed rows of `APPROVER_ASSOC` and `ESCALATION` become `CERTIFICATION_REVIEWER` and `CERTIFICATION_REVIEWER_ESCALATION`.

Check the migrated row counts, then set the flag back to `false`. Leaving it on is safe — it is a no-op once the target tables are populated.
{% endtab %}

{% tab title="2026.7.1 and 2026.8.1" %}

### PBAC and Privacy

Both arrive as their own service and database, and both are new capability rather than an extraction, so there is no legacy data to carry forward.

* **`pbac` (2026.7.1)** backs the policy-based access control console — policies with shadow, percentage and full rollout modes, a simulation runner, and a decision log. The evaluation microservice is separately deployable and scaled on its own.
* **`privacy` (2026.8.1)** backs Privacy Management — the consent ledger, the purpose and lawful authority registry, the privacy event backbone, and the Privacy Administration Console.

{% hint style="warning" %}
**Confirm these two with support before you plan the window.** Both are newer than the rest of this page, and whether either needs anything beyond the standard provisioning above — Privacy Management in particular, whose console may need seeding before it is usable — has not been established.
{% endhint %}
{% endtab %}

{% tab title="2026.9.2" %}

### The RabbitMQ broker encryption key

The key the services encrypt RabbitMQ message bodies with used to ship as a value in `rabbitmq.properties`, so every installation ran on the same key and anyone holding a copy of the distribution could read traffic off a broker. It is now a vault secret, and the upgrade script seeds one for you when vault does not already hold it.

**This is the one release-specific step that needs the platform stopped.** Every service resolves the same key, so a message written under the old key cannot be read under the new one. Anything still sitting on the broker when the key changes fails to decrypt rather than being processed.

{% hint style="danger" %}
**Messages queued under the old key are not recoverable.** Let in-flight work drain before you stop the services, rather than discarding it afterwards.
{% endhint %}

{% stepper %}
{% step %}
Stop the OpenIAM services, so nothing is publishing to or consuming from the broker. Leave RabbitMQ and Vault running — the next two steps need both.

{% code overflow="wrap" %}

```bash
systemctl stop openiam
```

{% endcode %}
{% endstep %}

{% step %}
Purge the OpenIAM queues. With no service running, everything left on them was encrypted under the old key and cannot be read back:

{% code overflow="wrap" %}

```bash
rabbitmqctl list_vhosts
rabbitmqctl list_queues -p <vhost> name messages
rabbitmqctl purge_queue <queue> -p <vhost>
```

{% endcode %}

The management console does the same thing per queue if you would rather see the depths before you clear them.
{% endstep %}

{% step %}
Run the upgrade. It reads vault, finds no key and generates one, which is all most installations need. To choose the key yourself — to match a value you already hold, or to keep several hosts in step — export it before running the upgrade and it will be used as-is:

{% code overflow="wrap" %}

```bash
export SECRET_ORG_OPENIAM_MQ_BROKER_ENCRYPTION_KEY=$(openssl rand -hex 16)
```

{% endcode %}

The upgrade only seeds a key when vault holds none, so it is safe to re-run and it will never overwrite a key you have already set.
{% endstep %}
{% endstepper %}

Vault stores it under `vault.secret.org.openiam.mq.broker.encryption.key`, which is what every service resolves at startup. The old `org.openiam.mq.broker.encryption.key` property is gone from `rabbitmq.properties`; a value left there is now ignored. Changing the key later means repeating all three steps.

### The RabbitMQ delayed-message plugin is retired

OpenIAM used a community plugin, `rabbitmq_delayed_message_exchange`, to hold a message back before delivering it. The plugin has no build past RabbitMQ 4.2, so keeping it meant the broker could never be upgraded again. It is gone, and the delay now comes from RabbitMQ itself: the message is published with an expiry onto a queue nothing consumes, and when it expires the broker forwards it to the queue that does the work.

**An exchange cannot change type once it exists.** Two exchanges on your broker — `AM_EXCHANGE` on the `openiam_am` vhost and `ELASTIC_SEARCH_EXCHANGE` on `openiam_common` — were created as delayed exchanges. The new services ask for ordinary ones, the broker refuses the mismatch, and the service stops with `PRECONDITION_FAILED`. Deleting the two exchanges is the whole fix; the services build them again, with their queues and bindings, the first time they start.

{% hint style="warning" %}
**`AM_EXCHANGE` carries the entire auth-manager vhost.** Deleting it takes every queue bound to it with it, so this belongs in a window where the services are down — which an upgrade already is.
{% endhint %}

**`upgrade.sh` does this for you**, before it starts the services and while the plugin is still loaded. Order matters there: RabbitMQ needs the plugin present to read an exchange of that type at boot, so the exchanges have to go first and the plugin second. Nothing is left for you to run.

To see what it will do before you commit to the window, run it against the broker yourself:

{% code overflow="wrap" %}

```bash
export RABBITMQ_USER=openiam
export RABBITMQ_PASSWORD=$(/usr/local/openiam/utils/vault/vault.fetch.property.sh vault.secret.rabbitmq.password)
/usr/local/openiam/utils/rabbitmq/migrate-delayed-exchanges.sh --dry-run
```

{% endcode %}

Re-running the upgrade is safe. The script deletes an exchange only while that exchange is still a delayed one, so once the services have rebuilt them it finds nothing to do.

#### Checking it worked

No vhost should have an exchange of type `x-delayed-message` left:

{% code overflow="wrap" %}

```bash
for v in $(rabbitmqctl list_vhosts --quiet); do
  rabbitmqctl list_exchanges -p "$v" --quiet name type | grep x-delayed-message && echo "  ^ in $v"
done
```

{% endcode %}

That should print nothing. You can also confirm the replacement is in place — `openiam_audit` gains a queue called `AuditExportDispatchRetryQueue`, which is the holding queue the expiry mechanism uses:

{% code overflow="wrap" %}

```bash
rabbitmqctl list_queues -p openiam_audit --quiet name | grep AuditExportDispatchRetryQueue
```

{% endcode %}

If a service still fails with `PRECONDITION_FAILED` naming an exchange, that exchange was not deleted. Run the script again without `--dry-run`, then restart the service.

{% hint style="info" %}
**Failed audit exports are retried properly now.** The retry interval was silently ignored before, because the audit exchange was never a delayed one — a failing export burned through its retries in a tight loop instead of pausing between them. `org.openiam.audit.export.retry.interval` now takes effect.
{% endhint %}
{% endtab %}

{% tab title="2026.10.1" %}

### The IdP stops publishing signing secrets

No database and no stop are needed, but three behaviors of the OAuth 2.0 identity provider (IdP) change, and an integration that depended on the old behavior needs attention **before** you upgrade:

* **HS-signed clients publish an empty JWKS.** Before 2026.10.1 the JWKS URL of an `HS256` or `HS512` client returned the shared secret itself. Any relying party that fetched the secret from there must receive it out of band, or the client must move to `RS256` or `RS512` and the relying party must re-read the key set after the upgrade.
* **RSA clients publish only the public key.** The private exponent is no longer in the key set or in the IdP log. If an earlier release ever exposed it, regenerate the client's key pair as part of the upgrade.
* **`jwks_uri` in the discovery document is now correct.** Relying parties configured with the literal JWKS URL keep working; ones that were patched to strip the doubled issuer name can drop the patch.

One new property, `org.openiam.oauth.token.info.public`, ships `true`, so `/idp/oauth2/token/info` behaves exactly as before. Set it to `false` once every caller of that endpoint can authenticate as an OAuth client — see [OAuth endpoints, grants, scopes and signing](https://docs.openiam.com/administration-guide/federation/oauth-and-oidc/oauth-and-oidc-reference.md).

### The report manager, and the read grant Oracle cannot make for you

The browser-based report builder arrives as a standalone service, `report-manager`, with its own `reporting` database for report definitions, schedules and run history. Provision `reporting` the same way as the databases above — its properties are `reporting.databaseSchema.name` and `jdbc.reporting.url`, and the service resolves its credentials from `vault.secret.reporting.jdbc.username` and `.password`.

Deploy `report-manager` alongside `openiam-esb`, the same way `batch-task-manager` is deployed.

{% hint style="info" %}
**The `reporting` schema references rows in both `openiam` and `batchtasks`** (without foreign keys). Both those databases must exist and be populated before `report-manager` starts.
{% endhint %}

Two things set this release apart.

**The service reads every other database.** Reports are built over users, logins, certification items, policies, batch tasks and workflow requests, so `report-manager` also connects to `openiam`, `certification`, `privacy`, `pbac`, `batchtasks` and `activiti` — as its own read-only user, `REPORTING` unless you named it differently, taken from the same `vault.secret.reporting.jdbc.username`. It never writes to them. `datasource.properties` ships six `jdbc.reporting.source.<name>.url` entries, one per source database, which default to that database's own URL; point one at a read replica to keep reporting load off the primary.

**On Oracle, you grant that read access yourself.** MariaDB, PostgreSQL and SQL Server have a database-wide read grant, and the installer's database initialization makes it. Oracle has neither a schema-wide grant nor default privileges — `SELECT` is granted table by table, and the tables only exist once each schema's migrations have run — so nothing in the installation can grant it for you. Run the block below once after the upgrade, as a database administrator (DBA).

{% hint style="warning" %}
**Without the grant, every relational report fails.** The service starts, the catalog and the report designer work, but a run ends **Failed** with error code `QUERY_FAILED` and `ORA-00942: table or view does not exist`, and the service log shows the same error for the `report-source-*` connection pools. Reports over OpenSearch data — the audit log, orphan accounts, provisioning results — keep working, which is how to tell this apart from a connectivity problem.
{% endhint %}

{% stepper %}
{% step %}
Confirm the names you are granting between. The reporting user is in vault; the schema owners are the users the other services connect as, under their own vault properties:

{% code overflow="wrap" %}

```bash
cd /usr/local/openiam/utils/vault
./vault.fetch.property.sh vault.secret.reporting.jdbc.username        # the grantee — REPORTING by default
./vault.fetch.property.sh vault.secret.jdbc.username                  # openiam — typically IDMUSER
./vault.fetch.property.sh vault.secret.certification.jdbc.username    # typically CERTIFICATION
./vault.fetch.property.sh vault.secret.privacy.jdbc.username          # typically PRIVACY
./vault.fetch.property.sh vault.secret.pbac.jdbc.username             # typically PBAC
./vault.fetch.property.sh vault.secret.batchtasks.jdbc.username       # typically BATCHTASKS
./vault.fetch.property.sh vault.secret.activiti.jdbc.username         # typically ACTIVITI
```

{% endcode %}

Then check that the reporting user exists and is open — `SELECT username, account_status FROM dba_users WHERE username = 'REPORTING';` as `SYSDBA`. If that returns no row, create the user with the privileges the installer gives it, using the password held in vault as `vault.secret.reporting.jdbc.password`:

{% code overflow="wrap" %}

```sql
CREATE USER REPORTING IDENTIFIED BY <password>;
GRANT RESOURCE TO REPORTING;
GRANT CONNECT TO REPORTING;
GRANT CREATE VIEW TO REPORTING;
GRANT CREATE SESSION TO REPORTING;
GRANT UNLIMITED TABLESPACE TO REPORTING;
```

{% endcode %}
{% endstep %}

{% step %}
Grant `SELECT` on every table and view of the six schemas. Connect as `SYS` (or any user holding `GRANT ANY OBJECT PRIVILEGE`), edit the two lists at the top if your names differ, and run the block. It skips objects that are already granted, reports anything it could not grant, and is safe to run as often as you like:

{% code overflow="wrap" expandable="true" %}

```sql
SET SERVEROUTPUT ON

DECLARE
    -- the reporting user: vault.secret.reporting.jdbc.username
    c_grantee CONSTANT VARCHAR2(128) := 'REPORTING';
    -- the owners of the six OpenIAM databases report-manager reads
    TYPE t_owners IS TABLE OF VARCHAR2(128);
    v_owners  t_owners := t_owners('IDMUSER', 'CERTIFICATION', 'PRIVACY', 'PBAC', 'BATCHTASKS', 'ACTIVITI');
    v_granted PLS_INTEGER := 0;
    v_skipped PLS_INTEGER := 0;
BEGIN
    FOR i IN 1 .. v_owners.COUNT LOOP
        FOR obj IN (
            SELECT owner, table_name AS object_name
              FROM dba_tables
             WHERE owner = v_owners(i) AND table_name NOT LIKE 'BIN$%'
            UNION
            SELECT owner, view_name
              FROM dba_views
             WHERE owner = v_owners(i)
            MINUS
            SELECT owner, table_name
              FROM dba_tab_privs
             WHERE owner = v_owners(i) AND grantee = c_grantee AND privilege = 'SELECT'
        ) LOOP
            BEGIN
                EXECUTE IMMEDIATE 'GRANT SELECT ON "' || obj.owner || '"."' || obj.object_name
                                  || '" TO "' || c_grantee || '"';
                v_granted := v_granted + 1;
            EXCEPTION
                WHEN OTHERS THEN
                    v_skipped := v_skipped + 1;
                    DBMS_OUTPUT.PUT_LINE('Skipped ' || obj.owner || '.' || obj.object_name || ': ' || SQLERRM);
            END;
        END LOOP;
    END LOOP;
    DBMS_OUTPUT.PUT_LINE('Granted SELECT on ' || v_granted || ' object(s) to ' || c_grantee
                         || ', skipped ' || v_skipped || '.');
END;
/
```

{% endcode %}

A schema that does not exist on your installation — `PRIVACY` on a deployment without the privacy module, say — simply contributes no objects; leave it in the list or take it out, the result is the same.
{% endstep %}

{% step %}
Verify as the reporting user, then from the product. Each query must return a count, not `ORA-00942`:

{% code overflow="wrap" %}

```sql
SELECT COUNT(*) FROM IDMUSER.USERS;
SELECT COUNT(*) FROM CERTIFICATION.CAMPAIGN;
SELECT COUNT(*) FROM PBAC.PBAC_POLICY;
SELECT COUNT(*) FROM BATCHTASKS.BATCH_CONFIG;
SELECT COUNT(*) FROM ACTIVITI.ACT_HI_PROCINST;
```

{% endcode %}

Then open the report builder in the Webconsole (`/webconsole-v2/audit/reports`) and run a shipped system report that reads relational data, such as **Users** — it should complete. To review what was granted, as a DBA: `SELECT owner, COUNT(*) FROM dba_tab_privs WHERE grantee = 'REPORTING' AND privilege = 'SELECT' GROUP BY owner;`
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Repeat the grant after every future upgrade.** A grant covers the tables that exist when it is made; a later release that adds a table leaves reports over it failing with the same `ORA-00942` until you run the block again. It skips what is already granted, so re-running it costs nothing. And keep the user read-only — `SELECT` only, never ownership of or write privileges on the OpenIAM schemas.
{% endhint %}

### Proxy and cookie settings changed

**`OPENIAM_TrustedProxy`** is a new setting — a comma-separated list of IPs or CIDR ranges from which `X-Forwarded-For` and client-IP headers are trusted. It ships **empty (no proxy trusted)**. If OpenIAM sits behind a reverse proxy, load balancer or CDN, add that address here; otherwise audit logs and IP-based rules record the proxy's address instead of the real client. (OE-4325)

**`OPENIAM_CookieIntegrity`** is now `on` in the shipped reference configurations. Environments that explicitly set this value keep their current value; environments that never touched it switch from `off` to `on`. Check whether anything relies on cookies being unprotected before upgrading. (OE-5251)

### PBAC seed for user management

A new PBAC seed (`user-management-seed-role9`) grants the Super Security Admin role every action under `Openiam::UserManagement::Action`. Any custom role that previously served as a de-facto user administrator must be granted a matching narrower PBAC policy, or those users will be refused on the user management screens. (OE-4550)

### SoD Groovy API changes

The SoD evaluator now **distinguishes pre-existing HARD violations from newly-introduced HARD violations** in its response. Any custom Groovy script that refuses a save on any HARD violation will now refuse legitimate saves — restrict the refusal to the newly-introduced set. (OE-5090)

SoD batch evaluation responses now include a **per-element status field**. Scripts that infer status from presence or absence of a result should switch to reading the explicit status field. (OE-5091)
{% endtab %}

{% tab title="2026.10.2" %}

### The IdP accepts Client ID Metadata Document clients

No database and no stop are needed. The OAuth 2.0 identity provider (IdP) gains a tenant-level metadata document, clients that register themselves from a Client ID Metadata Document (the way Claude and other Model Context Protocol clients identify themselves), the `resource` parameter and the `iss` response parameter. Four behaviors change for existing integrations; check them **before** you upgrade:

* **Public PKCE clients must use `S256`.** A client on `AUTHORIZATION_CODE_PKCE` with no client secret that sends `code_challenge_method=plain`, or no method at all, is refused. Fix the client, or set `org.openiam.oauth.pkce.plain.allowed=true` in `idp.ui.properties`.
* **Redirect parameters are URL-encoded.** A client that read `code`, `state` or `error` out of the redirect without decoding them now sees encoded values; a standard OAuth library is unaffected.
* **The `refresh_token` grant checks the client.** A refresh token presented by a client other than the one it was issued to, or presented a second time, is refused with `invalid_grant` instead of honoured.
* **Every authorization response carries `iss`.** A client that rejects parameters it does not expect on the redirect needs to accept it.

Three properties are worth a decision at upgrade time, all in `idp.ui.properties` under the deployment's `conf/properties` directory:

* `org.openiam.oauth.cimd.allowed.origins` ships as `https://claude.ai`, which lets Claude register itself as an OAuth client on a user's first sign-in. Set it to an empty value if you do not want that yet.
* `org.openiam.oauth.issuer` ships empty, so the issuer is derived from each request's host. Set it to `https://<your host>/idp/oauth2` when the IdP is reachable under more than one host name.
* `org.openiam.oauth.token.refresh.legacy.enabled` ships `true`, so the unauthenticated `/idp/oauth2/token/refresh` endpoint keeps answering. Set it to `false` once every client refreshes through `POST /idp/oauth2/token`; a later release defaults it to `false`.

Every property the release adds, with its shipped value, is listed in [OAuth endpoints, grants, scopes and signing](https://docs.openiam.com/administration-guide/federation/oauth-and-oidc/oauth-and-oidc-reference.md), and the procedure for letting an MCP client register itself is in [OAuth 2.0 and OpenID Connect](https://docs.openiam.com/administration-guide/federation/oauth-and-oidc.md).

### The MCP server

2026.10.2 adds the OpenIAM Model Context Protocol (MCP) server, which lets an AI assistant such as Claude answer questions from OpenIAM data on behalf of a signed-in user. **The RPM packages of 2026.10.2 do not include it**: it ships as the `mcp` container image and Helm chart only. To use it next to an RPM installation, run the container where it reaches the installation's RabbitMQ, Redis and Vault, make the installation's nginx forward `/mcp` and `/.well-known/oauth-protected-resource` to it, and follow [Connect AI assistants through the MCP server](https://docs.openiam.com/administration-guide/federation/mcp-server.md) for the gateway patterns and the graph rebuild. Nothing changes for an RPM installation that does not use it.

The `openiam` migration seeds the server's four OAuth 2.0 scopes, `openiam:mcp:identity:read`, `openiam:mcp:access:read`, `openiam:mcp:workflow:read` and `openiam:mcp:audit:read`, and grants them to the End User and Super Security Admin roles, the audit scope to Super Security Admin only. Unlike every other scope they are **not public**, so a user receives one only through a role that holds it; the grants are described in [OAuth endpoints, grants, scopes and signing](https://docs.openiam.com/administration-guide/federation/oauth-and-oidc/oauth-and-oidc-reference.md#the-mcp-scopes-are-non-public-and-role-granted). The grants are written straight into the entitlement tables, which the authorization manager does not re-read on its own, so the graph has to be rebuilt once before you use the server. Once `openiam-esb` runs 2026.10.2, rebuild it on the ESB host:

{% code overflow="wrap" %}

```bash
curl http://localhost:9080/openiam-esb/authmanager/rebuildGraph
```

{% endcode %}

Run it once. A response means the rebuild was queued, not that it finished; how to confirm it is in [Rebuild the authorization graph](https://docs.openiam.com/administration-guide/operations/rebuild-the-authorization-graph.md#verification). Until it has run, no user is entitled to the MCP scopes, so the IdP issues none of them.

### MCP agents and tool-call policies

The second half of the MCP server in 2026.10.2 gives every MCP client an **AI Agent record** in the non-human identity inventory, lets an agent act with no person behind it, and puts every tool call through a policy-based access control (PBAC) decision. No stop is needed, and the migration runs with the release's others; nothing it adds is enforced until you switch it on. Three things change for an upgraded deployment:

* **The migration touches `openiam` and `pbac`.** `NHI_IDENTITY` gains the client binding, `NHI_DRIFT_FINDING` is new, `OAUTH_TOKEN` and `OAUTH_CODE` gain the audience, the consented scopes and the resource, the user type `NHI service account` is seeded, and the `pbac` database receives the seven shipped `MCP - …` policies, active in shadow: they record what they would decide and change no decision until promoted. On SQL Server the binding is a filtered unique index, so a `sqlcmd` or `bcp` session that writes to `NHI_IDENTITY` needs `QUOTED_IDENTIFIER ON` (`sqlcmd -I`); JDBC, SSMS and the platform itself have it on.
* **Set `org.openiam.oauth.cimd.agent.owner` before the first Claude sign-in**, in `idp.ui.properties`, to the user ID of an administrator account. The IdP creates an AI Agent record for every client that registers itself and refuses to register one while the property is empty. A client registered before the upgrade receives its record on its next sign-in.
* **`client_credentials` tokens change subject.** A client bound to an AI Agent identity receives a token for the identity's service user, with its scopes filtered by that user's entitlements. A client that is not bound keeps the built-in `0001` subject only while `org.openiam.oauth.client_credentials.legacy.subject` is `true`, which 2026.10.2 ships; the next release ships it `false`, after which such a client is refused at the token endpoint. Find every client-credentials client you depend on and bind it before then.

Two properties are worth a decision at upgrade time:

* `org.openiam.mcp.agent.required` in the MCP container's `mcp.ui.properties` ships `false`, so MCP clients without a record keep working. Leave it for this release while the records are created, then set it to `true` so that an unregistered client is refused.
* `org.openiam.pbac.mcp.catalog.url` in `pbac-manager`'s properties ships empty. Point it at the MCP server's catalog document, `http://<MCP_CONTAINER_HOST>:8080/.well-known/mcp-catalog`, so policies can name tool groups; without it a policy can only name tools one by one.

Three more things are worth doing once the upgrade is through, none of them urgent:

* **Point Webconsole at the catalog too.** `org.openiam.mcp.catalog.url` in `webconsole.ui.properties` ships empty; the policy editor's autocomplete and the declared-tools picker offer no MCP vocabulary until it names the same catalog document.
* **Schedule the two new governance jobs.** The tool-drift job (`TOOL_DRIFT`) and the orphaned-sponsor job (`ORPHANED_AGENTS`) ship without a batch task; create one for each as described in [Schedule the jobs](https://docs.openiam.com/administration-guide/federation/mcp-server/mcp-agents.md#schedule-the-jobs). The sponsor job's mail template, `NHI_SPONSOR_INACTIVE`, is not seeded either.
* **Decide on approval.** `org.openiam.oauth.cimd.agent.approval` ships as `auto`. With `required`, a person's first sign-in through a new Claude client ends with `access_denied` until an administrator approves the agent record.

The record and the kill switch are in [Govern AI agents as non-human identities](https://docs.openiam.com/administration-guide/federation/mcp-server/mcp-agents.md); the permits every call needs and the seven policies are in [Decide MCP tool calls with policies](https://docs.openiam.com/administration-guide/federation/mcp-server/mcp-policies.md). 2026.11.1 enforces those policies on upgrade; see its tab.
{% endtab %}

{% tab title="2026.11.1" %}

### The MCP policy pack is enforced

From 2026.11.1 the MCP server has no policy mode of its own: it asks the policy service about every tool call and applies the answer. So that an upgraded installation enforces the pack it was given instead of refusing every call for want of an enforced permit, the `pbac` migration sets the seven shipped `MCP - …` policies to `FULL`. It runs whether or not you use the MCP server, and no stop is needed. A policy is promoted only while it is as seeded: active, still in `SHADOW`, and still at its seeded version with no other version. A policy you edited, deactivated, rolled out to a percentage or promoted yourself keeps your choice, and a re-run changes nothing.

If you run the MCP container next to the installation, then on the first day, for a tenant whose pack was untouched:

* Everyone who uses Claude sees e-mail addresses masked to initials in the identity tools.
* The audit tool is refused to anyone outside role `9`.
* An agent acting alone may call only the tools it declared, only while Active, may read people only inside its sponsor's reporting line, loses the workflow tools outside 06:00–22:00 UTC, and is refused when its health score is below 60 or it has been unused for over 90 days.
* People may read any user's record through the MCP tools, within their scopes. The server's separate `VIEW_USER` check is gone, so the MCP policies alone decide who may read whom; add a forbid to narrow it.

Four things to do or check:

* **Check both permits after the upgrade.** If you had changed `MCP - Humans may use the read tools`, the migration left it in its mode, and in `SHADOW` it refuses every person with `no policy permits the call` until you set it to `FULL`. The same holds for `MCP - Active agent may call a declared tool` and agents acting alone.
* **Remove the two retired MCP server properties.** `org.openiam.mcp.pbac.mode` and `org.openiam.mcp.pbac.guard.enabled` are no longer read. If the MCP container's `mcp.ui.properties` still sets either, the server logs a warning at startup that names it; remove it. A policy is tried out in its own `SHADOW` enforcement mode instead.
* **Keep the access gateway's PBAC guard off**, as shipped (`org.openiam.pbac.gateway.enabled`). With it on, every URL it governs that has no policy of its own is refused once the MCP pack is enforced, because the policy service applies a `FULL` policy with an open resource to every request. Webconsole and the non-human identity checks are unaffected. This applies whether or not you use the MCP server.
* **Update anything that reads `list_access`.** The tool now returns a page of access entries, 50 by default and at most 200, roles first, then groups, then resources, with `limit` and `offset`, instead of every entry at once as `roles`, `groups` and `resources`. An assistant reads the new shape from `tools/list`; a script or saved prompt of your own may need changing.

After the upgrade, the policy library lists the seven policies `FULL`:

<figure><img src="https://2965242200-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0uHWHRgcad6P03ehqgmX%2Fuploads%2Fgit-blob-3a987bb62a34ff83b64d6e5e470b0d18ed66bdc4%2Fpbac-policy-library-mcp-pack.png?alt=media" alt="The Policy Library tab under PBAC Policies, searched for MCP -, listing the seven shipped policies, all ACTIVE and FULL: MCP - Active agent may call a declared tool, MCP - Agent reads people only inside its sponsor reporting line, MCP - Agents do not touch workflow outside 06:00-22:00 UTC, MCP - Audit tool needs an admin, MCP - Humans may use the read tools at version MCP-01-v2, MCP - Identity tools through an agent client mask e-mail, and MCP - Unhealthy or dormant agents are refused"><figcaption></figcaption></figure>

As seeded, `MCP - Humans may use the read tools` reads, at its version 2:

{% code overflow="wrap" %}

```
permit(principal is Openiam::User::Human,
       action in [Openiam::McpTool::Action::"openiam:mcp:identity:read",
                  Openiam::McpTool::Action::"openiam:mcp:access:read",
                  Openiam::McpTool::Action::"openiam:mcp:workflow:read",
                  Openiam::McpTool::Action::"openiam:mcp:audit:read"],
       resource);
```

{% endcode %}

`MCP - Active agent may call a declared tool` reads:

{% code overflow="wrap" %}

```
permit(principal is Openiam::Nhi, action in Openiam::McpTool::Action::"openiam:mcp", resource)
when { context.mcp.declaredTool == true && principal.status == "A" };
```

{% endcode %}

The seven policies with their text, the first-day effects and how to review a policy in shadow are in [Decide MCP tool calls with policies](https://docs.openiam.com/administration-guide/federation/mcp-server/mcp-policies.md#the-shipped-pack-is-enforced).

### OpenSearch moves to 3.6.0

2026.11.1 ships OpenSearch 3.6.0, and **`upgrade.sh` now upgrades the OpenSearch it installed.** 3.6.0 is the newest version OCI Search with OpenSearch offers, so every deployment type runs the same version. Earlier releases downloaded the new OpenSearch package but never installed it, so your host may still run the version it was first installed with. The upgrade replaces `/etc/opensearch/jvm.options` and `/etc/sysconfig/opensearch` with the 3.6.0 copies, because OpenSearch 3 will not start with the 2.x ones. It also installs the Prometheus exporter built for 3.6.0. Your `opensearch.yml` and security configuration are kept, and the previous configuration is saved as `/usr/local/openiam/backup/opensearch-<version>-config.tar`.

**OpenSearch 3 cannot open an index created before OpenSearch 2.0.0.** That includes system indices such as `.opendistro_security`, and anything carried over from an Elasticsearch installation. `upgrade.sh` checks for them before it stops anything, and if it finds one it lists it and exits without changing the host. Run the same check yourself before you book the window:

{% code overflow="wrap" %}

```bash
AUTH="--cacert /etc/opensearch/root-ca.pem --cert /etc/opensearch/admin.pem --key /etc/opensearch/admin-key.pem"
OS=https://localhost:9200
curl -s $AUTH "$OS/_all/_settings/index.version.created*?human&expand_wildcards=all&flat_settings=true" \
  | jq -r 'to_entries[] | select((.value.settings["index.version.created"] | tonumber) < 136217827) | "\(.key) \(.value.settings["index.version.created_string"])"'
```

{% endcode %}

No output means there is nothing to rebuild. `136217827` is OpenSearch 2.0.0's version number; comparing numbers rather than version strings also catches indices from Elasticsearch, which report `7.x`.

OpenSearch cannot be downgraded. Back up `/var/lib/opensearch` while OpenSearch is stopped, or take a snapshot, before you run the upgrade. An OpenSearch that OpenIAM did not install, such as an external cluster, is left alone.

#### Rebuild an index created before OpenSearch 2.0.0

Do this on the OpenSearch you run today, before the upgrade. OpenIAM reads and deletes its indices by name, so each one keeps its name: copy it aside, recreate it, and copy it back. For an index called `auditlog`:

{% code overflow="wrap" %}

```bash
# The index's settings and mappings, without the values OpenSearch assigns itself
curl -s $AUTH "$OS/auditlog" | jq '.auditlog | {settings: {index: (.settings.index | del(.uuid, .version, .creation_date, .provided_name))}, mappings}' > /tmp/auditlog.json
curl -s $AUTH -XPUT "$OS/auditlog-tmp" -H 'Content-Type: application/json' -d @/tmp/auditlog.json
curl -s $AUTH -XPOST "$OS/_reindex?wait_for_completion=true&refresh=true" -H 'Content-Type: application/json' -d '{"source":{"index":"auditlog"},"dest":{"index":"auditlog-tmp"}}'
# Compare the two document counts before you delete anything
curl -s $AUTH "$OS/_cat/count/auditlog?h=count"; curl -s $AUTH "$OS/_cat/count/auditlog-tmp?h=count"
curl -s $AUTH -XDELETE "$OS/auditlog"
curl -s $AUTH -XPUT "$OS/auditlog" -H 'Content-Type: application/json' -d @/tmp/auditlog.json
curl -s $AUTH -XPOST "$OS/_reindex?wait_for_completion=true&refresh=true" -H 'Content-Type: application/json' -d '{"source":{"index":"auditlog-tmp"},"dest":{"index":"auditlog"}}'
curl -s $AUTH -XDELETE "$OS/auditlog-tmp"
```

{% endcode %}

**`.opendistro_security` cannot be copied this way.** Back up the security configuration with `securityadmin.sh -backup <dir>`, delete the index with the admin certificate, and load the backup again with `securityadmin.sh -cd <dir>`. The users, roles and mappings come back unchanged, in an index created by your current version.
{% endtab %}

{% tab title="2026.11.2" %}

### The AI assistant is switched on by its agent record

From 2026.11.2 the SelfService AI assistant is on only while its agent record, **AI Assistant** (`AI_ASSISTANT_AGENT`), is Active and holds a model connection: the Oracle Cloud Infrastructure (OCI) Generative AI base URL, model and API key the AI assistant service calls its model with. The key is kept in Vault and governed like any other non-human identity credential. No stop is needed. For an upgraded installation:

* **The assistant is off after the upgrade.** The migration moves the record to Draft while it is still as 2026.11.1 seeded it: Active, with no expiry date, no sponsor and no stored secret. The record's audit trail shows the change as an `UPDATED` lifecycle event. A record you already edited keeps its status.
* **`org.openiam.ai.assistant.enabled` is removed.** The migration deletes it, and setting it has no effect.
* **The service no longer reads the model from its own configuration.** In `${confpath}/conf/properties/ai-assistant.properties`, `org.openiam.ai.assistant.model.provider`, `org.openiam.ai.assistant.model`, `org.openiam.ai.assistant.gateway.api-key` and every `org.openiam.ai.assistant.oci.*`, `org.openiam.ai.assistant.ollama.*` and `org.openiam.ai.assistant.mock.*` property are removed. A file that still sets one logs `removed properties ignored:` at startup, and the value has no effect. The Vault entries `vault.secret.org.openiam.ai.assistant.oci.api-key` and `vault.secret.org.openiam.ai.assistant.gateway.api-key` are no longer read.
* **The old environment variables override the record.** `MODEL_PROVIDER`, `MODEL`, `OCI_GENAI_BASE_URL`, `OCI_GENAI_MODEL` and `OCI_GENAI_API_KEY`, in the service's environment or its `.env` file, are now a development override that wins over the record's connection. `AI_GATEWAY_API_KEY` alone is not an override. They never turn the assistant on by themselves.

To turn the assistant back on:

{% stepper %}
{% step %}
Give the AI assistant service a Vault identity it can use: a PEM client certificate and key in `vault.ssl.client-cert` and `vault.ssl.client-key` of its `vault.properties`, or the environment variables `VAULT_CLIENT_CERT` and `VAULT_CLIENT_KEY`, or a `VAULT_TOKEN`. The service cannot read the Java key store (JKS) the other modules sign in with. Without one of these, the **Agent** tab stays on `Waiting for the assistant service to load the new settings`.
{% endstep %}

{% step %}
Allow that identity to read `secret/openiam/vault.secret.nhi.AI_ASSISTANT_AGENT.AI_ASSISTANT_MODEL`.
{% endstep %}

{% step %}
Delete the removed properties from `ai-assistant.properties`.
{% endstep %}

{% step %}
Delete `MODEL_PROVIDER`, `MODEL`, `OCI_GENAI_BASE_URL`, `OCI_GENAI_MODEL`, `OCI_GENAI_API_KEY` and `AI_GATEWAY_API_KEY` from the service's environment and its `.env` file.
{% endstep %}

{% step %}
Restart the AI assistant service.
{% endstep %}

{% step %}
Add the model connection on the record's **Agent** tab, as described in [Add the model connection](https://docs.openiam.com/administration-guide/platform/turn-on-the-ai-assistant.md#add-the-model-connection).
{% endstep %}

{% step %}
Activate the record, as described in [Activate the agent record](https://docs.openiam.com/administration-guide/platform/turn-on-the-ai-assistant.md#activate-the-agent-record).
{% endstep %}

{% step %}
Delete the two old Vault entries once the assistant answers.
{% endstep %}
{% endstepper %}

### Vault and Consul move to new major versions

2026.11.2 moves the secret store to **Vault 2.2.1**, from the Vault 1.x the host runs (1.20.2 in the releases just before), its storage backend from Consul 1.20.5 to **Consul 2.1.0**, and the medusa export tool to 0.7.3. Both upgrade in place on their existing data: Vault is not initialized again, and no secret has to be entered again.

The release also prepares the `secret/` mount for key-value (KV) version 2, the versioned secrets engine. That switch is a separate step you turn on afterwards, described in [Switch the secrets engine to KV version 2](#switch-the-secrets-engine-to-kv-version-2). Until then the mount stays KV version 1, and every OpenIAM service of this release reads either version.

**Vault client certificates.** From 2026.11.2 each OpenIAM component signs in to Vault with a certificate of its own role, `services`, `bootstrap`, `connector` or `ops`, and verifies Vault's certificate against the host's certificate authority (CA). The upgrade issues the certificates from the CA already in `/usr/local/openiam/vault/certs/` and registers the roles: steps 4 and 8 below. The legacy cert-auth entry `web`, which every client signs in with today, stays registered in this release, so a client not moved yet, such as a connector on another host, keeps working through the upgrade. [Vault client identities](https://docs.openiam.com/administration-guide/security/vault-client-identities.md) has the roles, the files, and how to rotate them.

#### Before you start

**Nothing to put in place first.** Run `openiam-cli upgrade` as usual. The upgrade script on the host, the one of the release you are leaving, starts the upgrade and hands it over to the 2026.11.2 script as soon as it has unpacked the 2026.11.2 package. The 2026.11.2 script does the rest, the Vault and Consul step included. You answer the internet question once, the backup the first script took in `/usr/local/openiam/backup/` is kept, and nothing is downloaded twice. To see the hand-over:

{% code overflow="wrap" %}

```bash
grep -E 'Handing the upgrade over|Continuing the upgrade the' /usr/local/openiam/upgrade.log
```

{% endcode %}

**What you should see:** `Continuing the upgrade the 2026.11.1 upgrade.sh started: openiam-2026.11.2.noarch.x86_64.rpm is unpacked in /usr/src.`, with your version in place of 2026.11.1.

**Not on a three-node cluster.** There the hand-over runs the Vault and Consul step as well, which is written for a single host. See [Three-node clusters](#three-node-clusters-are-not-moved-by-this-release).

**Back up the secret store, and copy the backup off the host.** Take the Consul snapshot and the platform directory as in [Back up and restore](https://docs.openiam.com/installation/rpm/rpm-single-node/back-up-and-restore.md). The upgrade takes a snapshot of its own as well, in `/usr/local/openiam/backup/`, but every run of the upgrade script empties that directory first, so a second run loses the first run's snapshot.

**In a secure deployment** (`VAULT_SECURE_DEPLOYMENT=true`), have three unseal key holders and the root token available for the window. Vault restarts sealed on the new binary, and the script waits up to 30 minutes for the keys.

#### What the upgrade does

Run the upgrade as usual, with `openiam-cli upgrade`. With the OpenIAM services stopped, the script:

1. Saves a Consul snapshot to `/usr/local/openiam/backup/consul-<timestamp>.snap`, and checks it with `consul snapshot inspect`. If either fails, it stops before anything has changed.
2. Stops `openiam-vault`.
3. Replaces the `vault`, `consul` and `medusa` binaries under `/usr/local/openiam/vault/`, and refreshes the scripts under `/usr/local/openiam/utils/vault/`. It also makes sure the `consul` and `vault` users can reach their binaries. A host installed with 2026.11.1 or earlier has `/usr/local/openiam` at mode `750`, on which Consul does not start again, so the script gives the directory execute permission for others (`751`), as a fresh install has it.
4. Issues the Vault client certificates from the host's CA. Vault gets a new certificate, with the host's names and a new key, and the previous pair is kept as `vault-web.crt` and `vault-web.key`, which `web` stays pinned to. Each role gets its certificate in `/usr/local/openiam/vault/certs/client/`. Vault is still stopped, so it starts on the new certificate.
5. Restarts `consul` on 2.1.0, and waits for it to elect a leader.
6. Starts `openiam-vault` on 2.2.1, and waits until it is unsealed. With `VAULT_SECURE_DEPLOYMENT=false` Vault unseals itself. Otherwise the script prints the `vault operator unseal` command to run three times, once per key.
7. Re-applies the `openiam` policy, and runs the switch to KV version 2, which stays off until you turn it on. In a secure deployment it prints the `vault policy write` command to run with the root token instead of re-applying the policy.
8. Registers the four roles and their policies next to `web`, and rewrites `/usr/local/openiam/conf/properties/vault.properties` for the role `services` and `vault-connector.properties` next to it for the role `connector`.

The 2026.11.2 upgrade script also installs the drop-in `/etc/systemd/system/openiam-connector@.service.d/vault-identity.conf`, which gives the connectors `vault-connector.properties` in place of the services' file. After the upgrade, `openiam-cli` is the 2026.11.2 copy, with `vault-backup` and `vault-restore`.

**In a secure deployment** the host keeps no root token, so step 8 prints the command instead of registering the roles. Everything keeps signing in as `web`, over a verified connection, and the upgrade's closing checks print `NOTE` lines rather than failing. Once the upgrade is done, register the roles, typing the root token rather than putting it on the command line, then restart the services and any running connector:

{% code overflow="wrap" %}

```bash
read -rs VAULT_TOKEN && export VAULT_TOKEN
/usr/local/openiam/utils/vault/client-identities.sh
unset VAULT_TOKEN
openiam-cli stop
openiam-cli start
```

{% endcode %}

Restart each running connector with `systemctl restart openiam-connector@<name>`.

**Without `vault.ca.key`**, because the host's certificates come from your organization's CA, step 4 issues nothing and the host keeps working as before. The step lists the files to bring; see [Bring your own CA](https://docs.openiam.com/administration-guide/security/vault-client-identities.md#bring-your-own-ca).

**Consul goes from 1.20.5 to 2.1.0 in one step.** HashiCorp's rule of at most two major versions per upgrade is about clusters that run mixed versions while their servers are rolled one at a time. A single Consul server never has a peer on another version.

#### Three-node clusters are not moved by this release

A cluster built with the [cluster tooling](https://docs.openiam.com/installation/rpm/rpm-ha/install.md) runs Vault on a three-server Consul cluster, and the cluster's upgrade leaves Vault and Consul as they are. The cluster keeps the versions it runs, the `secret/` mount stays KV version 1, and every node keeps signing in as `web`.

Upgrade a cluster with its cluster tooling only. Do not run `openiam-cli upgrade` on a cluster node, which now runs this step through the hand-over, and do not run `upgrade_vault_consul.sh` there by hand. The step is written for a single host, and it recognizes a cluster only by the settings of the etcd-based layout of the 4.2.1 line: more than one entry in `VAULT_CLUSTER_HOSTS_LIST`, or a running etcd. Plan the cluster's move on your support case.

#### Check the Vault and Consul step

{% code overflow="wrap" %}

```bash
grep '\[vault/consul\]' /usr/local/openiam/upgrade.log | tail -n 5
systemctl status consul openiam-vault --no-pager
consul operator raft list-peers
```

{% endcode %}

**What you should see:** the log ends with `Done. Vault v2.2.1, Consul v2.1.0, secret/ is KV version 1.` and the rollback line. Both units are `active`, and the Consul server is the `leader`.

Then check the client identities. The script is safe to run at any time, as root:

{% code overflow="wrap" %}

```bash
/usr/local/openiam/utils/vault/client-identities.sh
```

{% endcode %}

**What you should see:** a `PASS` line for each role, such as `PASS: the role services logs in with the policy openiam-services`, and `PASS: the legacy role web still logs in (VAULT_KEEP_LEGACY_CERT_ROLE=true)`. In a secure deployment the roles show as `NOTE` lines until you register them, as above.

**If the Vault and Consul step fails**, the upgrade stops with the OpenIAM services stopped and prints `ERROR: the Vault/Consul upgrade did not complete`. Copy the snapshot in `/usr/local/openiam/backup/` off the host, because the next run of the upgrade script empties that directory. Fix the cause the error names, then run the step again on its own, and then the upgrade script:

{% code overflow="wrap" %}

```bash
/usr/src/openiam/utils/vault/upgrade_vault_consul.sh /usr/src/openiam
openiam-cli upgrade
```

{% endcode %}

The step checks what is already done, so it is safe to repeat.

### Switch the secrets engine to KV version 2

KV version 2 keeps a history of each secret. Switching converts the `secret/` mount in place: every existing secret becomes version 1 of itself, the keys and paths OpenIAM uses do not change, and from then on Vault keeps up to five versions of each secret (`max_versions=5`).

{% hint style="danger" %}
**Switch only once everything that reads Vault runs 2026.11.2 or later**: every OpenIAM service and user interface, every connector, including connectors on other hosts, and any script or tool of your own that reads `secret/openiam/`. A reader from an earlier release cannot read a version 2 mount. It gets `null` for every key, and the conversion cannot be undone in place.
{% endhint %}

The switch is `VAULT_KV_UPGRADE` in `/usr/local/openiam/env.conf`. The upgrade adds it set to `false`. Vault runs the switch every time it starts, and it does nothing while the value is `false`. It is for a single host: on a three-node cluster, leave it off, as described under [Three-node clusters](#three-node-clusters-are-not-moved-by-this-release).

{% stepper %}
{% step %}
Take a backup, and copy it off the host:

{% code overflow="wrap" %}

```bash
openiam-cli vault-backup
```

{% endcode %}

It writes a Consul snapshot and a copy of `/usr/local/openiam/vault/certs` to `VAULT_BACKUP_DIR`, `/var/backups/openiam/vault` by default.
{% endstep %}

{% step %}
Stop the OpenIAM services, so that nothing reads Vault while the mount converts:

{% code overflow="wrap" %}

```bash
openiam-cli stop
```

{% endcode %}
{% endstep %}

{% step %}
Set `export VAULT_KV_UPGRADE=true` in `/usr/local/openiam/env.conf`.
{% endstep %}

{% step %}
Restart Vault:

{% code overflow="wrap" %}

```bash
systemctl restart openiam-vault
journalctl -u openiam-vault --since "-5 min" --no-pager | grep 'KV version'
```

{% endcode %}

**What you should see:** `Upgrading secret/ from KV version 1 to version 2 ...`. A second restart logs `secret/ is already KV version 2`.
{% endstep %}

{% step %}
Start the OpenIAM services:

{% code overflow="wrap" %}

```bash
openiam-cli start
```

{% endcode %}
{% endstep %}
{% endstepper %}

Leave the value at `true`. The step is safe to repeat.

**In a secure deployment** (`VAULT_SECURE_DEPLOYMENT=true`), the host keeps no root token, so Vault cannot convert the mount itself: with the switch on, a start only logs the two commands to run. Skip steps 3 and 4, which would leave Vault sealed, and run the commands yourself while Vault is up. Type the root token rather than putting it on the command line:

{% code overflow="wrap" %}

```bash
read -rs VAULT_TOKEN && export VAULT_TOKEN
vault kv enable-versioning -address=https://localhost:8200 -ca-cert=/usr/local/openiam/vault/certs/client/vault.ca.crt secret/
vault write -address=https://localhost:8200 -ca-cert=/usr/local/openiam/vault/certs/client/vault.ca.crt secret/config max_versions=5
unset VAULT_TOKEN
```

{% endcode %}

Replace `localhost` with `VAULT_URL` from `env.conf` if it differs. A host without `vault/certs/client/vault.ca.crt` uses `-tls-skip-verify` in place of `-ca-cert`. For a few seconds after `enable-versioning`, the second command fails with `Upgrading from non-versioned to versioned data`. Repeat it until it succeeds. Until you run them, everything keeps using the mount as KV version 1.

[Rotate service credentials](https://docs.openiam.com/administration-guide/security/rotate-service-credentials.md#reading-a-key-and-its-versions) shows how a key and its versions read on a version 2 mount.

### Roll back the Vault and Consul upgrade

**To undo only the switch to KV version 2**, stay on 2026.11.2 and restore the backup taken just before it. Set `VAULT_KV_UPGRADE=false` in `env.conf` first, or the next Vault start converts the restored mount again. The restore refuses to run while an OpenIAM service is active:

{% code overflow="wrap" %}

```bash
openiam-cli stop
openiam-cli vault-restore /var/backups/openiam/vault/consul-<timestamp>.snap
openiam-cli start
```

{% endcode %}

The services detect the mount version when they start, so they read version 1 again.

**To undo the whole upgrade**, return the host to the snapshot taken before the window, as for any upgrade. The script's last line names the narrower way back for the secret store alone: the previous release's binaries, then `consul snapshot restore` of the snapshot it took in `/usr/local/openiam/backup/`. The unseal keys do not change during the upgrade, so the restored data unseals as before.
{% endtab %}
{% endtabs %}

## Custom Groovy scripts must be re-pointed

The extractions moved the base classes that customer scripts extend. **Scripts referencing the old packages will not compile until their imports are updated.** The scripts shipped under `conf/iamscripts/` were updated for you; anything you customized was not.

Find these before you upgrade, not after a batch job or a campaign fails to initialize.

<table><thead><tr><th width="237.800048828125">Old package</th><th width="271.99993896484375">New package</th><th>Moved in</th></tr></thead><tbody><tr><td><code>org.openiam.esb.core.batch.tasks.implementation.AbstractActivateProcess</code></td><td><code>org.openiam.batch.manager.initializer.implementation.AbstractActivateProcess</code></td><td>2026.5.2</td></tr><tr><td><code>org.openiam.esb.core.batch.tasks.implementation.AbstractLeaverProcess</code></td><td><code>org.openiam.batch.manager.initializer.implementation.AbstractLeaverProcess</code></td><td>2026.5.2</td></tr><tr><td><code>org.openiam.esb.core.batch.tasks.TerminatedUsersReportHelper</code></td><td><code>org.openiam.common.batch.TerminatedUsersReportHelper</code></td><td>2026.5.2</td></tr><tr><td><code>org.openiam.esb.domain.BatchTaskEntity</code></td><td><code>org.openiam.batch.manager.domain.BatchTaskEntity</code></td><td>2026.5.2</td></tr><tr><td><code>org.openiam.esb.core.batch.tasks.AccessCertificationHelper</code></td><td><code>org.openiam.certification.initializer.CertificationHelper</code></td><td>2026.5.2, and again in 2026.6.1</td></tr></tbody></table>

{% hint style="info" %}
**The certification base class moved twice.** It went to `org.openiam.batch.manager.initializer.AccessCertificationHelper` in 2026.5.2 and then to `org.openiam.certification.initializer.CertificationHelper` in 2026.6.1. If you upgraded through 2026.5.2 you may have already made the first move; the table shows the destination, not the intermediate stop.
{% endhint %}

More broadly, `org.openiam.esb.core.batch.tasks.*` moved wholesale to `org.openiam.batch.manager.initializer.*`, and the certification packages moved from `org.openiam.esb.*` to `org.openiam.certification.*`. The shared DTO contract is unchanged.

## Related

* [Minor upgrade](https://docs.openiam.com/installation/rpm/rpm-upgrade/minor-upgrade.md) — the standard within-line procedure
* [Major upgrade](https://docs.openiam.com/installation/rpm/rpm-upgrade/major-upgrade.md) — crossing to a different release line
* [After a major upgrade](https://docs.openiam.com/installation/rpm/rpm-upgrade/after-a-major-upgrade.md) — what to put right once the upgrade completes
* [Release-specific steps — Kubernetes](https://docs.openiam.com/installation/kubernetes/kubernetes-upgrade/release-specific-steps.md) — the same releases, configured through Helm


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/installation/rpm/rpm-upgrade/release-specific-steps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
