Merge branch 'master' into patch-3

.github/workflows/report-least-recent-modified-files.yml

@@ -0,0 +1,25 @@
+on:
+  schedule:
+    # Run at 1AM every saturday
+    - cron: '0 1 * * 6'
+  workflow_dispatch:
+    inputs:
+      quantity:
+        description: 'How many files to show'
+        required: false
+        default: '500'
+        type: string
+jobs:
+  report_least_recent_modified_files:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout primary branch'
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: '0'
+      - name: Report and upload
+        run: "cd docs; for file in $(find . -type f); do echo $(git log --pretty=format:%ai -n 1 --date=raw -w --follow -- $file) $file; done | sort > ../least-recent-files.txt"
+      - uses: actions/upload-artifact@v3
+        with:
+          name: least-recent-files.txt
+          path: ./least-recent-files.txt

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

@@ -63,7 +63,9 @@ To integrate login, call one of the following methods for login in the `ZaasClie
 
 These methods return the JWT token as a String. This token can then be used to authenticate the user in subsequent APIs.
 
-**Note:** Both methods automatically use the truststore file to add a security layer, which requires configuration in the `ConfigProperties` class.
+:::note
+Both methods automatically use the truststore file to add a security layer, which requires configuration in the `ConfigProperties` class.
+:::
 
 ### Validate and get details from the token (`query`)
 
@@ -109,7 +111,9 @@ This method has an added layer of security, whereby you do not have to provide a
 
 In return, this method provides a valid pass ticket as a String to the authorized user.
 
-**Tip:** For additional information about PassTickets in API ML see [Enabling single sign on for extending services via PassTicket configuration](../../user-guide/api-mediation/configuration-extender-passtickets).
+:::tip
+For additional information about PassTickets in API ML see [Enabling single sign on for extending services via PassTicket configuration](../../user-guide/api-mediation/configuration-extender-passtickets.md).
+:::
 
 ## Getting Started (Step by Step Instructions)
 
@@ -120,7 +124,7 @@ To use this library, use the procedure described in this section.
 1. Add `zaas-client` as a dependency in your project.  
 You will need to specify the version of the `zaas-client` you want. `zaas-client` versioning following the semantic versioning format of `major.minor.patch`. For example, `1.22.0`.
 
-    Gradle:
+    **Gradle:**
 
       1. Create a `gradle.properties` file in the root of your project if one does not already exist.
 
@@ -151,7 +155,7 @@ You will need to specify the version of the `zaas-client` you want. `zaas-client
         }
         ```
 
-    Maven:
+    **Maven:**
 
       1. Add the following _XML_ tags within the newly created `pom.xml` file:
 

docs/getting-started/zowe-security-authentication.md

@@ -12,7 +12,7 @@ The API Mediation Layer provides multiple methods which clients can use to authe
 
 When the user successfully authenticates with the API ML, the client receives a JWT token in exchange. This token can be used by the client to access REST services behind the API ML Gateway and also for subsequent user authentication. The access JWT Token is signed with the private key that is configured in the Zowe Identity Provider's certificate store, regardless of whether the token is in a keystore or keyring.
 
-To utilize [Single-Sign-On (SSO)](../user-guide/systemrequirements-zos#single-sign-on-sso), the Zowe API ML client needs to provide an access token to API services in the form of the cookie `apimlAuthenticationToken`, or in the `Authorization: Bearer` HTTP header as described in [this authenticated request example](https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-sample-spring/docs/api-client-authentication.md#authenticated-request).
+To utilize [Single-Sign-On (SSO)](../user-guide/api-mediation-sso.md), the Zowe API ML client needs to provide an access token to API services in the form of the cookie `apimlAuthenticationToken`, or in the `Authorization: Bearer` HTTP header as described in [this authenticated request example](https://github.com/zowe/sample-spring-boot-api-service/blob/master/zowe-rest-api-sample-spring/docs/api-client-authentication.md#authenticated-request).
 
 ## Authentication with client certificates
 
@@ -22,20 +22,20 @@ For more information, see the [Authentication for API ML services documentation]
 
 ## Authentication with Personal Access Token (PAT)
 
-A Personal Access Token (PAT) is a specific scoped JWT with a configurable validity duration. The PAT authentication method is an alternative to using a client certificate for authentication. It is disabled by default. To enable this functionality, see [Enabling single sign on for clients via personal access token configuration](../user-guide/api-mediation/configuration-personal-access-token).
+A Personal Access Token (PAT) is a specific scoped JWT with a configurable validity duration. The PAT authentication method is an alternative to using a client certificate for authentication. It is disabled by default. To enable this functionality, see [Enabling single sign on for clients via personal access token configuration](../user-guide/api-mediation/configuration-personal-access-token.md).
 
 **Benefits of PAT**
 
 - Long-lived. The maximum validity is 90 days.
 - Scoped. Users are required to provide a scope. It is only valid for the specified services.
 - Secure. If a security breech is suspected, the security administrator can invalidate all the tokens based on criteria as established by rules.
 
-For more information about PAT, see [Authenticating with a Personal Access Token documentation](../user-guide/api-mediation/authenticating-with-personal-access-token).
+For more information about PAT, see [Authenticating with a Personal Access Token documentation](../user-guide/api-mediation/authenticating-with-personal-access-token.md).
 
 ## Authentication with SAF Identity Tokens
 The SAF Authentication Provider allows the API Gateway to authenticate the user directly with the z/OS SAF provider that is installed on the system.
 
-For more information about configuring the token, see [Configure signed SAF Identity tokens (IDT)](../user-guide/configure-zos-system/#configure-signed-saf-identity-tokens-idt).
+For more information about configuring the token, see [Configure signed SAF Identity tokens (IDT)](../user-guide/configure-zos-system.md#configure-signed-saf-identity-tokens-idt).
 
 ## Multi-factor authentication (MFA)
 

docs/user-guide/api-mediation/api-mediation-personal-access-token.md

@@ -0,0 +1,3 @@
+# Personal Access Token
+
+The Personal access token documentation has been moved to: [Authenticating with a Personal Access Token](./authenticating-with-personal-access-token.md).

docs/user-guide/api-mediation/configuration-jwt.md

@@ -30,7 +30,7 @@ Authentication requests now utilize SAF as the authentication provider. API ML c
 
 Enable the `/gateway/api/v1/auth/refresh` endpoint to exchange a valid JWT token for a new token with a new expiration date. Call the endpoint with a valid JWT token and trusted client certificate. When using the z/OSMF authentication provider, enable API Mediation Layer for PassTicket generation and configure the z/OSMF APPLID. 
 
-For more information, see [Configure Passtickets](configuration-extender-passtickets.md)
+For more information, see [Configure Passtickets](configuration-extender-passtickets.md).
 
 1. Open the file `zowe.yaml`.
 2. Configure the following properties:
@@ -41,7 +41,22 @@ For more information, see [Configure Passtickets](configuration-extender-passtic
   * **components.gateway.apiml.security.zosmf.applid**  
   If you use z/OSMF as an authentication provider, provide a valid `APPLID`. The API ML generates a PassTicket for the specified `APPLID` and subsequently uses this PassTicket to authenticate to z/OSMF. The default value in the installation of z/OSMF is `IZUDFLT`.
 
-3. Restart Zowe.
+:::note
+
+Problems have been noted with the functionality of the property `components.gateway.apiml.security.allowtokenrefresh`. For more information about the bug, see [issue #3468 in the api-layer repo](https://github.com/zowe/api-layer/issues/3468). 
+
+We recommend you use the following workaround:
+
+1. Configure the following parameter in `environments`:
+
+```
+zowe:
+  environments:
+    APIML_SECURITY_ALLOWTOKENREFRESH: true 
+```
+:::
+
+2. Restart Zowe.
 
 ## Authorization
 

docs/user-guide/cli-configure-scs-on-headless-linux-os.md

@@ -2,12 +2,22 @@
 
 Perform the following configurations on headless and z/Linux operating systems.
 
+:::note
+
+For CI/CD pipelines we recommend using the credential management provided by the CI/CD tool (for example, Jenkins credentials or GitHub secrets) to store credentials and load them into environment variables in the pipeline. See [Using environment variables](../user-guide/cli-using-using-environment-variables.md#store-credentials-securely-in-cicd-pipelines) for more information.
+
+:::
+
 ## Headless Linux requirements
 
 - Ensure that you installed the Secure Credential Store requirements that are described in [System Requirements](../user-guide/systemrequirements-cli.md).
 - Unlock the Gnome keyring to allow you to load and store credentials on headless Linux operating systems. You can unlock the keyring manually or automatically.
 
-**Note:** On z/Linux operating systems, complete the steps in [Configuring z/Linux](#configuring-zlinux) before you continue.  
+:::note
+
+On z/Linux operating systems, complete the steps in [Configuring z/Linux](#configuring-zlinux) before you continue.
+
+:::
 
 ### Unlocking the keyring manually
 
@@ -18,13 +28,21 @@ export $(dbus-launch)
 gnome-keyring-daemon -r --unlock --components=secrets
 ```
 
-**Note:** The `gnome-keyring-daemon -r --unlock --components=secrets` prompts you to specify a password. Press `Ctrl+D` twice after you specify the password. 
+:::note
+
+The `gnome-keyring-daemon -r --unlock --components=secrets` prompts you to specify a password. Press `Ctrl+D` twice after you specify the password.
+
+:::
 
 ### Unlocking the keyring automatically
 
 When you are using SSH or TTY to log in to Linux, you can configure the Gnome keyring to unlock automatically when you log in.
 
-**Note:** The following steps were tested on CentOS, SUSE, and Ubuntu operating systems. The steps do not work on WSL (Windows Subsystem for Linux) because it bypasses TTY login. Results may vary on other Linux distributions. 
+:::note
+
+The following steps were tested on CentOS, SUSE, and Ubuntu operating systems. The steps do not work on WSL (Windows Subsystem for Linux) because it bypasses TTY login. Results may vary on other Linux distributions.
+
+:::
 
 **Follow these steps:**
 
@@ -78,7 +96,11 @@ The following steps describe how to install and build the credential store binar
     - libsecret-devel (sometimes available as libsecret-1-dev)
     - Python 3.6 or later
 
-    **Note:** If you are installing the Linux packages on a z/Linux system, the system where you are configuring SCS might require Internet access. When a site hosts its own package repositories, the repositories might not contain all of the packages that are required to configure the SCS. In this scenario, the z/Linux system requires Internet access to install the required packages.
+    :::note
+    
+    If you are installing the Linux packages on a z/Linux system, the system where you are configuring SCS might require Internet access. When a site hosts its own package repositories, the repositories might not contain all of the packages that are required to configure the SCS. In this scenario, the z/Linux system requires Internet access to install the required packages.
+
+    :::
 
 2. If you are configuring SCS on a Ubuntu z/Linux operating system, no further action is required. You can now install Zowe CLI. For all other platforms (RHEL), continue to the next step.
 

docs/user-guide/cli-using-integrating-apiml.md

@@ -2,7 +2,11 @@
 
 Zowe API Mediation Layer (ML) provides a secure single point of access to a defined set of mainframe services. The layer provides API management features such as high-availability, consistent security, and a single sign-on (SSO) and multi-factor authentication (MFA) experience.
 
-Use tokens to access services through API ML without reauthenticating every time you issue a command. Tokens allow for secure interaction between the client and server. When you issue commands to API ML, the layer routes requests to an appropriate API instance based on system load and available API instances.
+You can use tokens or client certificates to integrate with API ML.
+
+Tokens allow you to access services through API ML without reauthenticating every time you issue a command. Tokens allow for secure interaction between the client and server. When you issue commands to API ML, the layer routes requests to an appropriate API instance based on system load and available API instances.
+
+Some  users prefer to use certificates to access API ML. This can be the case in sites that use credentials such as passwords and multifactor authentication, which might be valid only for a short period of time. Certificates can be valid for much longer.
 
 ## How token management works
 
@@ -161,5 +165,32 @@ To perform SSO for the first set of services, log in to API ML and supply the `-
 
 To access the service that is *not* SSO-enabled, explicitly provide your username and password when you issue commands. Using the `--base-path` option ensures that the request is routed to API ML, but the username and password that you provide overrides the credentials in your base profile. This lets you sign in to the individual service.
 
+[def]: #specifying-a-base-path-with-zowe-v2-profiles
+
+## Using client certificates to authenticate to API ML
 
-[def]: #specifying-a-base-path-with-zowe-v2-profiles
+To use a client certificate to generate an API ML token, open a command line window and issue the following command:
+
+    ```
+    zowe auth login apiml --host <APIML Host> --port <APIML Port> --cert-file <PEM Public Certificate Path> --cert-key-file <PEM Private Certificate Path>
+    ```
+    - `<APIML Host>`
+    
+        Specifies the API ML host.
+    - `<APIML Port>`
+        
+        Specifies the API ML port.
+    - `<PEM Public Certificate Path>`
+    
+        Specifies the path for the PEM public certificate.
+    - `<PEM Private Certificate Path>`
+    
+        Specifies the path to the PEM private certificate.
+
+Zowe CLI procures a security token from the API ML and adds that token to the base profile in the applicable configuration file.
+
+:::note
+
+If you have multiple types of configuration files and base profiles, see [How configuration files and profiles work together](../../user-guide/cli-using-understand-profiles-configs.md#how-configuration-files-and-profiles-work-together) to learn which configuration and profile would be used to store the API ML token.
+
+:::

docs/user-guide/cli-using-using-environment-variables.md

@@ -17,3 +17,40 @@ Consider assigning a variable in the scenarios outlined in the following table.
 | Store a commonly used value. | Specify your mainframe username as an environment variable. | Issue commands without the `--user` option, and Zowe CLI automatically uses the value defined in the environment variable. |
 | Override a value in existing profiles. | Override a value previously defined in multiple profiles. Specify the new value as a variable to override the value in profiles. | Avoid recreating each profile. |
 | Secure credentials in an automation server or container | Set environment variables for use in scripts that run in your CI/CD pipeline. You can also define sensitive information in the Jenkins secure credential store. | Hide passwords and other sensitive information from plaintext in logs. |
+
+## Store credentials securely in CI/CD pipelines
+
+You can use environment variables when running CI/CD pipelines to load credentials that are securely stored.
+
+To do so, use the `ZOWE_OPT_` prefix to turn a Zowe CLI command option into the proper format for a Zowe CLI environment variable. For instructions, see [Formatting environment variables](../user-guide/cli-using-formatting-environment-variables.md).
+
+The environment variables to use environment variables for a username and password are `ZOWE_OPT_USER` and `ZOWE_OPT_PASSWORD`.
+
+Include the username and password environment variables in CI/CD pipelines that run Zowe CLI, as in the following example Jenkinsfile that uses the Jenkins credential store:
+
+```
+pipeline {
+    agent {
+        // Define agent details here
+    }
+    environment {
+        ZOWE_OPT_USER = credentials('jenkins-lpar1-zosmf-user')
+        ZOWE_OPT_PASSWORD = credentials('jenkins-lpar1-zosmf-password')
+
+    }
+    stages {
+        stage('Run Zowe CLI') {
+            steps {
+                sh "zowe jobs list jobs"
+            }
+        }
+        stage('Example stage 2') {
+            steps {
+                //
+            }
+        }
+    }
+}
+```
+
+For more information on Jenkins credential storage, see [Using credentials](https://www.jenkins.io/doc/book/using/using-credentials/) and Using a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#for-secret-text-usernames-and-passwords-and-secret-files).

docs/user-guide/configure-xmem-server.md

@@ -125,7 +125,7 @@ For example, the sample JCL below shows `ZWESISTC` where the APF-authorized PDSE
 
 Because the ZIS server makes z/OS security calls it restrits which clients are able to use it services, by requiring them to have `READ` access to a security profile `ZWES.IS` in the `FACILITY` class.  
 
-The Zowe launcher started task `ZWESLSTC` needs to be able to access the ZIS server, which requires that the user ID `ZWESVUSR` has access to `ZWES.IS`.  The steps to do this are desribed in [Configure the cross memory server for SAF](configure-zos-system.md#configure-the-cross-memory-server-for-saf).  
+The Zowe launcher started task `ZWESLSTC` needs to be able to access the ZIS server, which requires that the user ID `ZWESVUSR` has access to `ZWES.IS`.  The steps to do this are described in [Configure the cross memory server for SAF](configure-zos-system.md#configure-the-cross-memory-server-for-saf).  
 
 ## Zowe auxiliary service
 

docs/user-guide/configure-zos-system.md

@@ -123,7 +123,7 @@ Define or check the following configurations depending on whether ICSF is alread
         (repeat for user-acids IKED, NSSD, and Policy Agent)
 
 
-:::note Notes:
+:::note Notes
 - Determine whether you want SAF authorization checks against `CSFSERV` and set `CSF.CSFSERV.AUTH.CSFRNG.DISABLE` accordingly.
 - Refer to the [z/OS 2.3.0 z/OS Cryptographic Services ICSF System Programmer's Guide: Installation, initialization, and customization](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.csfb200/iandi.htm).
 - CCA and/or PKCS #11 coprocessor for random number generation.
@@ -481,7 +481,7 @@ To do this, issue the following commands that are also included in the `ZWESECUR
     TSS PERMIT(ZWESVUSR) IBMFAC(ZWES.IS) ACCESS(READ)
     ```
 
-:::note Notes:
+:::note Notes
 - The cross memory server treats "no decision" style SAF return codes as failures. If there is no covering profile for the `ZWES.IS` resource in the FACILITY class, the request will be denied.
 - Cross memory server clients other than Zowe might have additional SAF security requirements. For more information, see the documentation for the specific client.
 :::
@@ -693,7 +693,7 @@ Multi-factor authentication is provided by third-party products which Zowe is co
 - [CA Advanced Authentication Mainframe](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-advanced-authentication-mainframe/2-0.html)
 - [IBM Z Multi-Factor Authentication](https://www.ibm.com/products/ibm-multifactor-authentication-for-zos).
 
-:::notes**Notes**
+:::note Notes
 * To support the multi-factor authentication, it is necessary to apply z/OSMF APAR  [PH39582](https://www.ibm.com/support/pages/apar/PH39582). 
 
 * For information on using MFA in Zowe, see [Multi-Factor Authentication](mvd-configuration.md#multi-factor-authentication-configuration).