Custom Credential Managers in Zowe Explorer and Zowe CLI

Photo by Arthur Mazi on Unsplash

{Core} Open Mainframe Project’s Zowe Explorer and Zowe CLI users have the option to create team configuration profiles for interacting with a z/OS machine. By default, Keytaris the only available credential manager for these profiles. However, this blog will discuss the benefits of using custom credential managers, the process of building our own, and how to utilize them effectively.

Advantages of Custom Credential Managers

Customization: Custom credential managers can be tailored to meet the specific needs of your team or organization. This allows you to choose the features that are most important and configure the manager according to your specific security requirements.

Enhanced Security: Custom credential managers enable you to store sensitive information, such as passwords, in a secure manner. They utilize encryption and other security measures defined by your team to protect your data effectively.

Additionally, custom credential managers offer specific advantages, including:

Flexibility: To define a solution based on your use case custom credential managers allow you to define a solution that aligns with your unique requirements. You can choose convenient form factors for your team, such as fingerprint, facial recognition, or YubiKeys.

Customizable encryption for credentials: With custom credential managers, you can define your own secure solution for encrypting credentials based on your specific use case. This allows you to select encryption algorithms and vaults that best suit your team’s security needs.

Overall, custom credential managers offer several advantages that make them valuable tools for your team or organization. If you are seeking a secure and convenient way to store and manage your credentials, a custom credential manager may be an ideal choice.

Building Your Own Custom Credential Manager

If existing custom credential managers do not meet your needs, you can build your own too. The publicly available monorepo on Zowe’s github can serve as a foundation for creating your custom solution based on your specific requirements.

The monorepo contains two main repositories within the packages directory: vscode and cli. These packages define the necessary plugins for your plugin to communicate with Zowe Explorer’s VS Code Extension and Zowe CLI in the terminal. This article will focus primarily on the cli package, which contains the shared definition of the credential manager used across the VS Code extension and the CLI plugin.

Configuring Your Credential Manager

In the packages/cli/src/imperative/configuration.ts file, you can modify an object that contains properties for your credential manager. Pay attention to the overrides property, which needs to be renamed to your custom credential manager file that you will create in the future. The packages/cli/src/imperative/Constants.ts file contains most of the strings that you will modify to configure specific properties for your credential manager.

Plugin Life Cycle Functions: packages/cli/src/imperative/pluginLifeCycle.ts has the option (but not required) to define plugin lifecycle functions. The two available functions are:

• postInstall(): This function runs after the plugin is installed. In the provided sample, the override property is switched to the custom credential manager, allowing Zowe profiles to recognize which credential manager to use.
• preUninstall(): This function runs before uninstalling your plugin. In the provided sample, the override property is reverted to the default credential manager (keytar) since the plugin will no longer be installed, preventing potential errors.

It is important to note that the plugin life cycle functions for custom credential managers are currently only supported by the CLI version and do not reflect the behavior of the VS Code extension version of your plugin.

Writing your custom credential manager

The packages/cli/src/credentials path in the repository contains a file named k8sCredentialManager.ts. In this file, we will focus on defining the following functions:

constructor(): This function is executed when the credential manager is instantiated during Zowe Explorer activation or when Zowe CLI is installed for the first time. The file demonstrates a required call to super(), but we can also include other functions for the initial setup of your credential manager, such as the setupKubeConfig() function in the provided sample.

initialize() (optional): This function runs each time the credential manager is used and is an excellent place to perform checks specific to your credential manager before executing any CRUD operations. In the sample, we can see an example of checking if the Kubernetes namespace being used exists before any operation is performed.

loadCredentials(): This function reads credentials from the implemented storage location, such as local storage, keychain, or the cloud. It must return a string containing the secure credentials.

savecredentials(): This function doubles as a save and update function. When called for the first time, it saves the credentials to the defined storage location. On subsequent calls, it updates the secure credential. The provided sample demonstrates how the saveCredentials() function uses the Kubernetes API to save credentials as a secret and updates it if the secret already exists.

deleteCredentials(): This function is responsible for deleting credentials. In the sample, it first checks for the existence of the credentials and then proceeds to delete the secret.

If needed, you can add additional functions to support your custom credential manager in Zowe Explorer and not just the CLI. To achieve this, refactor the references to K8sCredentialManager.ts in the packages/vscode/src/extension.ts file with your implementation. This ensures that during activation in VS Code, the credential manager is exported and enables communication with Zowe profiles when using the Zowe Explorer VS Code extension.

Building and Bundling Your Credential Manager

To build and package your custom credential manager for both Zowe Explorer and Zowe CLI, use the following command:

npm run package

This command generates a .tgz file and a .vsix file in the dist/ folder of the project’s root directory. These files can be used for installation. For other available development commands, please refer to the package.json’s scripts section in the provided sample project.

It’s worth mentioning that the repository is built using Turbopack and TSUP, which provide faster bundling times through a Rust-based bundler and minimizer. If necessary, this can switched to the preferred bundler solution.

How to Use Custom Credential Managers

To utilize a custom credential manager with Zowe Explorer, you will need to use a plugin that facilitates communication between Zowe Explorer and Zowe CLI. This allows you to switch between credential managers seamlessly for storing the Zowe profile credentials.

Installing Our Custom Credential Manager on Zowe CLI

In the root of our project, open a terminal and install our .tgz file to Zowe CLI using the following command:

zowe plugins install `./dist/zowe-secrets-for-kubernetes-for-zowe-cli-0.0.1.tgz`

After a successful installation, you will notice that the imperative override in ~/.zowe/settings/imperative.json is updated with the name of the credential manager. This indicates that the custom credential manager is ready for use in Zowe CLI. To test, run any zowe profile operation, and should be prompted for credentials, with the credential storage reflecting the storage solution described in the custom credential manager.

Installing Our Custom Credential Manager on Zowe Explorer

In the dist/ folder, we will find a .vsix file that packages our custom credential manager. Right-click the file in VS Code, select “install custom vsix”, and it will install our plugin. After performing a window reload (or closing and reopening VS Code), our override value in Zowe Explorer will be updated to our custom credential manager. Please note that Zowe Explorer must be installed before installing our custom credential manager for this update to occur.

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-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the Open Mainframeprojectslack channel register here.”