Alex -

Working with PowerShell Secret Management and Secret Vault

The two new PowerShell modules put API keys, credentials and other secrets under lock and key to protect sensitive information in automation and remoting scenarios.

Automation with PowerShell is a double-edged sword. For a script to handle most administrative tasks, you risk exposing your organization's valuable credentials.

A common problem with PowerShell is how to manage the sensitive information -- credentials, keys and any sensitive values -- that scripts rely on to run. You can use existing PowerShell commands to generate and manage credentials, and export them as encrypted files. You can import these files when the script executes, but these are hacks, not a secure approach. An industrious attacker with access to your infrastructure could scrape credentials from a variety of sources. Microsoft developed two PowerShell modules named Secret Management and Secret Store to keep credentials and other sensitive data protected.

How do the Secret Management and Secret Store modules work?

The Secret Management module eases the way to store secrets within extension vaults, stored locally or remotely, and then retrieve them. The PowerShell Secret Management module serves as the worker process that performs all secret storage, management and encryption.

The Secret Management module supports five secret data types:

The module's core commands streamline PowerShell's ability to access and manage new and stored secrets, and register and manage vault extensions.

The Secret Store module is an extension vault that connects to the Secret Management module. It stores secrets in a file for the current user account context and uses .NET cryptographic APIs to encrypt any file contents. The module protects secrets in memory and decrypts them upon retrieval. During the configuration, you set a password to store, access and retrieve secrets. Extension vaults support the storage and management of metadata associated with a secret.

The module works on supported PowerShell platforms, including Windows PowerShell 5.1 and the newer cross-platform PowerShell for Windows, Linux and macOS.

How to install the PowerShell modules

To install the Secret Management module from the PowerShell Gallery, use the following command:

Install-Module -Name Microsoft.PowerShell.SecretManagement -Repository PSGallery

To install the Secret Store module from the PowerShell Gallery, use the following command:

Install-Module -Name Microsoft.PowerShell.SecretStore -Repository PSGallery

To see the available commands with each module, use Get-Command:

Get-Command -Module Microsoft.PowerShell.SecretManagement
Get-Secret Retrieves a secret by name from vaults.
Get-SecretInfo Retrieves secret metadata information for a secret.
Get-SecretVault Outputs information for a registered vault.
Register-SecretVault Adds a SecretManagement extension vault module for the current user.
Remove-Secret Deletes secret from an extension vault registered by SecretManagement.
Set-Secret Adds a secret to an extension vault registered by SecretManagement.
Set-SecretInfo Adds secret metadata to a secret in a vault.
Set-SecretVaultDefault Updates the vault registry to set vault name as the current user's default vault.
Test-SecretVault Checks the extension vault for errors.
Unregister-SecretVault Removes the extension vault from SecretManagement for the current user.

To find all the commands available for the SecretStore module, run the following command:

Get-Command -Module Microsoft.PowerShell.SecretStore
Get-SecretStoreConfiguration Finds SecretStore configuration information and outputs the properties.
Reset-SecretStore Deletes secret data and resets the SecretStore to the default values.
Set-SecretStoreConfiguration Configures the SecretStore properties.
Set-SecretStorePassword Changes current SecretStore password with a new one.
Unlock-SecretStore Decrypts SecretStore with password.

Working with Secret Management and Secret Store modules

You use the two PowerShell modules together for different scenarios and storage.

To start, run Get-SecretVault to see any registered secret vaults.

The Secret Management module helps you manage secrets after you register an extension vault. In addition to the Secret Store vault, Secret Management module works with several other vaults, including Azure Key Vault, KeePass, LastPass and HashiCorp. Click on this link to run a search in the PowerShell Gallery to find compatible extension vaults.

To start, create a vault with the Register-SecretVault cmdlet with a name, module name and other details if you do not want to use the default configuration. To create a default vault, run the following command:

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

Run Get-SecretVault to verify the vault named MySecret exists. It should return a value of True.

To create a secret, run Set-Secret with a name and value. For example, to add a secret, execute the following command:

Set-Secret -Name Password -Secret "[email protected]"
add secret to vault
The Set-Secret cmdlet adds a secret to a registered vault.

Because this is the first secret to be saved in the vault, PowerShell will prompt you for a password to add, retrieve, remove and save secrets.

To retrieve the value, call the Get-Secret command with the name of the item secret:

Get-Secret -Name Password

When you retrieve the secret, PowerShell does not return a plaintext version of the saved value but returns the type System.Security.SecureString. To get the actual value, use the -AsPlainText property:

Get-Secret -Name Password -AsPlainText

You can add metadata to describe the secret, such as the purpose of the saved value. You can also review the information about the kept secret, which will include any metadata associated with the secret. The module does not store metadata securely, so it should not contain restricted information.

Set-Secret -Name OAuthToken -Secret "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9" -Metadata @{Purpose="Office 365 OAuth Token"}

To find the associated information for the secret name, use the following command:

Get-SecretInfo -Name OAuthToken
Retrieve secret metadata
Use the Get-SecretInfo cmdlet to find secret metadata information.

Use standard PowerShell syntax to select the required field and retrieve the associated metadata:

Get-SecretInfo -Name OAuthToken | Select Name, Metadata
stored secret metadata
Output the metadata for the stored secret.

To remove a stored secret, use one of the two following PowerShell commands:

Remove-Secret -Name OAuthToken

Get-Secret -Name OAuthToken | Remove-Secret

Once executed, there is no way to recover the deleted secret.

These new modules ease the management and use of secrets in an extension vault. Employing multiple vaults gives you a way to store more critical values in more secure vaults as needed.

Scenarios for using Secret Management and Secret Store

The ability to store credentials, keys and any secure or sensitive values within a vault for reuse is a powerful addition to PowerShell. Following are three common situations for these modules:

  1. storing credentials for remote PowerShell connections;
  2. reusing tokens for access to other systems; and
  3. saving secure URLs for RESTful API calls.

These options cover most PowerShell automation scenarios. A connection to cloud services, such as Microsoft 365 and Azure, requires credentials, and these modules and the secure storage they provide are suited for this scenario.

The following example sets a secret with Microsoft 365 credentials, retrieves them and passes them to the Microsoft Online module to connect to the cloud.

# Create Microsoft 365 Credential Secret
$username = "[email protected]"
$password = ConvertTo-SecureString "[email protected]" -AsPlainText -Force
$creds = New-Object System.Management.Automation.PSCredential($username,$password)
# Create the secret by storing the PSCredential object
Set-Secret -Name M365 -Secret $cred -Metadata @{Information="M365 Credentials for Tenant"}
# Retrieve the Stored Credentials
$m365creds = Get-Secret -Name M365Creds
# Connect to Microsoft Online with the retrieved credentials
Connect-MsolService -Credential $m365creds

The PowerShell Secret Management and Secret Store modules add a layer of security not just for credentials but API keys, passphrases, GUIDs and other information that becomes available securely during PowerShell execution.

Dig Deeper on Windows administration tools