Sometimes you need to enter credentials in a script to connect to something, you can prompt the user to enter credentials but that doesn’t work for Scheduled Tasks of course 🙂 Using a clear-text password in a script is never a good idea and that’s where the SecretsManagement module comes into play, this blog post will show you how you can use it in your scripts.
What does the SecretManagement module do?
“The PowerShell SecretManagement module provides a convenient way for a user to store and retrieve secrets. The secrets are stored in SecretManagement extension vaults. An extension vault is a PowerShell module that has been registered to SecretManagement, and exports five module functions required by SecretManagement. An extension vault can store secrets locally or remotely. Extension vaults are registered to the current logged-in user context, and are available only to that user.”
Limitations
As stated above, the vault is created for the user you are signed in with and is only available to that user. If you want to use it in scripts, then you should register the vault with the same user that is being used in the Scheduled Task on the server that it should run on.
Installation
In order to start using the SecretsManagement module, you will need to install two modules: Microsoft.PowerShell.SecretManagement and Microsoft.PowerShell.SecretStore. The SecretManagement module is for creating and configuring everything, the SecretStore module is the local secure store extension vault for the SecretManagement module. You can install the modules by running this in an administrative PowerShell session:
Install-Module Microsoft.PowerShell.SecretManagement Install-Module Microsoft.PowerShell.SecretStore
Creating the SecretVault
In order to store the credentials you have to create your own default vault, you can do this by running:
Register-SecretVault -Name PowerShellisfunDB -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
You can check your vault by running Get-Secretvault:
Setting a password on the SecretVault
To protect the vault, you must set a password on it. This can be done by running Get-SecretStoreConfiguration:
Note: This is good for your personal DB which you unlock in your PowerShell session when needed, but for Scheduled Tasks you must set it to None instead of Password by running Set-SecretStoreConfiguration -Authentication None
Adding credentials to the SecretVault
Now that the vault has been created, you can start adding credentials to it. This is done by using the Set-Secret cmdlet, you can add Metadate to it for notes/more information. For example:
Set-Secret -Vault PowerShellisfunDB -Name adm_fun -Secret (Get-Credential powershellisfun.local\adm_fun) -Metadata @{Description = "Admin account PowerShellisfun.local"}
When running this, a prompt will open in a new window (Or in your PowerShell session, depending on your version) in which you can enter the password:
You can view basic information about stored credentials by running Get-Secretinfo | Format-List:
Viewing a stored password from the SecretVault
You can view the password in PowerShell 7 by running (Get-Secret -Vault PowerShellisfunDB -Name adm_fun).Password | ConvertFrom-SecureString -AsPlainText:
Using saved credentials from the SecretVault in scripts
To use a saved credential for the vault in a PowerShell script, you can specify it in the -credential parameter like this:
-credential (Get-Secret -Vault PowerShellisfunDB -Name adm_fun)
So, for example when using it in an Invoke-Command cmdlet that would look like when using it to restart the Windows Update service on DC01:
Invoke-Command -ComputerName DC01 -ScriptBlock {Restart-Service wuauserv -Force:$true -Confirm:$false} -Credential (Get-Secret -Vault PowerShellisfunDB -Name adm_fun)
Note: This only works when the vault is not protected by a password, you can remove the password from the vault by using:
Set-SecretStoreConfiguration -Authentication None
More information
For more information about the options in the SecretsManagement module, you can check out the https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.secretmanagement/?view=ps-modules page.