language refactor and question re: configuring AT-TLS for Zowe server

docs/user-guide/configuring-at-tls-for-zowe-server.md

@@ -1,13 +1,20 @@
 # Configuring AT-TLS for Zowe Server
 
-You can configure parameters in the Zowe server to enable Zowe to work with AT-TLS. Review this article for information about AT-TLS inbound and outbound rules, and the required configuration to use AT-TLS in high availability. You can also find troubleshooting tips as well as security recommendations.
+You can configure parameters in the Zowe server to enable Zowe to work with AT-TLS. Review this article for information about how to set AT-TLS inbound and outbound rules, and the required configuration to use AT-TLS in high availability. You can also find troubleshooting tips and security recommendations.
 
 :::info Role: security administrator
 :::
 
 ## AT-TLS configuration for Zowe
 
-Follow these steps to configure Zowe to support AT-TLS:
+In the network section in the Zowe.yaml file, set if inbound and outbound traffic rules apply to Zowe. Details about how to set these rules are described in the section [AT-TLS rules](#at-tls-configuration-for-zowe) later in this article.
+
+When AT-TLS is enabled, the Zowe Server components themselves do not handle TLS. Instead, the API Mediation Layer (API ML) utilizes information about the server certificate that is defined in the AT-TLS rule. 
+:::caution Important:
+Ensure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring. 
+:::
+
+**Example yaml:**
 
 ```yaml
 zowe:
@@ -22,7 +29,9 @@ zowe:
             attls: true
 ```
 
-While the Zowe Server components do not handle TLS on its own with AT-TLS enabled, the API Mediation Layer (API ML) requires information about the server certificate that is defined in the AT-TLS rule. Ensure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring. We strongly recommend that AT-TLS be configured with the same Zowe keyring.
+:::tip
+We strongly recommend that AT-TLS be configured with the same Zowe keyring.
+:::
 
 :::note Notes
 
@@ -40,13 +49,13 @@ Outbound AT-TLS rules (i.e. to make a transparent https call through http) that
 
 The Discovery Service endpoints are not reachable by standard API Gateway routing by default.
 
-Zowe v3 includes a new component named ZAAS (Zowe Authentication and Authorization Service). In AT-TLS-aware mode, calls to this service are all internal between API ML components. These must include the X.509 Client Certificate.
+Zowe v3 includes Zowe Authentication and Authorization Service (ZAAS). In AT-TLS-aware mode, calls to the ZAAS service are all internal between API ML components and must include the X.509 Client Certificate.
 :::
 
 ### Limitations
 
-If using AT-TLS with a z/OS Keyring backed by an ICSF hardware module, the only supported configuration is Zowe with z/OSMF authentication provider in JWT mode.
-A LTPA token and SAF provider cannot be used in this configuration because API ML cannot access the hardware key to sign its own tokens.
+If using AT-TLS with a z/OS Keyring backed by an ICSF hardware module, ensure that your Zowe configuration utilizes the z/OSMF authentication provider in JWT mode.
+A LTPA token and SAF provider cannot be used in this configuration as API ML cannot access the hardware key to sign its own tokens.
 Personal Access Tokens (PAT) are not supported in this configuration because API ML cannot access the hardware key to sign the tokens.
 
 ## AT-TLS rules
@@ -104,8 +113,9 @@ TTLSKeyringParms ZoweKeyring
   Keyring ZWEKRNG
 }
 ```
+<!--Can we provide a list of all parameters that need to be set in the previous example with the definitions of those parameters? -->
 
-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:
+Assign the `PortRange` of this inbound rule based on the list of API Mediation Layer components in the `zowe.yaml` file. Ensure that the `PortRange` covers the following components:
 
 | Component | Default Port |
 |----|-----------------------|
@@ -119,11 +129,17 @@ The `PortRange` of this inbound rule is taken from the list of API Mediation Lay
 
 **Follow this step:**
 
-Replace `ZoweKeyring` with the keyring configured for your installation. Follow [the SAF keyring instructions](../getting-started/zowe-certificates-overview.md#saf-keyring) in the article _Zowe Certificates overview_ to configure keyrings for your Zowe instance.
+Replace `ZoweKeyring` with the keyring configured for your installation. 
 
-Note the setting `HandshakeRole`. This setting applies to core services which authenticate through certificates with each other. This setting allows the API Gateway to receive and accept X.509 client certificates from API Clients.
+To configure keyrings for your Zowe instance, see [Use a z/OS keyring-based keystore with Zowe generated certificates](../user-guide/certificate-configuration-scenarios.md#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates).
 
-For more granularity in the AT-TLS rules, separate the rules that need to support Client Certificate authentication (Discovery Service, Gateway Service) from the rules that do not need to support Client Certificate authentication(for example a rule covering API Gateway to an onboarded service).
+:::note Notes:
+
+* The setting `HandshakeRole` applies to core services which authenticate through certificates with each other. This setting allows the API Gateway to receive and accept X.509 client certificates from API Clients.
+
+* For more granularity in the AT-TLS rules, separate the rules that need to support Client Certificate authentication (Discovery Service, Gateway Service) from the rules that do not need to support Client Certificate authentication, for example a rule that applies to communication between the API Gateway and an onboarded service.
+
+:::
 
 ### Outbound rules
 
@@ -146,11 +162,11 @@ TTLSConnectionAction ClientConnectionAction
 }
 ```
 
-#### For z/OSMF
+#### Outbound rule for z/OSMF
 
-This example rule covers the connection between the API Gateway and the z/OSMF instance. This connection is made to authenticate users in z/OS.
+The following example rule applies to the connection between the API Gateway and the z/OSMF instance. This connection is made to authenticate users in z/OS.
 
-If `zowe.network.client.tls.attls` is `true`, this rule is assumed set. The requests to z/OSMF are issued using `http`.
+This rule is set when `zowe.network.client.tls.attls` is set to `true`. The requests to z/OSMF are issued using `http`.
 
 ```bash
 TTLSRule ApimlZosmfClientRule
@@ -184,7 +200,7 @@ TTLSEnvironmentAction ApimlClientEnvironmentAction
 `Jobname` is defined explicitly for the ZAAS component and is formed with the `zowe.job.prefix` setting from `zowe.yaml` plus `AZ` as the ZAAS identifier.
 :::
 
-#### For communication between API Gateway and other core services
+#### Outbound rule for communication between API Gateway and other core services
 
 Use the example in this section as a template for internal connections between API Mediation Layer core services.
 
@@ -223,12 +239,14 @@ TTLSConnectionAdvancedParms ApimlClientX509ConnAdvParms
 }
 ```
 
-#### For communication between API Gateway and southbound services
+#### Outbound rule for communication between API Gateway and southbound services
 
 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 example covers routing scenarios.
+The following example covers routing scenarios.
+
+**Example:**
 
 ```bash
 TTLSRule ApimlServiceClientRule
@@ -265,7 +283,7 @@ Outbound connections from the Gateway to southbound services (onboarded services
 
 :::
 
-#### Services that validate tokens against the API Mediation Layer
+#### Outbound rule for services that validate tokens against the API ML
 
 In this scenario, the services issue a request against the API Gateway to validate the received authentication token.
 
@@ -277,8 +295,8 @@ These service also already have an outbound rule set for the onboarding process
 
 Ensure these rules are followed:
 
-- Outbound rule to Discovery Service: Sends X.509 Client Certificate to authorize the onboarding.
-- Outbound rule to API Gateway: __Do not__ set a Client Certificate.
+- Outbound rule to Discovery Service: Sends X.509 Client Certificate to authorize the onboarding
+- Outbound rule to API Gateway: __Do not__ set a Client Certificate
 
 ### Ciphers
 

docs/user-guide/mvd-configuration.md

@@ -114,7 +114,7 @@ The Inbound rules can be filtered by the listening ports of the servers, but Out
 
 The ports and jobnames can be found in the [Addressing network requirements](./address-network-requirements.md) documentation.
 
-The Outbound rules can have HandshakeRole of Client, but when APIML is enabled, it is required that `app-server` and `zss` include their server certificates as client certificates using the `CertificateLabel` property of a `TTLSConnectionAdvancedParms` rule. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md#for-communication-between-api-gateway-and-other-core-services).
+The Outbound rules can have HandshakeRole of Client, but when APIML is enabled, it is required that `app-server` and `zss` include their server certificates as client certificates using the `CertificateLabel` property of a `TTLSConnectionAdvancedParms` rule. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md#outbound-rule-for-communication-between-api-gateway-and-other-core-services).
 
 The Inbound rules can have a HandshakeRole of Server or ServerWithClientAuth.