SecretManagement Preview 3
We are excited to announce two modules are now available on the PowerShell Gallery:
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 blog will explain what to expect from these modules, how to try them out, and what is coming next.
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
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.