SecretManagement Preview 3

Sydney Smith

We are excited to announce two modules are now available on the PowerShell Gallery:

• Microsoft.PowerShell.SecretManagement preview3
• Microsoft.PowerShell.SecretStore preview1

To install the modules and register the SecretStore vault, open any PowerShell console and run:

Install-Module Microsoft.PowerShell.SecretManagement -AllowPrerelease
Install-Module Microsoft.PowerShell.SecretStore -AllowPrerelease
Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

NOTE: This version of the module has a major breaking changing, if you have used past preview versions of the SecretManagement module, secrets previously stored will not be accessible in this version. Please migrate your secrets before updating. Your old secrets will not be removed after updating so they can be accessed by explicitly importing an earlier version of the module.

If you see an error indicating the a dependency of SecretStore cannot be installed, please uninstall all previously installed versions of SecretManagement and try again (this is due to an issue in PowerShellGet with prerelease modules).

This blog will explain what to expect from these modules, how to try them out, and what is coming next.

Re-Introducing SecretManagement

The SecretManagement module helps users manage secrets by providing a common set of cmdlets to interface with secrets across vaults. This module supports an extensible model where local and remote vaults can be registered and unregistered for use in accessing and retrieving secrets. The module provides the following cmdlets for accessing secrets and managing SecretVaults:

Get-Secret
Get-SecretInfo
Get-SecretVault
Register-SecretVault
Remove-Secret
Set-Secret
Test-SecretVault
Unregister-SecretVault

SecretManagement is valuable in heterogeneous environments where you may want to separate the specifics of the vault from a common script which needs secrets. SecretManagement is also as a convenience feature which allows users to simplify their interactions with various vaults by only needing to learn a single set of cmdlets.

Some key scenarios we have heard from PowerShell users are:

• Sharing a script across my org (or Open Source) without knowing the platform/local vault of all the users
• Running my deployment script in local, test and production with the change of only a single parameter (-Vault)
• Changing the backend of the authentication method to meet specific security or organizational needs without needing to update all my scripts

Secret Management Preview 3

Since our first two preview releases we have done significant investigation to maximize the usability, supportability, and extensibility of the module. Through this process we have re-designed the module is a couple of impactful ways:

• Separated the SecretManagement module from a built-in default vault
• Simplified the experience for authoring vaults to give more flexibility to authors–for more information on that check out this vault-author focused blog post

Separating SecretManagement from a built in vault

In this release we have separated the interface for accessing secrets and registering vaults from any vault implementation. We made this decision based on feedback that there are trade-offs between security, usability, and specificity for any vault that would be built into the SecretManagement module. We opted for a configurable model that allows the user to install and set as default the vault that best matches their requirements.

Consequently, vault registration metadata is stored on the file system with the expectation that it is not sensitive data. As a part of this design we leave secure vault authentication up to the vault extensions. While some vault implementations may take advantage of user context others may require interactive authentication from the user (or use another method).

We recognize that the value of the SecretManagement interface comes from the available underlying vaults. In other words if there are no vault extensions to register the module is useless. With this in mind, we wrote (and published a preview of) a local, cross-platform vault called SecretStore. We hope this vault not only proves useful for SecretManagement users but also serves as an example for extension vault authors looking to build off of existing vaults. We have also provided an example implementation of a Windows Credential Manager vault in our GitHub repository.

SecretStore Preview 1

SecretStore is a cross-platform local extension vault which is available as a preview on the PowerShell Gallery. We designed this vault as a best attempt at creating a vault that is available where PowerShell is, usable in popular PowerShell scenarios (like automation and remoting) and utilizes common security practices. This vault does have security limitations and we recommend exploring alternative vaults if data is highly sensitive.

Features of SecretStore

The SecretStore vault stoes secrets locally on file for the current user, and uses .NET Core cryptographic APIs to encrypt file contents. This extension vault is configurable and works over all supported PowerShell platforms on Windows, Linux, and macOS. The following cmdlets are provided to manage SecretStore:

- Get-SecretStoreConfiguration
- Set-SecretStoreConfiguration
- Unlock-SecretStore
- Update-SecretStorePassword
- Reset-SecretStore

For more information on the design of the SecretStore please refer to this design document.

Getting started with SecretStore and SecretManagement

After you have installed the modules open any PowerShell console to register the vault and create your first secret.

# First Register the vault, the name parameter is a friendly name and can be anything you choose
PS C:\> Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
# Now you can create a secret, you will also need to provide a password for the SecretStore vault
PS C:\> Set-Secret -Name TestSecret -Secret "TestSecret"
Vault SecretStore requires a password.
Enter password:
*******
# Run Get-Secret to retrieve the secret, using the -AsPlainText switch will return it as a readable string
PS C:\> Get-Secret -Name TestSecret -AsPlainText
TestSecret
# To see metadata about all of your secrets you can run Get-SecretInfo
PS C:\> Get-SecretInfo

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

What’s Next

Based on user feedback we plan to move towards a General Availability (GA) release for both modules. Through this time, we hope to work with vault extension authors to build out the vault ecosystem. The timing of these releases is highly dependent on feedback from this release.

Feedback and Support

To get support or give feedback on the SecretManagement module please open an issue in the SecretManagement repository. To get support or give feedback on the SecretStore module please open an issue in the SecretStore repository.

Sydney Smith
PowerShell Team

Sydney Smith PM, PowerShell

Follow