Edit

Get started with the SecretStore module

  • Article

The SecretManagement and SecretStore modules are available from the PowerShell Gallery and can be installed using PowerShellGet commands.

# Install with PowerShellGet 2.x
Install-Module Microsoft.PowerShell.SecretManagement
Install-Module Microsoft.PowerShell.SecretStore

# Install with PSResourceGet 1.x
Install-PSResource Microsoft.PowerShell.SecretManagement
Install-PSResource Microsoft.PowerShell.SecretStore

Once you have installed the modules, you can load the modules and begin using or creating new secrets.

Import-Module Microsoft.PowerShell.SecretManagement
Import-Module Microsoft.PowerShell.SecretStore

Create a vault and add a secret

First you must register the vault. The Name parameter is a friendly name and can be any valid string.

Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

The DefaultVault parameter makes this the default vault.

Now you can create a secret.

Set-Secret -Name TestSecret -Secret "TestSecretPassword"

This example passes a plaintext string for the value of the secret. The secret value can be one of five supported types:

  • byte[]
  • String
  • SecureString
  • PSCredential
  • Hashtable

The first time you access the vault you must provide a password for the new vault. This password is used to lock and unlock the vault.

Vault SecretStore requires a password.
Enter password:
********
Enter password again for verification:
********

Run Get-Secret to retrieve the secret. Using the AsPlainText switch returns the secret as an unencrypted string.

PS> Get-Secret -Name TestSecret -AsPlainText
TestSecretPassword

To get the list of all of your secrets, you can run:

PS> Get-SecretInfo

Name       Type   VaultName
----       ----   ---------
TestSecret String SecretStore

Notes

When you run Set-Secret with the Name parameter to specify the name of the secret, the cmdlet calls GetSecret() that's implemented by the vault extension. Set-Secret passes through the name as provided by the user. The vault extension looks up the secret by that name. If GetGecret() returns a match, Set-Secret overwrites the secret unless you use the NoClobber parameter. The vault extension always writes the secret information it receives.

It's up to the vault extension implementation to decide whether or not to use a case-sensitive comparison on the name. For example, secret names in the Microsoft.PowerShell.SecretStore extension vault are case-insensitive. If the name you pass to Set-Secret differs only by case with the name of an existing secret in a SecretStore vault, the name is overwritten with the new value you provided.