Adam the Automator

Posted on Jan 14, 2021

Writing an Extension Vault for PowerShell SecretManagement Preview 4

#powershell

This article was written by Adam Listek. He is a frequent contributor to the Adam the Automator (ATA) blog. If you'd like to read more from this author, check out his ATA author page. Be sure to also check out more how-to posts on cloud computing, system administration, IT, and DevOps on adamtheautomator.com!

If you've ever hardcoded a password, an API key, or a private certificate in a script, stop! You need to secure that sensitive information! One way to do that is with the PowerShell SecretManagement module. Offering a convenient way for a user to store and retrieve secrets using PowerShell, the SecretManagement module also has the ability to interface with different back-end systems such as Azure KeyStore or KeePass too using an extension vault!

An extension vault is a term used within the SecretManagement module to refer to a nested PowerShell module used within the SecretManagement module. You'll also hear vaults referred to as extension modules also.

In this article, we create an extension vault that is backed by the open-source .NET database LiteDB. An extension module can use any back-end, but using LiteDB allows us to use a .NET native simple database that demonstrates the SecretManagement module capabilities and how to interact with different systems.

Note: Don't get confused with the "secret" in the name. Even though this module is meant to be used for "secret" management, as you'll see in this tutorial, it really could be used as a frontend or just about any data source, if you wish.

Prerequisites

This article is a tutorial. If you'd like to follow along, please be sure you have the following prerequisites in order.

PowerShell 7
The Powershell SecretManagement module - You can install this module by running Install-Module -Name 'Microsoft.PowerShell.SecretManagement' -AllowPrerelease. This tutorial will be using the most current version at the time of writing which is Preview 4.
The LiteDB database - Though you can create any backing store for your secret database, this article demonstrates creating an extension module to leverage LiteDB in the background. You can install LiteDB by running Install-Package -Name 'LiteDB' -MinimumVersion '5.0.9' -Source 'nuget.org' -Scope 'CurrentUser'

Understanding the PowerShell SecretManagement Module

The PowerShell SecretManagement module is a PowerShell module that provides a standardized, Microsoft-supported way of interacting with sensitive information. Think of this module as a better way of storing and retrieving sensitive information than using Get-Credential or perhaps storing secure strings in common text files.

This module has two main object types; secrets and vaults. A vault is a data store that stores secrets. To store and retrieve secrets, you must first register a vault to then add secrets to that vault. You can then unregister that vault if you no longer need to store secrets in that data source.

When you install the module, there are no actual vaults available. If you want to install the previously default extension vault, run Install-Module -Name 'Microsoft.PowerShell.SecretStore' -AllowPrerelease. Otherwise, keep reading as you'll learn how to create a custom one with LiteDb.

You'll find a few different cmdlets in the module to interact with the various objects.

Get-Secret - Retrieve a secret from a vault.
Get-SecretInfo - Retrieve information about one or more secrets in a vault.
Get-SecretVault - Retrieve information about a specific vault.
Register-SecretVault - Register a new secret vault.
Remove-Secret - Remove a secret from a vault.
Set-Secret - Create a new secret or update an existing secret in a vault.
Test-SecretVault - Verify that a vault is correctly configured.
Unregister-SecretVault - Unregister a previously registered vault.

To actually make any of the above cmdlets functional, you need to back them with a vault. To do that, the SecretManagement module requires you to build your own functions with the same name essentially overwriting the default cmdlets.

If your extension does not offer the ability to add or update a secret, you could implement the function but only throw an error message stating that it is not supported.

Next, we will explore how to structure a PowerShell SecretManagement extension vault and start to implement the commands.

Creating a PowerShell SecretManagement Extension Vault

Now that you have seen the basic cmdlet structure and objects you'll be working with, let's now learn how to create an example extension vault!

The root directory to create the first parent module directory is in the SecretManagement module's ExtensionModules folder. You can find this directory by running (Get-Module -Name Microsoft.PowerShell.SecretManagement).Path | Split-Path -Parent.

Create the Main Vault Folder and Manifest

Open up PowerShell and create a variable holding the path to the ExtensionsModule parent directory which all underlying module folders and files will be created.

$vaultParentPath = (Get-Module -Name Microsoft.PowerShell.SecretManagement).Path | Split-Path -Parent.

2. Create the parent module directory in the ExtensionModules directory. Name this directory SecretManagement.<Vault source>. In this case, the directory is called SecretManagement.LiteDB.

New-Item -Path "$vaultParentPath\SecretManagement.LiteDb" -ItemType Directory

3. Create a module manifest for the SecretManagement.LiteDb module outlining some common manifest attributes.

New-ModuleManifest -CompatiblePSEditions Core -Author '<you>' -NestedModules './SecretManagement.LiteDB.Extension/SecretManagement.LiteDB.Extension.psd1' -RequiredModules 'Microsoft.Powershell.SecretManagement' -PowerShellVersion 7.0 -Tags 'SecretManagement' -Path "$vaultParentPath\SecretManagement.LiteDb"

4. Once New-ModuleManifest creates the template manifest, open it up and ensure it mirrors the below manifest.

@{
  ModuleVersion        = '0.0.0.1'
  # Make this only compatible with PowerShell Core/7
  CompatiblePSEditions = @('Core')
  GUID                 = '<guid here>' ## Generate a GUID with New-Guid
  Author               = 'Adam Listek'
  # Pointed to the nested module definition file
  NestedModules   = @(
    './SecretManagement.LiteDB.Extension/SecretManagement.LiteDB.Extension.psd1'
  )
  # Make this module dependant on the SecretManagement module
  RequiredModules = @(
    "Microsoft.Powershell.SecretManagement"
  )
  # Set the minimum PowerShell version of 7.0 as Core is the only one supported by the primary module and this is the recommended PowerShell version
  PowershellVersion = '7.0'
  FunctionsToExport = @()
  CmdletsToExport   = @()
  VariablesToExport = @()
  AliasesToExport   = @()
  # Not necessary, but recommended to tag your module with SecretManagement to assist PowerShell Gallery users in finding your module
  PrivateData = @{
    PSData = @{
      Tags = @('SecretManagement')
    }
  }
}

Creating the Extension Vault Directory and Manifest

Once you've created the main extension folder and manifest, next create the extension vault module with its manifest. This module is a nested module inside of the main parent extension module directory.

Create the extension vault's folder.

New-Item -Path "$vaultParentPath\SecretManagement.LiteDb\SecretManagement.LiteDB.Extension" -ItemType Directory

2. Create the module manifest. This manifest only requires two attributes; RootModule and FunctionsToExport.

You'll notice the FunctionsToExport parameter shows the same function names as the SecretManagement module itself. An extension vault's commands "overwrite" the default SecretManagement modules.

New-ModuleManifest -RootModule '.\SecretManagement.LiteDB.Extension.psm1' -FunctionsToExport @('Set-Secret','Get-Secret','Remove-Secret','Get-SecretInfo','Test-SecretVault') -Path "$vaultParentPath\SecretManagement.LiteDb\SecretManagement.LiteDB.Extension.psd1"

3. Once New-ModuleManifest creates the template manifest, open it up and ensure it mirrors the below manifest.

@{
  ModuleVersion     = '0.0.0.1'
  # The command definitions located in the same directory as this module
  RootModule        = '.\SecretManagement.LiteDB.Extension.psm1'
  # Only export the functions that the SecretManagement module expects
  FunctionsToExport = @('Set-Secret','Get-Secret','Remove-Secret','Get-SecretInfo','Test-SecretVault')
}

Now that our module is all set up, let's implement the functions themselves! As mentioned before, to allow the PowerShell SecretManagement module to interact with your extension vault, you must define functions with the exact same name as the ones shown below other than the LiteDb-specific function Open-Database.

Create the Vault Function "Scaffolding"

Since you'll be devouring a lot of code in this article, first build the PSM1 module "scaffolding". This will allow you to insert code into this framework as you go along.

Create the extension vault PSM1 module by first creating a text file.

New-Item -Path "$vaultParentPath\SecretManagement.LiteDb\SecretManagement.LiteDB.Extension\SecretManagement.LiteDB.Extension.psm1" -ItemType File

2. Copy and paste the following "scaffolding" code into the PSM1 file. Code-specific comments are inline.

You must use the standard function names defined above in the Understanding section to interact with the SecretManagement module. You can also add your own functions to the module as "helper" functions if you'd like as shown in the below PSM1 file (Open-Database).

# Necessary to correctly override and implement the existing SecretManagement functions
Using Namespace Microsoft.PowerShell.SecretManagement

# An internal function, specific to this LiteDB vault, that will be used to open the database for interaction
Function Open-Database {}

# The following five functions are the standard SecretManagement functions that we will implement
Function Get-Secret {}

Function Set-Secret {}

Function Remove-Secret {} 

Function Get-SecretInfo {}

Function Test-SecretVault {}

Build the Functions

The next step is to add functionality to the extension vault. This functionality means adding functions to the extension vault (module).

Though we are creating an interface to store secrets, in this tutorial, we are not implementing the database's encryption, and in a production database that would be recommended. Once the database has been encrypted, decryption is done by passing a password upon opening the database for reading or writing.

Creating the "Helper" `Open-Database` Function

Typically, you'll only be building the standard set of functions but for LiteDB, the tutorial has a "helper" function called Open-Database. This function is strictly an internal function utilized by the extension module to simplify opening the database and making it available to the exposed functions. Code comments in-line.