We are excited to announce two modules are now generally available on the PowerShell Gallery:<\/p>\n
To install the modules, open any PowerShell console and run:<\/p>\n
Install-Module<\/span> Microsoft.PowerShell.SecretManagement,<\/span> Microsoft.PowerShell.SecretStore<\/pre>\n<\/div>\n<\/a>Introducing SecretManagement<\/h2>\nThe 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:<\/p>\n
\nGet-Secret<\/span>\r\nGet-SecretInfo<\/span>\r\nGet-SecretVault<\/span>\r\nRegister-SecretVault<\/span>\r\nRemove-Secret<\/span>\r\nSet-Secret<\/span>\r\nSet-SecretInfo<\/span>\r\nSet-SecretVaultDefault<\/span>\r\nTest-SecretVault<\/span>\r\nUnregister-SecretVault\r\n\r\n<\/span><\/pre>\n<\/div>\nReference documentation for this module is available on our Microsoft docs site<\/a>.<\/p>\n<\/a>SecretManagement Uses<\/h3>\nSecretManagement 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.<\/p>\n
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.<\/p>\n
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.<\/p>\n
Some key scenarios we have heard from PowerShell users are:<\/p>\n
\n- Sharing a script across my org (or open source) without knowing the platform\/local vault of all the users<\/li>\n
- Running my deployment script in local, test and production with the change of only a single parameter (
-Vault<\/code>)<\/li>\n- Changing the backend of the authentication method to meet specific security or organizational needs without needing to update all my scripts<\/li>\n<\/ul>\n
<\/a>Introducing SecretStore<\/h2>\nSecretStore<\/a>\u00a0is 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).<\/p>\n<\/a>Features of SecretStore<\/h3>\nThe 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:<\/p>\n
\n-<\/span> Get-SecretStoreConfiguration<\/span>\r\n-<\/span> Set-SecretStoreConfiguration<\/span>\r\n-<\/span> Unlock-SecretStore<\/span>\r\n-<\/span> Update-SecretStorePassword<\/span>\r\n-<\/span> Reset-SecretStore\r\n\r\n<\/span><\/pre>\n<\/div>\nReference documentation for this module is available on our Microsoft docs site<\/a>.<\/p>\n<\/a>Getting Started with SecretManagement<\/h2>\nOnce you have SecretManagement installed you can run\u00a0Get-SecretVault<\/code>\u00a0to 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.<\/p>\n<\/a>Extension Vault Ecosystem<\/h2>\nSecretManagement 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.<\/p>\n
<\/a>Discovering and Installing Vault Extensions<\/h3>\nTo find SecretManagement extension vault modules, search the PowerShell Gallery for the \u201cSecretManagement\u201d tag. Some community vault extensions that are available:<\/p>\n
\n- KeePass<\/a><\/li>\n
- LastPass<\/a><\/li>\n
- Hashicorp Vault<\/a><\/li>\n
- KeyChain<\/a><\/li>\n
- CredMan<\/a><\/li>\n
- Azure KeyVault<\/a>\u00a0(Microsoft Owned)<\/li>\n<\/ul>\n
Thank you to everyone who has created vaults thus far!<\/p>\n
<\/a>Getting Started with SecretStore<\/h2>\nWhile this example is being shown with SecretStore, the example can be followed with any number of extensions vaults.<\/p>\n
First Register the vault, the name parameter is a friendly name and can be anything you choose\u00a0Register-SecretVault -Name SecretStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault<\/code><\/p>\nNow you can create a secret, you will also need to provide a password for the SecretStore vault\u00a0Set-Secret -Name TestSecret -Secret \"TestSecret\"<\/code><\/p>\nVault SecretStore requires a password.\r\nEnter password:\r\n*******\r\n<\/code><\/pre>\nRun Get-Secret to retrieve the secret, using the\u00a0-AsPlainText<\/code>\u00a0switch will return it as a readable string\u00a0Get-Secret -Name TestSecret -AsPlainText<\/code>\u00a0TestSecret<\/code>\u00a0To see the names all of your secrets you can run\u00a0Get-SecretInfo<\/code><\/p>\nGet-SecretInfo<\/code><\/p>\nName Type VaultName\r\n---- ---- ---------\r\nTestSecret String SecretStore\r\n# To update your secret you can utilize the Set-Secret cmdlet\r\nPS C:\\> Set-Secret -Name TestSecret -Secret \"TestSecretUpdate\"\r\n# To remove the secret you can utilize the Remove-Secret cmdlet\r\nPS C:\\> Remove-Secret -Name TestSecret\r\n<\/code><\/pre>\n<\/a>Using Metadata with the SecretStore<\/h3>\nUsers 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.<\/p>\n
To create a new secret with metadata you can run:<\/p>\n
Set-Secret -Name foo -Secret fooSecret -Metadata @{purpose = \"example\"}<\/code><\/p>\nTo view secret metadata you can then run the command:<\/p>\n
Get-SecretInfo | select name, metadata<\/code><\/p>\nYou can also set metadata for an existing secret using the\u00a0Set-SecretInfo<\/code>\u00a0cmdlet:<\/p>\nSet-SecretInfo bar -Metadata @{purpose = \"showing the new cmdlet\"}<\/code><\/p>\nSince 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:<\/p>\n
Set-Secret -name secretMetadata -Secret @{ resource1 = \"username1, subID1\"; resource2 = \"username, subID2\"}<\/code><\/p>\n<\/a>Configuring the SecretStore<\/h3>\nSeparate from its integration with the SecretManagement interface, the SecretStore module is highly configurable.<\/p>\n
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.<\/p>\n
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.<\/p>\n
If password prompting is disabled and a password is required to access secrets, a\u00a0Microsoft.PowerShell.SecretStore.PasswordRequiredException<\/code>\u00a0will be thrown. In this case, the SecretStore can be unlocked using the\u00a0Unlock-SecretStore<\/code>\u00a0cmdlet.<\/p>\nThere is also a SecretStore Scope setting, but it is currently set to CurrentUser and cannot be changed.<\/p>\n
The default configuration is set by default for best security and interactive use.<\/p>\n
\nGet-SecretStoreConfiguration<\/span>\r\n\r\n Scope Authentication PasswordTimeout Interaction\r\n -----<\/span> --------------<\/span> ---------------<\/span> -----------<\/span>\r\nCurrentUser Password 900<\/span> Prompt<\/pre>\n<\/div>\n<\/a>Using the SecretStore in Automation<\/h3>\nThis 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\u00a0None<\/code>, 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\u00a0-Confirm:false<\/code>\u00a0parameter is used so that PowerShell will not prompt for confirmation.<\/p>\nThe 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.<\/p>\n
Next, the SecretManagement module is installed and the SecretStore module registered so that the SecretStore secrets can be managed.<\/p>\n
The\u00a0Unlock-SecretStore<\/code>\u00a0cmdlet 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.<\/p>\n\nInstall-Module<\/span> -<\/span>Name Microsoft.PowerShell.SecretStore -<\/span>Repository PSGallery -<\/span>Force\r\n$password<\/span> =<\/span> Import-CliXml<\/span> -<\/span>Path $securePasswordPath<\/span>\r\n\r\nSet-SecretStoreConfiguration<\/span> -<\/span>Scope CurrentUser -<\/span>Authentication Password -<\/span>PasswordTimeout 3600<\/span> -<\/span>Interaction None -<\/span>Password $password<\/span> -<\/span>Confirm:$false<\/span>\r\n\r\nInstall-Module<\/span> -<\/span>Name Microsoft.PowerShell.SecretManagement -<\/span>Repository PSGallery -<\/span>Force\r\nRegister-SecretVault<\/span> -<\/span>Name SecretStore -<\/span>ModuleName Microsoft.PowerShell.SecretStore -<\/span>DefaultVault\r\n\r\nUnlock-SecretStore<\/span> -<\/span>Password $password<\/span><\/pre>\n<\/div>\n<\/a>Getting Started with Azure Key Vault<\/h2>\nThe Azure Key Vault extension is available on the PowerShell Gallery beginning in\u00a0Az.KeyVault module<\/a>\u00a0v3.3.0. This vault extension utilizes a common authentication system with the rest of\u00a0the Az PowerShell module<\/a>, and allows users to interact with an existing Azure Key Vault through the SecretManagement interface.<\/p>\nTo utilize Azure Key Vault with SecretManagement first ensure that you have\u00a0the Az.KeyVault module<\/a>\u00a0installed (Install-Module Az.KeyVault<\/code>). You can then register the vault using your AZKVaultName and SubscriptionID:<\/p>\nRegister-SecretVault\u00a0-Module\u00a0Az.KeyVault\u00a0-Name\u00a0AzKV\u00a0\r\n-VaultParameters\u00a0\u00a0\r\n@{\u00a0AZKVaultName\u00a0=\u00a0$vaultName;\u00a0SubscriptionId\u00a0=\u00a0$subID}\r\n<\/code><\/pre>\nFrom there you can view the secrets you have (Get-SecretInfo<\/code>), get secrets you may need (Get-Secret<\/code>), create and update secrets (Set-Secret<\/code>), and remove secrets (Remove-Secret<\/code>).<\/p>\nFor any feature requests or support with the Azure Key Vault extension please refer to their\u00a0GitHub repository<\/a>.<\/p>\n<\/a>Building an Extension Vault<\/h2>\nThe 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\u00a0this design document<\/a>. We also hope\u00a0SecretStore<\/a>\u00a0not only proves useful for SecretManagement users but also serves as an example for extension vault authors looking to build off of existing vaults.<\/p>\n<\/a>A Note on Community Support<\/h2>\nCommunity 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.<\/p>\n
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.<\/p>\n
<\/a>What’s Next<\/h2>\nWe 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\u00a0SecretManagement<\/a>\u00a0and\u00a0SecretStore repository<\/a>.<\/p>\n<\/a>Feedback and Support<\/h2>\nTo file issues or get support for the SecretManagement interface or vault development experience please use the\u00a0SecretManagement repository<\/a>. For issues which pertain specifically to the SecretStore and its cmdlet interface please use the\u00a0SecretStore repository<\/a>.<\/p>\nSydney Smith<\/p>\n
PowerShell Team<\/p>\n","protected":false},"excerpt":{"rendered":"
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 […]<\/p>\n","protected":false},"author":2299,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[3174,3181],"class_list":["post-18955","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-secretmanagement","tag-secretstore"],"acf":[],"blog_post_summary":"
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 […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/18955","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/2299"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=18955"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/18955\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=18955"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=18955"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=18955"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}