From c683b5f2bc4e3036e3c5fb66b486e790971fd67d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Thu, 17 Oct 2024 17:00:10 +0200 Subject: [PATCH 1/7] v2 update attls documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../api-mediation/configuration-at-tls.md | 329 --------- .../user-guide/at-tls-configuration.md | 672 +++++++++++++++++- .../version-v2.18.x-sidebars.json | 1 - 3 files changed, 663 insertions(+), 339 deletions(-) delete mode 100644 versioned_docs/version-v2.18.x/user-guide/api-mediation/configuration-at-tls.md diff --git a/versioned_docs/version-v2.18.x/user-guide/api-mediation/configuration-at-tls.md b/versioned_docs/version-v2.18.x/user-guide/api-mediation/configuration-at-tls.md deleted file mode 100644 index 48131622ac..0000000000 --- a/versioned_docs/version-v2.18.x/user-guide/api-mediation/configuration-at-tls.md +++ /dev/null @@ -1,329 +0,0 @@ -# Configuring AT-TLS for API Mediation Layer - -Review this article for descriptions of the configuration parameters required to make Zowe API Mediation Layer work with AT-TLS, including AT-TLS inbound and outbound rules, using AT-TLS in high availability, and troubleshooting. Security recommendations are also provided. - -:::info Role: security administrator -::: - -- [AT-TLS configuration for Zowe](#at-tls-configuration-for-zowe) -- [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) - - [Ciphers](#ciphers) -- [Using AT-TLS for API ML in High Availability](#using-at-tls-for-api-ml-in-high-availability) -- [AT-TLS Troubleshooting](#at-tls-troubleshooting) - -## AT-TLS configuration for Zowe - -:::tip -Support for AT-TLS was introduced in Zowe v1.24. In this early version, startup was not possible in some versions of Zowe. For full support, we recommend that you upgrade to v2.13 or a later version of Zowe. -::: - -Follow these steps to configure Zowe to support AT-TLS: - -1. Enable the AT-TLS profile and disable the TLS application in API ML. -Update `zowe.yaml` with the following values under `gateway`, `discovery`, `api-catalog`, `caching-service` and `metrics-service` in the `zowe.components` section. - -**Example:** - -```yaml -zowe: - components: - gateway: - spring: - profiles: - active: attls - server: - ssl: - enabled: false - internal: - ssl: - enabled: false - discovery: - spring: - profiles: - active: attls - server: - ssl: - enabled: false - api-catalog: - spring: - profiles: - active: attls - server: - ssl: - enabled: false - caching-service: - spring: - profiles: - active: attls - server: - ssl: - enabled: false - metrics-service: - spring: - profiles: - active: attls - server: - ssl: - enabled: false -``` - -While API ML does not handle TLS on its own with AT-TLS enabled, 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. Ideally, AT-TLS should be configured with the same Zowe keyring. - -If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. - -:::note Notes -* AT-TLS is supported in the API Cloud Gateway Mediation Layer component beginning with version 2.17. - -* As the Gateway is a core component of API ML, other components that need to interact with the Gateway, such as Zowe ZLUX App Server, also require AT-TLS configuration. -::: - -:::caution Important security consideration - -Configuring AT-TLS for the Zowe API Mediation Layer requires careful consideration of security settings. These security settings apply to the Client Certificate authentication feature in Zowe API Mediation Layer components, as well as for onboarded services that support the x.509 client certificates authentication scheme. - -Outbound AT-TLS rules (i.e. to make a transparent https call through http) that are configured to send the server certificate should be limited to the services that __require__ service to service authentication. If an API ML-onboarded southbound service needs to support x.509 client certificate authentication, we recommend to use the integrated TLS handshake capabilities of API ML. Do not configure an outbound AT-TLS rule for these services. - -The Discovery Service endpoints are not reachable by standard API Gateway routing by default. -::: - -## AT-TLS rules - -This section describes suggested AT-TLS settings, and serves as guidelines to set your AT-TLS rules. - -### Inbound rules - -A generic inbound rule can be set for all core API Mediation Layer services: - -```pagent -TTLSRule ApimlServerRule -{ - LocalAddr All - RemoteAddr All - LocalPortRange 7551-7555 - Jobname ZWE* - Direction Inbound - TTLSGroupActionRef ServerGroupAction - TTLSEnvironmentActionRef ApimlServerEnvironmentAction - TTLSConnectionActionRef ApimlServerConnectionAction -} - -TTLSGroupAction ServerGroupAction -{ - TTLSEnabled On -} - -TTLSEnvironmentAction ApimlServerEnvironmentAction -{ - HandshakeRole ServerWithClientAuth - EnvironmentUserInstance 0 - TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms - TTLSKeyringParmsRef ApimlKeyring -} - -TTLSConnectionAction ApimlServerConnectionAction -{ - HandshakeRole ServerWithClientAuth - TTLSCipherParmsRef CipherParms - TTLSConnectionAdvancedParmsRef ApimlConnectionAdvParms -} -``` - -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: - -| Component | Port | -|----|-----------------------| -| Gateway | default port 7554 | -| Discovery | default port 7553 | -|Caching Service | 7555 | -|API Catalog | default port 7552 | -| Metrics Service | default port 7551 | - -**Follow this step:** - -Replace `ApimlKeyring` 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. - -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. - -### Outbound rules - -#### For z/OSMF - -```pagent -TTLSRule ApimlZosmfClientRule -{ - LocalAddr All - LocalPortRange 1024-65535 - RemoteAddr All - RemotePortRange 449 - Jobname ZWE1AG* - Direction Outbound - TTLSGroupActionRef ClientGroupAction - TTLSEnvironmentActionRef ApimlClientEnvironmentAction - TTLSConnectionActionRef ApimlNoX509ClientConnAction -} - -TTLSGroupAction ClientGroupAction -{ - TTLSEnabled ON -} - -TTLSEnvironmentAction ApimlClientEnvironmentAction -{ - HandshakeRole Client - TTLSKeyringParmsRef ApimlKeyring - TTLSCipherParmsRef CipherParms - TTLSEnvironmentAdvancedParmsRef ClientEnvironmentAdvParms -} -``` - -:::note -`Jobname` is defined explicitly for the API Gateway and is formed with the `zowe.job.prefix` setting from `zowe.yaml` plus `AG` as the Gateway identifier. -::: - -#### For communication between API Gateway and other core services - -```pagent -TTLSRule ApimlClientRule -{ - LocalAddr All - LocalPortRange 1024-65535 - RemoteAddr All - RemotePortRange 7551-7555 - Jobname ZWE1A* - Direction Outbound - TTLSGroupActionRef ClientGroupAction - TTLSEnvironmentActionRef ApimlClientEnvironmentAction - TTLSConnectionActionRef ApimlX509ClientConnAction -} - -TTLSConnectionAction ApimlX509ClientConnAction -{ - HandshakeRole Client - TTLSCipherParmsRef CipherParms - TTLSConnectionAdvancedParmsRef ApimlClientX509ConnAdvParms -} - -TTLSConnectionAdvancedParms ApimlClientX509ConnAdvParms -{ - ApplicationControlled Off - CertificateLabel Zowe Server - SecondaryMap Off -} -``` - -#### For communication between API Gateway and southbound services - -```pagent -TTLSRule ApimlServiceClientRule -{ - LocalAddr All - LocalPortRange 1024-65535 - RemoteAddr All - RemotePortRange 40030 - Jobname ZWE1AG* - Direction Outbound - TTLSGroupActionRef ClientGroupAction - TTLSEnvironmentActionRef ApimlClientEnvironmentAction - TTLSConnectionActionRef ApimlNoX509ClientConnAction -} - -TTLSConnectionAction ApimlNoX509ClientConnAction -{ - HandshakeRole Client - TTLSCipherParmsRef CipherParms - TTLSConnectionAdvancedParmsRef ApimlClientNoX509ConnAdvParms -} - -TTLSConnectionAdvancedParms ApimlClientNoX509ConnAdvParms -{ - ApplicationControlled Off - SecondaryMap Off -} -``` -:::important -- The outbound connection from the Gateway Service to the Discovery Service must be configured without a `CertificateLabel`. Ensure that the certificate label is not included to avoid sending the certificate in case routing would be possible to the Discovery Service. Note that this route is disabled by default. - -- 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. -::: - -### Ciphers - -:::note -This list of ciphers is provided as an example only. Actual ciphers should be customized according to your specific configuration. -::: - -The list of supported ciphers should be constructed according to the TLS supported versions. -Ensure that the cipher list has matches with non-AT-TLS-aware clients. - -```pagent -TTLSCipherParms CipherParms -{ - V2CipherSuites TLS_RC4_128_WITH_MD5 - V2CipherSuites TLS_RC4_128_EXPORT40_WITH_MD5 - V2CipherSuites TLS_RC2_CBC_128_CBC_WITH_MD5 - V2CipherSuites TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5 - V2CipherSuites TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5 - V2CipherSuites TLS_DES_192_EDE3_CBC_WITH_MD5 - V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 - V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 - V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 - V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 - V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - V3CipherSuites TLS_AES_128_GCM_SHA256 - V3CipherSuites TLS_AES_256_GCM_SHA384 - V3CipherSuites TLS_CHACHA20_POLY1305_SHA256 -} -``` - -## Using AT-TLS for API ML in High Availability - -AT-TLS settings for a Zowe API Mediation Layer installation configured in High Availability mode do not differ extensively. Changes need to be made to the previously described rules to allow for cross-lpar communication: - -Ensure that the `RemoteAddr` setting in the rules accounts for the following connections: - -- Discovery Service to Discovery Service. This is the replica request. -- Gateway Service to southbound services running in another LPAR. -- Southbound services to Discovery Service. This applies during onboarding. - -## Multi-tenancy deployment - -For specific scenario when Central API ML is running on z/OS with AT-TLS enabled, it is important to override protocol for external URL. This information is used by the Central API ML to call domain API ML and it needs to reflect outbound AT-TLS rule. In this case, update your domain API ML configuration as follows: - -``` -zowe: - components: - gateway: - apiml: - gateway: - externalProtocol: http -``` - -## AT-TLS Troubleshooting - -This section describes some common issues when using AT-TLS with API ML and how to resolve these issues. - -### The message `This combination of port requires SSL` is thrown - -Make sure the URL starts with `https://`. This message indicates that AT-TLS rules are in place and it is trying to connect on port 80 to the API Gateway, however the latter is still only listening on the secure port 443. - -**Solution:** -Review settings in the API Gateway. Ensure that the changes described in [AT-TLS configuration for Zowe](#at-tls-configuration-for-zowe) are applied. - -### AT-TLS rules are not applied - -If the application is responding in http, the application may not be properly configured to support http-only calls. AT-TLS is not correctly configured. - -**Solution:** -Ensure the rules are active and that the filters on port range and job names are properly set. - -### Non matching ciphers - -An error can occur if the [list of ciphers](#ciphers) does not match between the ones configured in the AT-TLS rules and the ones used by non AT-TLS-aware clients. - -**Solution:** -Review the supported TLS versions and ciphers used in both the client and the server. diff --git a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md index ab36c09d92..cbc54260cf 100644 --- a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md +++ b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md @@ -1,23 +1,677 @@ -# Enabling AT-TLS across your Zowe environment + +# Configuring AT-TLS for Zowe Server -The communication server on z/OS provides functionality to encrypt HTTP communication for on-platform jobs. This functionality is referred to as Application Transparent Transport Layer Security (AT-TLS). +Review this article for descriptions of the configuration parameters required to make Zowe work with AT-TLS, including AT-TLS inbound and outbound rules, using AT-TLS in high availability, and troubleshooting. Security recommendations are also provided. -:::info Required roles: security administrator +:::info Role: security administrator ::: -## Configuration Parameters +- [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) + - [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) +- [See also](#see-also) + +## AT-TLS configuration for Zowe + +:::tip +For full support, we recommend that you upgrade to v2.17 or a later version of Zowe. +::: + +Follow these steps to configure Zowe to support AT-TLS: + +These instructions are valid for Zowe 2.18 onwards: -To enable AT-TLS for Zowe components, configure the following parameters: ```yaml zowe: network: + # For inbound traffic rules: server: tls: attls: true + # If outbound traffic rules will be configured: + client: + tls: + 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. Ideally, AT-TLS should be configured with the same Zowe keyring. + +If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. + +:::note Notes + +- AT-TLS is supported in the API Cloud Gateway Mediation Layer component (SCGW) beginning with version 2.17. + - Support is partial. X.509 Client Certificates are not supported, if the AT-TLS rule is not in effect, the SCGW will allow unsecured connections. + +- As the API ML Gateway is a core component of API ML, other components that need to interact with the Gateway, such as Zowe ZLUX App Server, also require AT-TLS configuration. + +::: + +:::caution Important security consideration + +Configuring AT-TLS for Zowe requires careful consideration of security settings. These security settings apply to the Client Certificate authentication feature in Zowe API Mediation Layer components, as well as for onboarded services that support the x.509 client certificates authentication scheme. + +Outbound AT-TLS rules (i.e. to make a transparent https call through http) that are configured to send the server certificate should be limited to the services that __require__ service to service authentication. If an API ML-onboarded southbound service needs to support X.509 client certificate authentication, we recommend to use the integrated TLS handshake capabilities of API ML. Do not configure an outbound AT-TLS rule for these services. + +The Discovery Service endpoints are not reachable by standard API Gateway routing by default. +::: + +### 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. +LTPA token and SAF provider cannot be used in this configuration because API ML cannot access the hardware key to sign its own tokens. + +## AT-TLS rules + +This section describes suggested AT-TLS settings, and serves as guidelines to set your AT-TLS rules. + +### Inbound rules + +A generic inbound rule can be set for all Zowe services: + +```bash +TTLSRule ZoweServerRule +{ + LocalAddr All + RemoteAddr All + LocalPortRange 7551-7559 # Range covers all Zowe services + Jobname ZWE1* # Jobname according to zowe.job.prefix in zowe.yaml + Direction Inbound + TTLSGroupActionRef ServerGroupAction + TTLSEnvironmentActionRef ZoweServerEnvironmentAction + TTLSConnectionActionRef ZoweServerConnectionAction +} + +TTLSGroupAction ServerGroupAction +{ + TTLSEnabled On +} + +TTLSEnvironmentAction ZoweServerEnvironmentAction +{ + HandshakeRole ServerWithClientAuth + EnvironmentUserInstance 0 + TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms + TTLSKeyringParmsRef ZoweKeyring +} + +TTLSConnectionAction ZoweServerConnectionAction +{ + HandshakeRole ServerWithClientAuth + TTLSCipherParmsRef CipherParms + TTLSConnectionAdvancedParmsRef ZoweConnectionAdvParms +} +``` + +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: + +| Component | Port | +|----|-----------------------| +| Gateway | default port 7554 | +| Discovery | default port 7553 | +| Caching Service | default port 7555 | +| API Catalog | default port 7552 | +| Metrics Service | default port 7551 | +| Zowe System Services (ZSS) | default port 7557 | +| Zowe Application Server | default port 7556 | + +__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. + +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. + +For more granularity in the AT-TLS rules, separate the rules that need to support Client Certificate authentication (Discovery Service, Gateway Service) from the rest. + +### Outbound rules + +Outbound rules in this section allow Zowe services to communicate with each other and to other southbound services using HTTP. + +Careful consideration needs to be set especially regarding which rules will be configured to send a Client Certificate. Since this cannot be configured on a per-request basis. +I.E. __Do not__ 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. This will result in unintentionally authenticating the server ACID. + +__For example:__ + +```yaml +TTLSConnectionAction ClientConnectionAction +{ + HandshakeRole Client + TTLSCipherParmsRef CipherParms + TTLSConnectionAdvancedParmsRef ConnectionAdvancedParms + CertificateLabel +} +``` + +#### 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. + +Remember to set `zowe.zOSMF.scheme` to `http` in zowe.yaml if this rule is set. + +```bash +TTLSRule ApimlZosmfClientRule +{ + LocalAddr All + LocalPortRange 1024-65535 # Using any outbound port + RemoteAddr All + RemotePortRange 449 # Set to z/OSMF port + Jobname ZWE1AG* # Generate according to zowe.job.prefix in zowe.yaml + AG for Gateway outbound + Direction Outbound + TTLSGroupActionRef ClientGroupAction + TTLSEnvironmentActionRef ApimlClientEnvironmentAction + TTLSConnectionActionRef ApimlNoX509ClientConnAction # No X.509 Client Certificate required +} + +TTLSGroupAction ClientGroupAction +{ + TTLSEnabled ON +} + +TTLSEnvironmentAction ApimlClientEnvironmentAction +{ + HandshakeRole Client + TTLSKeyringParmsRef ApimlKeyring + TTLSCipherParmsRef CipherParms + TTLSEnvironmentAdvancedParmsRef ClientEnvironmentAdvParms +} +``` + +:::note +`Jobname` is defined explicitly for the API Gateway and is formed with the `zowe.job.prefix` setting from `zowe.yaml` plus `AG` as the Gateway identifier. +::: + +#### 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. + +:::important + +- The outbound connection from the Gateway Service to the Discovery Service must be configured without a `CertificateLabel`. Ensure that the certificate label is not included (but keep the `CertificateLabel` field) to avoid sending the certificate in case routing would be possible to the Discovery Service. Note that this route is disabled by default. + +::: + +```bash +TTLSRule ApimlClientRule +{ + LocalAddr All + LocalPortRange 1024-65535 + RemoteAddr All + RemotePortRange 7551-7555 # Range covers API ML services (gateway, discovery, api catalog, caching service) + Jobname ZWE1A* # Generate according to zowe.job.prefix in zowe.yaml + Direction Outbound + TTLSGroupActionRef ClientGroupAction + TTLSEnvironmentActionRef ApimlClientEnvironmentAction + TTLSConnectionActionRef ApimlX509ClientConnAction # X.509 Authentication is required in cross-service API ML communication +} + +TTLSConnectionAction ApimlX509ClientConnAction +{ + HandshakeRole Client + TTLSCipherParmsRef CipherParms + TTLSConnectionAdvancedParmsRef ApimlClientX509ConnAdvParms +} + +TTLSConnectionAdvancedParms ApimlClientX509ConnAdvParms +{ + ApplicationControlled Off + CertificateLabel Zowe Server + SecondaryMap Off +} +``` + +#### 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 covers routing scenarios. + +```bash +TTLSRule ApimlServiceClientRule +{ + LocalAddr All + LocalPortRange 1024-65535 + RemoteAddr All + RemotePortRange 8080 # Set to range of ports where services are listening + Jobname ZWE1AG* # Generate according to zowe.job.prefix in zowe.yaml + Direction Outbound + TTLSGroupActionRef ClientGroupAction + TTLSEnvironmentActionRef ApimlClientEnvironmentAction + TTLSConnectionActionRef ApimlNoX509ClientConnAction # Do not send X.509 Client Certificates +} + +TTLSConnectionAction ApimlNoX509ClientConnAction +{ + HandshakeRole Client + TTLSCipherParmsRef CipherParms + TTLSConnectionAdvancedParmsRef ApimlClientNoX509ConnAdvParms +} + +TTLSConnectionAdvancedParms ApimlClientNoX509ConnAdvParms +{ + ApplicationControlled Off + CertificateLabel # Leave empty to avoid sending a client certificate (i.e. if the keyring has a default certificate) + SecondaryMap Off +} +``` + +:::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. + +::: + +#### 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. + +This 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's 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. + +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. + +### Ciphers + +:::note +This list of ciphers is provided as an example only. Actual ciphers should be customized according to your specific configuration. +::: + +The list of supported ciphers should be constructed according to the TLS supported versions. +Ensure that the cipher list has matches with non-AT-TLS-aware clients. + +
+Click here for an example of Cipher parameters. + +```bash +TTLSCipherParms CipherParms +{ + V2CipherSuites TLS_RC4_128_WITH_MD5 + V2CipherSuites TLS_RC4_128_EXPORT40_WITH_MD5 + V2CipherSuites TLS_RC2_CBC_128_CBC_WITH_MD5 + V2CipherSuites TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5 + V2CipherSuites TLS_RC2_CBC_128_CBC_EXPORT40_WITH_MD5 + V2CipherSuites TLS_DES_192_EDE3_CBC_WITH_MD5 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_AES_128_GCM_SHA256 + V3CipherSuites TLS_AES_256_GCM_SHA384 + V3CipherSuites TLS_CHACHA20_POLY1305_SHA256 +} ``` -## Component-Specific Configuration +
+ +## Using AT-TLS for API ML in High Availability + +AT-TLS settings for a Zowe installation configured in High Availability mode do not differ extensively. Changes need to be made to the previously described rules to allow for cross-lpar communication: + +Ensure that the `RemoteAddr` setting in the rules accounts for the following connections: + +- Discovery Service to Discovery Service. This is the replica request. +- Gateway Service to southbound services (including app-server and ZSS) running in another LPAR. +- Southbound services to Discovery Service. This applies during onboarding. + +## Multi-tenancy deployment + +For specific scenario when Central API ML is running on z/OS with AT-TLS enabled, it is important to override the protocol for the external URL. This information is used by the Central API ML to call domain API ML and it needs to reflect outbound AT-TLS rule. In this case, update your domain API ML configuration as follows: + +```yaml +zowe: + components: + gateway: + apiml: + gateway: + externalProtocol: http +``` + +## AT-TLS Troubleshooting + +This section describes some common issues when using AT-TLS with Zowe and how to resolve these issues. + +### The message `This combination of port requires SSL` is thrown when accesing an API ML service through a Browser + +Make sure the URL starts with `https://`. This message indicates that AT-TLS rules are in place and it is trying to connect on an unsecured port to the API Gateway, however the latter is still only listening on a application-controlled secured port. + +__Solution:__ +Review settings in the API Gateway. Ensure that the changes described in [AT-TLS configuration for Zowe](#at-tls-configuration-for-zowe) are applied. + +### AT-TLS rules are not applied + +If the application is responding in http, the application may not be properly configured to support http-only calls. AT-TLS is not correctly configured. + +__Solution:__ + +Ensure the rules are active and that the filters on port range and job names are properly set. + +### Non matching ciphers / protocols + +An error can occur if the [list of ciphers](#ciphers) or the TLS protocol does not match between the ones configured in the AT-TLS rules and the ones used by non AT-TLS-aware clients. + +__Solution:__ +Review the supported TLS versions and ciphers used in both the client and the server. + +### Additional troubleshooting + +When asking for support make sure to follow IBM guides for troubleshooting AT-TLS problems. This is covered in the "Diagnosing Application Transparent Transport Layer Security (AT-TLS)" article on IBM documentation. + +Ensure you collect the logs and current configurations when contacting support. + +## Full example of AT-TLS configuration + +Review a full working example of an AT-TLS configuration file on z/OS, specifically used for defining secure communication between different services in a mainframe environment. All port values are examples. +The example is commented for convenience. +
+ +Click here to display the full AT-TLS configuration file. + +```bash +# Main inbound rule, all Zowe services have it defined. +TTLSRule ZoweServerRule +{ + LocalAddr All + RemoteAddr All + LocalPortRange 7554-7559 # Range covers all possible Zowe services + Jobname ZWE1* + Direction Inbound + TTLSGroupActionRef ServerGroupAction + TTLSEnvironmentActionRef ZoweServerEnvironmentAction + TTLSConnectionActionRef ZoweServerConnectionAction +} + +# Example southbound service inbound rule +TTLSRule ApimlDCServerRule +{ + LocalAddr All + RemoteAddr All + LocalPortRange 8080-8090 # Example service ports + Jobname ZWE1DC* # Jobname prefix (optional) + Direction Inbound + TTLSGroupActionRef ServerGroupAction + TTLSEnvironmentActionRef ZoweDCServerEnvironmentAction + TTLSConnectionActionRef ZoweServerConnectionAction +} + +TTLSGroupAction ServerGroupAction +{ + TTLSEnabled On +} + +# Environment action for all Zowe service +TTLSEnvironmentAction ZoweServerEnvironmentAction +{ + HandshakeRole ServerWithClientAuth # Zowe Servers can optionally support Client Certificate authentication + EnvironmentUserInstance 0 + TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms + TTLSKeyringParmsRef ZoweKeyring + TTLSSignatureParmsRef TNESigParms +} + +# Environment action for sample southbound service +TTLSEnvironmentAction ZoweDCServerEnvironmentAction +{ + HandshakeRole Server + EnvironmentUserInstance 0 + TTLSEnvironmentAdvancedParmsRef ServerEnvironmentAdvParms + TTLSKeyringParmsRef ZoweKeyring + TTLSSignatureParmsRef TNESigParms +} + +# Keyring, used for TLS, will be used also to load trusted certificates +TTLSKeyringParms ZoweKeyring +{ + Keyring ZWEKRNG +} + +# Advanced TLS settings, choose TLS versions supported. +TTLSEnvironmentAdvancedParms ServerEnvironmentAdvParms +{ + ClientAuthType Full # Support optional Client Certificate authentication + ApplicationControlled Off + Renegotiation Disabled + SSLv2 Off + SSLv3 Off + TLSv1 Off + TLSv1.1 Off + TLSv1.2 On + TLSv1.3 On +} + +# Server Connection Action for API ML core services. +TTLSConnectionAction ZoweServerConnectionAction +{ + HandshakeRole ServerWithClientAuth # API ML Core Services use Client Certificate authentication + TTLSCipherParmsRef CipherParms + TTLSConnectionAdvancedParmsRef ZoweConnectionAdvParms + TTLSSignatureParmsRef TNESigParms +} + +# API ML Server connection action. +# Certificate label indicates which certificate is used in the client certificate authentication process between core services. +TTLSConnectionAdvancedParms ZoweConnectionAdvParms +{ + ApplicationControlled Off + ServerCertificateLabel apimlcert + CertificateLabel apimlcert + SecondaryMap Off +} + +# Example outbound TTLS rule for a client calling API ML +# In this scenario this client (a southbound service) presents client certificate to authenticate (for example during onboarding) +TTLSRule ZoweClientRule +{ + LocalAddr All + LocalPortRange 1024-65535 + RemoteAddr All + RemotePortRange 7553-7555 # API ML Core services ports + Jobname ZWE1* + Direction Outbound + TTLSGroupActionRef ClientGroupAction + TTLSEnvironmentActionRef ApimlClientEnvironmentAction + TTLSConnectionActionRef ApimlX509ClientConnAction +} + +# Example outbound rule for connections from API ML Gateway to a southbound service running in port 40030 (during request routing) +# Note ConnectionAction doesn't configure a client certificate. +TTLSRule ApimlServiceClientRule +{ + LocalAddr All + LocalPortRange 1024-65535 + RemoteAddr All + RemotePortRange 40030 # Service ports + Jobname ZWE1AG* + Direction Outbound + TTLSGroupActionRef ClientGroupAction + TTLSEnvironmentActionRef ApimlClientEnvironmentAction + TTLSConnectionActionRef ApimlNoX509ClientConnAction +} + +# Optional. Can configure the outbound connection from Gateway to work with AT-TLS while connecting to z/OSMF. +TTLSRule ApimlZosmfClientRule +{ + LocalAddr All + LocalPortRange 1024-65535 + RemoteAddr All + RemotePortRange 449 + Jobname ZWE1AG* + Direction Outbound + TTLSGroupActionRef ClientGroupAction + TTLSEnvironmentActionRef ApimlClientEnvironmentAction + TTLSConnectionActionRef ApimlNoX509ClientConnAction +} + +# Example outbound rule from app server to gateway. +TTLSRule ApimlZLUXClientRule +{ + LocalAddr All + LocalPortRange 1024-65535 + RemoteAddr All + RemotePortRange 7556 + Jobname ZWE1AG* + Direction Outbound + TTLSGroupActionRef ClientGroupAction + TTLSEnvironmentActionRef ApimlClientEnvironmentAction + TTLSConnectionActionRef ApimlNoX509ClientConnAction # Southbound services should not sent a client certificate to Gateway +} + +TTLSEnvironmentAction ApimlClientEnvironmentAction +{ + HandshakeRole Client + TTLSKeyringParmsRef ApimlKeyring + TTLSEnvironmentAdvancedParmsRef ClientEnvironmentAdvParms + EnvironmentUserInstance 0 + TTLSSignatureParmsRef TNESigParms +} + +TTLSEnvironmentAdvancedParms ClientEnvironmentAdvParms +{ + Renegotiation Disabled + 3DESKEYCHECK OFF + CLIENTEDHGROUPSIZE legacy + SERVEREDHGROUPSIZE legacy + PEERMINCERTVERSION any + SERVERSCSV OFF + MIDDLEBOXCOMPATMODE Off + CertValidationMode Any +} + +TTLSGroupAction ClientGroupAction +{ + TTLSEnabled ON +} + +TTLSConnectionAction ApimlX509ClientConnAction +{ + HandshakeRole Client + TTLSCipherParmsRef CipherParms + TTLSConnectionAdvancedParmsRef ApimlClientX509ConnAdvParms +} + +TTLSConnectionAction ApimlNoX509ClientConnAction +{ + HandshakeRole Client + TTLSCipherParmsRef CipherParms + TTLSConnectionAdvancedParmsRef ZoweClientNoX509ConnAdvParms +} + +# ConnectionAdvanced parameters for connections not requiring x.509 Client Certificate authentication +# If the set Keyring has a default certificate this will not prevent sending it +TTLSConnectionAdvancedParms ZoweClientNoX509ConnAdvParms +{ + SSLv3 Off + TLSv1 Off + TLSv1.1 Off + ApplicationControlled Off + CertificateLabel # Keep the Label empty to ensure a default certificate will not be picked from the keyring + SecondaryMap Off + TLSv1.2 On + TLSv1.3 Off +} + +# In case the connection requires a client certificate authentication, this is where the label is set for outbound connections. +TTLSConnectionAdvancedParms ZoweClientX509ConnAdvParms +{ + SSLv3 Off + TLSv1 Off + TLSv1.1 Off + CertificateLabel apimlcert + SecondaryMap Off + TLSv1.2 On + 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 +{ + V3CipherSuites TLS_AES_128_GCM_SHA256 + V3CipherSuites TLS_AES_256_GCM_SHA384 + V3CipherSuites TLS_CHACHA20_POLY1305_SHA256 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 + V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 + V3CipherSuites TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 + V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 + V3CipherSuites TLS_RSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_DH_DSS_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_DH_RSA_WITH_AES_256_GCM_SHA384 + V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA256 + V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 + V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 + V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA256 + V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA256 + V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_ECDH_RSA_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA + V3CipherSuites TLS_RSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_DH_DSS_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_DH_RSA_WITH_AES_128_GCM_SHA256 + V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA256 + V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_ECDH_RSA_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA + V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA +} +``` + +
+ +## See also -For detailed configuration instructions specific to each component, refer to the following guides: -- [Configuring AT-TLS for API Mediation Layer](../user-guide/api-mediation/configuration-at-tls.md) -- [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework) \ No newline at end of file +- [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework) diff --git a/versioned_sidebars/version-v2.18.x-sidebars.json b/versioned_sidebars/version-v2.18.x-sidebars.json index 08e9cb62a9..14715cb666 100644 --- a/versioned_sidebars/version-v2.18.x-sidebars.json +++ b/versioned_sidebars/version-v2.18.x-sidebars.json @@ -388,7 +388,6 @@ ] }, "user-guide/api-mediation/configuration-customizing-the-api-catalog-ui", - "user-guide/api-mediation/configuration-at-tls", "user-guide/api-mediation/configuration-logging" ] } From b045238551516a59c4980485e28b9fe1e6ba8ec7 Mon Sep 17 00:00:00 2001 From: Pablo Carle Date: Fri, 18 Oct 2024 09:44:57 +0200 Subject: [PATCH 2/7] Update versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pavel Jareš <58428711+pj892031@users.noreply.github.com> Signed-off-by: Pablo Carle --- .../version-v2.18.x/user-guide/at-tls-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md index cbc54260cf..0fd7a67cdd 100644 --- a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md +++ b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md @@ -297,7 +297,7 @@ This list of ciphers is provided as an example only. Actual ciphers should be cu ::: The list of supported ciphers should be constructed according to the TLS supported versions. -Ensure that the cipher list has matches with non-AT-TLS-aware clients. +Ensure that the cipher list has matches with non-AT-TLS clients.
Click here for an example of Cipher parameters. From e6494159e8f3840c3a286c85d0752ccceb706a3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Fri, 18 Oct 2024 09:46:17 +0200 Subject: [PATCH 3/7] address review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../user-guide/at-tls-configuration.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md index cbc54260cf..10d7d4ce86 100644 --- a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md +++ b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md @@ -14,6 +14,7 @@ Review this article for descriptions of the configuration parameters required to - [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) @@ -74,6 +75,7 @@ The Discovery Service endpoints are not reachable by standard API Gateway routin 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. LTPA token and SAF provider cannot be used in this configuration because 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 @@ -119,15 +121,15 @@ TTLSConnectionAction ZoweServerConnectionAction 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: -| Component | Port | +| Component | Default Port | |----|-----------------------| -| Gateway | default port 7554 | -| Discovery | default port 7553 | -| Caching Service | default port 7555 | -| API Catalog | default port 7552 | -| Metrics Service | default port 7551 | -| Zowe System Services (ZSS) | default port 7557 | -| Zowe Application Server | default port 7556 | +| Gateway | 7554 | +| Discovery | 7553 | +| Caching Service | 7555 | +| API Catalog | 7552 | +| Metrics Service | 7551 | +| Zowe System Services (ZSS) | 7557 | +| Zowe Application Server | 7556 | __Follow this step:__ From 590118180f7498df192bdc860304e2aeb78618d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Fri, 18 Oct 2024 10:05:34 +0200 Subject: [PATCH 4/7] address review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../version-v2.18.x/user-guide/at-tls-configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md index 53d01d5025..bc0da31562 100644 --- a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md +++ b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md @@ -335,6 +335,7 @@ Ensure that the `RemoteAddr` setting in the rules accounts for the following con - Discovery Service to Discovery Service. This is the replica request. - Gateway Service to southbound services (including app-server and ZSS) running in another LPAR. - Southbound services to Discovery Service. This applies during onboarding. +- All outbound connections need to account for all LPARs including the same where the rules are applied. ## Multi-tenancy deployment From 92e10d8b9e01dbd469a19240b45c7579949eb0cb Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 21 Oct 2024 16:04:08 +0200 Subject: [PATCH 5/7] style/minor language refactor Signed-off-by: Andrew Jandacek --- .../user-guide/at-tls-configuration.md | 50 ++++++++++--------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md index bc0da31562..71fd998b22 100644 --- a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md +++ b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md @@ -1,7 +1,7 @@ # Configuring AT-TLS for Zowe Server -Review this article for descriptions of the configuration parameters required to make Zowe work with AT-TLS, including AT-TLS inbound and outbound rules, using AT-TLS in high availability, and troubleshooting. Security recommendations are also provided. +You can configure parameters in the Zowe server to enable Zowe 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. :::info Role: security administrator ::: @@ -24,7 +24,7 @@ Review this article for descriptions of the configuration parameters required to - [Non matching ciphers / protocols](#non-matching-ciphers--protocols) - [Additional troubleshooting](#additional-troubleshooting) - [Full example of AT-TLS configuration](#full-example-of-at-tls-configuration) -- [See also](#see-also) +- [Additional Zowe feature configuration with AT-TLS](#additional-zowe-feature-configuration-with-at-tls) ## AT-TLS configuration for Zowe @@ -34,7 +34,9 @@ For full support, we recommend that you upgrade to v2.17 or a later version of Z Follow these steps to configure Zowe to support AT-TLS: -These instructions are valid for Zowe 2.18 onwards: +:::note +These instructions are valid for Zowe v2.18 and later versions of Zowe. +::: ```yaml zowe: @@ -49,7 +51,7 @@ 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. Ideally, AT-TLS should be configured with the same Zowe keyring. +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. If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. @@ -66,7 +68,7 @@ If there is an outbound AT-TLS rule configured for the link between the API Gate Configuring AT-TLS for Zowe requires careful consideration of security settings. These security settings apply to the Client Certificate authentication feature in Zowe API Mediation Layer components, as well as for onboarded services that support the x.509 client certificates authentication scheme. -Outbound AT-TLS rules (i.e. to make a transparent https call through http) that are configured to send the server certificate should be limited to the services that __require__ service to service authentication. If an API ML-onboarded southbound service needs to support X.509 client certificate authentication, we recommend to use the integrated TLS handshake capabilities of API ML. Do not configure an outbound AT-TLS rule for these services. +Outbound AT-TLS rules (i.e. to make a transparent https calls through http) that are configured to send the server certificate should be limited to the services that __require__ service to service authentication. If an API ML-onboarded southbound service needs to support X.509 client certificate authentication, we recommend to use the integrated TLS handshake capabilities of API ML. Do not configure an outbound AT-TLS rule for these services. The Discovery Service endpoints are not reachable by standard API Gateway routing by default. ::: @@ -74,7 +76,7 @@ The Discovery Service endpoints are not reachable by standard API Gateway routin ### 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. -LTPA token and SAF provider cannot be used in this configuration because API ML cannot access the hardware key to sign its own tokens. +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. 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 @@ -131,7 +133,7 @@ The `PortRange` of this inbound rule is taken from the list of API Mediation Lay | Zowe System Services (ZSS) | 7557 | | Zowe Application Server | 7556 | -__Follow this step:__ +**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. @@ -143,10 +145,12 @@ 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. -Careful consideration needs to be set especially regarding which rules will be configured to send a Client Certificate. Since this cannot be configured on a per-request basis. -I.E. __Do not__ 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. This will result in unintentionally authenticating the server ACID. +:::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. + +::: -__For example:__ +**Example:** ```yaml TTLSConnectionAction ClientConnectionAction @@ -162,7 +166,7 @@ TTLSConnectionAction ClientConnectionAction 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. -Remember to set `zowe.zOSMF.scheme` to `http` in zowe.yaml if this rule is set. +Ensure that you set `zowe.zOSMF.scheme` to `http` in zowe.yaml if this rule is set. ```bash TTLSRule ApimlZosmfClientRule @@ -200,9 +204,9 @@ TTLSEnvironmentAction ApimlClientEnvironmentAction Use the example in this section as a template for internal connections between API Mediation Layer core services. -:::important +:::caution Important -- The outbound connection from the Gateway Service to the Discovery Service must be configured without a `CertificateLabel`. Ensure that the certificate label is not included (but keep the `CertificateLabel` field) to avoid sending the certificate in case routing would be possible to the Discovery Service. Note that this route is disabled by default. +The outbound connection from the Gateway Service to the Discovery Service must be configured without a `CertificateLabel`. Ensure that the certificate label is not included (but keep the `CertificateLabel` field) to avoid sending the certificate in case routing would be possible to the Discovery Service. Note that this route is disabled by default. ::: @@ -271,9 +275,9 @@ TTLSConnectionAdvancedParms ApimlClientNoX509ConnAdvParms } ``` -:::important +:::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, it is the server user who would be authenticated. ::: @@ -281,9 +285,9 @@ TTLSConnectionAdvancedParms ApimlClientNoX509ConnAdvParms In this scenario, the services will issue a request against the API Gateway to validate the received authentication token. -This 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 authentication scheme, those that require an Open ID Connect (OIDC) token, or forwarded X.509 certificates. -In this case it's 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. @@ -339,7 +343,7 @@ Ensure that the `RemoteAddr` setting in the rules accounts for the following con ## Multi-tenancy deployment -For specific scenario when Central API ML is running on z/OS with AT-TLS enabled, it is important to override the protocol for the external URL. This information is used by the Central API ML to call domain API ML and it needs to reflect outbound AT-TLS rule. In this case, update your domain API ML configuration as follows: +For a specific scenario when Central API ML is running on z/OS with AT-TLS enabled, it is important to override the protocol for the external URL. This information is used by the Central API ML to call domain API ML and needs to reflect the outbound AT-TLS rule. In this case, update your domain API ML configuration: ```yaml zowe: @@ -358,14 +362,14 @@ This section describes some common issues when using AT-TLS with Zowe and how to Make sure the URL starts with `https://`. This message indicates that AT-TLS rules are in place and it is trying to connect on an unsecured port to the API Gateway, however the latter is still only listening on a application-controlled secured port. -__Solution:__ +**Solution:** Review settings in the API Gateway. Ensure that the changes described in [AT-TLS configuration for Zowe](#at-tls-configuration-for-zowe) are applied. ### AT-TLS rules are not applied If the application is responding in http, the application may not be properly configured to support http-only calls. AT-TLS is not correctly configured. -__Solution:__ +**Solution:** Ensure the rules are active and that the filters on port range and job names are properly set. @@ -373,7 +377,7 @@ Ensure the rules are active and that the filters on port range and job names are An error can occur if the [list of ciphers](#ciphers) or the TLS protocol does not match between the ones configured in the AT-TLS rules and the ones used by non AT-TLS-aware clients. -__Solution:__ +**Solution:** Review the supported TLS versions and ciphers used in both the client and the server. ### Additional troubleshooting @@ -675,6 +679,6 @@ TTLSCipherParms CipherParms
-## See also +## Additional Zowe feature configuration with AT-TLS -- [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework) +The Zowe Application Framework also leverages AT-TLS. For more information, see [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework). From 1f1cae0f5a63020527e07e55613920654c2116a0 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Mon, 21 Oct 2024 16:05:51 +0200 Subject: [PATCH 6/7] fix typo Signed-off-by: Andrew Jandacek --- .../version-v2.18.x/user-guide/at-tls-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md index 71fd998b22..4a452245d7 100644 --- a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md +++ b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md @@ -1,7 +1,7 @@ # Configuring AT-TLS for Zowe Server -You can configure parameters in the Zowe server to enable Zowe 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 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. :::info Role: security administrator ::: From 78276c37e587416acd517b66f3161def9f81d422 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Hern=C3=A1n=20Carle?= Date: Mon, 21 Oct 2024 16:56:11 +0200 Subject: [PATCH 7/7] address review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle --- .../version-v2.18.x/user-guide/at-tls-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md index 4a452245d7..272e47cd76 100644 --- a/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md +++ b/versioned_docs/version-v2.18.x/user-guide/at-tls-configuration.md @@ -139,7 +139,7 @@ Replace `ZoweKeyring` with the keyring configured for your installation. Follow 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. -For more granularity in the AT-TLS rules, separate the rules that need to support Client Certificate authentication (Discovery Service, Gateway Service) from the rest. +For more granularity in the AT-TLS rules, separate the rules that need to support Client Certificate authentication (Discovery Service, Gateway Service) from the ones that do not (for example a rule covering API Gateway to an onboarded service). ### Outbound rules @@ -679,6 +679,6 @@ TTLSCipherParms CipherParms -## Additional Zowe feature configuration with AT-TLS +## Additional Zowe feature configuration with AT-TLS The Zowe Application Framework also leverages AT-TLS. For more information, see [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework).