Have a way to view available additional parameters for a vault.

[itfranck]

This is a suggestion.

For me, SecretManagement is about having a consistent way to access a ton of different providers in a consistend manner. (Get-Secret / Set-Secret)

My only "pain point" is when it come to the registration of the vault. I can try as is, but more often then not, I will need to check the documentation to determine what parameter can be used.

What if ...

There was something such as Get-SecretVaultRegistrationParameters that the implemented module could use to return a list of the available additional parameters ?

Example scenario Example end user call: (to determine how to register it)

Get-SecretVaultRegistrationParameters -ModuleName 'SecretManagement.AzKeyvault'

I would use that pretty much anytime before I register a vault since there's a lot of variation per module on that level.

Pre-requisites The module creator wanting to provide this insight to the users would need to expose the optional Get-SecretVaultRegistrationParameters function and add the return values.

function Get-SecretVaultRegistrationParameters() {
    return @(
        [SecretParameterInfos]::new('SubscriptionId', 'Azure subscription id', $true)
        [SecretParameterInfos]::new('VaultName', 'Azure vault name', $true)
        [SecretParameterInfos]::new('SessionTimeout', "Determine the session timeout for the user.`nIf set to 0, default will be used", $false,'60 minutes')
    )    
}

If not implemented, then it could return a Not implemented exception and / or display a warning so a distinction can be made between not implemented or the fact there is just no parameter to configure.

Complete sample

# Example class for the purpose of this example... Although I am well aware c# would be used for that part.
class SecretParameterInfos {
    [String]$Name
    [String]$Description
    [bool]$Mandatory
    [String]$Default

    SecretParameterInfos($Name, $Description) {
        $this.Name = $Name
        $this.Description = $Description
    }

    SecretParameterInfos($Name, $Description, $Mandatory) {
        $this.Name = $Name
        $this.Description = $Description
        $this.Mandatory = $Mandatory
    }

    SecretParameterInfos($Name, $Description, $Mandatory,$Default) {
        $this.Name = $Name
        $this.Description = $Description
        $this.Mandatory = $Mandatory
        $this.Default = $Default
    }
}

#Declared in SecretManagement.MyModule.psm1 
function Get-SecretVaultRegistrationParameters() {
    return @(
        [SecretParameterInfos]::new('SubscriptionId', 'Azure subscription id', $true)
        [SecretParameterInfos]::new('VaultName', 'Azure vault name', $true)
        [SecretParameterInfos]::new('SessionTimeout', "Determine the session timeout for the user.`nIf set to 0, default will be used", $false,'60 minutes')
    )    
}

#End user that want to register a vault but want to know if there are available parameters to him
Get-SecretVaultRegistrationParameters -ModuleName 'SecretManagement.MyModule'

If you were to go even deeper, you could also imagine the main module using that list and making the registration fail if it have elements listed as Required but not provided by the user automatically.

That being said, the core of this suggestion is to have that piece of information embedded (provided the module owner implement it) and readily available without having to do back and forth always with the implemented modules documentations.

Thank you for considering this.

[PaulHigin]

The vault parameters are already available:

Get-SecretVault -Name SecretManagement.AzKeyVault | Select VaultParameters

VaultParameters
---------------
{[SubscriptionId, 1f4653a9-5e4b-4d70-9591-3191b0fe3b28], [AZKVaultName, MySecretsVault1]}

[itfranck]

Get-SecretVault -Name SecretManagement.AzKeyVault | Select VaultParameters

VaultParameters
---------------
{[SubscriptionId, 1f4653a9-5e4b-4d70-9591-3191b0fe3b28], [AZKVaultName, MySecretsVault1]}

What you describes is a way to obtain the vault parameters to a specific vault registration part of the registry. I can see parameters I used when registering my vault (And that's great and I use that too).

My suggestion was the idea that you could get a list of the available parameter and metadata based on the extension module name.

Get-SecretVaultRegistrationParameters -ModuleName 'SecretManagement.AzKeyvault'

It could be summarized as a readily available vault parameter documentation lookup without having to fetch individual projects documentation to get the list of the parameter.

As an AzKeyvault extension user, I didn't knew I had to provide SubscriptionId and AZKVaultName parameter. The cmdlet I was suggesting was a way to expose that part to the user.

So, if the owner of the extension was to take the time to bind a designated cmdlet in his module (example:)

#Declared in SecretManagement.MyModule.psm1 
function Get-SecretVaultRegistrationParameters() {
    return @(
        [SecretParameterInfos]::new('SubscriptionId', 'Azure subscription id', $true)
        [SecretParameterInfos]::new('VaultName', 'Azure vault name', $true)
        [SecretParameterInfos]::new('SessionTimeout', "Determine the session timeout for the user.`nIf set to 0, default will be used", $false,'60 minutes')
    )    
}

Then calling Get-SecretVaultRegistrationParameters -ModuleName 'SecretManagement.AzKeyvault' would produce the list of available parameter that are available for me to use when I register my vault without having to fetch the project documentation.

I thought it was a good idea and it would definitely save back & forth with the different documentations of the different modules. I'll leave it up to you to close this ticket if this is unclear and / or out of scope.

[SydneyhSmith]

Thanks @itfranck this is an interesting idea and could be useful for users in the future...this would consider additional design work and could be difficult to maintain and enforce....for now we don't plan to implement this but will leave this open in case others feel differently for future iterations of the module

[JustinGrote]

@SydneyhSmith Not sure about the maintain/enforce part because it can always be optional. If a extension author doesn't define the shortcut, you just don't display any help (or display a warning that no help is available).

[JustinGrote]

In thinking about this for my Keepass vault, there's nothing to stop me from supplying a Get-KeepassVaultOptions command or whatever that provides a strictly typed object that casts to a hashtable with a type format that shows and explains the various options, similar to how pester options work.

It would of course be better to have an in-box way of doing it but this is a workaround.

[PaulHigin]

After thinking about this a bit, I feel that this is the right way to go. Secret metadata is not something that all vaults will need, and so it makes sense for individual vault implementations to provide that functionality if and when needed. This was one of the reasons for loosening SecretManagement vault requirements ... to allow individual vault implementations the ability to provide custom functionality as needed.