SecretsManagement module for PowerShell: Save passwords in PowerShell

• Author
• Recent Posts

Mike Kanakos

Mike Kanakos is a Cloud and Datacenter Microsoft MVP, tech blogger and PowerShell community leader. You can follow Mike's blog at networkadm.in or on Twitter at @MikeKanakos.

Latest posts by Mike Kanakos (see all)

• SecretsManagement module for PowerShell: Save passwords in PowerShell - Tue, Dec 22 2020
• Finding nested Active Directory groups faster with PowerShell - Tue, Sep 15 2020
• Monitoring Active Directory with the PowerShell module PSADHealth - Mon, Jan 20 2020

Overview ^

The PowerShell team at Microsoft has been working on the SecretsManagement module for over a year and has already released several versions. Each release has included additional features, functionality, and stronger security.

Secrets management in PowerShell is broken up into two parts: the engine and the storage vault. The SecretsManagement module is the engine and is responsible for the management and encryption of passwords and other secrets. The secrets are then stored in a vault. I will demo the SecretsManagement module and the SecretStore vault, which is a vault offered from Microsoft.

There are other vaults available for LastPass, KeePass, HashiCorp Vault, Keychain, and the Windows Credential Manager. These vaults are built by the open-source community, and more become available all the time. Sydney Smith from the PowerShell team at Microsoft wrote an excellent blog post explaining this in further detail. I encourage you to read her article, as it contains useful tips for working with the vault.

At the time of writing, the current modules from Microsoft are preview versions. They're not officially considered "production ready," but I have used these modules in my production environment for over a month now with no bugs, hiccups, or gotchas. Let's roll up our sleeves and see how these modules work.

Installation ^

I will be installing the Preview6 version of the SecretsManagement module and Preview4 of the SecretStore. Both modules work in Windows PowerShell (version 5.x) and PowerShell Core (versions 6.x and 7.x). Installation of the modules is easy to do, but there are two potential gotchas to watch for.

The first is that since these are preview modules, you need to use the -AllowPrelease parameter during installation. That parameter isn't available with the default version of WindowsPowerShell v5.x. To get around that issue, you need to update your version of the PowerShellGet module to the latest version. PowerShellGet is the module that handles installing modules. The syntax for the PowerShellGet module update is:

$params = @{
    Name              = 'PowerShellGet'
    Repository        = 'PSGallery'
    AllowClobber      = $true
    Force             = $true
}
Install-Module @Params

The second point to be aware of is that these latest versions of the modules contain breaking changes. You need to uninstall any old module versions before installing these recent versions. With that out of the way, let's install the SecretsManagement module, which I mentioned is the engine that does all the processing and encryption:

$params = @{
    Name              = 'Microsoft.PowerShell.SecretManagement'
    AllowPreRelease   = $true
    Repository        = 'PSGallery'
}
Install-Module @Params

Then you will install a vault that will store your secrets. I will be using the SecretStore module:

$params = @{
    Name              = 'Microsoft.PowerShell.SecretStore'
    AllowPreRelease   = $true
    Repository        = 'PSGallery'
}
Install-Module @Params

Creating the Secrets Vault ^

After installation is completed, the next step is to create a vault for storing your secrets. This process is called "registering a vault":

$params = @{
    Name            = 'VaultDemo'
    ModuleName      = 'Microsoft.PowerShell.SecretStore'
    DefaultVault    = $true
    AllowClobber    = $true
}
Register-SecretVault @params

Registering your first vault

The vault you create needs a master password assigned. But notice that it's not assigned when the vault is registered. While that may seem odd, that's the expected behavior because the vault doesn't exist until you attempt to store a secret. Registering a vault only adds the settings to the registry. It builds the vault on the fly when the first secret is saved to the vault.

Remember that the SecretStore vault is only one of a few different vault providers that you can use to store your secrets. The syntax to create and manage secrets is identical across vaults because the SecretsManagement module does all the work. You can have multiple vaults installed on your computer, and they can be different vaults.

Creating your first secret ^

Creating and storing your first secret is a simple task. The help file included with the module is a great way to start, and I recommend you use it to become familiar with the cmdlets. Let's generate a list of available commands:

get-command -module 'Microsoft.PowerShell.SecretManagement'

SecretsManagement module cmdlets

To create a secret, use the Set-Secret cmdlet.

Set-Secret -name "TestSecret" -secret "MySecretData"

Creating your secret in the vault

As I mentioned earlier, the vault is instantiated when the first secret is saved to it. You are also prompted to set the master password; this is a one-time process. After saving a secret, you can view the vault by typing:

Get-SecretInfo

Viewing a list of secrets in the vault

You're probably wondering though, "Secrets are great, but I need to save credentials."

In the earlier example, the cmdlet only accepted a secret; there were no parameters to accept a username AND a password. It's not obvious at first, but secrets can be more than a simple string of characters, and it is possible to save credentials to a vault. Remember that in PowerShell, we store credentials as a PSCredential object. The PSCredential object is one object that contains two pieces of information.

The trick here is to understand that a credential object (a username and password) is one secret. That secret can then be passed into the vault with the correct syntax. To store a credential object in the vault, you need to build the object first and pass the object to the vault cmdlet. That sounds harder than it is. Let me show you how.

Set-Secret -name MyAdminCred -secret (get-credential MyDomain\Admin)

Creating a PSCredential object as a secret

Once the credential is saved to the vault, you can view the vault to confirm that the new credential was added. I saved the PSCredential object in the old-school domain format, but I could have used UPN format instead (username@domainname). The vault stores data you type; it doesn't impose limits on what you type or validate the data.

Vault contains a PSCredential object

To take that point one step further, that username and password combination I typed was not validated against a domain. If I typed a bad password, the vault will save it. If I attempt to log in with faulty credentials, it will fail. The vault is a storage mechanism; it saves whatever you type for a secret.

Vaults have a default timeout value of 15 minutes. It will prompt you to enter the master password the first time you try to access a vault or if 15 minutes have passed with no activity. The timeout value can be changed, and you can also choose to remove the vaults' requirement of a master password. I would not recommend that, as I am sure you can imagine that would be a major security risk.

Recalling a secret from the vault ^

Once you have data saved to the vault, retrieving a secret from the vault is another process that is simple to execute. The syntax to recall a secret is easy to understand:

Get-secret -Name MyAdminCred

Recalling a Secret from the vault

I retrieved the secret from the vault. I was also prompted for my master password because the vault hadn't been accessed in the last 15 minutes.

You can recall the secret and save to a variable:

$Cred = Get-Secret MyAdminCred

Recalling a secret to a variable

Saving your credentials to a variable for reuse is a common scenario, but it's also one that doesn't need to happen at all. Instead, you can use the pipeline to recall a secret from the secret vault and pass it to a cmdlet.

You can see in the example below that I am logged in as a user named mkadmin. I am recalling a credential named CredVagrant, which contains the username and password for a user named Vagrant. I then pass that credential from the vault to the New-PSSession cmdlet, which sets up a session as the user named Vagrant. I then use that pssession cmdlet to connect to a domain controller as the user named Vagrant.

Connecting to a remote computer with alternate credentials

Summary ^

We have seen how the SecretsManagement and SecretStore modules from Microsoft enable you to safely and securely store encrypted passwords on your computer and recall them for use later on. This functionality allows anyone to secure not just passwords, but any type of information that may not be wise to save in unencrypted form in something like a plain-text script. Now we have a way to save API keys, GUID strings, pass phrases, and others in a simple-to-use and efficient tool that integrates effortlessly into our scripts and command-line tools.