SecretManagement and SecretStore are Generally Available

Sydney Smith

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

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:

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

4 comments

Discussion is closed. Login to edit/delete existing comments.

  • Joshua Gold 0

    PS C:\Windows\system32> Install-Module Microsoft.PowerShell.SecretManagement, Microsoft.PowerShell.SecretStore
    PackageManagement\Install-Package : No match was found for the specified search criteria and module name ‘Microsoft.PowerShell.SecretManagement’. Try Get-PSRepository to see all available registered module repositories.
    At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm1:1772 char:21

    PackageManagement\Install-Package : No match was found for the specified search criteria and module name ‘Microsoft.PowerShell.SecretStore’. Try Get-PSRepository to see all available registered
    module repositories.
    At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm1:1772 char:21

    PS C:\Windows\system32> get-psrepository
    WARNING: Unable to find module repositories.

    This module install did work on another VM though, so I am wondering if this has to do with the account I am using or the version of PowerShell installed possibly

  • Robin Malik 0

    EDIT: Leaving comment, but solved by running Reset-SecretStore.

    Hi. Unfortunately the following line doesn’t work (prompt for a password as suggested by the docs) within either PS 5.1 or 7, using v1.0.0 of the modules:
    Set-Secret -Name TestSecret -Secret “TestSecret”

    I get the following errors:

    Exception calling "GetInstance" with "0" argument(s): "Cannot convert null to 'Microsoft.PowerShell.SecretStore.Authenticate' because it is a non-nullable value type"
    At C:\Program Files\WindowsPowerShell\Modules\Microsoft.PowerShell.SecretStore\1.0.0\Microsoft.PowerShell.SecretStore.Extension\Microsoft.PowerShell.SecretStore.Extension.psm1:124 
    char:17
    + ...         if ([Microsoft.PowerShell.SecretStore.LocalSecretStore]::GetI ...
    +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
        + FullyQualifiedErrorId : RuntimeBinderException
     
    Exception calling "GetInstance" with "0" argument(s): "Cannot convert null to 'Microsoft.PowerShell.SecretStore.Authenticate' because it is a non-nullable value type"
    At C:\Program Files\WindowsPowerShell\Modules\Microsoft.PowerShell.SecretStore\1.0.0\Microsoft.PowerShell.SecretStore.Extension\Microsoft.PowerShell.SecretStore.Extension.psm1:124 
    char:17
    + ...         if ([Microsoft.PowerShell.SecretStore.LocalSecretStore]::GetI ...
    +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
        + FullyQualifiedErrorId : RuntimeBinderException
  • Sean McGovern 0

    in Building an Extension Vault section, the link to this design document is not working as PowerShell/SecretManagement/blob/master/Docs/DesignDoc.md is missing. i can’t wait to contribute. for Azure Key Vault is there a plan to add metadata, maybe utilizing tags?

  • Mahmood n 0

    Hi there.
    I want to use SecretStore in automation, however, I am not able to get rid of the password prompt. The steps I took are as follows:

    PS /home/mahmood> Reset-SecretStore -PassThru
    WARNING: !!This operation completely removes all SecretStore module secrets and resets configuration settings to new values!!
    
    Reset SecretStore
    Are you sure you want to erase all secrets in SecretStore and reset configuration settings to default?
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): y
    Creating a new Microsoft.PowerShell.SecretStore vault. A password is required by the current store configuration.
    Enter password:
    ************
    Enter password again for verification:
    ************
    
          Scope Authentication PasswordTimeout Interaction
          ----- -------------- --------------- -----------
    CurrentUser       Password             900      Prompt
    
    PS /home/mahmood> Set-SecretStoreConfiguration -Interaction None
    
    Confirm
    Are you sure you want to perform this action?
    Performing the operation "Changes local store configuration" on target "SecretStore module local store".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y
    PS /home/mahmood> Get-SecretStoreConfiguration
    Get-SecretStoreConfiguration: A valid password is required to access the Microsoft.PowerShell.SecretStore vault.
    Use the Unlock-SecretStore cmdlet to provide the required password to access the store.
    PS /home/mahmood> Unlock-SecretStore
    
    cmdlet Unlock-SecretStore at command pipeline position 1
    Supply values for the following parameters:
    Password: ************
    PS /home/mahmood> Get-SecretStoreConfiguration
    
          Scope Authentication PasswordTimeout Interaction
          ----- -------------- --------------- -----------
    CurrentUser       Password             900        None
    

    As you can see, although the interaction is now “None”, however, when I rerun pwsh command, the get configuration doesn’t work again.

    PS /home/mahmood> exit
    mahmood@Frontend:~$ pwsh
    PowerShell 7.1.3
    Copyright (c) Microsoft Corporation.
    
    https://aka.ms/powershell
    Type 'help' to get help.
    
    PS /home/mahmood> Get-SecretStoreConfiguration
    Get-SecretStoreConfiguration: A valid password is required to access the Microsoft.PowerShell.SecretStore vault.
    Use the Unlock-SecretStore cmdlet to provide the required password to access the store.
    

    How can I fix that?

Feedback usabilla icon