Secrets Management Development Release

At Ignite 2019 we gave a preview of our PowerShell Secrets Management Module. This Secrets Management module, first proposed in RFC #234, creates an extensible abstraction layer in PowerShell for interacting with Secrets and Secrets Vaults. We are excited to publish a development release of this module to the PowerShell Gallery to get feedback on the cmdlet interface and to enable an iterative development experience. While the current release of this module is Windows only, we plan to support Linux, and eventually MacOS, in coming releases. We made the decision to publish our first preview of this module without cross-platform support to allow you to develop alongside us–check out this blog post for an overview of developing vault extensions.

What is Secrets Management?

The Secrets Management module helps users manage secrets by providing a set of cmdlets that let you store secrets locally, using a local vault provider, and access secrets from remote vaults. This module supports an extensible model where local and remote vaults can be registered and unregistered on the local machine, per user, for use in accessing and retrieving secrets. The module leverages existing secrets vaults, for example it uses Credential Manager (Cred Man), to provide the default local vault experience on Windows. This module focuses on retrieving/using secrets from existing vaults, leaving the advanced secret/vault management to the existing vaults. While this module will eventually be cross-platform this alpha version of the module currently works only on Windows platforms. For a more detailed explanation of the goals of Secrets Management watch this session from Ignite 2019.

How can I start using this module?

The module has been published to the PowerShell Gallery, to install the module using PowerShellGet, open a PowerShell console and run the following Install-Module -Name Microsoft.PowerShell.SecretsManagement -AllowPrerelease.

Once you have the module installed you can begin using the seven cmdlets implemented by the module:

Add-Secret
Get-Secret
Get-SecretInfo
Get-SecretsVault
Register-SecretsVault
Remove-Secret
Unregister-SecretsVault

For example you may want to add a secret to your local vault, and then use that secret to invoke a rest method.

If you run Get-SecretsVault you will notice that your default vault is already registered.

To add your secret you can run Add-Secret -Name MyApiKey -Secret "This is my API key"

If you then run Get-SecretInfo -Name MyApiKey you will see that it has been added to your local vault, and if you run Get-Secret -Name MyTestSecret you will notice that it has been saved as a secure string. We automatically convert all strings to secure strings to avoid plain text passwords accidently being exposed in the console.

To use the secret, as a string, in order to invoke a rest method you can run

Publish-Module -Path C:\Modules\Publish\MyNewModule -NuGetApiKey (Get-Secret MyApiKey -AsPlainText)

By using the -AsPlainText switch the secret is returned as an ordinary string.

What is a “Development Release”?

A development release simply means that the module is still actively being developed. In other words, the module is not feature complete, we are not committing to not making breaking changes, and we do not recommend using the module in production environments. The goal of this development release is to get it in the hands of potential users so that we can get feedback to make the best possible decisions as we continue to develop it.

When will this module be production-ready?

Right now we do not have a committed date to publishing this module as “Generally Available”, instead we are committed to getting this module right, and feature complete so that it can be dependably used. We are targeting late spring/early summer 2020 for our GA release of this module, but will share more information on this as we progress closer to a production-ready module.

How can I give feedback on this module?

There are a few ways to provide feedback on this module. We have created a survey to target specific questions we are interested in answering in regards to this module. For feedback on the design of the module the best place to provide feedback is to comment on the RFC (the design specification). For support on the module, or reporting a bug, please open an issue in the PowerShell/modules repo with “(Secrets Management)” specified in the issue title.

Will “x” Vault be available? How can I develop vault extensions?

A large part of the value of the module comes from vault ecosystem, and while we want to encourage development of vault extensions through the design of our module, we (the PowerShell Team) do not have the expertise or capacity to manage various vault extensions. Therefore, we are leaving it up to the vault owners/users to help us build out that ecosystem. While we have tried to ensure that the design of our module makes for a simple and straightforward development process for vault extension owners we cannot be sure of that without feedback from developers. We have published a blog on vault extension development, along with example extensions for more information on how to start developing. If you have any questions about vault extension development please open an issue in our repository PowerShell/modules repo.

Sydney Smith Program Manager, PowerShell Team