Home

Usage Examples

Automated Unlocking

You can automate unlocking in your scripts by saving the user password to a file and reading it at runtime. As it contains a secret, this file should be locked down. On Windows I recommend encrypting it with the Encrypting File System. Alternatively, the Windows version of the Export-Clixml command will encrypt Credentials or SecureStrings during export. Securing things on Unix-like systems is less standardized, but at a bare minimum you should restrict permissions on the file to just the user that needs it.

Example Script

This script can be used to ensure the vault is unlocked prior to using the module programmatically. It will also warn users if a found secret file is not secured.

Unlock-Warden.ps1

<#
.SYNOPSIS
  Attempts to unlock the Secret Vault by searching for credentials in various locations. If a file doesn't exist in any of them, the user will be prompted to enter their password.
.DESCRIPTION
  Useful primarily in automated scripts. By making this a snippet, we can add/remove possible locations without updating a bunch of scripts.
.PARAMETER VaultName
  Name of the SecretVault you want to ensure is unlocked.
.NOTES
  Does nothing if the specified vault is not registered in Microsoft.PowerShell.SecretManagement.
.EXAMPLE
  PS> . "${HOME}\Documents\PowerShell\Scripts\Unlock-Warden.ps1"
  Ensures the default "warden" SecretVault is unlocked.
.EXAMPLE
  PS> . "${HOME}\Documents\PowerShell\Scripts\Unlock-Warden.ps1" -VaultName test
  Ensures the "test" SecretVault is unlocked.
#>
Param(
  [String]$VaultName = "warden"
)
if(!(Test-SecretVault -Name $VaultName -ErrorAction SilentlyContinue)) {
  # Search an array of possible paths for a file containing the password and return the first one that exists.
  $filePath = @(
    "${HOME}\.config\bw_password.txt",
    "${HOME}\.config\bw_password.xml",
    "$env:LOCALAPPDATA\Bitwarden CLI\bw_password.txt",
    "$env:LOCALAPPDATA\Bitwarden CLI\bw_password.xml"
  ).Where({ Test-Path $_ }, 'First', 1)[0]

  if($null -ne $filePath -and $filePath.Count -gt 0) {
    # *Check that files containing passwords in have been secured.
    if($IsWindows -and (
      ((Split-Path -Path $filePath -Extension) -ine ".xml") -and
      !((Get-ItemProperty $filePath).Attributes -split ",").Trim().Contains("Encrypted")
    )) {
      Write-Warning -Message "`"$filePath`" is not encrypted! You should encrypt it using the Encrypting File System (EFS) to prevent other users from reading it. See: https://support.microsoft.com/en-us/windows/how-to-encrypt-a-file-1131805c-47b8-2e3e-a705-807e13c10da7 Alternatively, convert the password to a SecureString and use Export-CliXml to create a file containing encrypted content."
    }
    elseif(($IsLinux -or $IsMacOS) -and (Get-ItemProperty $filePath).UnixMode -ne "-r--------") {
      Write-Warning -Message "`"$filePath`" has insecure file permissions! This file should only be readable by you. To make it so, run: chmod 0400 `"$filePath`""
    }

    # Import the password as a secure string.
    if((Split-Path -Path $filePath -Extension) -ieq ".xml") {
      [SecureString]$password = Import-Clixml -Path $filePath
    }
    else {
      [SecureString]$password = Get-Content $filePath | ConvertTo-SecureString -AsPlainText -Force
    }

    # Perform the Unlock Operation
    Unlock-SecretVault -Name $VaultName -Password $password
  }
  else {
    # Ask the user for their password
    Unlock-SecretVault -Name $VaultName
  }
}