@zowe/secure-credential-store-for-zowe-cli

Secure Credential Store Plug-in for Zowe CLI

Note: This plugin is not supported for Zowe v2 LTS because the secure credential manager is now built in to Zowe CLI. As long as Zowe v1 LTS is supported, it is still maintained and will receive bug fixes and security patches.

The Secure Credential Store Plug-in for Zowe CLI lets you store your credentials securely in the default credential manager in your computer's operating system.

As a systems programmer or application developer, you can store your credentials securely to help prevent your user name and password from being compromised as a result of a malware attack or unlawful actions by others.

• How the plug-in works
• Software requirements
• Installing
• Building from source
• Securing Zowe CLI profiles
• Running tests
• Uninstalling
• Contributing

How the plug-in works

The plug-in invokes a native Node module that manages user IDs and passwords in the default credential manager in your computer's operating system.

When you install Zowe CLI but do not install the plug-in, your Zowe CLI profiles display as plain text in your default credential manager. For example:

type: zosmf
host: test
port: 1234
user: USERNAME
pass: PASSWORD
rejectUnauthorized: false

With the plug-in installed and configured, the plug-in lets you store your Zowe CLI credentials securely. For example:

type: zosmf
host: test
port: 1234
user: 'managed by @zowe/secure-credential-store-for-zowe-cli'
pass: 'managed by @zowe/secure-credential-store-for-zowe-cli'
rejectUnauthorized: false

The initial behavior of the plug-in varies based on the method that you use to install the plug-in.

• When you install the plug-in using the Windows Installation Wizard, the installation process starts the plug-in and updates all of your existing Zowe CLI profiles automatically. No further action on your part is required.
• When you install the plug-in from an online registry or a local package, the plug-in starts, however, you must update your existing Zowe CLI profiles manually.

Software requirements

Before you install and use the plug-in:

• Install Zowe CLI on your computer. For more information, see Installing Zowe CLI.
• NPM version 7 (npm@7) and NPM version 8 (npm@8) requirements: On Windows operating systems, ensure that your computer is connected to the Internet and issue the following command before you install the plug-in:

  npm install -g prebuild-install
  

Linux (graphical)

• Install the packages gnome-keyring and libsecret (or libsecret-1-0 on Debian and Ubuntu).

Linux (headless)

• Install the packages listed for graphical Linux above.

• Run the commands below to unlock the Gnome keyring. The keyring must be unlocked again for each new user session.

  The second command will prompt for your password. Press Ctrl+D twice when you have finished typing it.

  export $(dbus-launch)
  gnome-keyring-daemon -r --unlock --components=secrets

• To automatically unlock the Gnome keyring at log on:

  Note: The following steps have been tested on CentOS, SUSE, and Ubuntu. Results may vary on other Linux distributions.

  1. Install the PAM module for Gnome keyring. The package name depends on your distribution:

     • gnome-keyring-pam - CentOS, Fedora, SUSE
     • libpam-gnome-keyring - Debian, Ubuntu

  2. Make the following edits to the files /etc/pam.d/login (for TTY login), and /etc/pam.d/sshd if it exists (for SSH login).

     • Add this line at the end of the auth section:

       auth optional pam_gnome_keyring.so
       

     • Add this line at the end of the session section:

       session optional pam_gnome_keyring.so auto_start
       

  3. Add the following lines to ~/.bashrc. This will launch DBus which is required by Gnome keyring, and start the keyring daemon so it is ready to be used by Zowe CLI commands.

     if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
       exec dbus-run-session -- $SHELL
     fi
     
     gnome-keyring-daemon --start --components=secrets

  4. Reboot your machine and run a Zowe CLI command that uses secure credentials to test that automatic unlock of the keyring works.

zLinux

• Follow all installation steps above for Linux

• Install the following packages:

  • Python 3 (> 3.6.0)
  • make
  • gcc-c++
  • libsecret-devel

Installing

Use one of the following methods to install the plug-in:

• Install the plug-in to Zowe CLI from an online registry or a local package.

  Use this method when you want to install the plug-in quickly and start using it. With this method, you secure your user IDs and passwords manually.

  For more information, see Install Plug-ins from an Online Registry or Install Plug-ins from a Local Package.

• Build the plug-in from source and install it into your Zowe CLI implementation.

  Use the build from source method when you want to install the plug-in to Zowe CLI using the most current binaries and modify the behavior of the plug-in. For example, you want to create a new command and use the plug-in with the command that you created.

  For more information, see Building from source.

Building from source

Follow these steps:

1. The first time that you clone the Secure Credential Store Plug-in for Zowe CLI from the GitHub repository, issue the following command against the local directory:

   npm install
   

   The command installs the required dependencies and several development tools. You can run the task at any time to update the tools as needed.

2. To build your code changes, issue the following command:

   npm run build
   

   The first time you build your code changes, you will be prompted for the location of the Imperative CLI Framework package, which is located in the node_modules/@zowe folder in the Zowe CLI home directory.

   Note: When you update package.json to include new dependencies, or when you pull changes that affect package.json, issue the npm update command to download the dependencies.

3. Issue one of the following commands to install the plug-in:

   zowe plugins install <local path your cloned repo>
   

   Or:

   zowe plugins install .
   

Tip: After the installation process completes, it validates that the plug-in was installed correct and the names of its commands, options, and arguments do not conflict with that of the other plug-ins that you installed into your Zowe CLI implementation.

When the validation process is successful, the following message displays:

Validation results for plugin 'secure-credential-store':
Successfully validated.

When an unsuccessful message displays, you can troubleshoot the installation by addressing the issues that the message describes. You can also review the information that is contained in the log file that is located in the Zowe CLI home directory.

Securing Zowe CLI profiles

When you install the plug-in using the Windows Installation Wizard, the plug-in secures all of your existing (Zowe CLI) profiles. Conversely, when you do not use the wizard to install the plug-in (you installed the plug-in from an online registry or from a local package), you secure your profiles manually using the Set command. For more information, see How the plug-in works.

Issue the following Set command to secure all of your Zowe CLI profiles:

zowe config set CredentialManager @zowe/secure-credential-store-for-zowe-cli

When you want to unsecure all of your Zowe CLI profiles, issue the following Reset command:

zowe config reset CredentialManager

Your profiles will need to be recreated after the CredentialManager is reset.

Note: For information about how you can customize the behavior of the plug-in, see Overriding the Default Credential Manager with a Plugin in the Imperative CLI Framework documentation.

Running tests

You can perform the following types of tests on the Secure Credential Store Plug-in:

• Unit
• Integration
• System

Note: For detailed information about conventions and best practices for running tests against Zowe CLI plug-ins, see see Zowe CLI Plug-in Testing Guidelines.

Before running the system and integration tests, you must have a server connection to run against. For more information, see Software requirements.

To define access credentials to the server, copy the file named .../__tests__/__resources__/properties/example_properties.yaml and create a file named .../__tests__/__resources__/properties/custom_properties.yaml.

Note: Information about how to customize the custom_properties.yaml file is provided in the yaml file itself.

Issue the following commands to run the tests:

1. npm run test:unit
2. npm run test:integration
3. npm run test:system

Any failures potentially indicate an issue with the set-up of the Rest API or configuration parameters that were passed in the custom_properties.yaml file.

Uninstalling

Follow these steps:

1. Issue the following command:

   zowe plugins uninstall @zowe/secure-credential-store-for-zowe-cli
   

After the uninstallation process completes successfully, the product no longer contains the plug-in.

Contributing

For information about contributing to the plug-in, see the Zowe CLI Contribution Guidelines. The guidelines contain standards and conventions for developing plug-ins for Zowe CLI. This includes information about running, writing, maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates properly with Zowe CLI.

Tutorials

To learn about building new commands or a new plug-in for Zowe CLI, see Develop for Zowe CLI.

Imperative CLI Framework documentation

Imperative CLI Framework documentation is a key source of information to learn about the features of Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to the documentation as you develop your plug-in.