Merge branch 'master' into anax-v2.17-versionexplainer-docs

.github/workflows/link-checker.yml

@@ -14,25 +14,28 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Workaround for MD links without extensions being detected as broken
+      # TODO Pass Lychee option "--fallback-extensions md" once it's available
+      # See https://github.com/lycheeverse/lychee/pull/1422
       - name: Create symlinks
         run: |
           find docs -name "*.md" -type f | while read f; do
             ln -s $(basename $f) ${f%.*}
           done
 
       - name: Restore lychee cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: .lycheecache
           key: cache-lychee-${{ github.base_ref || github.ref_name }}
           restore-keys: cache-lychee-
+          save-always: true
 
       - name: Run lychee
         uses: lycheeverse/lychee-action@v1
         with:
-          args: "--accept 403,406,429 --cache --max-cache-age 1d --max-concurrency 2 --no-progress --timeout 60 --verbose 'docs/**/*.md'"
+          args: "--accept 403,406,429 --cache --include-fragments --max-cache-age 1d --max-concurrency 2 --no-progress --timeout 60 --verbose 'docs/**/*.md'"
           fail: true
           token: ${{ secrets.GITHUB_TOKEN }}

docs/appendix/zowe-glossary.md

@@ -24,10 +24,10 @@ Click here for descriptions of the various components that form the API Mediatio
 </summary>
 
 #### API Catalog  
-Displays API services that have been discovered by the [API Mediation Layer](#api-mediation-layer-api-ml).
+Displays API services that have been discovered by the [API Mediation Layer](#zowe-api-mediation-layer-api-ml).
 
 #### API Discovery Service  
-As the central repository of active services in the [API Mediation Layer](#api-mediation-layer-api-ml) ecosystem, the API Discovery Service continuously collects and aggregates service information to provide status updates. This enables the discoverability of services.
+As the central repository of active services in the [API Mediation Layer](#zowe-api-mediation-layer-api-ml) ecosystem, the API Discovery Service continuously collects and aggregates service information to provide status updates. This enables the discoverability of services.
 
 #### API Gateway    
 A proxy server that routes requests from clients on its northbound edge (such as web browsers or [Zowe CLI](#zowe-cli)) to servers on its southbound edge that are able to provide data to serve the request.
@@ -241,7 +241,7 @@ The Zowe installation for Zowe z/OS components that is distributed as an SMP/E p
 
 #### SMP/E with z/OSMF workflow
 
-A similar process as [SMP/E](zowe-glossary.md#smp/e), except done through the z/OSMF web interface as a Zowe SMP/E workflow. It is the third most common way to install Zowe.
+A similar process as [SMP/E](zowe-glossary.md#smpe), except done through the z/OSMF web interface as a Zowe SMP/E workflow. It is the third most common way to install Zowe.
 
 #### Started task (STC)
 
@@ -283,19 +283,19 @@ A user group on the system that [ZWESVUSR](#zwesiusr) and [ZWESIUSR](#zwesvusr)
 
 #### ZWESIUSR
 
-A started task ID used to run the PROCLIB ZWESISTC that launches the cross memory server (also known as ZIS). It must have a valid [OMVS](#omvs) segment. For more information, see [ZWESIUSR requirements](../user-guide/systemrequirements-zos.md/#zwesiusr).
+A started task ID used to run the PROCLIB ZWESISTC that launches the cross memory server (also known as ZIS). It must have a valid [OMVS](#omvs) segment. For more information, see [ZWESIUSR requirements](../user-guide/assign-security-permissions-to-users.md).
 
 #### ZWESVUSR
 
-A started task ID used to run the PROCLIB ZWESLSTC. The task starts a USS environment using BPXBATSL that executes server components such as the Application Framework, the API ML, and ZSS. To work with USS, the user ID ZWESVUSR must have a valid OMVS segment. For more information, see [ZWESVUSR requirements](../user-guide/systemrequirements-zos.md#zwesvusr).
+A started task ID used to run the PROCLIB ZWESLSTC. The task starts a USS environment using BPXBATSL that executes server components such as the Application Framework, the API ML, and ZSS. To work with USS, the user ID ZWESVUSR must have a valid OMVS segment. For more information, see [ZWESVUSR requirements](../user-guide/assign-security-permissions-to-users.md).
 
 ## Plug-ins and extensions
 
 ### API Mediation Layer
 
 #### API Catalog
 
-Displays API services that have been discovered by the [API Mediation Layer](#api-mediation-layer-api-ml).
+Displays API services that have been discovered by the [API Mediation Layer](#zowe-api-mediation-layer-api-ml).
 
 ### Zowe Application Framework
 
@@ -365,7 +365,7 @@ A collection of enablers which help to simplify the process of onboarding a REST
 
 #### Accessing the Desktop
 
-The [Zowe Desktop](#zowe-desktop) is accessed through the [API ML](#api-mediation-layer-api-ml). The Desktop URL uses the following format:
+The [Zowe Desktop](#zowe-desktop) is accessed through the [API ML](#zowe-api-mediation-layer-api-ml). The Desktop URL uses the following format:
 ```
 https://${zowe.externalDomains[0]}:{zowe.externalPort}/zlux/ui/v1
 ```

docs/appendix/zowe-yaml-configuration.md

@@ -37,9 +37,6 @@ zowe:
     - [Configure component zss](#configure-component-zss)
     - [Configure component jobs-api](#configure-component-jobs-api)
     - [Configure component files-api](#configure-component-files-api)
-    - [Configure component explorer-jes](#configure-component-explorer-jes)
-    - [Configure component explorer-mvs](#configure-component-explorer-mvs)
-    - [Configure component explorer-uss](#configure-component-explorer-uss)
     - [Configure external extension](#configure-external-extension)
 - [YAML configurations - haInstances](#yaml-configurations---hainstances)
 - [Auto-generated environment variables](#auto-generated-environment-variables)
@@ -409,7 +406,7 @@ In this section, `<component>` represents any Zowe components or extensions. For
 - **`components.<component>.enabled`**  
  Defines if you want to start this component in this Zowe instance. This allows you to control each component instead of a group.
 - **`components.<component>.certificate`**  
- You can customize a component to use different certificate from default values. This section follows same format defined in [YAML configurations - certificate](#yaml-configurations-certificate). If this is not customized, the component will use certificates defined in `zowe.certificate`.
+ You can customize a component to use different certificate from default values. This section follows same format defined in [YAML configurations - certificate](#yaml-configurations---certificate). If this is not customized, the component will use certificates defined in `zowe.certificate`.
 - **`components.<component>.launcher`**  
  Any component can have a launcher section which overrides the overall Zowe Launcher default defined in `zowe.launcher`.
 

docs/extend/extend-apiml/api-mediation-oidc-authentication.md

@@ -20,8 +20,8 @@ The OIDC feature is currently unavailable on ACF2 systems.
 - [Usage](#usage)
 - [Authentication flow](#authentication-flow)
 - [Prerequisites](#prerequisites)
-  - [OIDC provider](#oidc-provider)
-  - [ESM configuration](#esm-configuration)
+  - [OIDC provider](#oidc-provider-prerequisites)
+  - [ESM configuration](#esm-configuration-prerequisites)
 - [API ML configuration](#api-ml-oidc-configuration)
 - [Troubleshooting](#troubleshooting)
 
@@ -57,9 +57,9 @@ The following diagram illustrates the interactions between the participants of t
 Ensure that the following prerequisites are met:  
 
 - Users who require access to mainframe resources using OIDC authentication have a mainframe identity managed by SAF/ESM.
-- Client application users have their distributed identity managed by the OIDC provider. For details, see the section [OIDC provider](#oidc-provider) in this topic.
-- SAF/ESM is configured with mapping between the mainframe and distributed user identities. For details, see the section [ESM configuration](#esm-configuration) in this topic.
-- If you are using Zowe release 2.14 or a later release, ensure that the API ML Gateway is configured to use the internal mapper functionality. For information about enabling the API ML mapper, see [Enabling the internal API ML mapper](../../user-guide/authenticating-with-client-certificates.md#enabling-the-internal-api-ml-mapper).  Alternatively, enable ZSS in the Zowe installation, however using the internal mapper is the recommended method. ZSS is enabled by default.
+- Client application users have their distributed identity managed by the OIDC provider. For details, see the section [OIDC provider](#oidc-provider-prerequisites) in this topic.
+- SAF/ESM is configured with mapping between the mainframe and distributed user identities. For details, see the section [ESM configuration](#esm-configuration-prerequisites) in this topic.
+- If you are using Zowe release 2.14 or a later release, ensure that the API ML Gateway is configured to use the internal mapper functionality. For information about enabling the API ML mapper, see [Configure internal API ML mapper](../../user-guide/api-mediation/configuration-client-certificates.md#configure-internal-api-ml-mapper).  Alternatively, enable ZSS in the Zowe installation, however using the internal mapper is the recommended method. ZSS is enabled by default.
 
 ### OIDC provider prerequisites
 
@@ -165,7 +165,7 @@ For more information about the Zowe CLI Identity Federation Plug-in, see the [RE
    Specifies the global feature toggle. Set the value to `true` to enable OIDC authentication functionality.
 
 - **`components.gateway.apiml.security.oidc.registry`**  
-   Specifies the SAF registry used to group the identities recognized as having a OIDC identity mapping. The registry name is the string used during the creation of the mapping between the dustributed and mainframe user identities. For more information, see the [ESM configuration](#esm-configuration).
+   Specifies the SAF registry used to group the identities recognized as having a OIDC identity mapping. The registry name is the string used during the creation of the mapping between the dustributed and mainframe user identities. For more information, see the [ESM configuration](#esm-configuration-prerequisites).
 
 - **`components.gateway.apiml.security.oidc.jwks.uri`**  
    Specifies the URI obtained from the authorization server's metadata where the Gateway will query for the JWK used to sign and verify the access tokens.
@@ -180,7 +180,7 @@ For more information about the Zowe CLI Identity Federation Plug-in, see the [RE
 
 - **`apiml.security.oidc.identityMapperUrl`**  
   Defines the URL where the Gateway can query the mapping of the distributed user ID to the mainframe user ID.
-  This property informs the Gateway about the location of this API. ZSS is the default API provider in Zowe, but if you are using Zowe release 2.14 or a later version, we recommend you use the [API ML internal mapper](../../user-guide/authenticating-with-client-certificates.md#enabling-the-internal-api-ml-mapper). You can provide your own API to perform the mapping. In this case, it is necessary to customize this value.
+  This property informs the Gateway about the location of this API. ZSS is the default API provider in Zowe, but if you are using Zowe release 2.14 or a later version, we recommend you use the [API ML internal mapper](../../user-guide/api-mediation/configuration-client-certificates.md#configure-internal-api-ml-mapper). You can provide your own API to perform the mapping. In this case, it is necessary to customize this value.
 
     The following URL is the default value for Zowe and ZSS:
 

docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md

@@ -133,7 +133,7 @@ Issue the following command:
       pref("security.enterprise_roots.enabled", true);
       ```
 
-### Generate a keystore and truststore for a new service on z/OS	
+### Generate a keystore and truststore for a new service on z/OS
 
 You can generate a keystore and truststore for a new service using the local CA in the keystore directory.
 

docs/extend/extend-apiml/implement-new-saf-provider.md

@@ -94,7 +94,7 @@ Your application then properly recognizes the SAF IDT scheme and fills the `X-SA
 
 You can generate and verify an existing SAF token by using an implementation of the SAF IDT provider that utilizes a ZSS solution. 
 
-[SafRestAuthenticationService](https://github.com/zowe/api-layer/blob/master/gateway-service/src/main/java/org/zowe/apiml/gateway/security/service/saf/SafRestAuthenticationService.java) is an example of the SAF IDT provider implementation which uses REST as a method of communication.
+[SafRestAuthenticationService](https://github.com/zowe/api-layer/blob/v3.x.x/zaas-service/src/main/java/org/zowe/apiml/zaas/security/service/saf/SafRestAuthenticationService.java) is an example of the SAF IDT provider implementation which uses REST as a method of communication.
 
 To use `SafRestAuthenticationService` ensure that `ZWE_configs_apiml_security_saf_provider` is set to `rest`. (This is the default value)
 Set the following environment parameters in `zowe.yaml`:

docs/extend/extend-apiml/onboard-direct-eureka-call.md

@@ -276,7 +276,7 @@ This parameter specifies a service authentication scheme. The following schemes
 
     * **httpBasicPassTicket**  
     This value specifies that a service accepts PassTickets in the Authorization header of the HTTP requests using the basic authentication scheme. It is necessary to provide a service APPLID in the `apiml.authentication.applid` parameter.  
-    **Tip:** For more information, see [Enabling PassTicket creation for API Services that Accept PassTickets](authentication-for-apiml-services.md#authentication-with-passtickets).
+    **Tip:** For more information, see [Accepting PassTickets](api-medation-sso-integration-extenders.md#accepting-passtickets).
 
     * **zosmf**  
     This value specifies that a service accepts z/OSMF LTPA (Lightweight Third-Party Authentication). This scheme should only be used for a z/OSMF service used by the API Gateway Authentication Service, and other z/OSMF services that are using the same LTPA key.  

docs/extend/extend-apiml/onboard-micronaut-enabler.md

@@ -9,10 +9,6 @@ For more information about onboarding API services with the API ML, see the [Onb
 For Micronaut-related documentation, see the [Micronaut website](https://docs.micronaut.io/latest/guide/index#introduction).
 
 - [Set up your build automation system](#set-up-your-build-automation-system)
-  - [Specify the main class](#specify-the-main-class)
-  - [Define the output jar file](#define-the-output-jar-file)
-  - (Optional) [Create a shadow jar](#create-a-shadow-jar)
-  - [Start the application](#start-the-application)
 - [Configure the Micronaut application](#configure-the-micronaut-application)
   - [Add API ML configuration](#add-api-ml-configuration)
   - [Add Micronaut configuration](#add-micronaut-configuration)

docs/extend/extend-apiml/onboard-plain-java-enabler-external-configuration.md

@@ -6,7 +6,7 @@ This article describes the process of configuring a REST service to onboard with
 * [Configuring a REST service for API ML onboarding](#configuring-a-rest-service-for-api-ml-onboarding)
 * [Plain Java Enabler service onboarding](#plain-java-enabler-service-onboarding-api)
     * [Automatic initialization of the onboarding configuration by a single method call](#automatic-initialization-of-the-onboarding-configuration-by-a-single-method-call)
-* [Validating successful onboarding with the API Mediation Layer](#Validating-successful-onboarding-with-the-API-Mediation-Layer)
+* [Validating successful onboarding with the API Mediation Layer](#validating-successful-onboarding-with-the-api-mediation-layer)
 * [Loading YAML configuration files](#loading-yaml-configuration-files)
     * [Loading a single YAML configuration file](#loading-a-single-yaml-configuration-file)
     * [Loading and merging two YAML configuration files](#loading-and-merging-two-yaml-configuration-files)
@@ -130,7 +130,7 @@ After successfully loading a configuration file, the loading method `loadConfigu
 ### Loading a single YAML configuration file
 
 To build your configuration from multiple sources, load a single configuration file, and then 
-rewrite parameters as needed using values from another configuration source. See: [Loading and merging two YAML configuration files](#Loading-and-merging-two-YAML-configuration-files) described later in this article.   
+rewrite parameters as needed using values from another configuration source. See: [Loading and merging two YAML configuration files](#loading-and-merging-two-yaml-configuration-files) described later in this article.   
 
 Use the following method to load a single _YAML_ configuration file:
 

docs/extend/extend-apiml/onboard-plain-java-enabler.md

@@ -262,7 +262,6 @@ The onboarding configuration parameters are broken down into the following group
 - [SAF Keyring configuration](#saf-keyring-configuration)
 - [Eureka Discovery Service](#eureka-discovery-service)
 - [Custom Metadata](#custom-metadata)
-- [Connection Timeout](#connection-timeout)
 
 ### REST service identification
 

docs/extend/extend-apiml/onboard-spring-boot-enabler.md

@@ -33,7 +33,6 @@ The following steps outline the overall process to onboard a REST service with t
     * [API ML Onboarding Configuration Sample](#api-ml-onboarding-configuration-sample)
     * [SAF Keyring configuration](#saf-keyring-configuration)
     * [Custom Metadata](#custom-metadata)
-    * [Api Mediation Layer specific metadata](#api-mediation-layer-specific-metadata)
 
 4. [Registering and unregistering your service with API ML](#registering-and-unregistering-your-service-with-api-ml)
 

docs/extend/extend-apiml/onboard-static-definition.md

@@ -8,7 +8,7 @@ When developing a new service, it is not recommended to onboard a REST service u
 
 The following procedure outlines the steps to onboard an API service through the API Gateway in the API Mediation Layer without requiring code changes.
 
-* [Identify the API that you want to expose](#identify-the-api-that-you-want-to-expose)
+* [Identify the APIs that you want to expose](#identify-the-apis-that-you-want-to-expose)
 * [Define your service and API in YAML format](#define-your-service-and-api-in-yaml-format)
 * [Route your API](#route-your-api)
 * [Customize configuration parameters](#customize-configuration-parameters)

docs/extend/extend-apiml/zaas-client.md

@@ -12,11 +12,11 @@ This article contains the following topics:
 
 * [Pre-requisites](#pre-requisites)
 * [API Documentation](#api-documentation)
-    * [Obtain a JWT token (`login`)](#obtain-a-jwt-token---login--)
-    * [Validate and get details from the token (`query`)](#validate-and-get-details-from-the-token---query--)
-    * [Invalidate a JWT token (`logout`)](#invalidate-a-jwt-token---logout--)
-    * [Obtain a PassTicket (`passTicket`)](#obtain-a-passticket---passticket--)
-* [Getting Started (Step by Step Instructions)](#getting-started--step-by-step-instructions-)
+    * [Obtain a JWT token (`login`)](#obtain-a-jwt-token-login)
+    * [Validate and get details from the token (`query`)](#validate-and-get-details-from-the-token-query)
+    * [Invalidate a JWT token (`logout`)](#invalidate-a-jwt-token-logout)
+    * [Obtain a PassTicket (`passTicket`)](#obtain-a-passticket-passticket)
+* [Getting Started (Step by Step Instructions)](#getting-started-step-by-step-instructions)
 ## Pre-requisites
 
 - Java SDK version 1.8.

docs/extend/extend-apiml/zowe-api-mediation-layer-security-overview.md

@@ -8,7 +8,7 @@ Review this article to learn about topics which address security features in Zow
     - [Zowe API ML services](#zowe-api-ml-services)
     - [Zowe API ML TLS requirements](#zowe-api-ml-tls-requirements)
   - [Setting ciphers for API ML services](#setting-ciphers-for-api-ml-services)
-  - [JSON Web Token(JWT)](#json-web-tokenjwt)
+  - [JSON Web Token (JWT)](#json-web-token-jwt)
   - [z/OSMF JSON Web Tokens Support](#zosmf-json-web-tokens-support)
 
 ## How API ML transport security works

docs/extend/extend-desktop/mvd-apptoappcommunication.md

@@ -10,7 +10,8 @@ The constructs are: the Dispatcher, Actions, Recognizers, Registry, and the feat
 1. [Actions](#actions)
 1. [Recognizers](#recognizers)
 1. [Dispatcher](#dispatcher)
-1. [URI Parameters](#uri-parameters)
+1. [Registry](#registry)
+1. [Pulling it all together in an example](#pulling-it-all-together-in-an-example)
 
 ## Why use application-to-application communication?