Add support for Secret Management, using the SecretMangement module and custom logic

[Badgerati]

I've thought about this feature on and off, but finally might have something that could work. But it's totally open for comments though, so please feel free! 😄

The idea is to add in Secret Management support - both using the SecretManagement module, but also support for custom logic as well. To get secrets back can be done using $secret:<name>, or a function for external modules/functions.

Prep for some reading, this is long! 😂

Functions

Register Vault

To start with you'll need to "register" the secret vault you wish to use. Akin to the SecretManagement module this will be done using a Register-PodeSecretVault function.

They'll be 2 initial ways of registering a vault: one for SecretManagement, and one for Custom:

• SecretManagement:

# call Import-Module on SecretManagement modules in runspaces
# call Register-SecretVault in runspaces
Register-PodeSecretVault
    -Name 'Vault1'
    -SecretManagement
    -ModuleName SecretManagement.Hashicorp.Vault.KV
    -VaultParameters @{}
    [-CacheTtl=0]
    [-VaultName=$Name]

• Custom:

# any custom modues will have to be Import-Module'd manually
# allows for custom secret retrieval (ie: using az/vault-cli, etc., directly)
Register-PodeSecretVault
    -Name 'Vault2'
    -Custom
    -ArgumentList
    -ScriptBlock {}
    [-CacheTtl=0]
    [-ConnectArgumentList @{}]
    [-Connect {}]

In both a -Name is required and should be unique, this will be the name used to reference the vault later on.

For SecretManagement the -Name sometimes needs to match the actual vault name, so if you want a more friendly name here then you can use -VaultName for the real name. -VaultParameters are the same as the VaultParameters in SecretManagement.

In both you'll spot -CacheTtl, and if set, any secrets retrieved will be cached for this number of seconds. -ArgumentList is an array of arguments to supply to the -ScriptBlock, along with "key" from adding a secret.

For Custom, there's also the option to have custom -Connect logic - such as logging into a vault, getting an auth token, etc.. This will be called once, and the token cached (with expiry). On expiry, it will be called again. The token will be supplied to the scriptblock for retrieving the secret.

Add Secret

After registering a vault, you'll need to "add" a secret to Pode using Add-PodeSecret. This is the same regardless of how the vault was registered, but you can specify the "key" for the secret to be looked up by using either a -ScriptBlock or a raw -Key string value:

# key
Add-PodeSecret `
    -Name 'Secret1' `
    -Vault 'Vault1' `
    -Key 'database/creds' `
    [-NoCache]
    [-CacheTtl=0]

# scriptblock
Add-PodeSecret `
    -Name 'Secret2' `
    -Vault 'Vault2' `
    -ArgumentList [] `
    -ScriptBlock {} `
    [-NoCache]
    [-CacheTtl=0]

The key returned should be the path/name of the secret (ie: in hashicorp vault it could be database/creds, and in the register scriptblock this is appended onto kv/data).

You'll also spot there's a -NoCache, so if you register a vault with global secret caching here you can disable it. Or you have have no global caching, and enable it for specific secrets using -CacheTtl.

Get Secret

The main way to get a secret in Routes, TImers, etc. will be using the secret variable scope:

Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
    $db = $secret:Secret1
}

Or, you could use the Get-PodeSecret function (which the above will use internally):

Get-PodeSecret `
    -Name

Example

SecretManagement

The following example will use the SecretManagement.Hashicorp.Vault.KV extension module for SecretManagement, to retrieve a secret from a HashiCorp Vault:

Start-PodeServer {
    # endpoint
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    # vault params
    $vaultParams = @{
        VaultServer = 'https://vault.domain.local:8200'
        VaultToken  = 's.abc123='
    }

    $vaultModule = 'SecretManagement.Hashicorp.Vault.KV'

    # register vault
    Register-PodeSecretVault `
        -Name 'Vault' `
        -VaultParameters $vaultParams `
        -SecretManagement `
        -ModuleName $vaultModule

    # add secret for database creds - cache for 30secs
    Add-PodeSecret `
        -Name 'Database' `
        -Vault 'Vault' `
        -CacheTtl 30 `
        -Key 'database/creds'

    # add route to use secret
    Add-PodeRoute -Method Post -Path '/users' -ScriptBlock {
        $users = Get-SomeExampleUsers -Credentials $secret:Database
        Write-PodeJsonResponse -Value $users
    }
}

Custom

Or, the same as above for HashiCorp Vault, but using the vault CLI:

Start-PodeServer {
    # endpoint
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    # vault params
    $vaultParams = @(
        'https://vault.domain.local:8200',
        's.abc123='
    )

    # register vault
    Register-PodeSecretVault `
        -Name 'Vault' `
        -ArgumentList $vaultParams `
        -Custom `
        -ScriptBlock {
            param($address, $token, $key)
            vault login --address=$address $token
            vault read kv/data/$key
        }

    # add secret for database creds - cache for 30secs
    Add-PodeSecret `
        -Name 'Database' `
        -Vault 'Vault' `
        -CacheTtl 30 `
        -Key 'database/creds'

    # add route to use secret
    Add-PodeRoute -Method Post -Path '/users' -ScriptBlock {
        $users = Get-SomeExampleUsers -Credentials $secret:Database
        Write-PodeJsonResponse -Value $users
    }
}

[breento]

Seems like a great idea to easily use secrets in Pode! 😄

[Badgerati]

I've been working on this for the last few days on and off when I can, and managed to put it all together 😄 It's fairly similar to what's above, but with tweaks.

Still the same, to start with, is the need to Register-PodeSecretVault first. This is will still support the SecretManagement module and Custom logic. Additional support has also been added for unregistering, unlocking, and initialising vaults. On the Custom logic, the -Connect parameters have been removed (in favour of -InitScriptBlock, and there are extra scriptblocks needed (if required) for updating/creating, removing, unlocking and unregistering - the default scriptblock is for retrieving the secret from the vault. For example:

• SecretManagement

Register-PodeSecretVault -Name 'FriendlyVaultName' -ModuleName 'Az.KeyVault' -VaultParameters @{
    AZKVaultName = 'VaultNameInAzure'
    SubscriptionId = $SubscriptionId
}

• Custom

Register-PodeSecretVault -Name 'HcpVault' `
    -VaultParameters @{
        Address = 'http://127.0.0.1:8200'
    } `
    -ScriptBlock {
        param($config, $key)
        return (vault kv get -format json -address $config.Address -mount secret $key | ConvertFrom-Json -AsHashtable).data.data
    }

The Add-PodeSecret is now Mount-PodeSecret - since we're technically mounting a secret from a vault and into Pode. This is still the same otherwise, and the same regardless of SecretManagement/Custom:

Mount-PodeSecret -Name 'Github' -Vault 'HcpVault' -Key 'tools/github'

Getting and updating secrets can still be done either via Get-PodeSecret and Update-PodeSecret, or by using the secret scope:

$value = $secret:NAME
$secret:NAME = 'VALUE'

---

I've also added additional functionality for interacting with secrets in vaults more adhoc, without having to mount them first - but you still need to register a vault:

• Set-PodeSecret - for creating new secrets or updating them
• Read-PodeSecret - for retrieving the value of a secret
• Remove-PodeSecret - for deleting a secret in a vault