Working with PowerShell Secret Management and Secret Vault

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:

• PSCredential
• Hashtable
• SecureString
• String
• Byte[]

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

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

Get-Command -Module Microsoft.PowerShell.SecretStore

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 "Pass@word1"

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

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

Get-SecretInfo -Name OAuthToken | Select Name, Metadata

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 "Pass@word1" -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.