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

• Microsoft.PowerShell.SecretManagement
• Microsoft.PowerShell.SecretStore

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

Install-Module Microsoft.PowerShell.SecretManagement, Microsoft.PowerShell.SecretStore

Introducing SecretManagement

The SecretManagement module helps users manage secrets by providing a common set of cmdlets to interface with secrets across vaults. SecretManagement utilizes 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
Set-SecretInfo
Set-SecretVaultDefault
Test-SecretVault
Unregister-SecretVault

Reference documentation for this module is available on our Microsoft docs site.

SecretManagement Uses

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 a convenience feature which allows users to simplify their interactions with various vaults by only needing to learn a single set of cmdlets.

Since SecretManagement is a module abstraction layer in PowerShell, it becomes useful once extension vaults are registered (more on that below). There are trade-offs between security, usability, and specificity for any vault so it is up to the user to configure SecretManagement to integrate with the vaults that best match their requirements, as well as to assess the extent to which they trust any vault extensions not developed by Microsoft.

SecretManagement does not impose a common authentication for extension vaults and allows each individual vault to provide its own mechanism. Some may require a password or token, while others may leverage current account credentials.

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

Introducing SecretStore

SecretStore is a cross-platform, local, extension vault which is available on the PowerShell Gallery. This vault is designed to be supported in all the same environments as PowerShell 7, usable in popular PowerShell scenarios (like automation and remoting), and utilizes common security practices. This vault encrypts secrets on the file system, for remote options we recommend exploring alternative vaults (like Azure Key Vault).

Features of SecretStore

The SecretStore vault stores 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

Reference documentation for this module is available on our Microsoft docs site.

Getting Started with SecretManagement

Once you have SecretManagement installed you can run Get-SecretVault to see what secret vaults you have registered. If this is your first time using the module this command will return nothing since nothing is registered, read on to learn how to discover, install, and register secret vaults. Once you have a vault registered you can utlize the SecretManagement cmdlets to view, get, set, and remove secrets.

Extension Vault Ecosystem

SecretManagement becomes useful once you install and register extension vaults. Extension vaults, which are PowerShell modules with a particular structure, provide the connection between the SecretManagement module and any local or remote Secret Vault.

Discovering and Installing Vault Extensions

To find SecretManagement extension vault modules, search the PowerShell Gallery for the “SecretManagement” tag. Some community vault extensions that are available:

• KeePass
• LastPass
• Hashicorp Vault
• KeyChain
• CredMan
• Azure KeyVault (Microsoft Owned)

Thank you to everyone who has created vaults thus far!

Getting Started with SecretStore

While this example is being shown with SecretStore, the example can be followed with any number of extensions vaults.

First Register the vault, the name parameter is a friendly name and can be anything you choose 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 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 Get-Secret -Name TestSecret -AsPlainText TestSecret To see the names all of your secrets you can run Get-SecretInfo

Get-SecretInfo

Name                       Type VaultName
----                       ---- ---------
TestSecret               String SecretStore
# To update your secret you can utilize the Set-Secret cmdlet
PS C:\> Set-Secret -Name TestSecret -Secret "TestSecretUpdate"
# To remove the secret you can utilize the Remove-Secret cmdlet
PS C:\> Remove-Secret -Name TestSecret

Using Metadata with the SecretStore

Users can optionally provide non-sensitive metadata for their secrets. Secret metadata was a highly requested feature because as users store more secrets in SecretManagment, they may want to know what the secrets are intended for (for example, a particular subscription, or scenario). As users manage their secrets they may also want to add metadata around secret creation date, expiration time, or other information to manage the secret lifecycle. Metadata is optional for secret vaults to support so it may not be available for all vault extensions.

To create a new secret with metadata you can run:

Set-Secret -Name foo -Secret fooSecret -Metadata @{purpose = "example"}

To view secret metadata you can then run the command:

Get-SecretInfo | select name, metadata

You can also set metadata for an existing secret using the Set-SecretInfo cmdlet:

Set-SecretInfo bar -Metadata @{purpose = "showing the new cmdlet"}

Since SecretMetadata is for non-sensitive data, if you need to store sensitive metadata you may want to consider storing it as a hashtable in the vault itself. For example, if I consider the username, or subscriptionID to be sensitive for particular secrets for resource1 and resource2, I may want to create a secret like:

Set-Secret -name secretMetadata -Secret @{ resource1 = "username1, subID1"; resource2 = "username, subID2"}

Configuring the SecretStore

Separate from its integration with the SecretManagement interface, the SecretStore module is highly configurable.

It can be configured to require a password to unlock the store, or operate without a password. The no-password option still encrypts secrets on file and in memory. But the key for decryption is stored on file in the current user location, and is less secure.

SecretStore can also be configured to prompt the user for the password if needed. When a password is provided, it applies only to the current PowerShell session and only for a limited time. The password timeout time is also configurable and set to 15 minutes by default. Password prompting is useful when SecretStore is used interactively. For automation scenarios, password prompting can be disabled and will instead return an error.

If password prompting is disabled and a password is required to access secrets, a Microsoft.PowerShell.SecretStore.PasswordRequiredException will be thrown. In this case, the SecretStore can be unlocked using the Unlock-SecretStore cmdlet.

There is also a SecretStore Scope setting, but it is currently set to CurrentUser and cannot be changed.

The default configuration is set by default for best security and interactive use.

Get-SecretStoreConfiguration

      Scope Authentication PasswordTimeout Interaction
      ----- -------------- --------------- -----------
CurrentUser       Password             900      Prompt

Using the SecretStore in Automation

This is an example of automation script that installs and configures the Microsoft.PowerShell.SecretStore module without user prompting. The configuration requires a password and sets user interaction to None, so that SecretStore will never prompt the user. The configuration also requires a password, and the password is passed in as a SecureString object. The -Confirm:false parameter is used so that PowerShell will not prompt for confirmation.

The SecretStore password must be provided in a secure fashion. Here the password is being imported from an encrypted file using Windows Data Protection API, but this is a Windows only solution. Another option is to use a CI system mechanism such as secure variables.

Next, the SecretManagement module is installed and the SecretStore module registered so that the SecretStore secrets can be managed.

The Unlock-SecretStore cmdlet is used to unlock the SecretStore for this session. The password timeout was configured for 1 hour and SecretStore will remain unlocked in the session for that amount of time, after which it will need to be unlocked again before secrets can be accessed.

Install-Module -Name Microsoft.PowerShell.SecretStore -Repository PSGallery -Force
$password = Import-CliXml -Path $securePasswordPath

Set-SecretStoreConfiguration -Scope CurrentUser -Authentication Password -PasswordTimeout 3600 -Interaction None -Password $password -Confirm:$false

Install-Module -Name Microsoft.PowerShell.SecretManagement -Repository PSGallery -Force
Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

Unlock-SecretStore -Password $password

Getting Started with Azure Key Vault

The Azure Key Vault extension is available on the PowerShell Gallery beginning in Az.KeyVault module v3.3.0. This vault extension utilizes a common authentication system with the rest of the Az PowerShell module, and allows users to interact with an existing Azure Key Vault through the SecretManagement interface.

To utilize Azure Key Vault with SecretManagement first ensure that you have the Az.KeyVault module installed (Install-Module Az.KeyVault). You can then register the vault using your AZKVaultName and SubscriptionID:

Register-SecretVault -Module Az.KeyVault -Name AzKV 
-VaultParameters  
@{ AZKVaultName = $vaultName; SubscriptionId = $subID}

From there you can view the secrets you have (Get-SecretInfo), get secrets you may need (Get-Secret), create and update secrets (Set-Secret), and remove secrets (Remove-Secret).

For any feature requests or support with the Azure Key Vault extension please refer to their GitHub repository.

Building an Extension Vault

The value of the SecretManagement interface comes from the available underlying vault and becomes more useful with each community supported extension vault module. With this in mind, we took care to design the extension vault ecosystem in a way that would support vault developers. For more information on the design of SecretManagement, and how to build extension vaults please refer to this design document. We also hope SecretStore not only proves useful for SecretManagement users but also serves as an example for extension vault authors looking to build off of existing vaults.

A Note on Community Support

Community feedback has been essential to the iterative development of these modules. We really appreciate everyone who took the time to try out our preview releases and participate in the design process of these modules.

A huge thank you also to those community members who also took the time to build extension vaults and provided us with valuable feedback on the developer experience.

What’s Next

We hope to continue to invest in the SecretManagement experience based on the feedback we recieve from this GA release. If you have feature requests or scenarios you would like the module to support in the future please let us know in our GitHub repositories for SecretManagement and SecretStore repository.

Feedback and Support

To file issues or get support for the SecretManagement interface or vault development experience please use the SecretManagement repository. For issues which pertain specifically to the SecretStore and its cmdlet interface please use the SecretStore repository.

Sydney Smith

PowerShell Team