refactor steps

Signed-off-by: Andrew Jandacek <[email protected]>

docs/extend/extend-apiml/authentication-for-apiml-services.md

@@ -105,22 +105,29 @@ with each authentication provider.
 The client can authenticate via Username and password. There are multiple methods which can be used to deliver  
 credentials. For more details, see the ZAAS Client documentation. 
 
-### Authentication with Client certificate
+### Authenticate with Client certificate
 
-It is possible to perform authentication with client certificates. There is a limitation with respect to the ACF2 systems. If you would like to offer feedback using client certificate authentication, please create an issue against the api-layer repository. 
+You can perform authentication with client certificates.
 
-If the keyring or a truststore contains at least one valid certificate authority (CA) other than the CA of API ML, it is possible to use the client certificates issued by this CA to authenticate to API ML. This feature is not enabled by default and needs to be configured.
+If the keyring or a truststore contains at least one valid certificate authority (CA) other than the CA of API ML, it is possible to use the client certificates issued by this CA to authenticate to API ML. This feature is not enabled by default and must be configured.
 
-When providing credentials in any form together with a client certificate on the same login request, the credentials take precedence and the client certificate is ignored.
+:::note
+There is a limitation with respect to ACF2 systems. If you would like to offer feedback using client
+certificate authentication, please create an issue against the api-layer repository.
+:::
+
+When providing credentials with a client certificate on the same login request, the credentials take precedence and the client certificate is ignored.
 
-Authentication against any endpoint is performed in the following way: 
+### How the Gateway resolves authentication 
+
+The Gateway resolves authetication by authenticating against an endpoint through the following process:
 
 * The client calls the service endpoint through API ML Gateway with the client certificate.
 * The client certificate and private key are checked as a valid TLS client certificate against the trusted CAs of the Gateway.
-* The public part of the provided client certificate is checked against SAF. SAF subsequently returns a user ID that owns this certificate. ZSS provides this API for API ML. 
+* The public part of the provided client certificate is checked against SAF. SAF subsequently returns a user ID that owns this certificate. ZSS provides this API for API ML.
 * The Gateway performs the login of the mapped user and provides valid authentication to the southbound service.
 
-Authentication via the login endpoint is performed in the following way:
+The Gateway resolves authentication via the login endpoint through the following process:
 
 * The client calls the API ML Gateway login endpoint with the client certificate.
 * The client certificate and private key are checked as a valid TLS client certificate against the trusted CAs of the Gateway.
@@ -129,40 +136,48 @@ Authentication via the login endpoint is performed in the following way:
 
 ![Zowe client certificate authentication diagram](../../images/api-mediation/zowe-client-cert-auth.png)
 
-### Procedure to authenticate with client certificates
-
-Follow these steps to authenticate with client certificates:
+### Prerequisites
 
 1. Specify the Zowe runtime user and set your protection by password. The user is created with the `NOPASSWORD` parameter by the Zowe installer. It is necessary to change this password. For RACF, issue the following TSO command:  
 `ALTUSER <ZOWE_RUNTIME_USER (ZWESVUSR by default)> PASSWORD(<NEWPASSWORD>)`  
 For other security systems, refer to the documentation for an equivalent command.
 
+<!-- Add sample command and output -->
+
 2. Verify that the Zowe runtime user is allowed to log in to z/OSMF. (Check that the user is member of the default `IZUUSER` group.)
 
+<!-- Add how to provide this verification.. Sample commands? -->
+
 :::note
-Ensure that you have an external Certificate Authority and signed client certificates. Alternatively, you can generate these certificates in SAF. The client certificate has to have correct `Extended Key Usage` metadata so these metadate can be used for TLS client authentication. (`OID: 1.3.6.1.5.5.7.3.2`)
+Ensure that you have an external Certificate Authority and signed client certificates. Alternatively, you can generate these certificates in SAF. The client certificate must have correct `Extended Key Usage` metadata so the metadate can be used for TLS client authentication. (`OID: 1.3.6.1.5.5.7.3.2`)
 :::
 
-3. Import the client certificates to SAF, or add them to a user profile.  
+### Configure your z/OS system to support client certificate authentication
+
+1. Import the client certificates to SAF, or add them to a user profile.  
 **Examples:** `RACDCERT ADD` or `RACDCERT GENCERT`.  
 For more information, see your security system documentation.
-4. Import the external CA to the truststore or keyring of the API Mediation Layer.
-5. [Configure the Gateway for client certificate authentication](../../user-guide/api-mediation/api-gateway-configuration/#gateway-client-certificate-authentication).
+2. Import the external CA to the truststore or keyring of the API Mediation Layer.
+3. [Configure the Gateway for client certificate authentication](../../user-guide/api-mediation/api-gateway-configuration/#gateway-client-certificate-authentication).
 
 :::note**Notes:**
 * PassTicket generation must be enabled for the Zowe runtime user. The user has to be able to generate a PassTicket for itself and for the APPLID of z/OSMF. For more information, see [Configure Passticket](#authentication-with-passtickets).
-* The Zowe runtime user has to be enabled to perform identity mapping in SAF. For more information, see [Additional security rights that need to be granted](../../user-guide/configure-zos-system/#configure-main-Zowe-server-use-identity-mapping).
+* The Zowe runtime user must be enabled to perform identity mapping in SAF. For more information, see [Additional security rights that need to be granted](../../user-guide/configure-zos-system/#configure-main-Zowe-server-use-identity-mapping).
 * ZSS has to be configured to participate in Zowe SSO. For more information, see [Configure components zss](../../appendix/zowe-yaml-configuration/#configure-component-zss).
 :::
 
 #### Validate the client certificate functionality
 
-To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was setup using the steps in the previous section, _Procedure to authenticate with client certificates_. The following example uses curl, which is generally available on Linux based systems. 
+To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was setup using the steps in _Configure your z/OS system to support client certificate authentication_. 
+
+Validate using CURL, a command line utility that runs on Linux based systems:
 
 **Example:**
 ```
 curl --cert /path/to/cert.pem --key /path/to/key.pem https://api-mediation-layer:7554/gateway/api/v1/login
 ```
+<!-- Add outcome -->
+
 
 ### Authentication with JWT Token