Zowe 3.6.0 API ML changes

docs/whats-new/breaking-changes-v3.md

@@ -19,10 +19,164 @@ 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
+
+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 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 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 in Zowe v3.6.0 are in two key areas:
+
+* **Modified existing properties**  
+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 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.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
+* 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 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`
+* `www.zowe.org`
+* `techdocs.broadcom.com`
+
+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:**
+
+```yaml
+zowe:
+  network:
+    allowedDomains:
+      - "*.zowe.org"
+      - "ibm.com"
+      - "10.0.0.5"
+```
+
+:::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`. 
+
+**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 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:
+  gateway:
+    apiml:
+      security:
+        enableStrictUrlValidation: false
+```
+
+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://<apiml.service.hostname>:<apiml.service.port>`).
+
+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:
+
+```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 configurations where `verifyCertificates` is set to `DISABLED` (not recommended).
+:::
+
+**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` 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 the Discovery Service in your `zowe.yaml`:
+
+**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 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` 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.
+
+**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:
+  caching-service:
+    apiml:
+      service:
+        http:
+          userId: eureka
+          password: password
+```
 
 
 ## Application Framework

docs/whats-new/release-notes/v3_6_0.md

@@ -0,0 +1,101 @@
+# 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
+
+:::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)
+
+#### 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.

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",