Secure Credentials for Extenders

Managing Zowe Explorer credential security

Please note that VS Code no longer provides the keytar shim since the October 2023 release, and the Zowe Secrets SDK is now used to interact with secure credentials.

Zowe Explorer extenders can adopt the Zowe Explorer Secure Credentials API to enable extensions to use Zowe profiles that are managed by the Secure Credential Store. The Secure Credentials API enables extenders to utilize the Zowe security practices when performing z/OS actions outside of the core Zowe Explorer functions. The API is available in @zowe/zowe-explorer-api version 1.15.1 and higher.

V1 instructions

You can access the Zowe Explorer Secure Credentials API using the KeytarApi() class. The class lets you handle profiles that are managed by Secure Credential Store. Initialize the API before any extension is registered with Zowe Explorer, so that extenders can access the Data Sets, USS, and Jobs views.

The following steps describe how to configure Zowe Explorer to use Zowe profiles that are managed by the Secure Credentials API.

Follow these steps:

1. Activate and initialize the Zowe Explorer API. Follow the steps in Zowe Explorer extension dependencies and activation.

2. Use the following code snippet to gain access to KeytarApi():

   export function activate(context: vscode.ExtensionContext) {
     const log = imperative.Logger.getAppLogger();
     const keytarApi = new KeytarApi(log);
     await keytarApi.activateKeytar(imperative.CredentialManagerFactory.initialized, EnvironmentManager.isTheia());
   }

3. Setup the required Node binaries so that the Zowe Secrets SDK can interact with secure credentials. Follow the webpacking/bundling instructions found here.

V2 instructions

If you are using Zowe Explorer API, we recommend using the ProfilesCache class to access profiles. If you are using Webpack or another bundler, you must setup the required Node binaries so that the Zowe Secrets SDK can interact with secure credentials. Follow the webpacking/bundling instructions found here.

This class handles the import procedure for the Secrets SDK, so as long as the Secret SDK binaries are accessible, your extension is ready to use secure credentials.

---

However, if your extension does not use Zowe Explorer API, please follow these instructions:

1. Construct a ProfileInfo instance from Imperative, setting the Secrets SDK as the default credential manager using the credMgrOverride option:

   const profileInfo = new imperative.ProfileInfo("zowe", {
       credMgrOverride: imperative.ProfileCredentials.defaultCredMgrWithKeytar(requireSecretsSdk)
   });

2. Define the requireSecretsSdk function (from the above snippet) that will provide the Secrets SDK module to ProfileInfo:

   function requireSecretsSdk(): NodeModule {
       require("@zowe/secrets-for-zowe-sdk");
   }

   If you are using Webpack or another bundler: be sure to use the native require module from Node.js and not __webpack_require__ to import the Secrets SDK. Webpack users can use __non_webpack_require__ as Webpack replaces the standard require function. Then, proceed to step 3.

   If you are not using a bundler, you can stop here.

3. Setup the required Node binaries so that the Zowe Secrets SDK can interact with secure credentials. Follow the webpacking/bundling instructions found here.

Using a custom credential manager

When a new custom credential manager extension is installed, this being through a VS Code extension. Zowe Explorer will activate that extension and handle credentials for Zowe Profiles through the custom credential manager override that is automatically setup for the user after the custom credential manager has activated successfully.

The common workflow when installing the custom credential manager is as follows when using the Kubernetes credential manager extension in this case:

1. The user installs Kubernetes secrets credential manager extension (through the VS Code marketplace or a .vsix file)
2. imperative.json is set to Secrets for Kubernetes
3. Zowe Explorer activates the extension and begins securing/storing credentials with Kubernetes secrets
4. User uninstalls Kubernetes secrets credential manager extension
5. Refresh is required for changes to happen
6. imperative.json is set to the default @zowe/cli
7. Zowe Explorer begins to secure credentials with Keytar

If you wish to develop your own custom credential manager when extending Zowe Explorer, please take a look at the Kubernetes credential manager extension repository for a sample monorepo on how integrating your own credential manager can be performed for Zowe Explorer and Zowe CLI.