Merge pull request #3994 from zowe/reboot/fix/attls-missingblock

Add missing block in AT-TLS configuration
zowe · Nov 19, 2024 · 54cff7c · 54cff7c
2 parents cf7e633 + dba55ab
commit 54cff7c
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 73 deletions.
diff --git a/docs/user-guide/configuring-at-tls-for-zowe-server.md b/docs/user-guide/configuring-at-tls-for-zowe-server.md
@@ -5,27 +5,6 @@ You can configure parameters in the Zowe server to enable Zowe to work with AT-T
 :::info Role: security administrator
 :::
 
-- [Configuring AT-TLS for Zowe Server](#configuring-at-tls-for-zowe-server)
-  - [AT-TLS configuration for Zowe](#at-tls-configuration-for-zowe)
-    - [Limitations](#limitations)
-  - [AT-TLS rules](#at-tls-rules)
-    - [Inbound rules](#inbound-rules)
-    - [Outbound rules](#outbound-rules)
-      - [For z/OSMF](#for-zosmf)
-      - [For communication between API Gateway and other core services](#for-communication-between-api-gateway-and-other-core-services)
-      - [For communication between API Gateway and southbound services](#for-communication-between-api-gateway-and-southbound-services)
-      - [Services that validate tokens against the API Mediation Layer](#services-that-validate-tokens-against-the-api-mediation-layer)
-    - [Ciphers](#ciphers)
-  - [Using AT-TLS for API ML in High Availability](#using-at-tls-for-api-ml-in-high-availability)
-  - [Multi-tenancy deployment](#multi-tenancy-deployment)
-  - [AT-TLS Troubleshooting](#at-tls-troubleshooting)
-    - [The message `This combination of port requires SSL` is thrown when accesing an API ML service through a Browser](#the-message-this-combination-of-port-requires-ssl-is-thrown-when-accesing-an-api-ml-service-through-a-browser)
-    - [AT-TLS rules are not applied](#at-tls-rules-are-not-applied)
-    - [Non matching ciphers / protocols](#non-matching-ciphers--protocols)
-    - [Additional troubleshooting](#additional-troubleshooting)
-  - [Full example of AT-TLS configuration](#full-example-of-at-tls-configuration)
-  - [Additional Zowe feature configuration with AT-TLS](#additional-zowe-feature-configuration-with-at-tls)
-
 ## AT-TLS configuration for Zowe
 
 Follow these steps to configure Zowe to support AT-TLS:
@@ -110,6 +89,20 @@ TTLSConnectionAction ZoweServerConnectionAction
   TTLSCipherParmsRef CipherParms
   TTLSConnectionAdvancedParmsRef ZoweConnectionAdvParms
 }
+
+TTLSConnectionAdvancedParms ZoweConnectionAdvParms
+{
+  ApplicationControlled Off
+  ServerCertificateLabel apimlcert # Specify the personal server certificate used for the Zowe Server
+  CertificateLabel apimlcert # Specify the personal server certificate used for the Zowe Server
+  SecondaryMap Off
+}
+
+# Keyring, used for TLS, will be used also to load trusted certificates
+TTLSKeyringParms ZoweKeyring
+{
+  Keyring ZWEKRNG
+}
 ```
 
 The `PortRange` of this inbound rule is taken from the list of API Mediation Layer components in the `zowe.yaml` file. The `PortRange` should cover the following components:
@@ -137,7 +130,7 @@ For more granularity in the AT-TLS rules, separate the rules that need to suppor
 Outbound rules in this section allow Zowe services to communicate with each other and to other southbound services using HTTP.
 
 :::caution Important:
-Careful consideration needs to be set especially regarding which rules are to be configured to send a Client Certificate. Since configuration cannot be performed on a per-request basis it is essential not to configure the rule to send the Zowe Server certificate to the API Gateway or to a southbound service that supports X.509 Client Certificate authentication. Doing so will result in unintentionally authenticating the server ACID.
+Careful consideration needs to be made regarding which rules are to be configured to send a Client Certificate. Since configuration cannot be performed on a per-request basis, it is essential not to configure the rule to send the Zowe Server certificate to the API Gateway or to a southbound service that supports X.509 Client Certificate authentication. Doing so will result in unintentionally authenticating the server ACID.
 
 :::
 
@@ -235,7 +228,7 @@ TTLSConnectionAdvancedParms ApimlClientX509ConnAdvParms
 In this example, the rule covers all outbound connections originating from the API Gateway to an example southbound service listening on port 8080.
 This rule applies for Zowe services as well, such as the ZSS and app-server if they are enabled.
 
-This covers routing scenarios.
+This example covers routing scenarios.
 
 ```bash
 TTLSRule ApimlServiceClientRule
@@ -268,19 +261,19 @@ TTLSConnectionAdvancedParms ApimlClientNoX509ConnAdvParms
 
 :::caution Important
 
-Outbound connections from the Gateway to southbound services (onboarded services) must not send the server certificate if the service accepts X.509 Client Certificate authentication. If the server certificate is sent, it is the server user who would be authenticated.
+Outbound connections from the Gateway to southbound services (onboarded services) must not send the server certificate if the service accepts X.509 Client Certificate authentication. If the server certificate is sent, the server user is subsequently authenticated.
 
 :::
 
 #### Services that validate tokens against the API Mediation Layer
 
-In this scenario, the services will issue a request against the API Gateway to validate the received authentication token.
+In this scenario, the services issue a request against the API Gateway to validate the received authentication token.
 
-This scenario includes services that set `zoweJwt` as authentication scheme, those that require an Open ID Connect (OIDC) token, or forwarded X.509 certificates.
+This scenario includes services that set `zoweJwt` as the authentication scheme, those that require an Open ID Connect (OIDC) token, or forwarded X.509 certificates.
 
-In this case it is necessary to have an Outbound rule from the service to the API Gateway.
+In this case, it is necessary to have an Outbound rule from the service to the API Gateway.
 
-These service will also already have an outbound rule set for the onboarding process against the Discovery Service.
+These service also already have an outbound rule set for the onboarding process against the Discovery Service.
 
 Ensure these rules are followed:
 
@@ -425,7 +418,6 @@ TTLSEnvironmentAction ZoweServerEnvironmentAction
   EnvironmentUserInstance 0
   TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms
   TTLSKeyringParmsRef ZoweKeyring
-  TTLSSignatureParmsRef TNESigParms
 }
 
 # Environment action for sample southbound service
@@ -435,7 +427,6 @@ TTLSEnvironmentAction ZoweDCServerEnvironmentAction
   EnvironmentUserInstance 0
   TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms
   TTLSKeyringParmsRef ZoweKeyring
-  TTLSSignatureParmsRef TNESigParms
 }
 
 # Keyring, used for TLS, will be used also to load trusted certificates
@@ -464,7 +455,6 @@ TTLSConnectionAction ZoweServerConnectionAction
   HandshakeRole ServerWithClientAuth # API ML Core Services use Client Certificate authentication
   TTLSCipherParmsRef CipherParms
   TTLSConnectionAdvancedParmsRef ZoweConnectionAdvParms
-  TTLSSignatureParmsRef TNESigParms
 }
 
 # API ML Server connection action.
@@ -552,10 +542,9 @@ TTLSRule ApimlZLUXClientRule
 TTLSEnvironmentAction ApimlClientEnvironmentAction
 {
   HandshakeRole Client
-  TTLSKeyringParmsRef ApimlKeyring
+  TTLSKeyringParmsRef ZoweKeyring
   TTLSEnvironmentAdvancedParmsRef ClientEnvironmentAdvParms
   EnvironmentUserInstance 0
-  TTLSSignatureParmsRef TNESigParms
 }
 
 TTLSEnvironmentAdvancedParms ClientEnvironmentAdvParms
@@ -615,11 +604,6 @@ TTLSConnectionAdvancedParms ZoweClientX509ConnAdvParms
   TLSv1.3 On
 }
 
-TTLSSignatureParms TNESigParms
-{
-  CLientECurves Any
-}
-
 # Example list of supported ciphers in handshake. Validate and filter this list based on local setup
 TTLSCipherParms                   CipherParms
 {

diff --git a/versioned_docs/version-v2.18.x/user-guide/configuring-at-tls-for-zowe-server.md b/versioned_docs/version-v2.18.x/user-guide/configuring-at-tls-for-zowe-server.md
@@ -5,26 +5,6 @@ You can configure parameters in the Zowe server to enable Zowe to work with AT-T
 :::info Role: security administrator
 :::
 
-- [AT-TLS configuration for Zowe](#at-tls-configuration-for-zowe)
-  - [Limitations](#limitations)
-- [AT-TLS rules](#at-tls-rules)
-  - [Inbound rules](#inbound-rules)
-  - [Outbound rules](#outbound-rules)
-    - [For z/OSMF](#for-zosmf)
-    - [For communication between API Gateway and other core services](#for-communication-between-api-gateway-and-other-core-services)
-    - [For communication between API Gateway and southbound services](#for-communication-between-api-gateway-and-southbound-services)
-    - [Services that validate tokens against the API Mediation Layer](#services-that-validate-tokens-against-the-api-mediation-layer)
-  - [Ciphers](#ciphers)
-- [Using AT-TLS for API ML in High Availability](#using-at-tls-for-api-ml-in-high-availability)
-- [Multi-tenancy deployment](#multi-tenancy-deployment)
-- [AT-TLS Troubleshooting](#at-tls-troubleshooting)
-  - [The message `This combination of port requires SSL` is thrown when accesing an API ML service through a Browser](#the-message-this-combination-of-port-requires-ssl-is-thrown-when-accesing-an-api-ml-service-through-a-browser)
-  - [AT-TLS rules are not applied](#at-tls-rules-are-not-applied)
-  - [Non matching ciphers / protocols](#non-matching-ciphers--protocols)
-  - [Additional troubleshooting](#additional-troubleshooting)
-- [Full example of AT-TLS configuration](#full-example-of-at-tls-configuration)
-- [Additional Zowe feature configuration with AT-TLS](#additional-zowe-feature-configuration-with-at-tls)
-
 ## AT-TLS configuration for Zowe
 
 :::tip
@@ -118,6 +98,20 @@ TTLSConnectionAction ZoweServerConnectionAction
   TTLSCipherParmsRef CipherParms
   TTLSConnectionAdvancedParmsRef ZoweConnectionAdvParms
 }
+
+TTLSConnectionAdvancedParms ZoweConnectionAdvParms
+{
+  ApplicationControlled Off
+  ServerCertificateLabel apimlcert # Specify the personal server certificate used for the Zowe Server
+  CertificateLabel apimlcert # Specify the personal server certificate used for the Zowe Server
+  SecondaryMap Off
+}
+
+# Keyring, used for TLS, will be used also to load trusted certificates
+TTLSKeyringParms ZoweKeyring
+{
+  Keyring ZWEKRNG
+}
 ```
 
 The `PortRange` of this inbound rule is taken from the list of API Mediation Layer components in the `zowe.yaml` file. The `PortRange` should cover the following components:
@@ -145,7 +139,7 @@ For more granularity in the AT-TLS rules, separate the rules that need to suppor
 Outbound rules in this section allow Zowe services to communicate with each other and to other southbound services using HTTP.
 
 :::caution Important:
-Careful consideration needs to be set especially regarding which rules are to be configured to send a Client Certificate. Since configuration cannot be performed on a per-request basis it is essential not to configure the rule to send the Zowe Server certificate to the API Gateway or to a southbound service that supports X.509 Client Certificate authentication. Doing so will result in unintentionally authenticating the server ACID.
+Careful consideration needs to be made regarding which rules are to be configured to send a Client Certificate. Since configuration cannot be performed on a per-request basis, it is essential not to configure the rule to send the Zowe Server certificate to the API Gateway or to a southbound service that supports X.509 Client Certificate authentication. Doing so results in unintentionally authenticating the server ACID.
 
 :::
 
@@ -243,7 +237,7 @@ TTLSConnectionAdvancedParms ApimlClientX509ConnAdvParms
 In this example, the rule covers all outbound connections originating from the API Gateway to an example southbound service listening on port 8080.
 This rule applies for Zowe services as well, such as the ZSS and app-server if they are enabled.
 
-This covers routing scenarios.
+This example covers routing scenarios.
 
 ```bash
 TTLSRule ApimlServiceClientRule
@@ -276,19 +270,19 @@ TTLSConnectionAdvancedParms ApimlClientNoX509ConnAdvParms
 
 :::caution Important
 
-Outbound connections from the Gateway to southbound services (onboarded services) must not send the server certificate if the service accepts X.509 Client Certificate authentication. If the server certificate is sent, it is the server user who would be authenticated.
+Outbound connections from the Gateway to southbound services (onboarded services) must not send the server certificate if the service accepts X.509 Client Certificate authentication. If the server certificate is sent, the server user is subsequently authenticated.
 
 :::
 
 #### Services that validate tokens against the API Mediation Layer
 
-In this scenario, the services will issue a request against the API Gateway to validate the received authentication token.
+In this scenario, the services issue a request against the API Gateway to validate the received authentication token.
 
 This scenario includes services that set `zoweJwt` as authentication scheme, those that require an Open ID Connect (OIDC) token, or forwarded X.509 certificates.
 
 In this case it is necessary to have an Outbound rule from the service to the API Gateway.
 
-These service will also already have an outbound rule set for the onboarding process against the Discovery Service.
+These service also already have an outbound rule set for the onboarding process against the Discovery Service.
 
 Ensure these rules are followed:
 
@@ -432,7 +426,6 @@ TTLSEnvironmentAction ZoweServerEnvironmentAction
   EnvironmentUserInstance 0
   TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms
   TTLSKeyringParmsRef ZoweKeyring
-  TTLSSignatureParmsRef TNESigParms
 }
 
 # Environment action for sample southbound service
@@ -442,7 +435,6 @@ TTLSEnvironmentAction ZoweDCServerEnvironmentAction
   EnvironmentUserInstance 0
   TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms
   TTLSKeyringParmsRef ZoweKeyring
-  TTLSSignatureParmsRef TNESigParms
 }
 
 # Keyring, used for TLS, will be used also to load trusted certificates
@@ -471,7 +463,6 @@ TTLSConnectionAction ZoweServerConnectionAction
   HandshakeRole ServerWithClientAuth # API ML Core Services use Client Certificate authentication
   TTLSCipherParmsRef CipherParms
   TTLSConnectionAdvancedParmsRef ZoweConnectionAdvParms
-  TTLSSignatureParmsRef TNESigParms
 }
 
 # API ML Server connection action.
@@ -545,10 +536,9 @@ TTLSRule ApimlZLUXClientRule
 TTLSEnvironmentAction ApimlClientEnvironmentAction
 {
   HandshakeRole Client
-  TTLSKeyringParmsRef ApimlKeyring
+  TTLSKeyringParmsRef ZoweKeyring
   TTLSEnvironmentAdvancedParmsRef ClientEnvironmentAdvParms
   EnvironmentUserInstance 0
-  TTLSSignatureParmsRef TNESigParms
 }
 
 TTLSEnvironmentAdvancedParms ClientEnvironmentAdvParms
@@ -608,11 +598,6 @@ TTLSConnectionAdvancedParms ZoweClientX509ConnAdvParms
   TLSv1.3 On
 }
 
-TTLSSignatureParms TNESigParms
-{
-  CLientECurves Any
-}
-
 # Example list of supported ciphers in handshake. Validate and filter this list based on local setup
 TTLSCipherParms                   CipherParms
 {