diff --git a/docs/appendix/zowe-security-glossary.md b/docs/appendix/zowe-security-glossary.md
index d7335d8ce3..3cdc7aeb13 100644
--- a/docs/appendix/zowe-security-glossary.md
+++ b/docs/appendix/zowe-security-glossary.md
@@ -74,6 +74,7 @@ If you do not yet have certificates, Zowe can create self-signed certificates fo
- [Extended key usage](#extended-key-usage)
- [Hostname validity](#hostname-validity)
- [z/OSMF access](#zosmf-access)
+
### Extended key usage
Zowe server certificates must either not have the `Extended Key Usage` (EKU) attribute, or have both the `TLS Web Server Authentication (1.3.6.1.5.5.7.3.1)` and `TLS Web Client Authentication (1.3.6.1.5.5.7.3.2)` values present within.
@@ -88,29 +89,21 @@ The z/OSMF certificate is verified according to Zowe [Certificate verification s
## Certificate setup types
-Whether importing or letting Zowe generate certificates, the setup for Zowe certificate automation and the configuration to use an existing keystore and truststore depends upon the content format: file-based (`PKCS12`) or z/OS key ring-based.
+Zowe requires certificates in one of two formats: file-based (`PKCS12`) or z/OS key ring-based. If you are bringing your own previously defined certificates to Zowe, you can configure `zowe.certificate` with this information directly. Key rings are required for Zowe AT-TLS configurations. If you are not bringing your own certificates, [Zowe can assist](../user-guide/certificates-configuration-scenarios.md) with certificate generation.
- [File-based (PKCS12) certificate setup](#file-based-pkcs12-certificate-setup)
- [z/OS key ring-based certificate setup](#zos-key-ring-based-certificate-setup)
+
### File-based (PKCS12) certificate setup
Zowe is able to use PKCS12 certificates that are stored in USS. Zowe uses a `keystore` directory to contain its certificates primarily in PKCS12 (`.p12`, `.pfx`) file format, but also in PEM (`.pem`) format. The truststore is in the `truststore` directory that holds the public keys and CA chain of servers which Zowe communicates with (for example z/OSMF).
-### z/OS key ring-based certificate setup
-
-Zowe is able to work with certificates held in a **z/OS Key ring**.
+Generating PKCS12 certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md) Scenario 1 and Scenario 2.
+Configuring PKCS12 certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md).
-The JCL member `.SZWESAMP(ZWEKRING)` contains security commands to create a SAF keyring. By default, this key ring is named `ZoweKeyring`. You can use the security commands in this JCL member to generate a Zowe certificate authority (CA) and sign the server certificate with this CA. The JCL contains commands for all three z/OS security managers: RACF, TopSecret, and ACF2.
-
-There are two ways to configure and submit `ZWEKRING`:
-
-- Copy the JCL `ZWEKRING` member and customize its values.
-- Customize the `zowe.setup.certificate` section in `zowe.yaml` and use the `zwe init certificate` command.
-
- You can also use the `zwe init certificate` command to prepare a customized JCL member using `ZWEKRING` as a template.
+### z/OS key ring-based certificate setup
-A number of key ring scenarios are supported:
+Zowe is able to work with certificates held in a **z/OS key ring**.
-- Creation of a local certificate authority (CA) which is used to sign a locally generated certificate. Both the CA and the certificate are placed in the `ZoweKeyring`.
-- Import of an existing certificate already held in z/OS to the `ZoweKeyring` for use by Zowe.
-- Creation of a locally generated certificate and signed by an existing certificate authority. The certificate is placed in the key ring.
+Generating key rings with certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 3-5.
+Configuring key rings with certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md).
\ No newline at end of file
diff --git a/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md b/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md
index dd49398eca..c992d90c23 100644
--- a/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md
+++ b/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md
@@ -63,8 +63,8 @@ There are two ways to set up certificates on a z/OS machine:
- [Certificates in SAF keyring](#api-ml-saf-keyring)
For detailed instructions about how to set up certificates during installation, see the following articles:
-* [Use PKCS12 certificates](../../user-guide/use-certificates.md#use-pkcs12-certificates)
-* [Use JCERACFS certificates](../../user-guide/use-certificates.md#use-jceracfks-certificates) in a keyring
+* [Use PKCS12 certificates](../../user-guide/certificates-configuration-scenarios.md#scenario-overview)
+* [Use JCERACFS certificates](../../user-guide/certificates-configuration-scenarios.md#scenario-overview) in a keyring
Follow the procedure in the applicable section in this article during installation.
diff --git a/docs/getting-started/zowe-certificates-overview.md b/docs/getting-started/zowe-certificates-overview.md
index 3fd408941f..7788da1abe 100644
--- a/docs/getting-started/zowe-certificates-overview.md
+++ b/docs/getting-started/zowe-certificates-overview.md
@@ -39,8 +39,6 @@ X.509 Digital certificates are primarly used to implement the following function
Zowe uses digital certificates as a foundational element for both communication and for identity security.
Additionally, Zowe provides a client identity validation functionality based on the ownership of the provided x.509 client certificate and the mainframe security authentication mechanism.
-For more information about how Zowe leverages certificates, see [Zowe certificate usage](../user-guide/use-certificates.md).
-
To review the various Zowe certificate configuration options, see the [Zowe certificate configuration overview](../user-guide/configure-certificates.md).
## Public key infrastructure
diff --git a/docs/getting-started/zowe-security-overview.md b/docs/getting-started/zowe-security-overview.md
index 4818cbb7c1..38cd71d825 100644
--- a/docs/getting-started/zowe-security-overview.md
+++ b/docs/getting-started/zowe-security-overview.md
@@ -49,8 +49,7 @@ Review digital certificates terminology in the [Zowe security glossary](../appen
Zowe uses digital certificates to secure the communication channel between Zowe components as well as between Zowe clients and Zowe services. Digital client certificates can also be used to validate that the identity of a client-user (the service user) is known to the mainframe security facility.
**Next Steps:**
-- For more information about the mechanics of digital certificate, see [Using certificates](../user-guide/use-certificates.md).
-- To learn more about the various options for Zowe certificate configuration, see [Zowe certificate configuration overview](../user-guide/configure-certificates.md) under the _Use_ tab.
+- To learn more about the various options for Zowe certificate configuration, see [Zowe certificate configuration overview](../user-guide/configure-certificates.md).
## User Authentication
Zowe always authenticates the users accessing its interfaces and services.
@@ -82,8 +81,6 @@ For more information about the SAF resource check, see [Configuring SAF resource
## Additional resources
For more information about getting started with certificates including determining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources:
-- [Certificate configuration scenarios](../user-guide/certificate-configuration-scenarios.md)
-- [Generating a certificate](../user-guide/generate-certificates.md)
-- [Importing and configuring a certificate](../user-guide/import-certificates.md)
+- [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md)
- [Configuring certificates](../user-guide/configure-certificates.md)
diff --git a/docs/troubleshoot/known-issues-with-apiml.md b/docs/troubleshoot/known-issues-with-apiml.md
index 42b52525dd..96409d87bc 100644
--- a/docs/troubleshoot/known-issues-with-apiml.md
+++ b/docs/troubleshoot/known-issues-with-apiml.md
@@ -201,6 +201,6 @@ Request a new certificate that contains a valid z/OSMF host name in the subject
### Re-create the Zowe keystore
-Re-create the Zowe keystore by deleting it and re-creating it. For more information, see [Importing a file-based PKCS12 certificate](../user-guide/import-certificates.md#importing-an-existing-pkcs12-certificate). The Zowe keystore directory is the value of the `KEYSTORE_DIRECTORY` variable in the `zowe.yaml` file that is used to launch Zowe.
+Recreate the Zowe keystore by deleting it and recreating it. For more information, see [Scenario 2: Importing a file-based PKCS12 certificate](../user-guide/certificates-configuration-scenarios.md#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca). The Zowe keystore directory is the value of the `KEYSTORE_DIRECTORY` variable in the `zowe.yaml` file that is used to launch Zowe.
diff --git a/docs/user-guide/api-mediation/configuration-client-certificates.md b/docs/user-guide/api-mediation/configuration-client-certificates.md
index 98db77b030..1fa6a3a6b6 100644
--- a/docs/user-guide/api-mediation/configuration-client-certificates.md
+++ b/docs/user-guide/api-mediation/configuration-client-certificates.md
@@ -105,7 +105,7 @@ The following steps are only required if the ZSS hostname or default Zowe user n
:::
* **components.gateway.apiml.security.x509.externalMapperUser**
- To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. The user authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow.
+ To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. The user authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is: `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow.
If you customized the `ZWESECUR` JCL or workflow (the customization of zowe runtime user: `// SET ZOWEUSER=ZWESVUSR * userid for Zowe started task`) and changed the default USERID, create the `components.gateway.apiml.security.x509.externalMapperUser` property and set the value by adding a new line as in the following example:
diff --git a/docs/user-guide/certificate-configuration-scenarios.md b/docs/user-guide/certificate-configuration-scenarios.md
deleted file mode 100644
index deed2211ea..0000000000
--- a/docs/user-guide/certificate-configuration-scenarios.md
+++ /dev/null
@@ -1,415 +0,0 @@
-# Certificate configuration scenarios
-
-
- After you complete the Zowe certificates configuration questionnaire to determine your specific configuration use case, choose from the five scenarios presented in this article to configure Zowe for automatic certificate setup. Examples of the zowe.yaml files are provided for each scenario.
-
-:::info Required roles: system programmer, security administrator
-:::
-
-:::tip
-To assist you with determining the specific certificate configuration scenario that applies to your use case, see [Zowe certificates configuration questionnaire](./certificates-configuration-questionnaire.md). This questionnaire guides you through questions that lead to a specific configuration scenario presented in this article.
-:::
-
-Zowe servers require both a keystore to store the certificates and a truststore to validate certificates.
-
-For use of Zowe on z/OS, the keystore and truststore can either be Unix file-based (PKCS12) or z/OS keyring-based.
-
-Both the keystore and truststore can automatically be created by Zowe regardless of which storage type is used. Keystores and truststores can be populated either with certificates that the user chooses, or with self-signed certificates generated by Zowe.
-This automation can be performed by defining and customizing the `zowe.setup.certificate` section of your Zowe YAML configuration.
-Zowe can then automate the certificate setup via the `zwe init certificate` command.
-
-
-:::note
-Automated generation of certificates is an option, but is not required. If you already have a keystore that contains a valid certificate *, and the corresponding private key of the certificate, along with a truststore which validates the certificate and any other certificates you expect to encounter, then you also have the option to directly define the parameter `zowe.certificate`, which specifies the location of each of these certificates and their storage objects. Note that this parameter should not be confused with the parameter `zowe.setup.certificate`.
-:::
-
-## * What is a valid certificate in Zowe?
-
-A valid certificate for use in Zowe conforms to one of the following two options:
-
-* The certificate does not contain the _Extended Key Usage_ section.
-* The certificate does contain the _Extended Key Usage_ section, and also includes the **Server** and **Client** authentication fields.
-
-## Considerations for certificate scenario selection
-
-Consider the scenario that best suits your use case:
-
-* Do you plan to use a file-based (PKCS12) certificates, or z/OS keyrings?
-* Do you plan to enable Zowe to create self-signed certificates, or will Zowe be using pre-made certificates which you are providing?
-* If you are providing certificates to Zowe and using a keyring, does the certificate already exist in your security database, or are you importing it via a dataset?
-
-There are five scenarios/use cases for configuring certificates.
-Use the applicable certificate configuration scenario according to your needs.
-
-Each scenario described in this article provides the configuration details via code snippets which you can use to edit your Zowe YAML configuration within the `zowe.setup.certificate` section.
-
-* [Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](#scenario-1-use-a-file-based-pkcs12-keystore-with-zowe-generated-certificates)
-* [Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA](#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca)
-* [Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates](#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates)
-* [Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate](#scenario-4-use-a-zos-keyring-based-keystore-and-connect-to-an-existing-certificate)
-* [Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set](#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set)
-
-
-:::note
-Ensure that all alias values for all scenarios use only lower-case.
-:::
-
-## Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates
-
-Use this procedure to configure the `zowe.setup.certificate` section in your yaml file to enable Zowe to use generated PKCS12 certificates to be used with a keystore directory to store your certificates.
-
-
-Click here for details.
-
-1. Set the `type` of the certificate storage to `PKCS12`.
-
-2. Customize the keystore directory in the following format:
- ```
- /var/zowe/keystore
- ```
-3. Lock the keystore directory so it is accessible only to the Zowe runtime user and group:
- ```
- lock: true
- ```
-4. Customize the certificate alias name. The default value is `localhost`.
-5. Set the keystore password. The default value is `password`.
-6. Set the alias name of self-signed certificate authority. The default value is `local_ca`.
- ```
- caAlias: local_ca
- ```
-7. Set the password of the keystore stored self-signed certificate authority. The default value is `local_ca_password`.
- ```
- caPassword: local_ca_password
- ```
-8. (Optional) Specify the distinguished name for Zowe generated certificates.
-
- ```
- dname:
- caCommonName: ""
- commonName: ""
- orgUnit: ""
- org: ""
- locality: ""
- state: ""
- country: ""
- ```
-9. Set the validity in days for the Zowe generated certificates
- ```
- validity: 3650
- ```
-10. Set the domain names and IPs specified in nested subsection `SAN`. If this field is not defined, the `zwe init` command uses the value `zowe.externalDomains`.
- ```
- san:
- sample domain name
- - dvipa.my-company.com
- sample IP address
- - 12.34.56.78
- ```
-:::note
-A bug in Java SDK 8.0.8.10 has been discovered that makes configuration scenario 1 non-operational. If you see the following message when running the `zwe init certificate` command, upgrade or downgrade your Java version:
-
-```
-keytool error (likely untranslated): java.lang.IllegalArgumentException: java.util.Vector incompatible with [Ljava.lang.Object;
-```
-For more information, see this article in [IBM Support](https://www.ibm.com/support/pages/apar/IJ48749).
-:::
-
- **Example zowe yaml for scenario 1:**
-
-```
- certificate:
- type: PKCS12
- pkcs12:
- directory: /var/zowe/keystore
- lock: true
- name: localhost
- password: password
- caAlias: local_ca
- caPassword: local_ca_password
- dname:
- caCommonName: "Zowe Instances CA"
- commonName: "Zowe Server"
- org: "My Company"
- locality: "Prague"
- state: "Prague"
- country: "CZ"
- validity: 3650
- san:
- - system.my-company.com
- - 12.34.56.78
-```
-Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates.
-
-For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also availabe in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29).
-
-
-
-## Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA
-
-Use this procedure to configure the `zowe.setup.certificate` section in your yaml file to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA.
-
-
-Click here for details.
-
-1. Set the `type` of the certificate storage to `PKCS12`.
-
-2. Customize the keystore directory in the following format:
- ```
- /var/zowe/keystore
- ```
-3. Lock the keystore directory so it is accessible only to the Zowe runtime user and group:
- ```
- lock: true
- ```
-4. Customize the certificate alias name. The default value is `localhost`.
-5. Set keystore password. The default value is `password`.
-6. Set the existing PKCS12 keystore which holds the certificate issued by an external CA.
- ```
- keystore: ""
- ```
-
-7. Set the password of the keystore set in step 6.
- ```
- password: ""
- ```
-
-8. Specify the alias of the certificate to be imported.
- ```
- alias: ""
- ```
-
-9. Set the path to the certificate authority that signed the certificate to be imported.
- ```
- importCertificateAuthorities:
- ```
-
-:::note
-PEM format certificate authorities can be imported and trusted.
-:::
-
- **Example zowe yaml for scenario 2 (PKCS12):**
-
- ```
- certificate:
- type: PKCS12
- pkcs12:
- directory: /var/zowe/keystore
- lock: true
- name: localhost
- password: password
- import:
- keystore: /certs/system.keystore.p12
- password: password
- alias: server
- importCertificateAuthorities:
- - /certs/extca.1.cer
- - /certs/extca.2.cer
- ```
-Your yaml file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generted by another CA.
-
-
-
-## Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates
-
-Use this procedure to configure the `zowe.setup.certificate` section in your yaml file to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates.
-
-
-Click here for details.
-
-1. Set the `type` of the certificate storage to one of the following keyring types:
-
- * JCEKS
- * JCECCAKS
- * JCERACFKS
- * JCECCARACFKS
- * JCEHYBRIDRACFKS
-
-2. Add the parameter `createZosmfTrust` and set to true.
- ```
- createZosmfTrust: true
- ```
-3. Under the nested subsection `keyring:`, specify the following keyring values:
-
- * keyring name
- ```
- name: ZoweKeyring
- ```
- * Label of Zowe certificate. The default value is `localhost`.
- ```
- label: localhost
- ```
- * Label of Zowe CA certificate. The default value is `localca`.
- ```
- caLabel: localca
- ```
- * The distinguished name for Zowe generated certificates.
- ```
- dname:
- caCommonName: ""
- commonName: ""
- orgUnit: ""
- org: ""
- locality: ""
- state: ""
- country: ""
- ```
-4. Set the validity in days for the Zowe generated certificates
- ```
- validity: 3650
- ```
-5. Set the domain names and IPs specified in the certificate SAN. If
-this field is not defined, the `zwe init` command uses the value `zowe.externalDomains`.
- ```
- san:
- - dvipa.my-company.com
- - 12.34.56.78
- ```
-:::note
-Due to the limitation of the `RACDCERT` command, this field should contain exactly two entries with the domain name and IP address.
-:::
-
- **Example zowe yaml for scenario 3:**
-
- ```
- certificate:
- #Type of certificate storage. Valid values are: PKCS12 or JCERACFKS
- type: JCERACFKS
- createZosmfTrust: true
- keyring:
- #**COMMONLY_CUSTOMIZED**
- #Keystore directory
- name: ZoweKeyring
- label: localhost
- caLabel: localca
- dname:
- caCommonName: "Zowe Instances CA"
- commonName: "Zowe Service"
- org: "My Company"
- locality: "Prague"
- state: "Prague"
- country: "CZ"
- validity: 3650
- san:
- - system.my-company.com
- - 12.34.56.78
- ```
-Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates.
-
-
-
-## Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate
-
-Use this procedure to configure the `zowe.setup.certificate` section in your yaml file to use a z/OS keyring-based keystore and connect to an existing certificate.
-
-
-Click here for details.
-
-1. Set the `type` of the certificate storage to one of the following keyring types:
-
- * JCEKS
- * JCECCAKS
- * JCERACFKS
- * JCECCARACFKS
- * JCEHYBRIDRACFKS
-
-2. Under `keyring:`, specify the keyring name:
- ```
- name: ZoweKeyring
- ```
-3. Under the nested subsection `connect:`, specify the following parameters:
- * The current owner of the certificate. Possible values can be `SITE` or a user ID.
- ```
- user: IBMUSER
- ```
- * The label of the existing certificate to be connected to the Zowe keyring.
- ```
- label: ""
- ```
- * All certificate authorities you want to be trusted in the Zowe keyring.
- ```
- importCertificateAuthorities:
- - ""
- ```
-:::note
-Due to the limitation of `RACDCERT` command, this field should contain a maximum of 2 entries.
-:::
-
-The following example uses an existing JCERACFKS certificate for Zowe's z/OS components. For more information about configuration in this scenario, see [this Medium blog post](https://medium.com/zowe/master-zowe-certificates-use-an-existing-jceracfks-certificate-for-zowes-z-os-components-975ffa0d9f2f), or the video tutorials in [this YouTube playlist](https://www.youtube.com/playlist?list=PL8REpLGaY9QEHLNA81DRgGqWcgOYC0PDX).
-
- **Example zowe yaml for scenario 4:**
-
-```
- # >>>> Certificate setup scenario 4
- # z/OS Keyring and connect to existing certificate
- certificate:
- type: JCERACFKS
- keyring:
- name: ZoweKeyringZOSMF
- connect:
- user: IZUSVR
- label: "DefaultzOSMFCert.IZUDFLT"
- importCertificateAuthorities:
- - "zOSMFCA"
-```
-
-If you would like to use this example in your Zowe configuration YAML file, replace the following four fields with your own values:
-
-* Replace `ZoweKeyringZOSMF` with the your own key ring name.
-* Replace `IZUSVR` with the user name who is the owner of the existing certificate.
-* Replace `DefaultzOSMFCert.IZUDFLT` with the label of the existing certificate you are connecting to (which is owned by the previously referenced user ID).
-* Replace `zOSMFCA` with the certificate authority that is used to sign the certificate.
-
-Your yaml file is now configured to use a z/OS keyring-based keystore and connect to an existing certificate.
-
-
-
-## Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set
-
-Use this procedure to configure the `zowe.setup.certificate` section in your yaml file to use a z/OS keyring-based keystore and import a certificate stored in a data set.
-
-
-Click here for details.
-
-1. Set the `type` of the certificate storage to one of the following keyring types:
-
- * JCEKS
- * JCECCAKS
- * JCERACFKS
- * JCECCARACFKS
- * JCEHYBRIDRACFKS
-
-2. Under `keyring:`, specify the following keyring values:
-
- * keyring name
- ```
- name: ZoweKeyring
- ```
- * Label of Zowe certificate. The default value is `localhost`.
- ```
- label: localhost
- ```
-3. Under the nested subsection `import:` specify the following parameters:
- * The name of the data set holds the certificate issued by another CA. This data set should be in PKCS12 format and contain private key.
- ```
- dsName: ""
- ```
- * The password for the PKCS12 data set.
- ```
- password: ""
- ```
- **Example zowe yaml for scenario 5:**
-
-```
- # >>>> Certificate setup scenario 5
- # z/OS Keyring and connect to existing certificate
- certificate:
- type: JCERACFKS
- keyring:
- name: ZoweKeyring
- import:
- dsName: PRODUCT.X.CERT.P12
- password: password
-```
-Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set.
-
-
\ No newline at end of file
diff --git a/docs/user-guide/certificates-configuration-questionnaire.md b/docs/user-guide/certificates-configuration-questionnaire.md
index b9ed04cb4e..c412e200cf 100644
--- a/docs/user-guide/certificates-configuration-questionnaire.md
+++ b/docs/user-guide/certificates-configuration-questionnaire.md
@@ -1,17 +1,22 @@
# Zowe certificates configuration questionnaire
-To properly configure Zowe to use certificates for server-side component installation, review the certificate setup options presented in this article.
-Understanding these options makes it possible to select the best certificate configuration scenario that fits your Zowe deployment use case.
-
:::info Required roles: system programmer, security administrator
If you know that you will be using certificates in a production deployment environment, and that you will be using an external certificate authority (CA), we recommend you consult with your organization's security administrator before you start certificate configuration.
:::
-Review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article.
+Zowe's assisted certificate setup provides scripts and automation for five different common certificate configurations, with each configuration separated into distinct scenarios. To identify which scenario best meets your site requirements, review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article. The five different certificate setup scenarios Zowe supports are:
+
+* Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates
+* Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA
+* Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates
+* Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate
+* Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set
+
+After completing the questionnaire, if you find that none of the certificate setup scenarios here satisfy to your site requirements, you should instead proceed by contacting your security administrator and [bringing your own certificates to Zowe](./certificates-finalize-configuration.md).
:::tip
-Before determining which scenario best suits your use case, it is practical to have a general understanding of the certificate configuration basics and Zowe certificates configuration overview. For more information, see the following articles:
+Before answering the questionnaire, it is useful to have a general understanding of the certificate configuration basics and Zowe certificates configuration overview. For more information, see the following articles:
- [Certificates concepts](../appendix/zowe-security-glossary.md#certificate-concepts) in the [Zowe Security Glossary](../appendix/zowe-security-glossary.md)
- [Zowe certificates overview](../getting-started/zowe-certificates-overview.md)
:::
@@ -20,14 +25,6 @@ The numerated decision blocks (yellow diamonds) in the following diagram corresp
Follow this sequence of questions to determine which certificate configuration scenario best suits your certificate use case.
-
-Each of the following certificate configuration scenarios are available in the article [Certificate configuration scenarios](./certificate-configuration-scenarios.md).
-
-* [Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](./certificate-configuration-scenarios.md#scenario-1-use-a-file-based-pkcs12-keystore-with-zowe-generated-certificates)
-* [Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA](./certificate-configuration-scenarios.md#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca)
-* [Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates](./certificate-configuration-scenarios.md#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates)
-* [Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate](./certificate-configuration-scenarios.md#scenario-4-use-a-zos-keyring-based-keystore-and-connect-to-an-existing-certificate)
-* [Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set](./certificate-configuration-scenarios.md#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set)
## Certificate configuration questionnaire
Answer each question and find which scenarios are relevant for the selected option:
@@ -42,20 +39,16 @@ If you plan to use Zowe generated self-signed certificates and your target envir
Decide if you want to store the certificate in a z/OS keyring or to a file based keystore/truststore.
:::tip
-While using a keystore/truststore pair is possible to store your certificates, we recommend that you use z/OS keyrings for production deployments.
+While using a keystore/truststore pair is possible to store your certificates, we recommend that you use z/OS key rings for production deployments.
:::
**Question 4:** Do you plan to use an existing certificate from another keyring or from a dataset?
If you have an existing certificate, you can import or connect this certificate to the planned z/OS keyring based storage.
-Before you import your certificates, check to make sure that the certificate format, type, and properties correspond to the required protection and acceptability depending on the planned deployment environment (DEV, TEST, PROD).
-For example, use Zowe generated self-signed certificates only with development or testing environments and not with production environments.
+Before you import your certificates, check to make sure that the certificate format, type, and properties meet your security requirements depending on the planned deployment environment (DEV, TEST, PROD). For example, Zowe generated self-signed certificates might be acceptable with development or testing environments, but not with production environments.
-For more information, see [Import and configure an existing certificate](./import-certificates.md).
-## Next steps
+Required certificate properties are covered in [the Zowe Security Glossary](../appendix/zowe-security-glossary.md#zowe-certificate-requirements).
-After you select your applicable certificate configuration scenario and review the certificate configurate sample in the article [Certificate configuration scenarios](./certificate-configuration-scenarios.md), you can continue to [Configure Zowe Certificates](./configure-certificates.md).
+## Next steps
-:::tip
-If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md), to find resolution of errors.
-:::
+After you have completed the questionnaire and selected a certificate configuration scenario, proceed to [Certificate configuration scenarios](./certificates-configuration-scenarios.md).
\ No newline at end of file
diff --git a/docs/user-guide/certificates-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md
new file mode 100644
index 0000000000..96eca2d49e
--- /dev/null
+++ b/docs/user-guide/certificates-configuration-scenarios.md
@@ -0,0 +1,533 @@
+# Certificate configuration scenarios
+
+After you have completed the [Zowe certificates configuration questionnaire](./certificates-configuration-questionnaire.md) and chosen a certificate configuration scenario, follow the scenario-specific documentation and `zowe.yaml` examples in this article.
+
+:::info Required roles: system programmer, security administrator
+:::
+
+Zowe servers require both a keystore to store the certificates and a truststore to validate certificates.
+
+Zowe's assisted certificate setup begins with customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. Zowe then uses these scenario configurations and complete certificate setup via the `zwe init certificate` command.
+
+:::note
+Reminder: Zowe assisted generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore/truststore combination you created on your own, you can instead go to [Finalize certificate configuration](./certificates-finalize-configuration.md).
+:::
+
+## What is a valid certificate in Zowe?
+
+A valid certificate for use in Zowe conforms to one of the following two options:
+
+* The certificate does not contain the _Extended Key Usage_ section.
+* The certificate does contain the _Extended Key Usage_ section, and also includes the **Server** and **Client** authentication fields.
+
+## Scenario overview
+
+Each scenario described in this article provides the configuration details via code snippets which you can use to edit your Zowe YAML configuration within the `zowe.setup.certificate` section.
+
+* [Running a Scenario file](#running-a-scenario-file)
+* [Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](#scenario-1-use-a-file-based-pkcs12-keystore-with-zowe-generated-certificates)
+* [Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA](#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca)
+* [Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates](#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates)
+* [Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate](#scenario-4-use-a-zos-keyring-based-keystore-and-connect-to-an-existing-certificate)
+* [Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set](#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set)
+
+:::note
+Ensure that all certificate alias values for all scenarios use only lowercase.
+:::
+
+## Running a scenario file
+
+Zowe supplies five certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario section below describes what each scenario accomplishes, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow the below instructions to execute the scenario.
+
+
+Run scenario YAML with configmgr
+
+1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we use `/path/to/files/examples/setup/certificate/scenario-1.yaml`.
+
+2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we use `/path/to/zowe.yaml`.
+
+3. Create the following configuration parameter, replacing our example paths with your real ones:
+ ```
+ FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)
+ ```
+
+4. Navigate to your Zowe installation root directory.
+
+5. Issue `./bin/zwe init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration parameter! If you are running Scenario 3, 4, or 5, you can add `--dry-run` to the command and review the JCL used to create the keyring before submission.
+ ```shell
+ ./bin/zwe init certificate --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)"
+
+ # If you are using scenarios 3, 4, or 5, this prints JCL to the console for review
+ ./bin/zwe init certificate --dry-run --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)"
+ ```
+
+
+
+
+
+:::tip
+If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md) to find resolution of errors.
+:::
+
+## Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates
+
+Follow this procedure and configure `scenario-1.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated PKCS12 certificates stored in a USS directory. These certificates are signed by a newly created, self-signed Certificate Authority. As such, this is not recommended for production environments.
+
+
+Click here for details.
+
+In your `scenario-1.yaml` configuration file:
+
+1. Customize the keystore directory in the following format:
+ ```yaml
+ directory: /var/zowe/keystore
+ ```
+2. Customize the certificate alias name. The default value is: `localhost`.
+3. Set the keystore password. The default value is: `password`.
+4. (Optional) Uncomment the lock field, which locks the keystore directory so it is accessible only to the Zowe runtime user and group:
+ ```yaml
+ lock: true
+ ```
+5. (Optional) Set the alias name of certificate authority. The default value is: `local_ca`.
+ ```yaml
+ caAlias: local_ca
+ ```
+6. (Optional) Set the password of the keystore stored certificate authority. The default value is: `local_ca_password`.
+ ```yaml
+ caPassword: local_ca_password
+ ```
+7. Set the validity in days for the Zowe generated certificates
+ ```yaml
+ validity: 3650
+ ```
+8. (Optional) Specify the distinguished name for Zowe generated certificates. If you do not want to customize this, you can leave it commented out.
+ ```yaml
+ dname:
+ caCommonName: ""
+ commonName: ""
+ orgUnit: ""
+ org: ""
+ locality: ""
+ state: ""
+ country: ""
+ ```
+9. (Optional) Set the domain names and IPs specified in nested subsection `SAN`. If this field is not defined, the `zwe init` command uses the value `zowe.externalDomains`, which are found in your main `zowe.yaml` file.
+ ```yaml
+ san:
+ # sample domain name
+ - dvipa.my-company.com
+ # sample IP address
+ - 12.34.56.78
+ ```
+:::tip
+To get the san IP address, run `ping dvipa.my-company.com` in your terminal.
+:::
+
+ **Example scenario-1 YAML file:**
+
+```yaml
+zowe:
+ setup:
+ certificate:
+ type: PKCS12
+ pkcs12:
+ directory: /global/zowe/keystore
+ lock: true
+ name: localhost # Optional, default value is localhost.
+ password: password # Optional, default value is password.
+ caAlias: local_ca # Optional, default value is local_ca.
+ caPassword: local_ca_password # Optional, default value is local_ca_password.
+ dname: # Distinguished name for Zowe generated certificates. All optional.
+ caCommonName: ""
+ commonName: ""
+ orgUnit: ""
+ org: ""
+ locality: ""
+ state: ""
+ country: ""
+ validity: 3650
+ san:
+ - dvipa.my-company.com
+ - 12.34.56.78
+```
+Your YAML file is now configured to enable Zowe to use generated PKCS12 certificates. You can now go to [Running a scenario file](#running-a-scenario-file).
+
+The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.)
+
+- The CA is created.
+- The keystore is created and the CA is added to the keystore.
+- The certificate is created and is added to the keystore.
+- The truststore is created.
+- Directory permissions are changed to restrict access to the private key.
+
+**Command output:**
+```
+#>zwe init certificate -c --update-config
+-------------------------------------------------------------------------------
+>> Creating certificate authority "local_ca"
+>> Certificate authority local_ca is created successfully.
+-------------------------------------------------------------------------------
+>> Export keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12
+>> Keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 is exported successfully.
+-------------------------------------------------------------------------------
+>> Creating certificate "localhost"
+>> Certificate localhost is created successfully.
+-------------------------------------------------------------------------------
+>> Export keystore /global/zowe/keystore/localhost/localhost.keystore.p12
+>> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully.
+-------------------------------------------------------------------------------
+>> Export keystore /global/zowe/keystore/localhost/localhost.truststore.p12
+>> Keystore /global/zowe/keystore/localhost/localhost.truststore.p12 is exported successfully.
+-------------------------------------------------------------------------------
+>> Lock keystore directory /global/zowe/keystore
+>> Keystore directory /global/zowe/keystore is locked.
+-------------------------------------------------------------------------------
+>> Update certificate configuration to
+
+- update "zowe.certificate.keystore.type" with value: PKCS12
+...
+- update "zowe.certificate.pem.certificateAuthorities" with value: /global/zowe/keystore/local_ca/local_ca.cer
+
+>> Zowe configuration is updated successfully.
+
+#>
+```
+
+You are ready to [Finalize your Zowe certificate configuration](./certificates-finalize-configuration.md).
+
+
+::note
+For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also available in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources target an older release of Zowe and modify `zowe.yaml` directly, so you will need to adapt some of their configuration to your `scenario-1.yaml` configuration file instead.
+::
+
+
+
+## Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA
+
+Follow this procedure and configure `scenario-2.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use previously generated certificates with a PKCS12 keystore stored in a USS directory.
+
+
+Click here for details.
+
+1. Set the `type` of the certificate storage to `PKCS12`.
+2. Customize the keystore `directory` in the following format:
+ ```yaml
+ directory: /var/zowe/keystore
+ ```
+3. Lock the keystore directory so it is accessible only to the Zowe runtime user and group:
+ ```yaml
+ lock: true
+ ```
+4. Set keystore password. The default value is: `password`.
+5. Set the existing PKCS12 keystore which holds the certificate issued by an external CA.
+ ```yaml
+ keystore: ""
+ ```
+
+6. Set the password of the keystore set in step 5.
+ ```yaml
+ password: ""
+ ```
+
+7. Specify the alias of the certificate to be imported.
+ ```yaml
+ alias: ""
+ ```
+
+8. Set the path to the certificate authority that signed the certificate to be imported. PEM-formatted certificate authorities can be imported.
+ ```yaml
+ importCertificateAuthorities:
+ - ""
+ ```
+
+:::note
+PEM format certificate authorities can be imported and trusted.
+:::
+
+ **Example zowe yaml for scenario 2 (PKCS12):**
+
+ ```yaml
+ certificate:
+ type: PKCS12
+ pkcs12:
+ directory: /var/zowe/keystore
+ lock: true
+ name: localhost
+ password: password
+ import:
+ keystore: /certs/system.keystore.p12
+ password: password
+ alias: server
+ importCertificateAuthorities:
+ - /certs/extca.1.cer
+ - /certs/extca.2.cer
+ ```
+:::note
+Due to the limitation of the RACDCERT command, the `importCertificateAuthorities` field can contain a maximum of two entries.
+:::
+
+
+Your YAML file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA. You can now go to [Running a scenario file](#running-a-scenario-file).
+
+
+
+## Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates
+
+Follow this procedure and configure `scenario-3.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated certificates with a z/OS keyring-based keystore.
+
+
+Click here for details.
+
+1. Set the `type` of the certificate storage to one of the following keyring types:
+ * JCERACFKS (default)
+ * JCEKS
+ * JCECCAKS
+ * JCECCARACFKS
+ * JCEHYBRIDRACFKS
+
+2. Under the nested subsection `keyring:`, specify the following keyring values:
+ * keyring name
+ ```yaml
+ name: ZoweKeyring
+ ```
+ * Label of Zowe certificate. The default value is: `localhost`.
+ ```yaml
+ label: localhost
+ ```
+ * Label of Zowe CA certificate. The default value is: `localca`.
+ ```yaml
+ caLabel: localca
+ ```
+ * (Optional) The distinguished name for Zowe generated certificates.
+ ```yaml
+ dname:
+ caCommonName: ""
+ commonName: ""
+ orgUnit: ""
+ org: ""
+ locality: ""
+ state: ""
+ country: ""
+ ```
+3. (Optional) Set the validity in days for the Zowe generated certificates. Defaults to 3650 days.
+ ```yaml
+ validity: 3650
+ ```
+4. (Optional, Recommended) Set the domain names and IPs specified in the certificate SAN. If
+this field is not defined, the `zwe init` command uses the value `zowe.externalDomains`.
+ ```yaml
+ san:
+ - dvipa.my-company.com
+ - 12.34.56.78
+ ```
+:::note
+Due to the limitation of the `RACDCERT` command, this field should contain exactly two entries with the domain name and IP address.
+:::
+
+ **Example zowe yaml for scenario 3:**
+
+ ```yaml
+ certificate:
+ type: JCERACFKS
+ keyring:
+ name: ZoweKeyring
+ label: localhost
+ caLabel: localca
+ dname:
+ caCommonName: "Zowe Instances CA"
+ commonName: "Zowe Service"
+ org: "My Company"
+ locality: "Prague"
+ state: "Prague"
+ country: "CZ"
+ validity: 3650
+ san:
+ - system.my-company.com
+ - 12.34.56.78
+ ```
+Your YAML file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to [Running a scenario file](#running-a-scenario-file).
+
+The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted.
+
+**Command output:**
+```
+#>zwe init certificate -c --update-config
+-------------------------------------------------------------------------------
+>> Generate Zowe certificate in keyring
+
+>>>> Modify ZWEKRING
+ - IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) is prepared
+>>>> Submit IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431)
+ - Job ZWEKRING(JOB03054) ends with code 0 (COMPLETED).
+>> Certificate is generated in keyring successfully.
+
+-------------------------------------------------------------------------------
+>> Update certificate configuration to
+>> Zowe configuration is updated successfully.
+
+#>
+```
+
+:::tip
+As shown in the example, the job ends with code `0`. There may, however, be failures in the individual steps. It is advised to check the job output. The security manager commands in the job are generated based on the value of `zowe.security.product`. Job steps for each product can be determined by the security manager.
+:::
+
+
+
+## Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate
+
+Follow this procedure and configure `scenario-4.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to connect existing certificates with a z/OS keyring-based keystore.
+
+
+Click here for details.
+
+1. Set the `type` of the certificate storage to one of the following keyring types:
+ * JCERACFKS (default)
+ * JCEKS
+ * JCECCAKS
+ * JCECCARACFKS
+ * JCEHYBRIDRACFKS
+
+2. Under keyring, specify the keyring `name`:
+ ```yaml
+ name: ZoweKeyring
+ ```
+3. Under the nested subsection `connect`, specify the following parameters:
+ * The current owner of the existing certificate. Possible values can be `SITE` or a user ID.
+ ```yaml
+ user: IBMUSER
+ ```
+ * The label of the existing certificate to be connected to the Zowe keyring.
+ ```yaml
+ label: ""
+ ```
+ * All certificate authorities you want to be trusted in the Zowe keyring.
+ ```yaml
+ importCertificateAuthorities:
+ - ""
+ ```
+:::note
+Due to the limitation of `RACDCERT` command, this field should contain a maximum of two entries.
+:::
+
+ **Example zowe yaml for scenario 4:**
+
+```yaml
+zowe:
+ setup:
+ certificate:
+ type: JCERACFKS
+ keyring:
+ name: ZoweKeyring
+ connect:
+ user: IBMUSER
+ label: ""
+ importCertificateAuthorities:
+ - "zOSMFCA"
+```
+
+Your YAML file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to [Running a scenario file](#running-a-scenario-file).
+
+The following example uses an existing JCERACFKS certificate for Zowe's z/OS components. For more information about configuration in this scenario, see [this Medium blog post](https://medium.com/zowe/master-zowe-certificates-use-an-existing-jceracfks-certificate-for-zowes-z-os-components-975ffa0d9f2f), or the video tutorials in [this YouTube playlist](https://www.youtube.com/playlist?list=PL8REpLGaY9QEHLNA81DRgGqWcgOYC0PDX).
+
+**Example:**
+
+
+:::note
+In this example, the command `zwe init certificate -c ./zowe.yaml --security-dry-run` allows the JCL to be inspected before submission, as well as handed off to a security administrator who has privileges to submit the JCL under their user ID. By default, the JCL is submitted immediately.
+:::
+
+If you would like to use this example in your Zowe configuration YAML file, replace the following four fields with your own values:
+
+* Replace `ZoweKeyringZOSMF` with your own key ring name.
+* Replace `IZUSVR` with the user name that is the owner of the existing certificate.
+* Replace `DefaultzOSMFCert.IZUDFLT` with the label of the existing certificate you are connecting to (which is owned by the previously referenced user ID).
+* Replace `zOSMFCA` with the certificate authority that is used to sign the certificate.
+
+
+
+## Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set
+
+Follow this procedure and configure `scenario-5.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to import existing certificates from a data set into a z/OS keyring-based keystore.
+
+
+Click here for details.
+
+1. Set the `type` of the certificate storage to one of the following keyring types:
+ * JCERACFKS (default)
+ * JCEKS
+ * JCECCAKS
+ * JCECCARACFKS
+ * JCEHYBRIDRACFKS
+
+2. Under `keyring`, specify the following keyring values:
+
+ * keyring `name`
+ ```yaml
+ name: ZoweKeyring
+ ```
+ * Label of Zowe certificate. The default value is: `localhost`.
+ ```yaml
+ label: localhost
+ ```
+3. Under the nested subsection `import`, specify the following parameters:
+ * The name of the data set that holds the certificate issued by another CA. This data set should be in PKCS12 format and contain private key.
+ ```yaml
+ dsName: ""
+ ```
+ * The password for the PKCS12 data set.
+ ```yaml
+ password: ""
+ ```
+ **Example zowe yaml for scenario 5:**
+
+```yaml
+zowe:
+ setup:
+ certificate:
+ type: JCERACFKS
+ keyring:
+ name: ZoweKeyring
+ label: localhost # Optional, default value is localhost.
+ import:
+ dsName: ""
+ password: ""
+```
+
+Your YAML file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set. You can now go to [Running a scenario file](#running-a-scenario-file).
+
+
+
diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md
new file mode 100644
index 0000000000..3353456483
--- /dev/null
+++ b/docs/user-guide/certificates-finalize-configuration.md
@@ -0,0 +1,88 @@
+# Finalize certificate configuration
+
+Once you have your certificates and either key ring or USS keystore and truststore ready, you can finish configuring certificates with Zowe. Follow the procedure described in this article according to your requirements to finalize and review your Zowe certificate configuration.
+
+:::info Required roles: system programmer, security administrator
+:::
+Choose from the following procedures:
+
+- [Review PKCS12 Certificate Configuration](#review-pkcs12-certificate-configuration)
+- [Review JCERACFKS Certificate Configuration](#review-key-ring-certificate-configuration)
+
+## Review PKCS12 certificate configuration
+
+When Zowe is launched, details about the PKCS12 certificates are found in the `zowe.yaml` file's `zowe.certificate` section. This configuration block contains information about the certificate name and the location of the certificate, together with the keystore and truststore location.
+
+If you have used [Zowe assisted certificate setup](./certificates-configuration-scenarios.md) with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own PKCS12 certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide:
+
+```yaml
+zowe:
+ # ... you have other fields before certificate
+ certificate:
+ keystore:
+ type: PKCS12
+ file: /path/to/your/keystore.p12
+ # the password to your keystore
+ password: password
+ # alias is the name of your key/cert
+ alias: my_cert_in_keystore_label
+ truststore:
+ # truststore can have the same values as keystore (minus alias), but can be a separate truststore if desired.
+ # This example shows a separate truststore definition.
+ type: PKCS12
+ file: /path/to/your/truststore.p12
+ # the password to your truststore
+ password: password
+ pem:
+ key: /path/to/your/cert.key
+ certificate: /path/to/your/cert.cer
+ certificateAuthorities: /path/to/your/cert_authority.cer
+```
+
+Manually review that all the values you provided are correct:
+* The keystore, truststore, and certificates exist in their stated locations.
+* The passwords to the keystore and truststore are accurate.
+* The certificate alias is correct and exists in the provided keystore.
+* All file locations are accessible by your Zowe runtime user.
+
+After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it performs another series of verifications against your configuration and alerts you in the job output if there are any problems.
+
+## Review key ring certificate configuration
+
+When Zowe is launched, details about the key ring certificates are found in the `zowe.yaml` file's `zowe.certificate` section. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore are z/OSMF key rings in this case.
+
+If you have used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own key ring and certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using the below guide.
+
+If you are using AT-TLS with Zowe, consult the [Enabling AT-TLS for single-service deployment mode](./configuring-at-tls-for-zowe-server-single-service.md) article before proceeding. The key ring you define in your AT-TLS configuration should be the key ring you supply in the below guide.
+
+If you want to use ICSF-backed private keys, consult the [Using ICSF hardware private keys](./using-icsf-hardware-private-keys.md) article before proceeding. As mentioned in that article, ensure you are using `JCEHYBRIDRACFKS` as you follow the below example.
+
+:::note If there is a `zowe.certificate.pem` section, remove it from your `zowe.yaml` file.
+:::
+
+```yaml
+zowe:
+ # ... you have other fields before certificate
+ certificate:
+ keystore:
+ # Type of certificate storage. Value by default should be JCERACFKS. APIML additionally supports: JCEKS, JCECCAKS, JCECCARACFKS, or JCEHYBRIDRACFKS
+ type: JCERACFKS
+ file: safkeyring://YOURID/YOURKEYRING
+ # "password" should literally be "password" for key rings
+ password: password
+ # alias is the name of your key/cert. Use the Case Sensitive, Space Sensitive value in your ESM's list ring capability
+ alias: your_cert_label_in_keyring
+ truststore:
+ # Truststore usually has same values as keystore (minus alias), but can be different if desired.
+ # In this example, we link the truststore values to match the keystore values. You can copy this verbatim in most cases.
+ type: "${{ zowe.certificate.keystore.type }}"
+ file: "${{ zowe.certificate.keystore.file }}"
+ password: "${{ zowe.certificate.keystore.password }}"
+```
+
+Manually review that all the values you provided are correct:
+* The key ring exists.
+* The certificate alias is correct and exists in the provided key ring.
+* The key ring is accessible by your Zowe runtime user.
+
+After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it performs another series of verifications against your configuration and alerts you in the job output if there are any problems.
diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md
new file mode 100644
index 0000000000..80e89b2824
--- /dev/null
+++ b/docs/user-guide/certificates-trust-off-platform.md
@@ -0,0 +1,113 @@
+# Trusting certificates off platform
+
+Zowe services are protected by the certificates you set in your `zowe.yaml` configuration file, and these certificates are presented to all clients connecting to Zowe, including off-platform clients. If you are using your browser to view Zowe's API Mediation Layer or Web Desktop, or if you are using Zowe Explorer with an API Mediation Layer connection profile, the certificate Zowe presents might be challenged by your browser or operating system. This article covers a common method for trusting certificates: importing them in your off-platform client environment.
+
+## Importing a certificate authority (CA)
+
+Importing a certificate authority (CA) is a prerequisite to importing a PKCS12 certificate. Use the method that applies to your use case.
+
+* [Manually importing a certificate authority into a web browser](#manually-importing-a-certificate-authority-into-a-web-browser)
+* [Importing commands according to your operating system](#importing-commands-according-to-your-operating-system)
+
+### Manually importing a certificate authority into a web browser
+
+To avoid the browser untrusted CA challenge, import Zowe certificates into the browser.
+
+Trust in the API ML server is a necessary precondition for secure communication between the browser or API Client application. Ensure this trust by installing a Certificate Authority public certificate. By default, API ML creates a local CA. Import the CA public certificate to the truststore for REST API clients and to your browser. You can also import the certificate to your root certificate store.
+
+:::tip
+ If a SAF key ring is used and the certificate was generated on z/OS, the procedure to obtain the certificate does not apply. In this case, it is recommended that you work with your security system administrator to obtain the certificate.
+:::
+
+The public certificate in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) is stored in a USS directory and defined in the `zowe.yaml` configuration file in the section `zowe.certificate.pem.certificateAuthorities`. The certificate is stored in UTF-8 encoding so you need to transfer the certificate as a binary file. Since this is the certificate to be trusted by your browser, it is recommended to use a secure connection for transfer.
+
+:::note
+Windows currently does not recognize the PEM format. For Windows, use the P12 version of the `local_cer`.
+:::
+
+#### Importing commands according to your operating system
+
+To import the certificate to your root certificate store and trust it, follow the applicable procedure based on your operating system.
+
+
+
+
+For Windows, click here for command details.
+
+
+```
+certutil -enterprise -f -v -AddStore Root localca.cer
+```
+
+:::note
+Ensure that you open the terminal as **administrator**. This operation installs the certificate to the Trusted Root Certification Authorities.
+:::
+
+
+
+
+
+For macOS, click here for command details.
+
+
+```
+$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localca.cer
+```
+
+
+
+
+
+For Firefox, click here for command details.
+
+
+Manually import your root certificate via the Firefox settings, or force Firefox to use the Windows truststore.
+As a default, Firefox uses its own certificate truststore.
+
+Create a new Javascript file firefox-windows-truststore.js at `C:\Program Files (x86)\Mozilla Firefox\defaults\pref` with the following content:
+
+```
+/* Enable experimental Windows truststore support */
+pref("security.enterprise_roots.enabled", true);
+```
+
+
+
+:::tip
+To avoid requiring each browser to trust the CA that signed the Zowe certificate, you can use a public certificate authority to create a certificate. Optional public certificate authorities include _Symantec_, _Comodo_, _Let's Encrypt_, or _GoDaddy_. Certificates generated by such public CAs are trusted by all browsers and most REST API clients. This option, however, requires a manual process to request a certificate and might incur a cost payable to the publicly trusted CA.
+:::
+
+
+### Importing a local CA certificate on Linux
+
+Zowe also supports importing certificates to make REST HTTPS curl request from the command line.
+
+Follow these steps to import `local_ca.cer` from the path `.../zowe/keystore/local_ca`.
+
+:::note
+Steps are verified with Ubuntu 20.04.6 LTS.
+:::
+
+1. Rename `local_ca.cer` with `local_ca.crt` and copy to the shared ca-certificates path.
+
+ `$ cp local_ca.cer /usr/local/share/ca-certificates/zowe_local_ca.crt`
+
+2. Execute a ca-certificate store update by running the following command:
+
+ `$ sudo update-ca-certificates`
+
+3. Verify that the new expected certificate was added (the newest certificate is at the bottom of the list which contains an extended list of concatenated CAs).
+
+ `$ cat /etc/ssl/certs/ca-certificates.crt`
+
+4. Run a basic curl HTTPS request from the command line. For example, run the following command:
+
+ ```
+ curl --request 'GET'
+ --url 'https://tvt6092.svl.ibm.com:7554/jobs/api/v1?owner=ibmuser&prefix=*'
+ --header 'Authorization: Basic ************'
+ ```
+## Next steps
+
+Once your certificate is successfully imported, your browser and operating system should no longer challenge every connection as untrusted.
+
diff --git a/docs/user-guide/certificates-setup.md b/docs/user-guide/certificates-workflow-setup.md
similarity index 100%
rename from docs/user-guide/certificates-setup.md
rename to docs/user-guide/certificates-workflow-setup.md
diff --git a/docs/user-guide/configure-certificates.md b/docs/user-guide/configure-certificates.md
index 25bb90b2b2..654e3d9011 100644
--- a/docs/user-guide/configure-certificates.md
+++ b/docs/user-guide/configure-certificates.md
@@ -9,16 +9,16 @@ Zowe uses digital certificates for secure, encrypted network communication over
Zowe's certificates are stored in its **keystore**. Verification of these certificates and any incoming certificates from other servers or clients is done by using certificates of certificate authorities (CAs) within Zowe's **truststore**.
-Zowe supports using either file-based (`PKCS12`) or z/OS key ring-based (when on z/OS) keystores and truststores, and can reuse compatible stores if they exist. Zowe can assist in creating the stores by either generating certificates or by allowing users to import their own compatible certificates via the `zwe init certificate` command.
+Zowe supports using either file-based (`PKCS12`) or z/OS key ring-based (when on z/OS) keystores and truststores, and can reuse compatible stores if they exist.
* [Certificate concepts](#certificate-concepts)
* [Certificate verification](#certificate-verification)
* [Zowe certificate requirements](#zowe-certificate-requirements)
* [Certificate setup type](#certificate-setup-type)
-* [Next steps: Creating or importing certificates to Zowe](#next-steps-creating-or-importing-certificates-to-zowe)
+* [Next steps: Creating or importing certificates to Zowe](#next-steps-configuring-certificates-for-zowe)
:::note
-If you are already familiar with certificate concepts and how Zowe uses certificates and are ready to get started, see the options under the section _Next steps: Creating or importing certificates to Zowe_ at the end of this article.
+If you are already familiar with certificate concepts and how Zowe uses certificates and are ready to get started, see the options under the section [_Next steps: Creating or importing certificates to Zowe_](#next-steps-configuring-certificates-for-zowe) at the end of this article.
:::
## Certificate concepts
@@ -34,44 +34,41 @@ Before you get started with configuring certificates, it is useful to familiariz
* [Self-signed certificates](#self-signed-certificates)
### Keystore
-The keystore is the location where Zowe stores certificates that Zowe servers present to clients and other servers. In the simplest case, the keystore contains one private key and a certificate pair, which can then be used by each Zowe server.
-When you are using a key ring, a single key ring can serve both as a keystore and as a truststore if desired.
+The keystore is the location where Zowe stores certificates that Zowe servers present to clients and other servers. In the simplest case, the keystore contains one certificate represented by a public/private key pair, which can then be used by each Zowe server.
### Truststore
-The truststore is used by Zowe to verify the authenticity of the certificates that Zowe encounters. The authenticity is required when Zowe is communicating with another server, with one of Zowe's own servers, or with a client that presents a certificate. A truststore is composed of Certificate Authority (CA) certificates that are compared against the CAs that an incoming certificate claims to be signed by. To ensure a certificate is authentic, Zowe must verify that the certificate's claims are correct. Certificate claims include that the certificate was sent by the host that the certificate was issued to, and that the cryptographic signature of the authorities the certificate claims to have been signed by match those found within the truststore. This process helps to ensure that Zowe only communicates with hosts that you trust and have verified as authentic.
-When using a key ring, a single key ring can be both a keystore and a truststore if desired.
+The truststore is used by Zowe to verify the authenticity of the certificates that Zowe encounters. The authenticity is required when Zowe is communicating with another server, with one of Zowe's own servers, or with a client that presents a certificate. A truststore is composed of Certificate Authority (CA) certificates that are compared against the CAs that an incoming certificate claims to be signed by. To ensure a certificate is authentic, Zowe must verify that the certificate's claims are correct. This process helps to ensure that Zowe only communicates with hosts that you trust and have verified as authentic.
### PKCS12
-PKCS12 is a file format that allows a Zowe user to hold many cryptographic objects in one encrypted, passworded file. This file format is well supported across platforms but because it is just a file, you can prefer to use z/OS key rings instead of PKCS12 certificates for ease of administration and maintenance.
+PKCS12 is a file format that allows a Zowe user to hold many cryptographic objects in one encrypted, password-protected file which is well supported across platforms. PKCS12 setups typically have distinct keystores and truststores, though you can use one store as both keystore and truststore. Throughout Zowe's documentation, we will by default treat the keystore and truststore as separate and distinct.
-### z/OS key ring
-z/OS provides an interface to manage cryptographic objects in "key rings". As opposed to PKCS12 files, using z/OS key rings allows the crypto objects of many different products to be managed in a uniform manner. z/OS key rings are still encrypted, but do not use passwords for access. Instead, SAF privileges are used to manage access. Java's key ring API requires that the password field for key ring access to be set to "password", so despite not needing a password, you can see this keyword.
+* Use of PKCS12 keystores and truststores is recommended for non-production environments.
-Use of a z/OS keystore is the recommended option for storing certificates if system programmers are already familiar with the certificate operation and usage.
-Creating a key ring and connecting the certificate key pair requires elevated permissions. When the TSO user ID does not have the authority to manipulate key rings and users want to create a Zowe sandbox environment or for testing purposes, the USS keystore is a good alternative.
+### z/OS key ring
+z/OS provides an interface to manage cryptographic objects in "key rings". Compared with PKCS12, using z/OS key rings grants a deeper integration of certificates into z/OS systems and security management, which benefits systems management and operations across multiple products. z/OS key rings are still encrypted, but do not use passwords for access. Instead, SAF privileges are used to manage access.
-One option for certificate setup for key rings is to copy the JCL `ZWEKRING` member of Zowe's SAMPLIB and customize its values.
+* Use of z/OS key rings is recommended for production environments.
### Server certificate
Servers need a certificate to identify themselves to clients. Every time that you go to an HTTPS website, for example, your browser checks the server certificate and its CA chain to verify that the server you reached is authentic.
### Client certificate
-Clients do not always need certificates when they are communicating with servers, but sometimes client certificates can be used wherein the server verifies authenticity of the client similar to how the client verifies authenticity for the server. When client certificates are unique to a client, the certificate can be used as a form of authentication to provide convenient yet secure login.
+Clients do not always need certificates when they are communicating with servers, but sometimes client certificates can be used to establish the server's trust of a client's identity, similar to how the client verifies authenticity for the server. When client certificates are unique to a client, the certificate can be used as a form of authentication and login.
### Self-signed certificates
-A self-signed certificate is one that is not signed by a CA at all – neither private nor public. In this case, the certificate is signed with its own private key, instead of requesting verification from a public or a private CA. It means that there is no chain of trust to guarantee that the host with this certificate is the one you wanted to communicate with. Note that these certificates are not secure against other hosts masquerading as the one you want to access. As such, it is highly recommended that certificates be verified against the truststore for production environments.
+A self-signed certificate is one that is not signed by a public or private certificate authority. Instead, the certificate is signed with its own private key, hence self-signed. Self-signed certificates means there is no chain of trust to guarantee that the host with such a certificate is definitively the one you wanted to communicate with, and such they are considered **insecure**. Therefore, we highly recommended and by default require that all certificates are verified against a certificate authority in the truststore.
## Certificate verification
-When you configure Zowe, it is necessary to decide whether Zowe verifies certificates against its truststore.
+When you configure Zowe, you can change whether Zowe verifies certificates against its truststore or not.
In the Zowe configuration YAML, the property `zowe.verifyCertificates` controls the verification behavior. It can be `DISABLED`, `NONSTRICT`, or `STRICT`.
-You can set this property either before or after certificate setup, but **it is recommended to set `zowe.verifyCertificates` before certificate setup** because it affects the automation that Zowe can perform during certificate setup.
+You can set this property either before or after certificate setup, but **it is recommended to set `zowe.verifyCertificates` before certificate setup**.
### DISABLED verification
If you set `zowe.verifyCertificates` to `DISABLED`, certificate verification is not performed. It is not recommended for security reasons, but may be used for proof of concept or when certificates within your environment are self-signed.
-If you set `DISABLED` before certificate setup, Zowe does not automate putting z/OSMF trust objects into the Zowe truststore. This action can result in failure to communicate with z/OSMF if later you enable verification. As such. It is recommended to either set verification on by default, or to reinitialize the keystore if you choose to turn on verification at a later point.
+If you set `DISABLED` before certificate setup, Zowe does not automate putting z/OSMF trust objects into the Zowe truststore. This action can result in failure to communicate with z/OSMF if later you enable verification. As such, it is recommended to either set verification on by default, or to reinitialize the keystore if you choose to turn on verification at a later point.
### NON-STRICT verification
If you set `zowe.verifyCertificates` to `NONSTRICT`, certificate verification is performed except for hostname validation. Using this setting, the certificate Common Name or Subject Alternate Name (SAN) is not checked. Skipping hostname validation facilitates deployment to environments where certificates are valid but do not contain a valid hostname. This configuration is for development purposes only and should not be used for production.
@@ -89,60 +86,31 @@ Zowe server certificates must either not have the `Extended Key Usage` (EKU) att
Some Zowe components act as a server, some as a client, and some as both - client and server. The component certificate usage for each of these cases is controlled by the Extended Key Usage (EKU) certificate attribute. The Zowe components use a single certificate (or the same certificate) for client and server authentication, so it is required that this certificate is valid for the intended usage/s of the component - client, server, or both. The EKU certificate extension attribute is not required, however, if it is specified, it must be defined with the intended usage/s. Otherwise, connection requests will be rejected by the other party
-### Supported algorithm
+### JWT Token Signing Algorithm
The server certificate could be used to sign JWT tokens when one of the following conditions is valid:
- The token provider is set as SAF (see `apiml.security.auth.provider=saf`)
-- The token provider is set as z/OSMF (see `apiml.security.auth.provider=zosmf`), but the z/OSMF is not [configured to support JWT tokens](https://www.ibm.com/docs/en/zos/3.1.0?topic=configurations-enabling-json-web-token-support)
-- [Personal access token (PAT)](../getting-started/zowe-security-authentication.md/#authentication-with-personal-access-token-pat) are enabled
+- The token provider is set as z/OSMF (see `apiml.security.auth.provider=zosmf`) _and_ z/OSMF is not [configured to support JWT tokens](https://www.ibm.com/docs/en/zos/3.1.0?topic=configurations-enabling-json-web-token-support)
+- [Personal access tokens (PAT)](../getting-started/zowe-security-authentication.md#authentication-with-personal-access-token-pat) are enabled
-The supported algorithm is: RSASSA-PKCS1-v1_5 using SHA-256 signature algorithm as defined by RFC 7518, Section 3.3. This algorithm requires a 2048-bit key.
+Given one of those conditions, the supported JWT signing algorithm is `RSASSA-PKCS1-v1_5` using SHA-256 signature algorithm as defined by RFC 7518, Section 3.3. This algorithm requires a 2048-bit key, so ensure your server certificate has a key size of at least 2048 bits.
### Hostname validity
-The host communicating with a certificate should have its hostname match one of the values of the certificate's Common Name or Subject Alternate Name (SAN). If this condition is not true for at least one of the certificates that are seen by Zowe, then you may wish to set [NON-STRICT verification](#non-strict-verification) within Zowe's configuration.
+The host communicating with a certificate should have its hostname match one of the values of the certificate's Common Name or Subject Alternate Name (SAN). If this condition is not true for at least one of the certificates that are seen by Zowe, then you can set [NON-STRICT verification](#non-strict-verification) within Zowe's configuration as a workaround. It is recommended to update your certificates so their SAN or Common Name match the hostname.
### z/OSMF access
-The z/OSMF certificate is verified according to Zowe's [Certificate verification setting](#certificate-verification), as is the case with any certificate that is seen by Zowe. However, Zowe will also set up a trust relationship with z/OSMF within Zowe's truststore during certificate setup automation if the certificate setting is set to any value other than [DISABLED](#disabled-verification).
+z/OSMF's certificate is verified according to Zowe's [Certificate verification setting](#certificate-verification), as is the case with any certificate that is seen by Zowe. Therefore, you will need the certificate authority which signed z/OSMF's certificate in Zowe's truststore.
## Certificate setup type
-Whether importing or letting Zowe generate certificates, the setup for Zowe certificate automation and the configuration to use an existing keystore and truststore depends upon the content format: file-based (`PKCS12`) or z/OS key ring-based.
-
-### File-based (PKCS12) certificate setup
-
-Zowe is able to use PKCS12 certificates that are stored in USS. Zowe uses a `keystore` directory to contain its certificates primarily in PKCS12 (`.p12`, `.pfx`) file format, but also in PEM (`.pem`) format. The truststore is in the `truststore` directory that holds the public keys and CA chain of servers that Zowe communicates with (for example z/OSMF).
-
-### z/OS key ring-based certificate setup
-
-Zowe is able to work with certificates held in a **z/OS key ring**.
-
-The JCL member `.SZWESAMP(ZWEKRING)` contains security commands to create a SAF key ring. By default, this key ring is named `ZoweKeyring`. You can use the security commands in this JCL member to generate a Zowe certificate authority (CA) and sign the server certificate with this CA. The JCL contains commands for all three z/OS security managers: RACF, TopSecret, and ACF2.
-
-There are two ways to configure and submit `ZWEKRING`:
+Zowe offers automated assistance setting up certificates, though this is disabled by default during the installation process, as we expect most users to bring their own certificates to Zowe. Zowe offers automation for five different scenarios covering both PKCS12 and z/OS key ring options, detailed later under [Certificate Configuration Scenarios](./certificates-configuration-scenarios.md).
-- Copy the JCL `ZWEKRING` member and customize its values.
-- Customize the `zowe.setup.certificate` section in `zowe.yaml` and use the `zwe init certificate` command.
-
- You can also use the `zwe init certificate` command to prepare a customized JCL member by using `ZWEKRING` as a template.
-
-A number of key ring scenarios are supported:
-
-- Creation of a local certificate authority (CA) which is used to sign a locally generated certificate. Both the CA and the certificate are placed in the `ZoweKeyring`.
-- Import of an existing certificate that is already held in z/OS to the `ZoweKeyring` for use by Zowe.
-- Import of an existing certificate already held in z/OS to the `ZoweKeyring` for use by Zowe.
-
-## Next steps: Creating or importing certificates to Zowe
+## Next steps: configuring certificates for Zowe
Review the following options and choose which best applies to your use case:
-* Take our [Certificates Configuration Questionnaire](./certificates-configuration-questionnaire.md) to assist with determining which configuration scenario and associated zowe.yaml format best suits your use case.
-
-* To review the various zowe.yaml files to see which certificate configuration applies to your specific use case, see [Certificate configuration scenarios](./certificate-configuration-scenarios.md).
-
-* If you have an existing certificate, you can import this certificate to the keystore. For more information, see [Import and configure an existing certificate](./import-certificates.md).
-
-* If you do not have an existing certificate, you can create one. For more information, see [Generate a certificate](./generate-certificates.md).
+* If you are bringing your own certificates and key ring, and configuring them without Zowe's automated assistance, see [Finalize Certificate Configuration](./certificates-finalize-configuration.md). You should also choose this option if you are setting up Zowe with an [AT-TLS configuration](./configuring-at-tls-for-zowe-server-single-service.md).
-* When your certificate is already in the keystore, it is ready for use. For more information about how to use it, see [Use certificates](./use-certificates.md).
+* If you are not bringing your own certificates and key ring and will use Zowe's automated assistance, take our [Certificates Configuration Questionnaire](./certificates-configuration-questionnaire.md) to determine which configuration scenario best suits your use case and proceed from there.
-* If you run into any error when configuring certificates, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md).
+If you run into any error when configuring certificates, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md).
diff --git a/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md b/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md
index 1d61c005c2..594d226daa 100644
--- a/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md
+++ b/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md
@@ -8,7 +8,7 @@ Configuring AT-TLS allows Zowe to offload all TLS responsibilities to the z/OS C
This article explains how to enable AT-TLS for single-service deployment mode so your Zowe environment can benefit from this streamlined, system-driven approach to secure communications.
:::tip
-Beginning with Zowe v3.4.0 and for later versions, we recommend the use of single-service deployment mode. For the benefits of running Zowe in this mode, see [Enabling Single-Service deployment of API Mediation Layer](api-mediation/api-mediation-modulith.md).
+Beginning with Zowe v3.4.0 and for later versions, it is recommend to use single-service deployment mode. For the benefits of running Zowe in this mode, see [Enabling Single-Service deployment of API Mediation Layer](api-mediation/api-mediation-modulith.md).
:::
:::note
diff --git a/docs/user-guide/generate-certificates.md b/docs/user-guide/generate-certificates.md
deleted file mode 100644
index e70079419f..0000000000
--- a/docs/user-guide/generate-certificates.md
+++ /dev/null
@@ -1,285 +0,0 @@
-
-# Generating a certificate
-
-If you do not have a certificate, follow the procedure in this article that corresponds to the certificate type you choose to generate.
-
-:::info Required roles: system programmer, security administrator
-:::
-
-Choose from the following certificate types:
-
-* [Creating a PKCS12 certificate](#creating-a-pkcs12-keystore)
-* [Creating a JCERACFKS certificate](#creating-a-jceracfks-certificate)
-
-Both certificate types are self-signed certificates.
-
-## Creating a PKCS12 keystore
-
-Use can create PKCS12 certificates that are stored in USS. This certificate is used for encrypting TLS communication between Zowe clients and Zowe z/OS servers, as well as intra z/OS Zowe server to server communcation. Zowe uses a keystore directory to contain its external certificate, and a truststore directory to hold the public keys of servers it communicate with (for example z/OSMF).
-
-Follow these steps to generate a PKCS12 keystore:
-
-1. [Configure the PKCS12 setup section in zowe.yaml](#configure-the-pkcs12-setup-section-in-zoweyaml)
-2. [Run the command to generate a PKCS12 keystore](#run-the-command-to-generate-a-pkcs12-keystore)
-
-### Configure the PKCS12 setup section in zowe.yaml
-
-To assist with updating `zowe.yaml`, see the example yaml for [scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](certificate-configuration-scenarios.md/#scenario-1-use-a-file-based-pkcs12-keystore-with-zowe-generated-certificates) in the article Certificate configuration scenarios.
-
-For PKCS12 certificate users, customize the following parameters in the `zowe.yaml` file:
-
-| Parameter | Description |
-| --------- | ----------- |
-| `zowe.setup.certificate.pkcs12.directory` | Specifies the directory where you plan to store the PKCS12 keystore and truststore. This is required if `zowe.setup.certificate.type` is PKCS12. |
-| `zowe.setup.certificate.pkcs12.lock` | Is a boolean configuration to tell if we should lock the PKCS12 keystore directory only for Zowe runtime user and group. Default value is true. |
-| `zowe.setup.certificate.pkcs12` (*Optional*) | Defines name, password, caAlias and caPassword to customize the keystore and truststore. It is recommended to update these values from the default values. **Note:** Alias names should be all in lower case.|
-| `dname` (*Optional*) | Specifies the distinguished name. Domain names and IPs should be added into certificate SAN. If the field `san` is not defined, the `zwe init` command uses `zowe.externalDomains`.|
-
-**Configuring the `zowe.yaml` file for a PKCS12 certificate**
-The following `zowe.yaml` example generates the following artifacts:
-
- - A `PKCS12` certificate, specified in `zowe.setup.certificate.type`.
- - A keystore directory `/var/zowe/keystore`, specified in `zowe.setup.certificate.pkcs12.directory`.
- - A certificate name (or alias) `localhost`, specified in `zowe.setup.certificate.pkcs12.name`.
- - A certificate authority name `local_ca`, specified in `zowe.setup.certificate.certificate.pkcs12.caAlias`.
-
-**Example `zowe.yaml` using PKCS12:**
-```
-zowe:
- setup:
- certificate:
- type: PKCS12
- pkcs12:
- directory: /var/zowe/keystore
- lock: true
- name: localhost # Optional, default value is localhost.
- password: password # Optional, default value is password.
- caAlias: local_ca # Optional, default value is local_ca.
- caPassword: local_ca_password # Optional, default value is local_ca_password.
- dname: # Distinguished name for Zowe generated certificates. All optional.
- caCommonName: ""
- commonName: ""
- orgUnit: ""
- org: ""
- locality: ""
- state: ""
- country: ""
- validity: 3650
- san:
- - dvipa.my-company.com
- - 12.34.56.78
-```
-
-:::tip
-To get the san IP address, run `ping dvipa.my-company.com` in your terminal.
-:::
-
-### Run the command to generate a PKCS12 keystore
-
-After you configure the `zowe.yaml`, use the following procedure to generate the PKCS12 certificate.
-
-1. Log in to your system. In this example, run `ssh dvipa.my-company.com` with your password.
-
-2. Run the following command in the directory with this `zowe.yaml` in the terminal to generate the certificate and update the configuration values in the `zowe.yaml` file.
-
- `zwe init certificate -c --update-config`
-
-The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.)
-
-- The CA is created.
-- The keystore is created and the CA is added to the keystore.
-- The certificate is created and is added to the keystore.
-- The truststore is created.
-- Directory permissions are changed to restrict access to the private key.
-
-**Command output:**
-```
-#>zwe init certificate -c --update-config
--------------------------------------------------------------------------------
->> Creating certificate authority "local_ca"
->> Certificate authority local_ca is created successfully.
--------------------------------------------------------------------------------
->> Export keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12
->> Keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 is exported successfully.
--------------------------------------------------------------------------------
->> Creating certificate "localhost"
->> Certificate localhost is created successfully.
--------------------------------------------------------------------------------
->> Export keystore /global/zowe/keystore/localhost/localhost.keystore.p12
->> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully.-------------------------------------------------------------------------------
->> Export keystore /global/zowe/keystore/localhost/localhost.truststore.p12
->> Keystore /global/zowe/keystore/localhost/localhost.truststore.p12 is exported successfully.
--------------------------------------------------------------------------------
->> Lock keystore directory /global/zowe/keystore
->> Keystore directory /global/zowe/keystore is locked.
--------------------------------------------------------------------------------
->> Update certificate configuration to
-
-- update "zowe.certificate.keystore.type" with value: PKCS12
-...
-- update "zowe.certificate.pem.certificateAuthorities" with value: /global/zowe/keystore/local_ca/local_ca.cer
-
->> Zowe configuration is updated successfully.
-
-#>
-```
-
-The `zwe init certificate` command generates a certificate based on `zowe.yaml` values in the `zowe.setup.certificate` section. The certificate values used at runtime are referenced in the `zowe.certificate` section in the `zowe.yaml` file. The command `zwe init certificate -c --update-config` updates the runtime `zowe.certificate` section to reference the generated certificate generated from the `zowe.setup.certificate`.
-
-3. Open the `zowe.yaml` file to check the references to the newly generated certificate values as shown in the following code snippet:
-
-**Updated `zowe.certificate` section in `zowe.yaml`:**
-
-```
- certificate:
- keystore:
- type: PKCS12
- file: /var/zowe/keystore/localhost/localhost.keystore.p12
- password: password
- alias: localhost
- truststore:
- type: PKCS12
- file: /var/zowe/keystore/localhost/localhost.truststore.p12
- password: password
- pem:
- key: /var/zowe/keystore/localhost/localhost.key
- certificate: /var/zowe/keystore/localhost/localhost.cer
- certificateAuthorities: /var/zowe/keystore/local_ca/local_ca.cer
-```
-
-4. (Optional) For details about the certificate you generated, run the following command:
-`keytool -v -list -keystore localhost.keystore.p12 -storetype PKCS12`
-
-You completed the procedure to generate a PKCS12 keystore.
-
- For more information about additional commands to manage a keystore, see the [keytool documentation](https://docs.oracle.com/en/java/javase/11/tools/keytool.html).
-
-### Next steps after PKCS12 setup
-
-When using a Zowe-generated certificate, you will be challenged by your browser when logging in to Zowe to accept Zowe's untrusted certificate authority. Depending on the browser you are using, there are different ways to proceed. See next steps about how to [import the PKCS12 certificate to your browser](./import-certificates.md).
-
-## Creating a JCERACFKS certificate
-
-You can create a JCERACFKS certificate for use in a z/OS keystore. JCERACFKS uses SAF and RACF services to protect key material and certificates.
-
-Use the following procedure to configure the `zowe.yaml` file for JCERACFKS certificates:
-
-1. [Configure the JCERACFKS setup section in zowe.yaml](#configure-the-jceracfks-setup-section-in-zoweyaml)
-2. [Run the command to generate a JCERACFKS certificate](#run-the-command-to-generate-a-jceracfks-certificate)
-
-To assist with updating `zowe.yaml`, see the example yaml in [Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates](certificate-configuration-scenarios.md#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates) in the article Certificate configuration scenarios.
-### Configure the JCERACFKS setup section in zowe.yaml
-
-For JCERACFKS certificate (z/OS key ring) users, customize the following parameters in the `zowe.yaml` file:
-
-| Parameter | Description |
-| ---------- | ----------- |
-| `zowe.setup.certificate.keyring.owner` | The key ring owner. This parameter is optional and the default value is `zowe.setup.security.users.zowe`. If this parameter is not defined, the default value is ZWESVUSR.|
-| `zowe.setup.certificate.keyring.name` | Specifies the key ring name to be created on z/OS. This parameter is required if `zowe.setup.certificate.type` is `JCERACFKS`.|
-
-The following `zowe.yaml` example generates the following artifacts:
-
- - A `JCERACFKS` certificate, specified in `zowe.setup.certificate.type`.
- - A key ring named `ZoweKeyring` specified in `zowe.setup.certificate.keyring.name`.
- - A certificate with the label `localhost` specified in `zowe.setup.certificate.keyring.label`.
- - A certificate authority with the label `localca` specified in `zowe.setup.certificate.keyring.caLabel` with a common name `Zowe Service CA`.
-
-**Example `zowe.yaml` file using a JCERACFKS certificate:**
-```
-zowe:
- setup:
- certificate:
- type: JCERACFKS
- createZosmfTrust: true
- keyring:
- name: ZoweKeyring
- label: localhost # Optional, default value is localhost.
- caLabel: localca # Optional, default value is localca.
- dname: # Distinguished name for Zowe generated certificates. All optional.
- caCommonName: ""
- commonName: ""
- orgUnit: ""
- org: ""
- locality: ""
- state: ""
- country: ""
- validity: 3650
- san:
- - dvipa.my-company.com
- - 12.34.56.78
-```
-
-:::note Notes:
-- Alias names should be all lower cases.
-- The name and lables shown above are the default value in `zowe.yaml`.
-- `dname` for distinguished name is all optional.
-- Domain names and IPs should be added to the certificate SAN. If the field `san` is not defined, the `zwe init` command will use `zowe.externalDomains`. The value for the `san` parameter presented in the example is for demonstration purposes.
-:::
-
-### Run the command to generate a JCERACFKS certificate
-
-After you configure the `zowe.yaml`, use the following procedure to generate a JCERACFKS certificate.
-
-1. Log in to your system. In this example, run `ssh dvipa.my-company.com` with your password.
-
-2. Run the following command in the directory with this `zowe.yaml` in terminal to generate the certificate and update the configuration values in `zowe.yaml`.
-
- `zwe init certificate -c --update-config`
-
- When the command is run, a customized JCL member name is created in the `CUST.JCLLIB` data set. The PDS name is defined in the `zowe.setup.dataset.jcllib` property. In the following example output, the PDS member `USER.ZWE3.CUST.JCLLIB(ZW101431)` is created that contains the security manager commands, and then submitted as a job ID: `ZWEKRING(JOB03054)`.
-
-The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted.
-
-**Command output:**
-```
-#>zwe init certificate -c --update-config
--------------------------------------------------------------------------------
->> Generate Zowe certificate in keyring
-
->>>> Modify ZWEKRING
- - IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) is prepared
->>>> Submit IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431)
- - Job ZWEKRING(JOB03054) ends with code 0 (COMPLETED).
->> Certificate is generated in keyring successfully.
-
--------------------------------------------------------------------------------
->> Update certificate configuration to
->> Zowe configuration is updated successfully.
-
-#>
-```
-
-:::tip
-As shown in the example, the job ends with code `0`. There may, however, be failures in the individual steps. It is advised to check the job output. The security manager commands in the job are generated based on the value of `zowe.security.product`. Job steps for each product can be determined by the security manager.
-:::
-
-3. Open the `zowe.yaml` file to check the references to the newly generated certificate values. Because the `--update-config` parameter was specified, the runtime configuration section of zowe.yaml is updated to match the values to the generated keystore, certificate, and certificate authority. The updated section is shown in the following code snippet:
-
-**Updated `zowe.certificate` section in `zowe.yaml`:**
-```
-zowe:
- certificate:
- keystore:
- alias: localhost
- password: 'password'
- file: safkeyring://ZWESVUSR/ZoweKeyring
- type: JCERACFKS
- truststore:
- type: JCERACFKS
- file: safkeyring://ZWESVUSR/ZoweKeyring
- password: "password"
- pem:
- key:
- certificate:
- certificateAuthorities: safkeyring://ZWESVUSR/ZoweKeyring&localca
-```
-
-:::note
-`zowe.certificate.keystore.password` has a hardcoded password value. If you are using `type: PKCS12`, the password field must be the real password.
-:::
-
-You completed the procedure to generate a JCERACFKS certificate.
-
-### Next steps after JCERACFKS setup
-
-For more information about how to use your JCERACFKS certificate, see [Use JCERACFKS certificates](./use-certificates.md).
diff --git a/docs/user-guide/import-certificates.md b/docs/user-guide/import-certificates.md
deleted file mode 100644
index b21beaa205..0000000000
--- a/docs/user-guide/import-certificates.md
+++ /dev/null
@@ -1,225 +0,0 @@
-# Importing and configuring a certificate
-
-One option to use certificates in Zowe is to import and configure existing certificates. Use the procedure that applies to the type of certificate you wish to import.
-
-:::info Required roles: system programmer, security administrator
-:::
-
-Choose from the following certificate importing options:
-
-* [Importing a file-based PKCS12 certificate](#importing-an-existing-pkcs12-certificate)
-* [Importing a JCERACFKS certificate](#importing-an-existing-jceracfks-certificate)
-* [Importing a certificate stored in an MVS data set into a Zowe key ring](#importing-a-certificate-stored-in-an-mvs-data-set-into-a-zowe-key-ring).
-## Importing an existing PKCS12 certificate
-
-To import a PKCS12 certificate, it is first necessary to import a certificate authority (CA). There are two options for importing a CA:
-
-* [Manually importing a certificate authority into a web browser](#manually-importing-a-certificate-authority-into-a-web-browser)
-* [Importing a local CA certificate on Linux](#importing-a-local-ca-certificate-on-linux)
-
-Once you have imported your CA, you can configure the zowe.yaml according to [Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA](../user-guide/certificate-configuration-scenarios.md#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca) described in the article Certificate configuration scenarios.
-
-For PKCS12 certificate users, specify the following parameters in the `zowe.yaml` file:
-
-| Parameter | Description |
-| --------- | ------------|
-| `zowe.setup.certificate.pkcs12.import.keystore` | Specify this parameter if you acquired one or more certificates from another CA, stored them in PKCS12 format, and now want to import the certificate(s) into the Zowe PKCS12 keystore.
-| `zowe.setup.certificate.pkcs12.import.password` | Specify this password value for the keystore defined in `zowe.setup.certificate.pkcs12.import.keystore`. |
-| `zowe.setup.certificate.pkcs12.import.alias` | This value is the original certificate alias defined in `zowe.setup.certificate.pkcs12.import.keystore`. |
-| `zowe.setup.certificate.pkcs12.name`| The imported certificate is saved under the alias specified in it. |
-
-**Configure `zowe.yaml` for a PKCS12 certificate:**
-```
-zowe:
- setup:
- certificate:
- type: PKCS12
- pkcs12:
- directory: /var/zowe/keystore
- lock: true
- name: localhost # Optional, default value is localhost.
- password: password # Optional, default value is password.
- import:
- keystore: ""
- password: ""
- alias: ""
- importCertificateAuthorities:
- - ""
-```
-
-:::note
-Due to the limitation of the RACDCERT command, the `importCertificateAuthorities` field can contain a maximum of two entries.
-:::
-
-You can now use your imported PKCS12 certificate. See [next steps](#next-steps).
-## Importing a certificate Authority (CA)
-
-Importing a certificate authority (CA) is a prerequisite to importing a PKCS12 certificate. Use the method that applies to your use case.
-
-* [Manually importing a certificate authority into a web browser](#manually-importing-a-certificate-authority-into-a-web-browser)
-* [Importing a local CA certificate on Linux](#importing-a-local-ca-certificate-on-linux)
-
-### Manually importing a certificate authority into a web browser
-
-To avoid the browser untrusted CA challenge, import Zowe certificates into the browser.
-
-Trust in the API ML server is a necessary precondition for secure communication between the browser or API Client application. Ensure this trust by installing a Certificate Authority (CA) public certificate. By default, API ML creates a local CA. Import the CA public certificate to the truststore for REST API clients and to your browser. You can also import the certificate to your root certificate store.
-
-:::tip
- If a SAF keyring is used and set up with `ZWEKRING` JCL, the procedure to obtain the certificate does not apply. In this case, we recommended that you work with your security system administrator to obtain the certificate.
-:::
-
-The public certificate in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) is stored in a USS directory a defined in the `zowe.yaml` configuration file in the section `zowe.certificate.pem.certificateAuthorities`. The certificate is stored in UTF-8 encoding so you need to transfer the certificate as a binary file. Since this is the certificate to be trusted by your browser, it is recommended to use a secure connection for transfer.
-
-:::note
-Windows currently does not recognize the PEM format. For Windows, use the P12 version of the `local_cer`.
-:::
-
-#### Importing commands according to your operating system
-
-To import the certificate to your root certificate store and trust it, follow the applicable procedure based on your operating system.
-
-
-
-
-For Windows, click here for command details.
-
-
-```
-certutil -enterprise -f -v -AddStore Root" localca.cer
-```
-
-**Note:** Ensure that you open the terminal as **administrator**. This operation installs the certificate to the Trusted Root Certification Authorities.
-
-
-
-
-
-For macOS, click here for command details.
-
-
-```
-$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localca.cer
-```
-
-
-
-
-
-For Firefox, click here for command deails.
-
-
-Manually import your root certificate via the Firefox settings, or force Firefox to use the Windows truststore.
-As a default, Firefox uses its own certificate truststore.
-
-Create a new Javascript file firefox-windows-truststore.js at `C:\Program Files (x86)\Mozilla Firefox\defaults\pref` with the following content:
-
-```
-/* Enable experimental Windows truststore support */
-pref("security.enterprise_roots.enabled", true);
-```
-
-
-
-:::tip
-To avoid requiring each browser to trust the CA that signed the Zowe certificate, you can use a public certificate authority to create a certificate. Optional public certificate authorities include _Symantec_, _Comodo_, _Let's Encrypt_, or _GoDaddy_. Certificates generated by such public CAs are trusted by all browsers and most REST API clients. This option, however, requires a manual process to request a certificate and may incur a cost payable to the publicly trusted CA.
-:::
-
-After successfully manually importing a certificate authority into a web browser, you can now [import an existing PKCS12 certificate](#importing-an-existing-pkcs12-certificate).
-
-### Importing a local CA certificate on Linux
-
-Zowe also supports importing certificates to make REST HTTPS curl request from the command line.
-
-Follow these steps to import `local_ca.cer` from the path `.../zowe/keystore/local_ca`.
-
-:::note
-Steps are verified with Ubuntu 20.04.6 LTS.
-:::
-
-1. Rename `local_ca.cer` with `local_ca.crt` and copy to the shared ca-certificates path.
-
- `$ cp local_ca.cer /usr/local/share/ca-certificates/zowe_local_ca.crt`
-
-2. Execute a ca-certificate store update by running the following command:
-
- `$ sudo update-ca-certificates`
-
-3. Verify that the new expected certificate was added (the newest will be at the bottom of the list which contains an extended list of concatenated CAs).
-
- `$ cat /etc/ssl/certs/ca-certificates.crt`
-
-4. Run a basic curl HTTPS request from the command line. For example, run the following command:
-
- ```
- curl --request 'GET'
- --url 'https://tvt6092.svl.ibm.com:7554/jobs/api/v1?owner=ibmuser&prefix=*'
- --header 'Authorization: Basic ************'
- ```
-
-After successfully importing your local CA certificate on Linux, you can now [import an existing PKCS12 certificate](#importing-an-existing-pkcs12-certificate).
-
-## Importing an existing JCERACFKS certificate
-
-To import a JCERACFKS certificate, use the example yaml according to [Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate](certificate-configuration-scenarios.md#scenario-4-use-a-zos-keyring-based-keystore-and-connect-to-an-existing-certificate) in the article Certificate configuration scenarios.
-
-To use a JCERACFKS certificate, specify the following parameters in the `zowe.yaml` file:
-
-| Parameter | Description |
-| --------- | ------------|
-| `zowe.setup.certificate.keyring.connect.user` | This is a required parameter that specifies the owner of existing certificate. This field can have value of SITE or a user ID.|
-| `zowe.setup.certificate.keyring.connect.label` | This is a required parameter that sets the label of an existing certificate. |
-
-**Configure `zowe.yaml` for a JCERACFKS certificate:**
-
-```
-zowe:
- setup:
- certificate:
- type: JCERACFKS
- keyring:
- name: ZoweKeyring
- connect:
- user: IBMUSER
- label: ""
- importCertificateAuthorities:
- - ""
-```
-
-:::note
-Due to the limitation of the RACDCERT command, the `importCertificateAuthorities` field can contain a maximum of two entries.
-:::
-
-You can now use your imported JCERACFKS certificate. See [next steps](#next-steps).
-
-## Importing a certificate stored in an MVS data set into a Zowe key ring
-
-To import a certificate that is stored in a data set into a key ring, configure the zowe.yaml according to the example yaml in [Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set](certificate-configuration-scenarios.md#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set)
-
- To use a JCERACFKS certificate, specify the following parameters in the `zowe.yaml` file.
-
-| Parameter | Description |
-| --------- | ----------- |
-|`zowe.setup.certificate.keyring.connect.dsName` | This is a required parameter which specifies the data set where the certificate stored.|
-|`zowe.setup.certificate.keyring.connect.password` | This parameter specifies the password when importing the certificate. |
-| `zowe.setup.certificate.keyring.label` | This parameter specifies that label of the certificate that is imported. |
-
-**Configure `zowe.yaml` for a JCERACFKS certificate stored in an MVS data set:**
-
-```
-zowe:
- setup:
- certificate:
- type: JCERACFKS
- keyring:
- name: ZoweKeyring
- label: localhost # Optional, default value is localhost.
- import:
- dsName: ""
- password: ""
-```
-The configuration of `zowe.setup.certificate` populates information to be used by the subcommand `zwe init certificate` of `zwe init`.
-## Next steps
-
-Once your certificate is successfully imported, review the documentation about how to [use certificates](./use-certificates.md) in a Zowe production environment.
-
diff --git a/docs/user-guide/tls-configuration.md b/docs/user-guide/tls-configuration.md
index 62f453a488..6f4d192b5c 100644
--- a/docs/user-guide/tls-configuration.md
+++ b/docs/user-guide/tls-configuration.md
@@ -2,7 +2,7 @@
Zowe's servers have built-in TLS support to enable HTTPS connections.
-TLS support is the default setting, and an alternative to using AT-TLS. For information about using AT-TLS, see [Enabling AT-TLS](./configuring-at-tls-for-zowe-server.md).
+TLS support is the default setting, and an alternative to using AT-TLS. For information about using AT-TLS, see [Enabling AT-TLS](./configuring-at-tls-for-zowe-server-single-service.md).
:::info Required role: security administrator
:::
diff --git a/docs/user-guide/use-certificates.md b/docs/user-guide/use-certificates.md
deleted file mode 100644
index c32ae73243..0000000000
--- a/docs/user-guide/use-certificates.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# Using certificates
-
-Once you have generated or imported your certificates, you can now use the certificates with Zowe. Use the procedure descibed in this article that corresponds to the type of certificates you generated or imported.
-
-:::info Required roles: system programmer, security administrator
-:::
-Choose from the following procedures:
-
-- [Use PKCS12 certificates](#use-pkcs12-certificates)
-- [Use JCERACFKS certificates](#use-jceracfks-certificates)
-
-## Use PKCS12 certificates
-
-To use PKCS12 certificates, run the command `zwe start -c ./zowe.yaml` in the directory with the `zowe.yaml` file to start Zowe.
-
-Details about the PKCS12 certificate used when Zowe is launched are specified in the `zowe.yaml` section `certificates`. This section contains information about the certificate name and the location of the certificate, together with the truststore location.
-
-The two most common scenarios for using a PKCS12 certificate are:
-
-* You have an existing certificate and wish to configure Zowe to use the certificate.
-* You do not have a certificate and wish to [generate a new certificate](./generate-certificates.md).
-
- The `zwe init certificate` command supports both scenarios. The input parameters that control certificate configuration are specified in the section `zowe.setup.certificates`.
-
-To troubleshoot issues during Zowe startup, see [Troubleshooting startup of Zowe z/OS components](https://docs.zowe.org/stable/troubleshoot/troubleshoot-zos-startup).
-
-## Use JCERACFKS certificates
-
-Details about the JCERACFKS certificate used when Zowe is launched are specified in the `zowe.yaml` section `certificates`. This section contains information about the certificate name and location, together with the truststore location.
-
-The two most common scenarios for using a JCERACFKS certificate are:
-
-* You have been given an existing certificate and wish to configure Zowe to use it.
-* You do not have a certificate and wish to generate a new one.
-
- The `zwe init certificate` command supports both scenarios. The input parameters that control certificate configuration are specified in the section `zowe.setup.certificates`. See the example of connecting a JCERACFKS certificate below.
-
-**Example:**
-
-
-**Note:**
-In this example, the command `zwe init certificate -c ./zowe.yaml --security-dry-run` allows the JCL to be inspected before submission, as well as handed off to a security administrator who has privileges to submit the JCL under their user ID. By default, the JCL id submitted immediately. For details about this example, see this [playlist](https://youtube.com/playlist?list=PL8REpLGaY9QEHLNA81DRgGqWcgOYC0PDX).
-
-
diff --git a/docs/user-guide/zos-components-installation-checklist-dev.md b/docs/user-guide/zos-components-installation-checklist-dev.md
index be2e16bc48..ba883e9005 100644
--- a/docs/user-guide/zos-components-installation-checklist-dev.md
+++ b/docs/user-guide/zos-components-installation-checklist-dev.md
@@ -28,7 +28,7 @@ Use one of the following installation options to install Zowe z/OS components.
| Task | Results | Time Estimate |
|--------------------|----|------|
-| Zowe is able to use PKCS12 certificates or certificates held in a z/OS Keyring.
Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:
**Option 1:** Review [Zowe certificates configuration questionnaire](../user-guide/certificates-configuration-questionnaire.md) and [certificate configuration scenarios](../user-guide/certificate-configuration-scenarios.md) to determine which scenario best applies to your use case. Once you have imported or generated a certificate, see [Use certificates](../user-guide/use-certificates.md). **Option 2:** [Set up Zowe certificates using workflows](../user-guide/certificates-setup.md) | Your certificates are configured and stored securely|2 hours
+| Zowe is able to use PKCS12 certificates or certificates held in a z/OS Keyring.
Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:
**Option 1:** Review [Zowe certificates configuration questionnaire](../user-guide/certificates-configuration-questionnaire.md) and [certificate configuration scenarios](../user-guide/certificate-configuration-scenarios.md) to determine which scenario best applies to your use case. Once you have imported or generated a certificate, see [Finalize Certificate Configuration](../user-guide/certificates-finalize-configuration.md). **Option 2:** [Set up Zowe certificates using workflows](../user-guide/certificates-workflow-setup.md) | Your certificates are configured and stored securely|2 hours
## Starting and Stopping Zowe
diff --git a/docs/user-guide/zos-components-installation-checklist.md b/docs/user-guide/zos-components-installation-checklist.md
index d92584369f..4b81500ef3 100644
--- a/docs/user-guide/zos-components-installation-checklist.md
+++ b/docs/user-guide/zos-components-installation-checklist.md
@@ -45,7 +45,7 @@ Zowe is able to use PKCS12 certificates or certificates held in a z/OS Keyring.
| Task | Results | Time Estimate |
|--------------------|----|------|
-| Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:
**Option 1: Choose the [certificate configuration scenario](../user-guide/certificate-configuration-scenarios.md)** that best applies to your use case, and follow the configuration procedure and scenario template.
**Option 2: [Set up Zowe certificates using workflows](../user-guide/certificates-setup.md)** | Your certificates are configured and stored securely. |2 hours
+| Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:
**Option 1: Choose the [certificate configuration scenario](../user-guide/certificate-configuration-scenarios.md)** that best applies to your use case, and follow the configuration procedure and scenario template.