From 838cc3ceb2cda6254427b843fdfdaae4968d3d5b Mon Sep 17 00:00:00 2001 From: anaxceron Date: Tue, 5 Nov 2024 16:05:32 -0500 Subject: [PATCH 01/12] proxy env variable doc Signed-off-by: anaxceron --- docs/user-guide/cli-configuringcli-ev.md | 10 ++++++++++ .../cli-using-formatting-environment-variables.md | 1 - .../cli-using-using-environment-variables.md | 2 +- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/cli-configuringcli-ev.md b/docs/user-guide/cli-configuringcli-ev.md index f9a627604d..79a988e2bd 100644 --- a/docs/user-guide/cli-configuringcli-ev.md +++ b/docs/user-guide/cli-configuringcli-ev.md @@ -74,3 +74,13 @@ Use the `--show-inputs-only` option in a Zowe CLI command to view the property v | Environment variable | Description | Values | Default | | ---------------------- | ----------- |------- | ------- | | `ZOWE_SHOW_SECURE_ARGS` | Displays secure property values used by a Zowe CLI command | `TRUE`, `FALSE` | `FALSE` | + +## Using Zowe CLI with a proxy + +If your network configuration requires communication with the mainframe to be performed through a proxy server, set environment variables to route Zowe CLI traffic through an HTTP/HTTPS proxy. + +| Environment Variable | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `HTTPS_PROXY`, `https_proxy` | Use the `https` proxy to route communication to the mainframe when your proxy server supports `https`. | +| `HTTP_PROXY`, `http_proxy` | Use the `http` proxy to route communication to the mainframe. | +| `NO_PROXY` | Set a list of host addresses (separated by commas) to connect to the specified hosts without going through a proxy.| diff --git a/docs/user-guide/cli-using-formatting-environment-variables.md b/docs/user-guide/cli-using-formatting-environment-variables.md index 523a3aa80c..102ea11d61 100644 --- a/docs/user-guide/cli-using-formatting-environment-variables.md +++ b/docs/user-guide/cli-using-formatting-environment-variables.md @@ -19,4 +19,3 @@ The following table provides examples of CLI options and the corresponding envir | `--user` | `ZOWE_OPT_USER` | Define your mainframe username to an environment variable to avoid specifying it on all commands or profiles. | | `--reject-unauthorized` | `ZOWE_OPT_REJECT_UNAUTHORIZED` | Define a value of `true` to the `--reject-unauthorized` flag when you always require the flag and do not want to specify it on all commands or profiles. | | `--editor` | `ZOWE_OPT_EDITOR` | Define an editor that Zowe CLI uses to open files. The value can be either the editor's executable file location or the name of a program (for example, *notepad* on Windows or *nano* on Linux).| - diff --git a/docs/user-guide/cli-using-using-environment-variables.md b/docs/user-guide/cli-using-using-environment-variables.md index 51d9c889e1..91fa1a17c1 100644 --- a/docs/user-guide/cli-using-using-environment-variables.md +++ b/docs/user-guide/cli-using-using-environment-variables.md @@ -53,4 +53,4 @@ pipeline { } ``` -For more information on Jenkins credential storage, see [Using credentials](https://www.jenkins.io/doc/book/using/using-credentials/) and Using a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#for-secret-text-usernames-and-passwords-and-secret-files). \ No newline at end of file +For more information on Jenkins credential storage, see [Using credentials](https://www.jenkins.io/doc/book/using/using-credentials/) and Using a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#for-secret-text-usernames-and-passwords-and-secret-files). From e789ebdaef8a7019cb949707a74c6286313354b0 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Fri, 8 Nov 2024 13:47:59 +0100 Subject: [PATCH 02/12] change title for v2 ref to vx ref Signed-off-by: Andrew Jandacek --- docs/whats-new/zowe-v3-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/whats-new/zowe-v3-migration.md b/docs/whats-new/zowe-v3-migration.md index 278c7999d9..51970b7322 100644 --- a/docs/whats-new/zowe-v3-migration.md +++ b/docs/whats-new/zowe-v3-migration.md @@ -1,6 +1,6 @@ -# Migrating from Zowe V2 to Zowe V3 +# Migrating from Zowe Vx to Zowe V3 -Follow the procedure outlined in this article to migrate from Zowe v2 to Zowe v3. While the migration process is similar to a Zowe v2 minor release upgrade, there are several new and updated configuration parameters to consider. The workspace directory should be re-created only if you are using the app-server component. +Follow the procedure outlined in this article to migrate from Zowe v2 to Zowe v3, or Zowe v1 to Zowe v3. While the migration process is similar to a Zowe v2 minor release upgrade, there are several new and updated configuration parameters to consider. The workspace directory should be re-created only if you are using the app-server component. Follow the steps described in this article to ensure a smooth migration. From a9c8ec32da68166241a9f3d990140a58411dea42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Fri, 8 Nov 2024 17:09:54 +0100 Subject: [PATCH 03/12] 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 --- ...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**
-Click here for an example command in RACF. +Click here for an example command in RACF. - ``` - RACDCERT ADD() ID() WITHLABEL('
@@ -69,11 +88,9 @@ Alternatively, if you are using the internal API ML mapper, use the following co
Click here for an example command in ACF2. - `INSERT . DSNAME('') LABEL(
+ Alternatively, if you disabled the internal API ML mapper, use the following command to add the certificate to an ACID + ```acf2 + INSERT . DSNAME('') LABEL(