PowerShell SecretManagement Module: Securely Manage Credentials and Secrets

Microsoft recently released a very useful SecretManagement PowerShell module. You can use it to securely store and use saved passwords (secrets) in your PowerShell scripts. The module consists of two components: a SecretStore vault (a default password store), and a SecretManagement (engine to access different password vaults). Both the built-in SecretStore vault and third-party secret vaults (like KeePass, LastPass, HashiCorp Vault, Azure Key Vault, Bitwarden, Windows Credential Manager, etc.) are supported. Using SecretManagement, you can save any passwords (credentials) to the secret vault and retrieve them at any time. You can also store license keys, access keys, and other sensitive information (Hashtable, Byte, String, SecureString, and PSCredential object types are supported).

In this article, we’ll show how to use the SecretManagement module in your PowerShell scripts to store and retrieve credentials, as well as an example of KeePass integration.

Installation of the Secret Management Module

The SecretManagement module requires Windows PowerShell version 5.1 or PowerShell Core 6.x, 7.x.

To install the SecretManagement using the NuGet package manager, run the command below:

Install-Module -Name Microsoft.PowerShell.SecretManagement

To install the default SecretStore vault offered by Microsoft, run the following command:

Install-Module -Name Microsoft.PowerShell.SecretStore

To display a list of available cmdlets in the module, use these commands:

Get-Command -Module Microsoft.PowerShell.SecretManagement
Get-Command -Module Microsoft.PowerShell.SecretStore

Create a Password Store (SecretStore Vault) via PowerShell

First of all, create a local secret vault. I will name it MyDomainPassdb and make it a default password store.

Register-SecretVault -Name MyDomainPassdb -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

You can create and use both local and remote password vaults.

The command below displays a list of registered password vaults for the current user:

Get-SecretVault

Create a master password to access your SecretStore Vault:

Get-SecretStoreConfiguration

By default, the following settings determine who and how can access password stores:

• Scope – CurrentUser (only the current user can access the SecretStore)
• Authentication – Password (access vault using a master password)
• PasswordTimeout – 900 – the duration of the session (in seconds) during which you don’t need to re-enter your master password, You can extend a session length: Set-SecretStoreConfiguration -PasswordTimeout 1200
• Interaction – Prompt (whether to enter the master password when making changes)

To change the master password, use the Set-SecretStorePassword cmdlet.

Managing Saved Credentials Using Secret Management Module

The Set-Secret cmdlet is used to add a secret of type SecureString to the password vault. Specify the vault name and the entry name:

Set-Secret -Vault MyDomainPassdb -Name user1

Enter the password (secret) you want to save in the store.

Or, you can save a protected value as follows (e. g., a GitHub key):
Set-Secret -Vault MyDomainPassdb -Name MY_GITHUB_TOKEN -Secret 'GitHub_AUTH_API_Token'

You can display a list of entries in the secret vault:

Get-SecretInfo

In most cases, you have to save both a username and a password instead of saving a password only when working in Windows networks. In this case, save the credentials as a PSCredential object. You can also add metadata with the description of the saved entry.

Set-Secret -Vault MyDomainPassdb -Name adm_maxbak -Secret (Get-Credential) -Metadata @{description = "AD enterprise admin woshub.com"}

If you don’t want to enter an account name in the Get-Credential window, you can specify it like this:

Set-Secret -Vault MyDomainPassdb -name adm_maxbak -Secret (get-credential woshub\adm_maxbak)

Here is how you can display a list of saved passwords and their descriptions:

Get-SecretInfo | Ft Name, Metadata

Using Saved Passwords from Secret Vault in PowerShell Scripts

Now you can use saved passwords in your PowerShell scripts and commands. For example, one of my customers is using a dozen of accounts for each administrator and different services/tasks for security and administrative account protection reasons. Using the same passwords is forbidden, passwords are regularly audited. Administrators find it tedious to constantly enter different passwords.

Using the SecretManagement module, you can safely store your passwords in a local vault and get them if necessary.

For example, to connect to a remote computer and run a command through PowerShell Remoting, you can use the following code:

Enter-PSSession -ComputerName mun-dc01 -Credential (Get-Secret -Vault MyDomainPassdb -Name adm_maxbak)

In the same way, you can connect Exchange or Microsoft 365 (ex-Office 365) easier:

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://mun-exch1.woshub.com/PowerShell/ -Authentication Kerberos -Credential (Get-Secret -Vault MyDomainPassdb -Name adm_ex_maxbak)

Or connect your Azure AD tenant:

Connect-AzureAD -Credential (Get-Secret -Vault MyDomainPassdb -Name azadm_ maxbak)

Or just get the credentials and store them in a PowerShell variable:

$Cred = Get-Secret -Vault MyDomainPassdb user1

Managing KeePass Passwords and Secrets with PowerShell

You can use the SecretManagement module to access other popular password vaults. Let’s see how to access saved passwords in a KeePass file (*.kdbx).

First of all, install the SecretManagement module to interact with KeePass:

Install-Module -Name SecretManagement.KeePass

Then register the KeePass vault file located in your user profile:

Register-SecretVault -Name "KeePassDB" -ModuleName "SecretManagement.Keepass" -VaultParameters @{
Path = "C:\Users\maxbak\Documents\personal_creds.kdbx"
UseMasterPassword = $true
}

To check access to a KeePass file, run the command:

Test-SecretVault -Name KeePassDB

Enter the master password to access the KeePass vault. If you have entered the password correctly, the command returns True.

Then display a list of saved passwords in the KeePass database:

Get-SecretInfo -Vault KeePassDB

To save a new secret in KeePass:

Set-Secret -Vault KeePassDB -Name "ILO_adm" -Secret (Get-Credential woshub\ILO_adm)

In the same way, you can connect any other popular password store solution and use it in PowerShell.