User/joewinchester/keyringsupported (#1891)

* troubleshooting tip for BPXTLS failure message Signed-off-by: Joe-Winchester <[email protected]> * Added as optional to the core system requirements chapter Signed-off-by: Joe-Winchester <[email protected]> * Keyrings now supported Signed-off-by: Joe-Winchester <[email protected]> * edits Signed-off-by: nannanli <[email protected]> Co-authored-by: nannanli <[email protected]>
zowe · Nov 10, 2021 · 682b44a · 682b44a
1 parent 8213257
commit 682b44a
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 12 deletions.
diff --git a/docs/troubleshoot/app-framework/app-troubleshoot.md b/docs/troubleshoot/app-framework/app-troubleshoot.md
@@ -318,3 +318,23 @@ When you log in to the Zowe Desktop, you cannot open the JES, MVS, or USS Explor
 **Solution:**
 
 A new property `ZOWE_EXPLORER_FRAME_ANCESTORS` was introduced in V1.12. This property is required to be present in the `instance.env` file with some valid value. When undefined, it is treated as Boolean, which breaks the string split function. To resolve the issue, define the value for this property in the `instance.env` file. 
+
+## Warning: Zowe extensions access to ZSS security endpoints fail 
+
+**Symptom:**
+
+Zowe extensions fail when accessing the ZSS APIs such as the `security-mgmt/classes/default-class/profiles` endpoint. The following error is written to the log.
+
+```
+BPXTLS failed: rc=-1, return code=163, reason code=0x0be80820
+```
+
+**Solution:**
+
+Access to the ZSS endpoints are protected. To access the ZSS endpoints, the user must have `READ` access on the `OMVSAPPL` resource in the `APPL` class.
+
+To fix this permit access, issue the following TSO command, where `userID` is the started task ID of the requesting process. The vendor documentation describes which userID to use which might be `ZWESVUSR`.  
+
+```
+PERMIT OMVSAPPL CLASS(APPL) ACCESS(READ) ID(userID)
+```
diff --git a/docs/user-guide/configure-certificates.md b/docs/user-guide/configure-certificates.md
@@ -41,23 +41,19 @@ The lines in bold green are external certificates for servers that are not manag
 
 ## Keystore versus key ring
 
-Zowe supports certificates that are stored in a USS directory **Java KeyStore** format.  
-
-Beginning with release 1.15, Zowe is including the ability to work with certificates held in a **z/OS Keyring**.  Support for Keyring certificates is currently incomplete and being provided as a beta technical preview for early preview by customers.  If you have any feedback using keyrings please create an issue in the [zowe-install-packaging repo](https://github.com/zowe/zowe-install-packaging/issues).  It is expected that in a future release keyring support will be made available as a fully supported feature.  
-
-<!--
 Zowe supports certificates that are stored either in a USS directory **Java KeyStore** format or else held in a **z/OS Keyring**.  z/OS keystore are the preferred choice for storing certificates where system programmers are already familiar with their operation and usage.  The user ID setting up a keystore and connecting it with certificates requires elevated permissions, and in scenarios where you need to create a Zowe sandbox environment or for testing purposes and your TSO user ID doesn't have authority to manipulate key rings, USS keystores are a good alternative.  
--->
-
-<!--
 
-If you are using a USS keystore, then the script `zowe-setup-certificates.env` is the only configuration step required.  This is described in detail in [Configuring Zowe certificates in a USS KeyStore](./configure-certificates-keystore.md).
+- If you are using a USS keystore, then the script `zowe-setup-certificates.env` is the configuration step required to create the USS directory that contains the certificate.  This is described in detail in [Configuring Zowe certificates in a USS KeyStore](./configure-certificates-keystore.md).
 
-If you are using a key ring, the sample JCL member `ZWEKRING` provided in the PDS library `SZWESAMP` contains the security commands to create a key ring and manage its associated certificates. This is described in [Configuring Zowe certificates in a key ring](./configure-certificates-keyring.md).  
+- If you are using a key ring, the sample JCL member `ZWEKRING` provided in the PDS library `SZWESAMP` contains the security commands to create a key ring and manage its associated certificates. This is described in [Configuring Zowe certificates in a key ring](./configure-certificates-keyring.md) which provides instructions for how to configure Zowe to work with the following certificates.
+  - a self-signed certificate
+  - a certificate signed with an existing certificate authority
+  - an existing certificate already held in the SAF database that can be added to the Zowe key ring.  
 
 For both scenarios, where the certificate is held in a USS Java Keystore or a z/OS key ring, the USS `KEYSTORE_DIRECTORY` is still required which is created with the script `zowe-setup-certificates.sh`.  
 
--->
+- In the USS scenario, this directory holds the `.cer` and `.pem` files for the certificate itself.
+- In the key ring scenario, this directory stores the location and name of the Zowe key ring and its certificates.  
 
 ## Keystore directory creation
 
@@ -82,4 +78,4 @@ At launch time, a Zowe instance is started using the script `<INSTANCE_DIR>/bin/
 **Note:** If you generated your own server certificate, and you want to enable Client Authentication for it, your server certificate must contain the `TLS Web Client Authentication (1.3.6.1.5.5.7.3.2)` value in the Extended Key Usage section. 
 Additionally, the `Digital signature and/or key agreement` must also be set as extension value in the Key Usage section. For more information, see [key usage extensions and extended key usage](https://help.hcltechsw.com/domino/10.0.1/admin/conf_keyusageextensionsandextendedkeyusage_r.html).
 
-For more information on the Zowe launch topology, see [Topology of the Zowe z/OS launch process](./installandconfig.md#topology-of-the-zowe-z-os-launch-process).
+For more information on the Zowe launch topology, see [Topology of the Zowe z/OS launch process](./installandconfig.md#topology-of-the-zowe-z-os-launch-process).
diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md
@@ -87,6 +87,7 @@ The task starts a USS environment using `BPXBATSL` that executes the core Zowe D
 | FACILITY | `IRR.RUSERMAP` | READ | To allow Zowe to [map an X.509 client certificate to a z/OS identity](./configure-zos-system.md#configure-main-zowe-server-to-use-identity-mapping) | 
 | FACILITY | `BPX.JOBNAME` | READ | To allow z/OS address spaces for unix processes to be renamed for [ease of identification](./configure-zos-system.md#configure-address-space-job-naming) |
 | FACILITY | `IRR.RADMIN.LISTUSER` | READ | To allow Zowe to obtain information about OMVS segment of the user profile using `LISTUSER` TSO command |
+| APPL     | 'OMVSAPPL' | READ | **Optional** To allow Zowe Desktop vendor extensions the ability to use single-sign on.  
 
 ### ZWESIUSR