Usage

Revised: May 6, 2024

Service accounts and other non-interactive logins can access credentials you store for them. And of course you can always user PowerPass with your own login, too. Login to the system with your account, or the service account you use for automation, deploy PowerPass, and use Write-PowerPassSecret to store a credential for that account.

The credentials you store while logged in will only be accessible to that same account.

The PowerPass module, Lockers, keys, and salts are all contained within the user’s profile directory and everything is encrypted. The How It Works article explains the technical workings in detail. To incorporate PowerPass into your scritps and modules, follow these examples.

Reading and Writing Secrets

• To read a secret from PowerPass use the Read-PowerPassSecret cmdlet.
• To write a secret into PowerPass use the Write-PowerPassSecret cmdlet.
• To remove a secret from PowerPass use the Remove-PowerPassSecret cmdlet.

Reading and Writing Files

• To get the list of files in PowerPass use the Get-PowerPassAttachments cmdlet.
• To read a file from PowerPass use the Read-PowerPassAttachment cmdlet.
• To write a file into PowerPass use the Write-PowerPassAttachment cmdlet.
• To remove a file from PowerPass use the Remove-PowerPassAttachment cmdlet.
• To add multiple files to PowerPass at once from disk use the Add-PowerPassAttachment cmdlet.
• To export multiple files from PowerPass back to disk use the Export-PowerPassAttachment cmdlet.

Back Up, Restore, and Maintenance

• To export a copy of all your secrets and files use the Export-PowerPassLocker cmdlet.
• To import secrets and files previously exported use the Import-PowerPassLocker cmdlet.
• To erase all secrets and files from PowerPass use the Clear-PowerPassLocker cmdlet.
• To rotate your PowerPass Locker keys use the Update-PowerPassKey cmdlet.

Utilities

• To generate a random password use the New-PowerPassRandomPassword cmdlet.
• To get PowerPass information use the Get-PowerPass cmdlet.

Full Cmdlet Reference

1. For the AES edition: PowerPass AES Cmdlet Reference
2. For the DP API edition: PowerPass DP API Cmdlet Reference

Getting Secrets from KeePass

• To open a KeePass database use the Open-PowerPassDatabase cmdlet.
• Pipe or pass the output to Get-PowerPassSecret to fetch secrets from the KeePass database.

Storing KeePass Database Passwords

If you are opening KeePass databases which use master passwords or key files, you can store these passwords and even the key files as well in PowerPass to keep them secure.

Use Case: Automating Access to Active Directory

One of the most common scenarios is automating access to Active Directory. Configuring a script to run with Domain Admin permissions is risky as the script must have access to highly privileged credentials. To ensure these credentials are not compromised, you can store them with PowerPass in an encrypted locker.

Setup the PowerPass Locker

1. First, determine which logon account you plan to use to run the script.
2. Login to the computer with this account and deploy PowerPass using the Deploy-PowerPass.ps1 script provided with the release.
3. Using the Write-PowerPassSecret cmdlet, write the credentials into the locker using a distinct Title to recall them later.
4. Close PowerShell and log off.

For detailed instructions on how to store and retrieve Active Directory Domain credentials with PowerPass, please see the Domain Credentials article. Now that you have credentials in your locker, you can use them in your script.

Update your Script

1. Open your script in your favorite PowerShell editor.
2. Using the Read-PowerPassSecret cmdlet, fetch the credentials you stored earlier by selecting with the distinct Title.
3. Configure your script to run as the logon account.
4. When your script runs it will read the credentials from the encrypted PowerPass Locker.

See below for an example.

Example

This code uses PowerPass to load Domain credentials from the logon account’s PowerPass Locker:

# Get the username and password as a PSCredential
$creds = Read-PowerPassSecret -Match "DEV Domain Admin" -AsCredential

# Call out to Active Directory with the credential
Get-ADUser -Credential $creds

To create the PSCredential, the secret must have a UserName and a Password property set. If either property is blank, the operation may fail with an error.

All PowerPass topics can be found at the bottom of this page.

All PowerPass Topics

Select one of the links below to browse to another topic.

AES Cmdlet Reference | Data Structures | Deployment | Domain Credentials | DP API Cmdlet Reference | Home | How It Works | OneDrive Backup | Prerequisites | Release Notes | Usage