From f6b493b605aa2bb79417decb7335f9d85b784da0 Mon Sep 17 00:00:00 2001 From: Pablo Carle Date: Tue, 4 Aug 2026 15:38:01 +0200 Subject: [PATCH 01/13] initial version Signed-off-by: Pablo Carle --- migration-3.6.0.md | 135 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 migration-3.6.0.md diff --git a/migration-3.6.0.md b/migration-3.6.0.md new file mode 100644 index 0000000000..6c5fa0f25e --- /dev/null +++ b/migration-3.6.0.md @@ -0,0 +1,135 @@ +# Summary of changes in Zowe 3.6.0 + +This article lists changes introduced in the API Mediation Layer (API ML) for Zowe 3.6. + +Two kinds of changes are covered: + +* Properties that **already existed** at `Zowe_3.5.0` and whose default, source, or meaning changed. +* **Brand-new** properties whose default is restrictive enough that an installation which worked at `Zowe_3.5.0` may need to explicitly set them after upgrading to stay fully functional. + +## 1. Discovery Service now enforces an allowlist of domains for service registration + + + +In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now validates, for **every** registering instance, its hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. This check is unconditional — it runs for every registration, regardless of any other setting — and by default **rejects the entire registration** if any of those URLs point to a domain that isn't allowed. + +The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. +A small set of Zowe/IBM documentation domains (`www.ibm.com`, `zowe.github.io`, `www.zowe.org`, `techdocs.broadcom.com`) is always allowed to permit core service registrations. + +**Required action:** + +* The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. +* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. For example: + +```yaml +zowe: + network: + allowedDomains: + - "*.zowe.org" + - "ibm.com" + - "10.0.0.5" +``` + +* As a temporary mitigation while you adjust the allowlist, the Discovery Service honors the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`, which downgrades rejections to warnings instead of failing registration. + +### 2. Strict URL validation replaces `allowEncodedSlashes` + +The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and replaced by `apiml.security.enableStrictUrlValidation`. In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`, allowing encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. + +**Required action:** Remove any existing `apiml.service.allowEncodedSlashes` setting — it has no effect anymore. If routed requests need to carry encoded slashes or similar encoded characters in the URL path, explicitly disable strict validation: + +```yaml +components: + gateway: + apiml: + security: + enableStrictUrlValidation: false +``` + +Without this change, routed requests containing encoded slashes, backslashes, or semicolons — previously allowed by default — are now rejected by default. + +### 3. CORS: default allowed origin for routed services narrowed + +This only matters if you have `apiml.service.corsEnabled: true` (CORS handling in the Gateway is `false`/disabled by default). + +When CORS handling is enabled, for a southbound service that opts in via its own `apiml.corsEnabled` metadata but does not declare its own `apiml.corsAllowedOrigins`, the Gateway used to allow **any** origin (`Access-Control-Allow-Origin: *`). It now falls back to a configurable default, `apiml.service.corsDefaultAllowedOrigins`, whose effective default is the Gateway's own base URL (`https://:`) rather than "any origin." A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so it does not require action. + +**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an origin other than the Gateway's own hostname/port, set: + +```yaml +components: + gateway: + apiml: + service: + corsDefaultAllowedOrigins: https://my-external-client.example.com +``` + +### 4. Eureka discovery service credentials are now configurable + +At `Zowe_3.5.0`, the credentials used to authenticate against the Discovery Service's `/eureka` endpoint were fixed to the literal values `eureka` / `password` in the `apiml` and `discovery` components and were not configurable; the other API ML services sent no credentials at all. These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. Their default depends on `zowe.verifyCertificates`: + +* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set — this is also the credential pair automatically reused for the Caching Service authentication described in change 5, so deployments using `DISABLED` need no action for either change. +* If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, there is no default — the credentials are empty unless configured. + +**Required action:** If `zowe.verifyCertificates` is `STRICT` or `NONSTRICT` and your Discovery Service enforces Eureka basic authentication, set matching credentials on the Discovery Service and every service that registers with it: + +```yaml +components: + discovery: + apiml: + discovery: + userid: eureka + password: password + gateway: + apiml: + discovery: + userid: eureka + password: password + # repeat for caching-service, api-catalog, zaas (or apiml.apiml.discovery.* for the convenience bundle) +``` + +No action is required if `zowe.verifyCertificates: DISABLED`. + +### 5. Caching Service requires authentication when certificate validation is disabled + +At `Zowe_3.5.0`, when `apiml.service.ssl.verifySslCertificatesOfServices` was `false` (that is, `zowe.verifyCertificates: DISABLED`), the Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`). It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses mutual-TLS/X.509 authentication and is unaffected. + +**Required action:** For deployments using Zowe's own `*-package` components, `apiml.service.http.userId`/`password` automatically fall back to the same `apiml.discovery.userid`/`password` described in change 4, so **no action is needed** if you rely on the defaults in `DISABLED` mode. Action is only needed if: + +* You have a custom client calling the Caching Service's REST API directly (not through Gateway/ZAAS) — it must now send matching Basic Auth credentials. +* You explicitly override `apiml.discovery.userid`/`password` or `apiml.service.http.userId`/`password` differently between the Caching Service and its callers, in which case they must be set to the same values everywhere: + +```yaml +components: + caching-service: + apiml: + service: + http: + userId: eureka + password: password +``` + +### 6. Infinispan initial hosts are now auto-constructed for HA + +The Caching Service's `storage.infinispan.initialHosts` property previously defaulted to the hardcoded value `localhost[7600]`. In a high-availability (HA) deployment with more than one instance, this default never pointed at the other instances in the sysplex, which contributed to Infinispan clustering failures in HA on Java 21+. + +The default has been changed to an empty value. When `storage.infinispan.initialHosts` is not explicitly set, the Caching Service now automatically builds the initial hosts list from the `haInstances` entries defined in `zowe.yaml`, falling back to the local `apiml.service.hostname` only if no HA instances are configured. + +**Required action:** + +* If you never explicitly set `storage.infinispan.initialHosts`, no action is required — your deployment now gets the corrected, auto-constructed value instead of the previous, largely non-functional `localhost[7600]` default. +* If you manually set `storage.infinispan.initialHosts` as a workaround for HA clustering issues, you can likely remove it and let it be auto-constructed: + +```yaml +components: + caching-service: + storage: + infinispan: + initialHosts: # remove, or leave unset, to auto-construct from haInstances +``` + +Explicit values are still honored and take precedence over the auto-constructed list. From df704d704db15b6f2d2d611109374ed95839c2bf Mon Sep 17 00:00:00 2001 From: Pablo Carle Date: Tue, 4 Aug 2026 15:56:28 +0200 Subject: [PATCH 02/13] update Signed-off-by: Pablo Carle --- migration-3.6.0.md | 53 ++++++++++++++-------------------------------- 1 file changed, 16 insertions(+), 37 deletions(-) diff --git a/migration-3.6.0.md b/migration-3.6.0.md index 6c5fa0f25e..f3ced7ea68 100644 --- a/migration-3.6.0.md +++ b/migration-3.6.0.md @@ -9,12 +9,6 @@ Two kinds of changes are covered: ## 1. Discovery Service now enforces an allowlist of domains for service registration - - In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now validates, for **every** registering instance, its hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. This check is unconditional — it runs for every registration, regardless of any other setting — and by default **rejects the entire registration** if any of those URLs point to a domain that isn't allowed. The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. @@ -70,12 +64,17 @@ components: ### 4. Eureka discovery service credentials are now configurable -At `Zowe_3.5.0`, the credentials used to authenticate against the Discovery Service's `/eureka` endpoint were fixed to the literal values `eureka` / `password` in the `apiml` and `discovery` components and were not configurable; the other API ML services sent no credentials at all. These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. Their default depends on `zowe.verifyCertificates`: +**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` + +The credentials used to authenticate against the Discovery Service's `/eureka/**` endpoints when certificate validation is disabled were fixed to the literal values `eureka` / `password`. +These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. + +* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set. +* If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, a valid client certificate issued by a Zowe-trusted CA is used. -* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set — this is also the credential pair automatically reused for the Caching Service authentication described in change 5, so deployments using `DISABLED` need no action for either change. -* If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, there is no default — the credentials are empty unless configured. +**Required action:** If `zowe.verifyCertificates` is `DISABLED` (not recommended), set matching credentials on the Discovery Service and every service that registers with it: -**Required action:** If `zowe.verifyCertificates` is `STRICT` or `NONSTRICT` and your Discovery Service enforces Eureka basic authentication, set matching credentials on the Discovery Service and every service that registers with it: +**Example:** ```yaml components: @@ -89,19 +88,20 @@ components: discovery: userid: eureka password: password - # repeat for caching-service, api-catalog, zaas (or apiml.apiml.discovery.* for the convenience bundle) + # repeat for caching-service, api-catalog, zaas ``` -No action is required if `zowe.verifyCertificates: DISABLED`. - ### 5. Caching Service requires authentication when certificate validation is disabled -At `Zowe_3.5.0`, when `apiml.service.ssl.verifySslCertificatesOfServices` was `false` (that is, `zowe.verifyCertificates: DISABLED`), the Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`). It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses mutual-TLS/X.509 authentication and is unaffected. +**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` + +The Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`) when certificate validation was disabled at Zowe level. +It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. +When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. -**Required action:** For deployments using Zowe's own `*-package` components, `apiml.service.http.userId`/`password` automatically fall back to the same `apiml.discovery.userid`/`password` described in change 4, so **no action is needed** if you rely on the defaults in `DISABLED` mode. Action is only needed if: +**Required action:** Action is only needed if: * You have a custom client calling the Caching Service's REST API directly (not through Gateway/ZAAS) — it must now send matching Basic Auth credentials. -* You explicitly override `apiml.discovery.userid`/`password` or `apiml.service.http.userId`/`password` differently between the Caching Service and its callers, in which case they must be set to the same values everywhere: ```yaml components: @@ -112,24 +112,3 @@ components: userId: eureka password: password ``` - -### 6. Infinispan initial hosts are now auto-constructed for HA - -The Caching Service's `storage.infinispan.initialHosts` property previously defaulted to the hardcoded value `localhost[7600]`. In a high-availability (HA) deployment with more than one instance, this default never pointed at the other instances in the sysplex, which contributed to Infinispan clustering failures in HA on Java 21+. - -The default has been changed to an empty value. When `storage.infinispan.initialHosts` is not explicitly set, the Caching Service now automatically builds the initial hosts list from the `haInstances` entries defined in `zowe.yaml`, falling back to the local `apiml.service.hostname` only if no HA instances are configured. - -**Required action:** - -* If you never explicitly set `storage.infinispan.initialHosts`, no action is required — your deployment now gets the corrected, auto-constructed value instead of the previous, largely non-functional `localhost[7600]` default. -* If you manually set `storage.infinispan.initialHosts` as a workaround for HA clustering issues, you can likely remove it and let it be auto-constructed: - -```yaml -components: - caching-service: - storage: - infinispan: - initialHosts: # remove, or leave unset, to auto-construct from haInstances -``` - -Explicit values are still honored and take precedence over the auto-constructed list. From 350620f2c95d7b798ece6b06b84baecabe7b2238 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 12 Aug 2026 10:59:07 +0200 Subject: [PATCH 03/13] move content to v3.6.0 release notes Signed-off-by: Andrew Jandacek --- docs/whats-new/release-notes/v3_6_0.md | 209 +++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 docs/whats-new/release-notes/v3_6_0.md diff --git a/docs/whats-new/release-notes/v3_6_0.md b/docs/whats-new/release-notes/v3_6_0.md new file mode 100644 index 0000000000..77ce7f11ff --- /dev/null +++ b/docs/whats-new/release-notes/v3_6_0.md @@ -0,0 +1,209 @@ +# Version 3.6.0 (October 2026) + +Welcome to the Zowe Version 3.6.0 release! + +See [New features and enhancements](#new-features-and-enhancements) for a full list of changes to the functionality. See [Bug fixes](#bug-fixes) for a list of issues addressed in this release. + +**Download v3.6.0 build**: Want to try new features as soon as possible? You can download the v3.6.0 build from [Zowe.org](https://www.zowe.org/download.html). + +## New features and enhancements + +Zowe Version 2.3.0 contains the enhancements that are described in the following topics. + +### Zowe installation and packaging + +### Zowe Application Framework + +### Zowe API Mediation Layer + +Two kinds of changes are covered: + +* Properties that **already existed** at `Zowe_3.5.0` and whose default, source, or meaning changed. +* **Brand-new** properties whose default is restrictive enough that an installation which worked at `Zowe_3.5.0` may need to explicitly set them after upgrading to stay fully functional. + +## Discovery Service now enforces an allowlist of domains for service registration + +In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now validates, for **every** registering instance, its hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. This check is unconditional — it runs for every registration, regardless of any other setting — and by default **rejects the entire registration** if any of those URLs point to a domain that isn't allowed. + +The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. +A small set of Zowe/IBM documentation domains (`www.ibm.com`, `zowe.github.io`, `www.zowe.org`, `techdocs.broadcom.com`) is always allowed to permit core service registrations. + +**Required action:** + +* The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. +* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. For example: + +```yaml +zowe: + network: + allowedDomains: + - "*.zowe.org" + - "ibm.com" + - "10.0.0.5" +``` + +* As a temporary mitigation while you adjust the allowlist, the Discovery Service honors the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`, which downgrades rejections to warnings instead of failing registration. + +### Strict URL validation replaces `allowEncodedSlashes` + +The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and replaced by `apiml.security.enableStrictUrlValidation`. In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`, allowing encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. + +**Required action:** Remove any existing `apiml.service.allowEncodedSlashes` setting — it has no effect anymore. If routed requests need to carry encoded slashes or similar encoded characters in the URL path, explicitly disable strict validation: + +```yaml +components: + gateway: + apiml: + security: + enableStrictUrlValidation: false +``` + +Without this change, routed requests containing encoded slashes, backslashes, or semicolons — previously allowed by default — are now rejected by default. + +### CORS: default allowed origin for routed services narrowed + +This only matters if you have `apiml.service.corsEnabled: true` (CORS handling in the Gateway is `false`/disabled by default). + +When CORS handling is enabled, for a southbound service that opts in via its own `apiml.corsEnabled` metadata but does not declare its own `apiml.corsAllowedOrigins`, the Gateway used to allow **any** origin (`Access-Control-Allow-Origin: *`). It now falls back to a configurable default, `apiml.service.corsDefaultAllowedOrigins`, whose effective default is the Gateway's own base URL (`https://:`) rather than "any origin." A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so it does not require action. + +**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an origin other than the Gateway's own hostname/port, set: + +```yaml +components: + gateway: + apiml: + service: + corsDefaultAllowedOrigins: https://my-external-client.example.com +``` + +### Eureka discovery service credentials are now configurable + +**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` + +The credentials used to authenticate against the Discovery Service's `/eureka/**` endpoints when certificate validation is disabled were fixed to the literal values `eureka` / `password`. +These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. + +* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set. +* If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, a valid client certificate issued by a Zowe-trusted CA is used. + +**Required action:** If `zowe.verifyCertificates` is `DISABLED` (not recommended), set matching credentials on the Discovery Service and every service that registers with it: + +**Example:** + +```yaml +components: + discovery: + apiml: + discovery: + userid: eureka + password: password + gateway: + apiml: + discovery: + userid: eureka + password: password + # repeat for caching-service, api-catalog, zaas +``` + +### Caching Service requires authentication when certificate validation is disabled + +**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` + +The Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`) when certificate validation was disabled at Zowe level. +It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. +When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. + +**Required action:** Action is only needed if: + +* You have a custom client calling the Caching Service's REST API directly (not through Gateway/ZAAS) — it must now send matching Basic Auth credentials. + +```yaml +components: + caching-service: + apiml: + service: + http: + userId: eureka + password: password +``` + + +### Zowe CLI + +#### Zowe CLI (Core) + +#### Zowe CLI Imperative Framework + +#### CICS Plug-in for Zowe CLI + +#### DB2 Plug-in for Zowe CLI + +#### MQ Plug-in for Zowe CLI + +#### IMS Plug-in for Zowe CLI + +### Zowe Explorer + +#### Zowe Explorer (Core) + +- See the [Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/zowe-explorer/CHANGELOG.md) changelog for updates included in this release. + +#### Zowe Explorer API + +- See the [Zowe Explorer API](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/zowe-explorer-api/CHANGELOG.md) changelog for updates included in this release. + +#### Zowe Explorer for IBM z/OS FTP + +- See the [Zowe® Explorer for IBM® z/OS® FTP](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/zowe-explorer-ftp-extension/CHANGELOG.md) changelog for updates included in this release. + +#### Zowe Explorer ESLint Plug-in + +- See the [Zowe Explorer ESLint Plug-in](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/eslint-plugin-zowe-explorer/CHANGELOG.md) changelog for updates included in this release. + +## Bug fixes + +Zowe Version 2.3.0 contains the bug fixes that are described in the following topics. + +### Zowe installation and packaging + +### Zowe Application Framework + +### Zowe API Mediation Layer + +### Zowe CLI + +#### Zowe CLI (Core) + +#### Zowe CLI Imperative Framework + +#### CICS Plug-in for Zowe CLI + +#### DB2 Plug-in for Zowe CLI + +#### MQ Plug-in for Zowe CLI + +#### IMS Plug-in for Zowe CLI + +### Zowe Explorer + +#### Zowe Explorer (Core) + +- See the [Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/zowe-explorer/CHANGELOG.md) changelog for updates included in this release. + +#### Zowe Explorer API + +- See the [Zowe Explorer API](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/zowe-explorer-api/CHANGELOG.md) changelog for updates included in this release. + +#### Zowe Explorer for IBM z/OS FTP + +- See the [Zowe® Explorer for IBM® z/OS® FTP](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/zowe-explorer-ftp-extension/CHANGELOG.md) changelog for updates included in this release. + +#### Zowe Explorer ESLint Plug-in + +- See the [Zowe Explorer ESLint Plug-in](https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/eslint-plugin-zowe-explorer/CHANGELOG.md) changelog for updates included in this release. + +### Vulnerabilities fixed + +Zowe discloses fixed vulnerabilities in a timely manner giving you sufficient time to plan your upgrades. Zowe does not disclose the vulnerabilities fixed in the latest release as we respect the need for at least 45 days to decide when and how you upgrade Zowe. When a new release is published, Zowe publishes the vulnerabilities fixed in the previous release. For more information about the Zowe security policy, see the [Security page](https://www.zowe.org/security.html) on the Zowe website. + +The following security issues were fixed by the Zowe security group in version 3.5. \ No newline at end of file From 8fc2176bf728e98c590a903afa017d1ee76e8c6f Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 12 Aug 2026 12:15:52 +0200 Subject: [PATCH 04/13] create section Security updates in Zowe 3.6.0 Signed-off-by: Andrew Jandacek --- docs/whats-new/breaking-changes-v3.md | 131 ++++++++++++++++++++++++- docs/whats-new/release-notes/v3_6_0.md | 112 --------------------- 2 files changed, 128 insertions(+), 115 deletions(-) diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index fd8d090e91..f8f07f7784 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -19,10 +19,135 @@ Review this article for details about changes to various Zowe components that ar | Java 17 will be required for the API Mediation Layer to run | For V3, it is necessary to update z/OS to version 2.5 or later as this brings support of Java 17. It is necessary to install Java 17 and provide the path to Java 17 to Zowe Java configuration. | | z/OSMF in version V2R5 with APAR PH12143 applied (JWT setup) | If you are running a version of z/OS before 3.1, validate that the PH12143 APAR was applied to the z/OSMF installation used by Zowe. The value `auto` is no longer supported. For v3R1, validate that the JWT support is enabled. If you do not want to enable JWT support, make sure that you set the value of `components.gateway.apiml.security.auth.zosmf.jwtAutoconfiguration` to `ltpa`. The `ltpa` option cannot be used with hardware accelerated ICSF Keyrings. See [example-zowe.yaml](https://github.com/zowe/zowe-install-packaging/blob/v3.x/staging/example-zowe.yaml) for new component values. | | Configuration of keyrings will require transformation from `safkeyring:////` to `safkeyring://` | If your Zowe configuration contains `safkeyring:////`, change this part to `safkeyring://`. | -| Support access to z/OSMF only through `/ibmzosmf` route. V3 will not support access through the `/zosmf` route | If you use z/OSMF via `{apimlUrl}/zosmf/{zosmfEndpoint}` it is necessary to move to `{apimlUrl}/ibmzosmf/{zosmfEndpoint}.` | -### Important API ML updates +| Support access to z/OSMF only through `/ibmzosmf` route. V3 will not support access through the `/zosmf` route | If you use z/OSMF via `{apimlUrl}/zosmf/{zosmfEndpoint}` it is necessary to move to `{apimlUrl}/ibmzosmf/{zosmfEndpoint}.` | -The current API Gateway contains the Authentication and Authorization Service. This service will be separated as a standalone service. The Authentication and Authorization Service is the only API ML service that directly requires z/OS. +### Important API ML updates in Zowe v3 + +In previous versions of Zowe, the API Gateway directly contained the code for the Authentication and Authorization Service (ZAAS). In Zowe V3, ZAAS was architecturally decoupled into a standalone component with its own configuration, as it is the only API Mediation Layer (API ML) service that natively requires direct interaction with z/OS security services (such as z/OSMF and SAF). + +While ZAAS is now a standalone service, how ZAAS runs depends on your deployment configuration. In multi-service deployment, ZAAS runs as a physically independent microservice (a separate JVM process) on its own port. Starting with Zowe v3.4, the default and recommended single-service deployment mode bundles the standalone ZAAS component back into a single JVM process alongside the Gateway, Discovery Service, and API Catalog at runtime. + +### Security updates in Zowe 3.6.0 + +Zowe 3.6.0 introduces several important updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your zowe.yaml configuration to avoid disruptions during the upgrade process. + +Configuration changes are in two key areas: + +* **Modified existing properties** +Configuration properties that existed in Zowe 3.5.0, but whose default value, source, or underlying behavior has changed. + +* **Restrictive new properties** +New properties introduced with strict default settings. An installation that functioned correctly in Zowe 3.5.0 may require explicit configuration of these new properties to retain previous behaviors. + +#### Discovery Service now enforces an allowlist of domains for service registration + +In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now validates, for **every** registering instance, its hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. This check is unconditional — it runs for every registration, regardless of any other setting — and by default **rejects the entire registration** if any of those URLs point to a domain that isn't allowed. + +The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. +A small set of Zowe/IBM documentation domains (`www.ibm.com`, `zowe.github.io`, `www.zowe.org`, `techdocs.broadcom.com`) is always allowed to permit core service registrations. + +**Required action:** + +* The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. +* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. For example: + +```yaml +zowe: + network: + allowedDomains: + - "*.zowe.org" + - "ibm.com" + - "10.0.0.5" +``` + +* As a temporary mitigation while you adjust the allowlist, the Discovery Service honors the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`, which downgrades rejections to warnings instead of failing registration. + +### Strict URL validation replaces `allowEncodedSlashes` + +The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and replaced by `apiml.security.enableStrictUrlValidation`. In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`, allowing encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. + +**Required action:** Remove any existing `apiml.service.allowEncodedSlashes` setting — it has no effect anymore. If routed requests need to carry encoded slashes or similar encoded characters in the URL path, explicitly disable strict validation: + +```yaml +components: + gateway: + apiml: + security: + enableStrictUrlValidation: false +``` + +Without this change, routed requests containing encoded slashes, backslashes, or semicolons — previously allowed by default — are now rejected by default. + +#### CORS: default allowed origin for routed services narrowed + +This only matters if you have `apiml.service.corsEnabled: true` (CORS handling in the Gateway is `false`/disabled by default). + +When CORS handling is enabled, for a southbound service that opts in via its own `apiml.corsEnabled` metadata but does not declare its own `apiml.corsAllowedOrigins`, the Gateway used to allow **any** origin (`Access-Control-Allow-Origin: *`). It now falls back to a configurable default, `apiml.service.corsDefaultAllowedOrigins`, whose effective default is the Gateway's own base URL (`https://:`) rather than "any origin." A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so it does not require action. + +**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an origin other than the Gateway's own hostname/port, set: + +```yaml +components: + gateway: + apiml: + service: + corsDefaultAllowedOrigins: https://my-external-client.example.com +``` + +#### Eureka discovery service credentials are now configurable + +:::note +This change only applies to not-recommended setups with `verifyCertificates: DISABLED` +::: + +The credentials used to authenticate against the Discovery Service's `/eureka/**` endpoints when certificate validation is disabled were fixed to the literal values `eureka` / `password`. +These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. + +* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set. +* If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, a valid client certificate issued by a Zowe-trusted CA is used. + +**Required action:** If `zowe.verifyCertificates` is `DISABLED` (not recommended), set matching credentials on the Discovery Service and every service that registers with it: + +**Example:** + +```yaml +components: + discovery: + apiml: + discovery: + userid: eureka + password: password + gateway: + apiml: + discovery: + userid: eureka + password: password + # repeat for caching-service, api-catalog, zaas +``` + +#### Caching Service requires authentication when certificate validation is disabled + +:::note +This change only applies to not-recommended setups with `verifyCertificates: DISABLED` +::: + +The Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`) when certificate validation was disabled at Zowe level. +It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. +When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. + +**Required action:** Action is only needed if: + +* You have a custom client calling the Caching Service's REST API directly (not through Gateway/ZAAS) — it must now send matching Basic Auth credentials. + +```yaml +components: + caching-service: + apiml: + service: + http: + userId: eureka + password: password +``` ## Application Framework diff --git a/docs/whats-new/release-notes/v3_6_0.md b/docs/whats-new/release-notes/v3_6_0.md index 77ce7f11ff..a5d0c6ea34 100644 --- a/docs/whats-new/release-notes/v3_6_0.md +++ b/docs/whats-new/release-notes/v3_6_0.md @@ -16,118 +16,6 @@ Zowe Version 2.3.0 contains the enhancements that are described in the following ### Zowe API Mediation Layer -Two kinds of changes are covered: - -* Properties that **already existed** at `Zowe_3.5.0` and whose default, source, or meaning changed. -* **Brand-new** properties whose default is restrictive enough that an installation which worked at `Zowe_3.5.0` may need to explicitly set them after upgrading to stay fully functional. - -## Discovery Service now enforces an allowlist of domains for service registration - -In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now validates, for **every** registering instance, its hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. This check is unconditional — it runs for every registration, regardless of any other setting — and by default **rejects the entire registration** if any of those URLs point to a domain that isn't allowed. - -The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. -A small set of Zowe/IBM documentation domains (`www.ibm.com`, `zowe.github.io`, `www.zowe.org`, `techdocs.broadcom.com`) is always allowed to permit core service registrations. - -**Required action:** - -* The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. -* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. For example: - -```yaml -zowe: - network: - allowedDomains: - - "*.zowe.org" - - "ibm.com" - - "10.0.0.5" -``` - -* As a temporary mitigation while you adjust the allowlist, the Discovery Service honors the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`, which downgrades rejections to warnings instead of failing registration. - -### Strict URL validation replaces `allowEncodedSlashes` - -The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and replaced by `apiml.security.enableStrictUrlValidation`. In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`, allowing encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. - -**Required action:** Remove any existing `apiml.service.allowEncodedSlashes` setting — it has no effect anymore. If routed requests need to carry encoded slashes or similar encoded characters in the URL path, explicitly disable strict validation: - -```yaml -components: - gateway: - apiml: - security: - enableStrictUrlValidation: false -``` - -Without this change, routed requests containing encoded slashes, backslashes, or semicolons — previously allowed by default — are now rejected by default. - -### CORS: default allowed origin for routed services narrowed - -This only matters if you have `apiml.service.corsEnabled: true` (CORS handling in the Gateway is `false`/disabled by default). - -When CORS handling is enabled, for a southbound service that opts in via its own `apiml.corsEnabled` metadata but does not declare its own `apiml.corsAllowedOrigins`, the Gateway used to allow **any** origin (`Access-Control-Allow-Origin: *`). It now falls back to a configurable default, `apiml.service.corsDefaultAllowedOrigins`, whose effective default is the Gateway's own base URL (`https://:`) rather than "any origin." A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so it does not require action. - -**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an origin other than the Gateway's own hostname/port, set: - -```yaml -components: - gateway: - apiml: - service: - corsDefaultAllowedOrigins: https://my-external-client.example.com -``` - -### Eureka discovery service credentials are now configurable - -**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` - -The credentials used to authenticate against the Discovery Service's `/eureka/**` endpoints when certificate validation is disabled were fixed to the literal values `eureka` / `password`. -These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. - -* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set. -* If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, a valid client certificate issued by a Zowe-trusted CA is used. - -**Required action:** If `zowe.verifyCertificates` is `DISABLED` (not recommended), set matching credentials on the Discovery Service and every service that registers with it: - -**Example:** - -```yaml -components: - discovery: - apiml: - discovery: - userid: eureka - password: password - gateway: - apiml: - discovery: - userid: eureka - password: password - # repeat for caching-service, api-catalog, zaas -``` - -### Caching Service requires authentication when certificate validation is disabled - -**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` - -The Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`) when certificate validation was disabled at Zowe level. -It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. -When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. - -**Required action:** Action is only needed if: - -* You have a custom client calling the Caching Service's REST API directly (not through Gateway/ZAAS) — it must now send matching Basic Auth credentials. - -```yaml -components: - caching-service: - apiml: - service: - http: - userId: eureka - password: password -``` - - ### Zowe CLI #### Zowe CLI (Core) From c15f0f301256e4cd9c65a504fdaaeb54ff483d07 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 12 Aug 2026 12:37:08 +0200 Subject: [PATCH 05/13] remove original file as the content is now under breaking-changes-v3.md Signed-off-by: Andrew Jandacek --- docs/whats-new/breaking-changes-v3.md | 16 ++-- migration-3.6.0.md | 114 -------------------------- 2 files changed, 10 insertions(+), 120 deletions(-) delete mode 100644 migration-3.6.0.md diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index f8f07f7784..14dec4ff5a 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -27,9 +27,9 @@ In previous versions of Zowe, the API Gateway directly contained the code for th While ZAAS is now a standalone service, how ZAAS runs depends on your deployment configuration. In multi-service deployment, ZAAS runs as a physically independent microservice (a separate JVM process) on its own port. Starting with Zowe v3.4, the default and recommended single-service deployment mode bundles the standalone ZAAS component back into a single JVM process alongside the Gateway, Discovery Service, and API Catalog at runtime. -### Security updates in Zowe 3.6.0 +### Security updates in Zowe v3.6.0 -Zowe 3.6.0 introduces several important updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your zowe.yaml configuration to avoid disruptions during the upgrade process. +Zowe 3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. Configuration changes are in two key areas: @@ -39,17 +39,21 @@ Configuration properties that existed in Zowe 3.5.0, but whose default value, so * **Restrictive new properties** New properties introduced with strict default settings. An installation that functioned correctly in Zowe 3.5.0 may require explicit configuration of these new properties to retain previous behaviors. -#### Discovery Service now enforces an allowlist of domains for service registration +#### Discovery Service enforces domain allowlist for service registration -In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now validates, for **every** registering instance, its hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. This check is unconditional — it runs for every registration, regardless of any other setting — and by default **rejects the entire registration** if any of those URLs point to a domain that isn't allowed. +In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now strictly validates all URLs provided by registering services, including hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. + +**Operational Impact:** +By default, if a service attempts to register using a domain or IP address that is not on the allowlist, the registration is rejected entirely. The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. A small set of Zowe/IBM documentation domains (`www.ibm.com`, `zowe.github.io`, `www.zowe.org`, `techdocs.broadcom.com`) is always allowed to permit core service registrations. **Required action:** - * The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. -* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. For example: +* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. + +**Example:** ```yaml zowe: diff --git a/migration-3.6.0.md b/migration-3.6.0.md deleted file mode 100644 index f3ced7ea68..0000000000 --- a/migration-3.6.0.md +++ /dev/null @@ -1,114 +0,0 @@ -# Summary of changes in Zowe 3.6.0 - -This article lists changes introduced in the API Mediation Layer (API ML) for Zowe 3.6. - -Two kinds of changes are covered: - -* Properties that **already existed** at `Zowe_3.5.0` and whose default, source, or meaning changed. -* **Brand-new** properties whose default is restrictive enough that an installation which worked at `Zowe_3.5.0` may need to explicitly set them after upgrading to stay fully functional. - -## 1. Discovery Service now enforces an allowlist of domains for service registration - -In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now validates, for **every** registering instance, its hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. This check is unconditional — it runs for every registration, regardless of any other setting — and by default **rejects the entire registration** if any of those URLs point to a domain that isn't allowed. - -The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. -A small set of Zowe/IBM documentation domains (`www.ibm.com`, `zowe.github.io`, `www.zowe.org`, `techdocs.broadcom.com`) is always allowed to permit core service registrations. - -**Required action:** - -* The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. -* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. For example: - -```yaml -zowe: - network: - allowedDomains: - - "*.zowe.org" - - "ibm.com" - - "10.0.0.5" -``` - -* As a temporary mitigation while you adjust the allowlist, the Discovery Service honors the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`, which downgrades rejections to warnings instead of failing registration. - -### 2. Strict URL validation replaces `allowEncodedSlashes` - -The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and replaced by `apiml.security.enableStrictUrlValidation`. In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`, allowing encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. - -**Required action:** Remove any existing `apiml.service.allowEncodedSlashes` setting — it has no effect anymore. If routed requests need to carry encoded slashes or similar encoded characters in the URL path, explicitly disable strict validation: - -```yaml -components: - gateway: - apiml: - security: - enableStrictUrlValidation: false -``` - -Without this change, routed requests containing encoded slashes, backslashes, or semicolons — previously allowed by default — are now rejected by default. - -### 3. CORS: default allowed origin for routed services narrowed - -This only matters if you have `apiml.service.corsEnabled: true` (CORS handling in the Gateway is `false`/disabled by default). - -When CORS handling is enabled, for a southbound service that opts in via its own `apiml.corsEnabled` metadata but does not declare its own `apiml.corsAllowedOrigins`, the Gateway used to allow **any** origin (`Access-Control-Allow-Origin: *`). It now falls back to a configurable default, `apiml.service.corsDefaultAllowedOrigins`, whose effective default is the Gateway's own base URL (`https://:`) rather than "any origin." A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so it does not require action. - -**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an origin other than the Gateway's own hostname/port, set: - -```yaml -components: - gateway: - apiml: - service: - corsDefaultAllowedOrigins: https://my-external-client.example.com -``` - -### 4. Eureka discovery service credentials are now configurable - -**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` - -The credentials used to authenticate against the Discovery Service's `/eureka/**` endpoints when certificate validation is disabled were fixed to the literal values `eureka` / `password`. -These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. - -* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set. -* If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, a valid client certificate issued by a Zowe-trusted CA is used. - -**Required action:** If `zowe.verifyCertificates` is `DISABLED` (not recommended), set matching credentials on the Discovery Service and every service that registers with it: - -**Example:** - -```yaml -components: - discovery: - apiml: - discovery: - userid: eureka - password: password - gateway: - apiml: - discovery: - userid: eureka - password: password - # repeat for caching-service, api-catalog, zaas -``` - -### 5. Caching Service requires authentication when certificate validation is disabled - -**Note:** This change only applies to not-recommended setups with `verifyCertificates: DISABLED` - -The Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`) when certificate validation was disabled at Zowe level. -It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. -When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. - -**Required action:** Action is only needed if: - -* You have a custom client calling the Caching Service's REST API directly (not through Gateway/ZAAS) — it must now send matching Basic Auth credentials. - -```yaml -components: - caching-service: - apiml: - service: - http: - userId: eureka - password: password -``` From a04de2418cc533ed7a5b72ec32df99f0fe6202fe Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 12 Aug 2026 14:09:55 +0200 Subject: [PATCH 06/13] language refactoring for clarity Signed-off-by: Andrew Jandacek --- docs/whats-new/breaking-changes-v3.md | 13 ++++++++++--- docs/whats-new/release-notes/v3_6_0.md | 4 ++++ 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index 14dec4ff5a..ff65a8b800 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -64,13 +64,20 @@ zowe: - "10.0.0.5" ``` -* As a temporary mitigation while you adjust the allowlist, the Discovery Service honors the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`, which downgrades rejections to warnings instead of failing registration. +:::tip Temporary Mitigation: +If registrations begin to fail after the upgrade, you can temporarily downgrade these rejections to warnings by setting the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`. This setting allows services to register while you identify and configure the missing domains. +::: ### Strict URL validation replaces `allowEncodedSlashes` -The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and replaced by `apiml.security.enableStrictUrlValidation`. In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`, allowing encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. +The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and replaced by `apiml.security.enableStrictUrlValidation`. + +**Operational Impact:** +In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`. This default setting allowed encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this validation behavior: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. -**Required action:** Remove any existing `apiml.service.allowEncodedSlashes` setting — it has no effect anymore. If routed requests need to carry encoded slashes or similar encoded characters in the URL path, explicitly disable strict validation: +**Required Actions:** +1. Remove the deprecated `apiml.service.allowEncodedSlashes` property from your `zowe.yaml` (THis property will be ignored). +2. Opt-out (if needed). If you route traffic to APIs that require encoded slashes or semicolons in the URL path, you must explicitly disable strict validation for the Gateway: ```yaml components: diff --git a/docs/whats-new/release-notes/v3_6_0.md b/docs/whats-new/release-notes/v3_6_0.md index a5d0c6ea34..f682d72529 100644 --- a/docs/whats-new/release-notes/v3_6_0.md +++ b/docs/whats-new/release-notes/v3_6_0.md @@ -58,6 +58,10 @@ Zowe Version 2.3.0 contains the bug fixes that are described in the following to ### Zowe API Mediation Layer +:::info +Zowe 3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. For more information, see [Security updates in Zowe v3.6.0](../../whats-new/breaking-changes-v3.md#security-updates-in-zowe-v360). +::: + ### Zowe CLI #### Zowe CLI (Core) From 0218e9d611d53622346ae586f159fe8b28e084b8 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 12 Aug 2026 17:08:32 +0200 Subject: [PATCH 07/13] language refactor Signed-off-by: Andrew Jandacek --- docs/whats-new/breaking-changes-v3.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index ff65a8b800..dff59d2cb5 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -41,17 +41,31 @@ New properties introduced with strict default settings. An installation that fun #### Discovery Service enforces domain allowlist for service registration -In Zowe versions up to 3.5 the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. Discovery Service now strictly validates all URLs provided by registering services, including hostname, IP address, home page URL, health-check URL, status page URL, and any `apiml.*.swaggerUrl` / `documentationUrl` / `graphqlUrl` / `externalUrl` / `corsAllowedOrigins` metadata against an allowlist of domains. +In Zowe versions up to v3.5, the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. The Discovery Service now strictly validates all URLs provided by registering services against an allowlist of domains, including: +* hostname +* IP address +* home page URL +* health-check URL +* status page URL +* `apiml.*.swaggerUrl` +* `documentationUrl` +* `graphqlUrl` +* `externalUrl` +* `corsAllowedOrigins` **Operational Impact:** By default, if a service attempts to register using a domain or IP address that is not on the allowlist, the registration is rejected entirely. +**Required action:** The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. -A small set of Zowe/IBM documentation domains (`www.ibm.com`, `zowe.github.io`, `www.zowe.org`, `techdocs.broadcom.com`) is always allowed to permit core service registrations. - -**Required action:** -* The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. -* Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. +The following set of Zowe/IBM documentation domains is always allowed to permit core service registrations: +* (`www.ibm.com` +* `zowe.github.io` +* `www.zowe.org` +* `techdocs.broadcom.com`) + +The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. +Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. **Example:** From 3b9873879caa7538c1b00892c45d1a5224daafa8 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 13 Aug 2026 13:37:50 +0200 Subject: [PATCH 08/13] language refactor Signed-off-by: Andrew Jandacek --- docs/whats-new/breaking-changes-v3.md | 54 ++++++++++++++------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index dff59d2cb5..3daca85707 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -23,25 +23,25 @@ Review this article for details about changes to various Zowe components that ar ### Important API ML updates in Zowe v3 -In previous versions of Zowe, the API Gateway directly contained the code for the Authentication and Authorization Service (ZAAS). In Zowe V3, ZAAS was architecturally decoupled into a standalone component with its own configuration, as it is the only API Mediation Layer (API ML) service that natively requires direct interaction with z/OS security services (such as z/OSMF and SAF). +Prior to Zowe v3, the API Gateway directly contained the code for the Authentication and Authorization Service (ZAAS). In Zowe v3, ZAAS was architecturally decoupled into a standalone component with its own configuration, as it is the only API ML service that natively requires direct interaction with z/OS security services (such as z/OSMF and SAF). -While ZAAS is now a standalone service, how ZAAS runs depends on your deployment configuration. In multi-service deployment, ZAAS runs as a physically independent microservice (a separate JVM process) on its own port. Starting with Zowe v3.4, the default and recommended single-service deployment mode bundles the standalone ZAAS component back into a single JVM process alongside the Gateway, Discovery Service, and API Catalog at runtime. +While ZAAS is now a standalone service, how ZAAS runs depends on your deployment configuration. In multi-service deployment, ZAAS runs as an independent microservice (a separate JVM process) on a port dedicated to ZAAS. Starting with Zowe v3.4, the default and recommended single-service deployment mode bundles the standalone ZAAS component into a single JVM process alongside the Gateway, Discovery Service, and API Catalog at runtime. ### Security updates in Zowe v3.6.0 -Zowe 3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. +Zowe v3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. -Configuration changes are in two key areas: +Configuration changes in Zowe v3.6.0 are in two key areas: * **Modified existing properties** -Configuration properties that existed in Zowe 3.5.0, but whose default value, source, or underlying behavior has changed. +Configuration properties that existed in Zowe v3.5.0, but whose default value, source, or underlying behavior has changed. * **Restrictive new properties** -New properties introduced with strict default settings. An installation that functioned correctly in Zowe 3.5.0 may require explicit configuration of these new properties to retain previous behaviors. +New properties introduced with strict default settings. An installation that functioned correctly in Zowe v3.5.0 may require explicit configuration of these new properties to retain previous behavior. #### Discovery Service enforces domain allowlist for service registration -In Zowe versions up to v3.5, the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. The Discovery Service now strictly validates all URLs provided by registering services against an allowlist of domains, including: +In Zowe versions up to v3.5.0, the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. The Discovery Service now strictly validates all URLs provided by registering services against an allowlist of domains, including: * hostname * IP address * home page URL @@ -59,12 +59,12 @@ By default, if a service attempts to register using a domain or IP address that **Required action:** The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. The following set of Zowe/IBM documentation domains is always allowed to permit core service registrations: -* (`www.ibm.com` +* `www.ibm.com` * `zowe.github.io` * `www.zowe.org` -* `techdocs.broadcom.com`) +* `techdocs.broadcom.com` -The allowlist will already contain your system's hostnames and no action is needed for Zowe's own services. +The allowlist will already contain your system's hostnames. No action is needed for Zowe's own services. Update `zowe.network.allowedDomains` with other domains and/or IP addresses the instance connects to. **Example:** @@ -78,7 +78,7 @@ zowe: - "10.0.0.5" ``` -:::tip Temporary Mitigation: +:::tip Temporary Mitigation: If registrations begin to fail after the upgrade, you can temporarily downgrade these rejections to warnings by setting the environment variable `ZWE_ONLY_WARN_ON_URL_NOT_ALLOWED=true`. This setting allows services to register while you identify and configure the missing domains. ::: @@ -90,7 +90,7 @@ The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`. This default setting allowed encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this validation behavior: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. **Required Actions:** -1. Remove the deprecated `apiml.service.allowEncodedSlashes` property from your `zowe.yaml` (THis property will be ignored). +1. Remove the deprecated `apiml.service.allowEncodedSlashes` property from your `zowe.yaml` (Th is property will be ignored). 2. Opt-out (if needed). If you route traffic to APIs that require encoded slashes or semicolons in the URL path, you must explicitly disable strict validation for the Gateway: ```yaml @@ -105,11 +105,11 @@ Without this change, routed requests containing encoded slashes, backslashes, or #### CORS: default allowed origin for routed services narrowed -This only matters if you have `apiml.service.corsEnabled: true` (CORS handling in the Gateway is `false`/disabled by default). +When CORS handling is enabled globally (`apiml.service.corsEnabled: true)`, southbound services can explicitly ask the Gateway to manage CORS on their behalf by setting their own `apiml.corsEnabled` metadata to `true`. For these services, if they opt in but fail to define a specific list of allowed origins (`apiml.corsAllowedOrigins`), the API Gateway no longer defaults to allowing any origin (`Access-Control-Allow-Origin: *`). Instead, the API Gateway falls back to a new property, `apiml.service.corsDefaultAllowedOrigins`. The default value is now the API Gateway's base URL (`https://:`). -When CORS handling is enabled, for a southbound service that opts in via its own `apiml.corsEnabled` metadata but does not declare its own `apiml.corsAllowedOrigins`, the Gateway used to allow **any** origin (`Access-Control-Allow-Origin: *`). It now falls back to a configurable default, `apiml.service.corsDefaultAllowedOrigins`, whose effective default is the Gateway's own base URL (`https://:`) rather than "any origin." A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so it does not require action. +A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so no action is required. -**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an origin other than the Gateway's own hostname/port, set: +**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an external origin (other than the Gateway's own hostname and port), you must explicitly allow the origin in your `zowe.yaml` file: ```yaml components: @@ -122,16 +122,18 @@ components: #### Eureka discovery service credentials are now configurable :::note -This change only applies to not-recommended setups with `verifyCertificates: DISABLED` +This change only applies to configurations where `verifyCertificates` is set to `DISABLED` (not recommended). ::: -The credentials used to authenticate against the Discovery Service's `/eureka/**` endpoints when certificate validation is disabled were fixed to the literal values `eureka` / `password`. -These are now sourced from `apiml.discovery.userid` / `apiml.discovery.password` on every API ML service. +**Operational Impact:** +When certificate validation is disabled, the credentials used to authenticate against the Discovery Service's /eureka/** endpoints are no longer hardcoded to the literal values `eureka` / `password` +These values are now sourced from `apiml.discovery.userid` and `apiml.discovery.password` on every API ML service. -* If `zowe.verifyCertificates: DISABLED`, they still default to `eureka` / `password` when not explicitly set. +* If `zowe.verifyCertificates` is `DISABLED`, the credentials still default to `eureka` / `password` when not explicitly set. * If `zowe.verifyCertificates` is `STRICT` (the default) or `NONSTRICT`, a valid client certificate issued by a Zowe-trusted CA is used. -**Required action:** If `zowe.verifyCertificates` is `DISABLED` (not recommended), set matching credentials on the Discovery Service and every service that registers with it: +**Required action:** +If `zowe.verifyCertificates` is `DISABLED` (not recommended), set matching credentials on the Discovery Service and every service that registers with the Discovery Service in your `zowe.yaml`: **Example:** @@ -153,16 +155,16 @@ components: #### Caching Service requires authentication when certificate validation is disabled :::note -This change only applies to not-recommended setups with `verifyCertificates: DISABLED` +This change only applies to configurations where `verifyCertificates` is set to `DISABLED` (not recommended). ::: -The Caching Service's REST API allowed **any unauthenticated caller** (`permitAll()`) when certificate validation was disabled at Zowe level. -It now requires HTTP Basic authentication via `apiml.service.http.userId` / `apiml.service.http.password` in that mode; requests without valid matching credentials are rejected. -When certificate validation is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. +**Operational Impact:** +The Caching Service's REST API no longer permits unauthenticated callers (`permitAll()`) when Zowe-level certificate validation is disabled. In this mode, the service now requires HTTP Basic authentication via the `apiml.service.http.userId` and `apiml.service.http.password` propserties. Requests without valid matching credentials are rejected. -**Required action:** Action is only needed if: +When certificate validation configuration is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. -* You have a custom client calling the Caching Service's REST API directly (not through Gateway/ZAAS) — it must now send matching Basic Auth credentials. +**Required action:** +Action is only required if you have a custom client that calls the Caching Service's REST API directly (bypassing the API Gateway or ZAAS). The client must now send matching HTTP Basic Authentication credentials. Ensure these credentials are configured in your `zowe.yaml` file: ```yaml components: From 16dbb2d306b9eaa46f4cf4d38abbb2cff87e33aa Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 13 Aug 2026 13:51:45 +0200 Subject: [PATCH 09/13] fix header levels Signed-off-by: Andrew Jandacek --- docs/whats-new/breaking-changes-v3.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index 3daca85707..fc44e5b077 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -27,7 +27,7 @@ Prior to Zowe v3, the API Gateway directly contained the code for the Authentica While ZAAS is now a standalone service, how ZAAS runs depends on your deployment configuration. In multi-service deployment, ZAAS runs as an independent microservice (a separate JVM process) on a port dedicated to ZAAS. Starting with Zowe v3.4, the default and recommended single-service deployment mode bundles the standalone ZAAS component into a single JVM process alongside the Gateway, Discovery Service, and API Catalog at runtime. -### Security updates in Zowe v3.6.0 +## Security updates in Zowe v3.6.0 Zowe v3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. @@ -39,7 +39,7 @@ Configuration properties that existed in Zowe v3.5.0, but whose default value, s * **Restrictive new properties** New properties introduced with strict default settings. An installation that functioned correctly in Zowe v3.5.0 may require explicit configuration of these new properties to retain previous behavior. -#### Discovery Service enforces domain allowlist for service registration +### Discovery Service enforces domain allowlist for service registration In Zowe versions up to v3.5.0, the Discovery Service accepted any service registration without validating the hostnames or URLs the service advertised. The Discovery Service now strictly validates all URLs provided by registering services against an allowlist of domains, including: * hostname @@ -103,13 +103,15 @@ components: Without this change, routed requests containing encoded slashes, backslashes, or semicolons — previously allowed by default — are now rejected by default. -#### CORS: default allowed origin for routed services narrowed +### CORS: default allowed origin for routed services narrowed -When CORS handling is enabled globally (`apiml.service.corsEnabled: true)`, southbound services can explicitly ask the Gateway to manage CORS on their behalf by setting their own `apiml.corsEnabled` metadata to `true`. For these services, if they opt in but fail to define a specific list of allowed origins (`apiml.corsAllowedOrigins`), the API Gateway no longer defaults to allowing any origin (`Access-Control-Allow-Origin: *`). Instead, the API Gateway falls back to a new property, `apiml.service.corsDefaultAllowedOrigins`. The default value is now the API Gateway's base URL (`https://:`). +**Operational Impact:** +When CORS handling is enabled globally (`apiml.service.corsEnabled: true)`, southbound services can explicitly ask the Gateway to manage CORS on their behalf by setting their own `apiml.corsEnabled` metadata to `true`. For services that enable this Gateway-managed CORS but fail to define a specific list of allowed origins (`apiml.corsAllowedOrigins)`, the API Gateway no longer defaults to allowing any origin (`Access-Control-Allow-Origin: *`). Instead, the API Gateway falls back to a new property: `apiml.service.corsDefaultAllowedOrigins`. The default value is now the API Gateway's base URL (`https://:`). -A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but its effective default (`*`) matches previous behavior, so no action is required. +A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but the effective default (`*`) matches previous behavior, so no action is required. -**Required action:** If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an external origin (other than the Gateway's own hostname and port), you must explicitly allow the origin in your `zowe.yaml` file: +**Required action:** +If `apiml.service.corsEnabled: true` and your browser-based clients call routed services from an external origin (other than the Gateway's own hostname and port), you must explicitly allow the origin in your `zowe.yaml` file: ```yaml components: @@ -119,7 +121,7 @@ components: corsDefaultAllowedOrigins: https://my-external-client.example.com ``` -#### Eureka discovery service credentials are now configurable +### Eureka Discovery Service credentials are now configurable :::note This change only applies to configurations where `verifyCertificates` is set to `DISABLED` (not recommended). @@ -152,14 +154,14 @@ components: # repeat for caching-service, api-catalog, zaas ``` -#### Caching Service requires authentication when certificate validation is disabled +### Caching Service requires authentication when certificate validation is disabled :::note This change only applies to configurations where `verifyCertificates` is set to `DISABLED` (not recommended). ::: -**Operational Impact:** -The Caching Service's REST API no longer permits unauthenticated callers (`permitAll()`) when Zowe-level certificate validation is disabled. In this mode, the service now requires HTTP Basic authentication via the `apiml.service.http.userId` and `apiml.service.http.password` propserties. Requests without valid matching credentials are rejected. +**Operational Impact:** +The Caching Service's REST API no longer permits unauthenticated callers (`permitAll()`) when Zowe-level certificate validation is disabled. In this mode, the service now requires HTTP Basic authentication via the `apiml.service.http.userId` and `apiml.service.http.password` properties. Requests without valid matching credentials are rejected. When certificate validation configuration is `STRICT` or `NONSTRICT`, the Caching Service still uses X.509 authentication and is unaffected. From a1bd350642e9f36179f5857434c9e04fd88ffa1a Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 13 Aug 2026 13:54:28 +0200 Subject: [PATCH 10/13] minor fix Signed-off-by: Andrew Jandacek --- docs/whats-new/release-notes/v3_6_0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/whats-new/release-notes/v3_6_0.md b/docs/whats-new/release-notes/v3_6_0.md index f682d72529..678c999c3a 100644 --- a/docs/whats-new/release-notes/v3_6_0.md +++ b/docs/whats-new/release-notes/v3_6_0.md @@ -59,7 +59,7 @@ Zowe Version 2.3.0 contains the bug fixes that are described in the following to ### Zowe API Mediation Layer :::info -Zowe 3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. For more information, see [Security updates in Zowe v3.6.0](../../whats-new/breaking-changes-v3.md#security-updates-in-zowe-v360). +Zowe v3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. For more information, see [Security updates in Zowe v3.6.0](../../whats-new/breaking-changes-v3.md#security-updates-in-zowe-v360). ::: ### Zowe CLI From 2bc9ac884164b9cba270e6d0ba603af2570ce99f Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 13 Aug 2026 14:13:58 +0200 Subject: [PATCH 11/13] fix formatting Signed-off-by: Andrew Jandacek --- docs/whats-new/breaking-changes-v3.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index fc44e5b077..b6f4b8fb72 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -57,7 +57,7 @@ In Zowe versions up to v3.5.0, the Discovery Service accepted any service regist By default, if a service attempts to register using a domain or IP address that is not on the allowlist, the registration is rejected entirely. **Required action:** -The allowlist can be customized via `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. +The allowlist can be customized via the `zowe.network.allowedDomains` property. Items of this array should be enclosed in double quotes (`"`) to allow wildcards. If no wildcard is used, strict matching is assumed. The following set of Zowe/IBM documentation domains is always allowed to permit core service registrations: * `www.ibm.com` * `zowe.github.io` @@ -90,7 +90,7 @@ The Gateway's `apiml.service.allowEncodedSlashes` property has been removed and In Zowe versions up to 3.5, `allowEncodedSlashes` defaulted to `true`. This default setting allowed encoded characters (such as `%2F`) to pass through routed request URLs unvalidated. The new property inverts this validation behavior: when `enableStrictUrlValidation` is `true` (the new default), the Gateway strictly validates request URLs and rejects encoded slashes, backslashes, and semicolons in routed traffic. Gateway-internal endpoints are always validated strictly regardless of this setting. **Required Actions:** -1. Remove the deprecated `apiml.service.allowEncodedSlashes` property from your `zowe.yaml` (Th is property will be ignored). +1. Remove the deprecated `apiml.service.allowEncodedSlashes` property from your `zowe.yaml` (This property will be ignored). 2. Opt-out (if needed). If you route traffic to APIs that require encoded slashes or semicolons in the URL path, you must explicitly disable strict validation for the Gateway: ```yaml @@ -101,12 +101,12 @@ components: enableStrictUrlValidation: false ``` -Without this change, routed requests containing encoded slashes, backslashes, or semicolons — previously allowed by default — are now rejected by default. +Without this change, routed requests containing encoded slashes, backslashes, or semicolons, which were previously allowed by default, are now rejected by default. ### CORS: default allowed origin for routed services narrowed **Operational Impact:** -When CORS handling is enabled globally (`apiml.service.corsEnabled: true)`, southbound services can explicitly ask the Gateway to manage CORS on their behalf by setting their own `apiml.corsEnabled` metadata to `true`. For services that enable this Gateway-managed CORS but fail to define a specific list of allowed origins (`apiml.corsAllowedOrigins)`, the API Gateway no longer defaults to allowing any origin (`Access-Control-Allow-Origin: *`). Instead, the API Gateway falls back to a new property: `apiml.service.corsDefaultAllowedOrigins`. The default value is now the API Gateway's base URL (`https://:`). +When CORS handling is enabled globally (`apiml.service.corsEnabled: true`), southbound services can explicitly ask the Gateway to manage CORS on their behalf by setting their own `apiml.corsEnabled` metadata to `true`. For services that enable this Gateway-managed CORS but fail to define a specific list of allowed origins (`apiml.corsAllowedOrigins`), the API Gateway no longer defaults to allowing any origin (`Access-Control-Allow-Origin: *`). Instead, the API Gateway falls back to a new property: `apiml.service.corsDefaultAllowedOrigins`. The default value is now the API Gateway's base URL (`https://:`). A companion property, `apiml.service.corsDefaultAllowedHeaders`, was also added but the effective default (`*`) matches previous behavior, so no action is required. @@ -128,7 +128,7 @@ This change only applies to configurations where `verifyCertificates` is set to ::: **Operational Impact:** -When certificate validation is disabled, the credentials used to authenticate against the Discovery Service's /eureka/** endpoints are no longer hardcoded to the literal values `eureka` / `password` +When certificate validation is disabled, the credentials used to authenticate against the Discovery Service's `/eureka/**` endpoints are no longer hardcoded to the literal values `eureka` / `password` These values are now sourced from `apiml.discovery.userid` and `apiml.discovery.password` on every API ML service. * If `zowe.verifyCertificates` is `DISABLED`, the credentials still default to `eureka` / `password` when not explicitly set. From 6ef24e62adfefc641166e6f435d1bbcc2093c8e9 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 17 Aug 2026 10:41:12 +0200 Subject: [PATCH 12/13] add v3_6_0 to sidebar Signed-off-by: Andrew Jandacek --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index ed5f52ce4b..0220744a8a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -9,6 +9,7 @@ module.exports = { link: { type: "doc", id: "whats-new/release-notes/release-notes-overview" }, collapsed: false, items: [ + "whats-new/release-notes/v3_6_0", "whats-new/release-notes/v3_5_0", "whats-new/release-notes/v3_4_1", "whats-new/release-notes/v3_4_0", From 19bdf2e55d96e9d7663c731c3bc7defc4c5811d9 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 18 Aug 2026 10:19:03 +0200 Subject: [PATCH 13/13] relocate breaking changes admonition Signed-off-by: Andrew Jandacek --- docs/whats-new/release-notes/v3_6_0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/whats-new/release-notes/v3_6_0.md b/docs/whats-new/release-notes/v3_6_0.md index 678c999c3a..d5307a735b 100644 --- a/docs/whats-new/release-notes/v3_6_0.md +++ b/docs/whats-new/release-notes/v3_6_0.md @@ -16,6 +16,10 @@ Zowe Version 2.3.0 contains the enhancements that are described in the following ### Zowe API Mediation Layer +:::info API ML Breaking Changes in v3.6.0 +Zowe v3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. For more information, see [Security updates in Zowe v3.6.0](../../whats-new/breaking-changes-v3.md#security-updates-in-zowe-v360). +::: + ### Zowe CLI #### Zowe CLI (Core) @@ -58,10 +62,6 @@ Zowe Version 2.3.0 contains the bug fixes that are described in the following to ### Zowe API Mediation Layer -:::info -Zowe v3.6.0 introduces several updates to API ML to strengthen security defaults, improve network validation, and tighten component authentication. These enhancements prioritize a secure-by-default posture which include breaking changes that may require updates to your `zowe.yaml` configuration to avoid disruptions during the upgrade process. For more information, see [Security updates in Zowe v3.6.0](../../whats-new/breaking-changes-v3.md#security-updates-in-zowe-v360). -::: - ### Zowe CLI #### Zowe CLI (Core)