Tips and Tricks: Zowe Secure setup for Production
{Core} If you’ve been following the evolution of The Open Mainframe Project’s Zowe, an award winning open source initiative, you’re probably already aware of the range of applications bundled together as Zowe z/OS components including the API Mediation Layer, Virtual Desktop, and Zowe System Services (ZSS). The first step in your journey in getting started with Zowe is to tackle the installation. You may soon discover, however, that there are various considerations about which path to follow when performing the Zowe z/OS component installation depending on your specific use case. These various use cases include:
- New developer’s being able to leverage modern IDEs to start being productive faster.
- DBAs automating processes around database management and simplifying the resolution f system failures.
- Engineers creating automated pipelines for faster packaging and deployment of applications across environments
- Operators integrate the data coming from mainframes with data from distributed environments using tools such as Kafka or Splunk.
While Zowe documentation supports various scenarios for installation, it can be a bit disorienting to figure out which steps need to be performed based on which use case you choose. This article will help guide you through tips and tricks for installing and configuring Zowe z/OS Components.
The procedure described in this post is based on the state of Zowe as of version 2.5, and that you aim to deploy in production. Some technical details may change if you want to install older versions. While the configuration outlined here may not be the simplest approach to configuration, it is the safer option.
One important detail to bear in mind is that it is necessary to run the production instance of Zowe using the High Availability setup. To get the most out of the platform’s security, certificates used to validate the servers in network communication should be stored in Keyrings. To limit future risk, the network should be secured using TLS in version 1.3.
Note
Keep in mind that If you want to test Zowe, only a single instance is recommended and, if possible, install this instance in HTTP-only mode. This will reduce potential issues you may encounter. You should also use SAF as the authentication provider for the API ML, as z/OSMF does not need to be fully configured in order to use Zowe on the server side.
What should I know before installing?
As mentioned already, there are many ways to install Zowe, depending on what solutions you use and your specific use case. The first tip is to know that the recommended approach is to use Portable Software Instances and z/OSMF to install Zowe. This is the simplest approach, and should continue to be supported well into the future.
There are some prerequisites that you should check off your list before starting in order to prevent startup and installation failures, and time-consuming debugging.
- Java in version at least 8 sr6 fp25 is installed on the system
- Node.js in the version at least 14.x, preferably 16.x
- Recommended: z/OSMF to support the installation and the CLI functionality.
The complete list of requirements is available in the Zowe Documentation.
There are two options for Zowe API Mediation Layer authentication. The first option is for z/OSMF to issue and validate tokens. Using this approach, API Mediation Layer is just an intermediary. This could be an effective solution if you already have and trust z/OSMF. The complication, however, is that z/OSMF needs to be deployed and configured in High Availability mode. There are more ways to configure z/OSMF in High Availability mode:
- The first option is Hot Backup where multiple instances are configured and ready, but only one instance handles the traffic. Zowe tests this option.
- The second option is load balancing, where multiple instances are running, and all instances handle the traffic.
This second load-balancing option for authentication is the direct route using Enterprise Security Manager (ESM). In this case, the API Mediation Layer validates the user’s credentials directly with ESM and then issues a valid token that API ML also validates on subsequent calls. If you do not have z/OSMF in High Availability mode, this is the recommended option as it is simpler to set up with the same level of safety.
All Zowe services use certificates for securing network communication via the Transport Layer Security (TLS) protocol, wherein it is necessary for a certificate to be issued for Zowe. It is possible to have just a single certificate for Zowe, even for High Availability mode but, in this case, the certificate must satisfy the following requirements:
- The certificate must be stored in the Keyring to which the Zowe user Zowe is running under has access. As such, the installation utility can create a new Zowe Keyring and link the certificate to the tool.
- The Extended Key Usage either must not be set, or must allow client authentication as the services use the certificate to verify the identity of the other Zowe services.
- The Subject Alternative Name (SAN) must contain all hostnames used within the Zowe setup. In the case of a High Availability setup, the hostname of the DVIPA for the external world and the hostname of each of the LPARs participating in deployment are required. The hostnames of the LPARs are required as Discovery Services are not exposed to the public but need to communicate with each other. The reason is that it is necessary for Discovery Services to act as a cluster and synchronize the information about the onboarded services.
How do I configure Zowe?
Ok, so now that you’ve worked out the authentication consideration, the next step is to take a look at the configuration. Let’s take a look at the vital configuration excerpts that are necessary for production setup. The main configuration of all Zowe server components is coded in the zowe.yaml file which, by default, is located in Zowe’s root directory. Most of the configuration should be self-explanatory with every property listed and defined in Zowe Docs. There’s also an example available in the installation repository.
Fortunately, Zowe provides a tool (zwe) to automate installation and configuration. With sufficient privileges, you can run zwe to handle the correct preparation of the zowe.yaml and everything needed for Zowe installation and configuration. If the user does not have sufficient privileges, then the zwe tool can still generate JCLs for your security team to prepare, review, and submit as much of the configuration as possible. In this case, you should be aware of the need to manually apply steps before completing the task.
In addition, a new configuration manager was introduced with version 2.4 and is enabled by default in version 2.5. The main functionality that may be relevant for you is that it supports multiple zowe.yaml files and that it is possible to use templates within the file to prevent duplications. The following image shows how to use the ${{ }} syntax.
The zwe utility is capable of creating a valid keyring with valid ownership for Zowe. As recommended previously, when running the utility, you should already have the certificate prepared and stored in a keyring that this utility has access to. The utility then creates the keyring for Zowe and links the existing certificate to this new keyring. The following image shows this as scenario 4 from the zowe.yaml.
This shows the configuration for running the API Mediation Layer in the ESM direct authentication route. The key part is the apiml.security.auth.provider: saf
For the High Availability setup within a sysplex, Zowe runs in multiple instances from the same directory. To configure the differences that apply to a specific instance, there is the `haInstances` section. In this section, you add a specific key for each LPAR that runs Zowe. The following example shows how such a configuration would look like for an LPAR named “2a” and accessible via hostname “lpar2.my-company.com”. The configuration for the specific instance is composed of the defaults in the main section and the overrides in the specific ha sections.
Zowe is a holistic solution that contains many different projects and components. This article will enable an easier installation and configuration experience. We know each mainframe is different, so if you are not able to find an answer to your specific questions, feel free to contact the community via Slack or GitHub, or reach out to one of the Zowe conformant support providers.
Learn more:
If you enjoyed this blog check out more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #zowe-api, #zowe-explorer-intellij, #zowe-explorer, #zowe-cli, #zowe-dev, #zowe-user, or #zowe-onboarding. If this is your first time using the Open Mainframe Slack Channel register here.
