From a9c8ec32da68166241a9f3d990140a58411dea42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= <pablo.carle@broadcom.com>
Date: Fri, 8 Nov 2024 17:09:54 +0100
Subject: [PATCH 1/4] update x509 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Pablo Hernán Carle <pablo.carle@broadcom.com>
---
 ...authenticating-with-client-certificates.md | 87 ++++++++++++-------
 ...authenticating-with-client-certificates.md | 45 +++++++---
 2 files changed, 88 insertions(+), 44 deletions(-)

diff --git a/docs/user-guide/authenticating-with-client-certificates.md b/docs/user-guide/authenticating-with-client-certificates.md
index 3245730850..7d0a477ae3 100644
--- a/docs/user-guide/authenticating-with-client-certificates.md
+++ b/docs/user-guide/authenticating-with-client-certificates.md
@@ -3,17 +3,18 @@
 :::info Required roles: system administrator, security administrator
 :::
 
-Authentication for integration with API Mediation Layer (API ML) can also be performed by the client when the service endpoint is called through 
+Authentication for integration with API Mediation Layer (API ML) can also be performed by the client when the service endpoint is called through
 the API ML Gateway with client certificates. This method of authentication requires client certification to be enabled and configured. For details about this configuration, see [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates.md).
 
 :::note Notes:
+
 * When calling the login endpoint with basic authentication credentials, as well as with client certificate, the basic 
-  authentication credentials take precedence and the client certificate is ignored. 
+  authentication credentials take precedence and the client certificate is ignored.
 
 * If you are calling a specific endpoint on one of the onboarded services, API Mediation Layer ignores Basic authentication. In this case, the Basic authentication is not part of the authenticated request.
 :::
 
-## How the Gateway resolves authentication 
+## How the Gateway resolves authentication
 
 When sending a request to a service with a client certificate, the Gateway performs the following process to resolve authentication:
 
@@ -30,11 +31,12 @@ When sending a request to the login endpoint with a client certificate, the Gate
 4. The Gateway then performs the login of the mapped user and returns a valid JWT token.
 
 :::note Notes:
+
 * As of Zowe release 3.0.0, the Internal API ML Mapper is the default API that provides this mapping between the public part of the client certificate and SAF user ID. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, with the noted exception when using ACF2, although we recommend using the internal API ML mapper.
 * For information about ZSS, see the section Zowe runtime in the [Zowe server-side installation overview](./install-zos.md).
 :::
 
-The following diagram shows how routing works with ZSS, in the case where the ZSS API is used for the identity mapping. 
+The following diagram shows how routing works with ZSS, in the case where the ZSS API is used for the identity mapping.
 
 ![Zowe client certificate authentication diagram](../images/api-mediation/zowe-client-cert-auth.png)
 
@@ -42,24 +44,41 @@ The following diagram shows how routing works with ZSS, in the case where the ZS
 For more information, see the Medium blog post [Zowe client certificate authentication](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579).
 :::
 
-## Configure your z/OS system to support client certificate authentication for a specific user
+## Configure your z/OS system to support client certificate authentication for specific users
+
+Register the client certificate with the user IDs in your ESM. 
 
-Register the client certificate with the user ID in your ESM. The following commands apply to both the internal API ML mapper and ZSS.
+The following commands show options for both the internal API ML mapper and ZSS.
 
-**RACF** 
+:::note
+
+If using the internal API ML mapper (default from Zowe v3) and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format as displayed.
+:::
+
+**RACF**
 <details>
-<summary>Click here for an example command in RACF. </summary> 
+<summary>Click here for an example command in RACF. </summary>
 
-  ``` 
-  RACDCERT ADD(<dataset>) ID(<userid>) WITHLABEL('<label>') TRUST
-  SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
+  Activate the `DIGTNMAP` class:
+  
+  ```racf
+  SETROPTS CLASSACT(DIGTNMAP) RACLIST(DIGTNMAP)
   ```
-Alternatively, if you are using the internal API ML mapper, use the following command:
 
-  ```
+  Create the mapping for the user and a distinguished name filter:
+
+  ```racf
   RACDCERT ID(<userid>) MAP 
   SDNFILTER('<subject's-distinguished-name-filter>')
   WITHLABEL('<label>')
+  SETROPTS RACLIST(DIGTMAP) REFRESH
+  ```
+
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID
+
+  ```racf
+  RACDCERT ADD(<dataset>) ID(<userid>) WITHLABEL('<label>') TRUST
+  SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
   ```
 
 </details>
@@ -69,11 +88,9 @@ Alternatively, if you are using the internal API ML mapper, use the following co
 <details>
 <summary>Click here for an example command in ACF2. </summary>  
 
-  `INSERT <userid>.<certname> DSNAME('<dataset>') LABEL(<label>) TRUST`
-
-Alternatively, if you are using the internal API ML mapper, use the following command:
+  Create the mapping for the user and a distinguished name filter:
 
-  ```
+  ```acf2
   CERTMAP.<recid>     
   SDNFILTR(<subject's-distinguished-name-filter>)
   LABEL(<label>)
@@ -81,30 +98,40 @@ Alternatively, if you are using the internal API ML mapper, use the following co
   TRUST
   ```
 
-</details>
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID
 
+  ```acf2
+  INSERT <userid>.<certname> DSNAME('<dataset>') LABEL(<label>) TRUST
+  ```
 
-**Top Secret** 
-
-<details>
-<summary>Click here for an example command in Top Secret. </summary> 
+</details>
 
-  `TSS ADDTO(<userid>) DIGICERT(<certname>) LABLCERT('<label>') DCDSN('<dataset>') TRUST`
+**Top Secret**
 
-Alternatively, if you are using the internal API ML mapper, use the following command:
+<details>
+<summary>Click here for an example command in Top Secret. </summary>
 
-  ```
+  Create the mapping for the user and a distinguished name filter:
+  
+  ```tss
   TSS ADDT0(<userid>) CERTMAP(<recid>)
   SDNFILTR('<subject's-distinguished-name-filter>')
   USERID(<userid>)
   TRUST
   ```
-</details>
 
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID
+
+  ```tss
+  TSS ADDTO(<userid>) DIGICERT(<certname>) LABLCERT('<label>') DCDSN('<dataset>') TRUST
+  ```
+
+</details>
 
 Additional details are likely described in your security system documentation.
 
 :::note Notes
+
 * The alternative ESM map commands allow mapping a certificate to a user without adding the X.509 certificate to the ESM database. While this approach is more convenient, it could be considered less secure than adding the certificate to the ACID, which offers better control and protection.
 * Ensure that you have the Issuer certificate imported in the truststore or in the SAF keyring. Alternatively, you can generate these certificates in SAF.
 * Ensure that the client certificate has the following `Extended Key Usage` metadata:  
@@ -112,16 +139,16 @@ Additional details are likely described in your security system documentation.
 This metadata can be used for TLS client authentication.
 :::
 
-
 ## Validate the client certificate functionality
 
-To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was set up using the steps in [Configure your z/OS system to support client certificate authentication for a specific user](#configure-your-zos-system-to-support-client-certificate-authentication-for-a-specific-user) described previously in this article. 
+To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was set up using the steps in [Configure your z/OS system to support client certificate authentication for a specific user](#configure-your-zos-system-to-support-client-certificate-authentication-for-specific-users) described previously in this article.
 
 Validate using _CURL_, a command line utility that runs on Linux based systems:
 
 **Example:**
-```
+
+```bash
 curl --cert /path/to/cert.pem --key /path/to/key.pem https://api-mediation-layer:7554/gateway/api/v1/login
 ```
-Your Zowe instance is configured to accept x.509 client certificates authentication.
 
+Your Zowe instance is configured to accept x.509 client certificates authentication.
diff --git a/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md b/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
index 3f50dc482f..fbc78c9b92 100644
--- a/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
+++ b/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
@@ -7,22 +7,24 @@ Authentication for integration with API Mediation Layer (API ML) can also be per
 the API ML Gateway with client certificates. Client certification must be enabled and configured. For details about this configuration, see [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates.md).
 
 :::note Notes:
+
 * When calling the login endpoint with basic authentication credentials, as well as with client certificate, the basic 
-  authentication credentials take precedence and the client certificate is ignored. 
+  authentication credentials take precedence and the client certificate is ignored.
 
 * If you are calling a specific endpoint on one of the onboarded services, API Mediation Layer ignores Basic authentication. In this case, the Basic authentication is not part of the authenticated request.
 :::
 
-## How the Gateway resolves authentication 
+## How the Gateway resolves authentication
 
 When sending a request to a service with a client certificate, the Gateway performs the following process to resolve authentication:
 
 1. The client calls the service endpoint through the API ML Gateway with the client certificate.
 2. The client certificate is verified as a valid TLS client certificate against the trusted certificate authorities (CAs) of the Gateway.
 3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe version 2.14, the API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper.
-4. The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service. 
+4. The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service.
 
 :::note Notes:
+
 * Currently, ZSS is the default API that provides this mapping between the public part of the client certificate and SAF user ID. However, the recommended method is to use the internal API ML mapper. For information about the enabling the internal API ML mapper, see [Configure Internal API ML Mapper](./api-mediation/configuration-client-certificates.md#configure-internal-api-ml-mapper) in the article _Enabling single sign on for clients via client certificate configuration_.
 * For information about ZSS, see the section Zowe runtime in the [Zowe server-side installation overview](./install-zos.md).
 :::
@@ -38,7 +40,7 @@ When sending a request to the login endpoint with a client certificate, the Gate
 ZSS is currently the default API that provides this mapping between the public part of the client certificate and SAF user ID. Using the internal API ML mapper is, however, the recommended method.
 :::
 
-The following diagram shows how routing works with ZSS. 
+The following diagram shows how routing works with ZSS.
 
 ![Zowe client certificate authentication diagram](../images/api-mediation/zowe-client-cert-auth.png)
 
@@ -55,31 +57,43 @@ Register the client certificate with the user ID in your ESM. The following comm
 <details>
 <summary>Click here for command details for RACF.</summary>
 
-  ``` 
+  ``` racf
   RACDCERT ADD(<dataset>) ID(<userid>) WITHLABEL('<label>') TRUST
   SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
   ```
-  Alternatively, if you are using the internal API ML mapper, you can use the following command:
+
+  Alternatively, if you are using the internal API ML mapper, you can use the following commands:
+
+  Activate the `DIGTNMAP` class:
   
+  ```racf
+  SETROPTS CLASSACT(DIGTNMAP) RACLIST(DIGTNMAP)
   ```
+
+  Add mapping to the user:
+  
+  ```racf
   RACDCERT ID(<userid>) MAP 
   SDNFILTER('<subject's-distinguished-name-filter>')
   WITHLABEL('<label>')
   ```
+
   **Note:**  The `RACDCERT MAP` command allows mapping a certificate to a user without adding the X.509 certificate to the ESM database. While this approach is more convenient, it could be considered less secure than adding the certificate to the ACID, which offers better control and protection.
 
   </details>
 
-  **ACF2** 
+  **ACF2**
 
   <details>
 <summary>Click here for command details for ACF2.</summary>
 
-  `INSERT <userid>.<certname> DSNAME('<dataset>') LABEL(<label>) TRUST`
+  ```acf2
+  INSERT <userid>.<certname> DSNAME('<dataset>') LABEL(<label>) TRUST
+  ```
 
   Alternatively, if you are using the internal API ML mapper, you can use the following command:
 
-  ```
+  ```acf2
   CERTMAP.<recid>     
   SDNFILTR(<subject's-distinguished-name-filter>)
   LABEL(<label>)
@@ -94,11 +108,13 @@ Register the client certificate with the user ID in your ESM. The following comm
 <details>
 <summary>Click here for command details for Top Secret.</summary>
 
-`TSS ADDTO(<userid>) DIGICERT(<certname>) LABLCERT('<label>') DCDSN('<dataset>') TRUST`
+```
+TSS ADDTO(<userid>) DIGICERT(<certname>) LABLCERT('<label>') DCDSN('<dataset>') TRUST
+```
 
 Alternatively, in case you are using the internal API ML mapper, you can use the following command:
 
-  ```
+  ```tss
   TSS ADDT0(<userid>) CERTMAP(<recid>)
   SDNFILTR('<subject's-distinguished-name-filter>')
   USERID(<userid>)
@@ -110,6 +126,7 @@ Alternatively, in case you are using the internal API ML mapper, you can use the
   Additional details are likely described in your security system documentation.
 
 :::note Notes
+
 * ZSS is currently the default API that provides this mapping between the public part of the client certificate and SAF user ID. Using the internal API ML mapper is, however, the recommended method.
 * The alternative ESM map commands allow mapping a certificate to a user without adding the X.509 certificate to the ESM database. While this approach is more convenient, it could be considered less secure than adding the certificate to the ACID, which offers better control and protection.
 * Ensure that you have the Issuer certificate imported in the truststore or in the SAF keyring. Alternatively, you can generate these certificates in SAF.
@@ -118,7 +135,6 @@ Alternatively, in case you are using the internal API ML mapper, you can use the
 This metadata can be used for TLS client authentication.
 :::
 
-
 ## Validate the client certificate functionality
 
 To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was set up using the steps in [Configure your z/OS system to support client certificate authentication for a specific user](#configure-your-zos-system-to-support-client-certificate-authentication-for-a-specific-user) described previously in this article. 
@@ -126,8 +142,9 @@ To validate that the client certificate functionality works properly, call the l
 Validate using _CURL_, a command line utility that runs on Linux based systems:
 
 **Example:**
-```
+
+```bash
 curl --cert /path/to/cert.pem --key /path/to/key.pem https://api-mediation-layer:7554/gateway/api/v1/login
 ```
-Your Zowe instance is configured to accept x.509 client certificates authentication.
 
+Your Zowe instance is configured to accept x.509 client certificates authentication.

From 417f196d336c41f2a6167eb4993c4d94e9dbe601 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= <pablo.carle@broadcom.com>
Date: Fri, 8 Nov 2024 17:10:42 +0100
Subject: [PATCH 2/4] note about distinguished name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Pablo Hernán Carle <pablo.carle@broadcom.com>
---
 .../user-guide/authenticating-with-client-certificates.md  | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md b/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
index fbc78c9b92..6db3cd3235 100644
--- a/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
+++ b/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
@@ -50,7 +50,12 @@ For more information, see the Medium blog post [Zowe client certificate authenti
 
 ## Configure your z/OS system to support client certificate authentication for a specific user
 
-Register the client certificate with the user ID in your ESM. The following commands apply to both the internal API ML mapper and ZSS.
+Register the client certificate with the user ID in your ESM. The following commands show options for both the internal API ML mapper and ZSS.
+
+:::note
+
+If using the internal API ML mapper and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format as displayed.
+:::
 
 **RACF**  
 

From fea94e9a47dfeed32b703d1eb7a4db6897d11c78 Mon Sep 17 00:00:00 2001
From: Andrew Jandacek <andrew.jandacek@broadcom.com>
Date: Mon, 11 Nov 2024 10:54:02 +0100
Subject: [PATCH 3/4] minor grammar fix

Signed-off-by: Andrew Jandacek <andrew.jandacek@broadcom.com>
---
 docs/user-guide/authenticating-with-client-certificates.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/user-guide/authenticating-with-client-certificates.md b/docs/user-guide/authenticating-with-client-certificates.md
index 7d0a477ae3..47cf4ec05a 100644
--- a/docs/user-guide/authenticating-with-client-certificates.md
+++ b/docs/user-guide/authenticating-with-client-certificates.md
@@ -74,7 +74,7 @@ If using the internal API ML mapper (default from Zowe v3) and the MAP / CERTMAP
   SETROPTS RACLIST(DIGTMAP) REFRESH
   ```
 
-  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID:
 
   ```racf
   RACDCERT ADD(<dataset>) ID(<userid>) WITHLABEL('<label>') TRUST
@@ -120,7 +120,7 @@ If using the internal API ML mapper (default from Zowe v3) and the MAP / CERTMAP
   TRUST
   ```
 
-  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID
+  Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID:
 
   ```tss
   TSS ADDTO(<userid>) DIGICERT(<certname>) LABLCERT('<label>') DCDSN('<dataset>') TRUST

From c05f8193a564881d1471d03972d93402abb18c7f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= <pablo.carle@broadcom.com>
Date: Mon, 11 Nov 2024 11:03:40 +0100
Subject: [PATCH 4/4] pr review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Pablo Hernán Carle <pablo.carle@broadcom.com>
---
 .../authenticating-with-client-certificates.md  | 17 ++++++++++++++---
 .../authenticating-with-client-certificates.md  | 15 +++++++++++++--
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/docs/user-guide/authenticating-with-client-certificates.md b/docs/user-guide/authenticating-with-client-certificates.md
index 47cf4ec05a..7c47d9e19d 100644
--- a/docs/user-guide/authenticating-with-client-certificates.md
+++ b/docs/user-guide/authenticating-with-client-certificates.md
@@ -46,13 +46,13 @@ For more information, see the Medium blog post [Zowe client certificate authenti
 
 ## Configure your z/OS system to support client certificate authentication for specific users
 
-Register the client certificate with the user IDs in your ESM. 
+Register the client certificate with the user IDs in your ESM.
 
 The following commands show options for both the internal API ML mapper and ZSS.
 
 :::note
 
-If using the internal API ML mapper (default from Zowe v3) and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format as displayed.
+If using the internal API ML mapper (default from Zowe v3) and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format of the certificate's distinguished name as displayed.
 :::
 
 **RACF**
@@ -148,7 +148,18 @@ Validate using _CURL_, a command line utility that runs on Linux based systems:
 **Example:**
 
 ```bash
-curl --cert /path/to/cert.pem --key /path/to/key.pem https://api-mediation-layer:7554/gateway/api/v1/login
+curl -X POST \
+--cert /path/to/cert.pem \
+--key /path/to/key.pem \
+https://api-mediation-layer:7554/gateway/api/v1/auth/login -v
 ```
 
+Where:
+
+* `cert`: Specifies the certificate location
+* `key`: Path to the private key
+* `7554`: Replace with the configured API Gateway port in the intance
+
+x.509 Client Certificate authentication is correctly configured if the result of the request is HTTP 200 with an `apimlAuthenticationToken` cookie generated.
+
 Your Zowe instance is configured to accept x.509 client certificates authentication.
diff --git a/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md b/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
index 6db3cd3235..43a1853ca8 100644
--- a/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
+++ b/versioned_docs/version-v2.18.x/user-guide/authenticating-with-client-certificates.md
@@ -54,7 +54,7 @@ Register the client certificate with the user ID in your ESM. The following comm
 
 :::note
 
-If using the internal API ML mapper and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format as displayed.
+If using the internal API ML mapper and the MAP / CERTMAP option with distinguished name filters, use the `CHCKCERT` or equivalent command on the certificate to use the same order and format of the certificate's distinguished name as displayed.
 :::
 
 **RACF**  
@@ -149,7 +149,18 @@ Validate using _CURL_, a command line utility that runs on Linux based systems:
 **Example:**
 
 ```bash
-curl --cert /path/to/cert.pem --key /path/to/key.pem https://api-mediation-layer:7554/gateway/api/v1/login
+curl -X POST \
+--cert /path/to/cert.pem \
+--key /path/to/key.pem \
+https://api-mediation-layer:7554/gateway/api/v1/auth/login -v
 ```
 
+Where:
+
+* `cert`: Specifies the certificate location
+* `key`: Path to the private key
+* `7554`: Replace with the configured API Gateway port in the intance
+
+x.509 Client Certificate authentication is correctly configured if the result of the request is HTTP 200 with an `apimlAuthenticationToken` cookie generated.
+
 Your Zowe instance is configured to accept x.509 client certificates authentication.