Refactor secret management providers and introduce unified handling
- Removed KeePass and SecretStore provider implementations. - Integrated KeePass and SecretStore as vaults under the SecretManagement provider. - Added new functions: Get-DSCConfigurationDataCredentialProvider and Set-DSCConfigurationDataCredentialProvider for managing credential providers. - Implemented Unlock-ConfigurationDataSecretManagementVault to handle vault unlocking with master passwords. - Updated README to reflect changes in provider usage and examples. - Enhanced error handling and validation for vault registration and settings.
This commit is contained in:
Torsten Brendgen
191
Readme.md
191
Readme.md
@@ -108,9 +108,9 @@ Supported parameter types:
|
||||
FarmPassphrase = @{
|
||||
Type = 'secureString'
|
||||
Required = $true
|
||||
Sensitive = $true
|
||||
Value = @{
|
||||
Provider = 'KeePass'
|
||||
Sensitive = $true
|
||||
Value = @{
|
||||
Provider = 'SecretManagement'
|
||||
Vault = 'Contoso'
|
||||
Name = 'SharePoint/FarmPassphrase'
|
||||
}
|
||||
@@ -119,9 +119,9 @@ FarmPassphrase = @{
|
||||
SetupCredential = @{
|
||||
Type = 'credential'
|
||||
Required = $true
|
||||
Sensitive = $true
|
||||
Value = @{
|
||||
Provider = 'KeePass'
|
||||
Sensitive = $true
|
||||
Value = @{
|
||||
Provider = 'SecretManagement'
|
||||
Vault = 'Contoso'
|
||||
Name = 'Application/SetupAccount'
|
||||
UserName = 'CONTOSO\svc-app-setup'
|
||||
@@ -133,7 +133,7 @@ Secret references are validated and resolved by `Resolve-DSCConfigurationData` b
|
||||
|
||||
```powershell
|
||||
$resolved = Resolve-DSCConfigurationData -ConfigurationData $merged -ProviderSettings @{
|
||||
KeePass = @{
|
||||
SecretManagement = @{
|
||||
DefaultVault = 'Contoso'
|
||||
}
|
||||
}
|
||||
@@ -141,28 +141,43 @@ $resolved = Resolve-DSCConfigurationData -ConfigurationData $merged -ProviderSet
|
||||
|
||||
Use `-SkipSecrets` when you only want structural validation/resolution without loading provider secrets.
|
||||
|
||||
For unattended KeePass access, pass the KeePass master key through `ProviderSettings`, not through the PSD1 parameter definition:
|
||||
SecretManagement is the only built-in secret resolver provider. KeePass, SecretStore, Azure Key Vault, and other backends should be registered as SecretManagement vaults.
|
||||
|
||||
```powershell
|
||||
$resolved = Resolve-DSCConfigurationData -ConfigurationData $merged -ProviderSettings @{
|
||||
KeePass = @{
|
||||
DefaultVault = 'Contoso'
|
||||
MasterKey = (Get-Secret -Name 'KeePass-Contoso-MasterKey')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can generate the provider settings file with:
|
||||
KeePass can be registered through the `SecretManagement.KeePass` vault extension:
|
||||
|
||||
```powershell
|
||||
Register-DSCConfigurationDataCredentialProvider `
|
||||
-Provider KeePass `
|
||||
-Provider SecretManagement `
|
||||
-Vault Contoso `
|
||||
-KeyPath 'C:\DSC\Contoso\KeePass-Contoso.key' `
|
||||
-VaultType KeePass `
|
||||
-DatabasePath 'C:\DSC\Contoso\Secrets.kdbx' `
|
||||
-KeyPath 'C:\DSC\Contoso\Secrets.key' `
|
||||
-UseMasterPassword `
|
||||
-RegisterVault `
|
||||
-DefaultVault `
|
||||
-SettingsPath 'C:\DSC\Contoso'
|
||||
```
|
||||
|
||||
SecretManagement can be initialized through the same entry point:
|
||||
For unattended KeePass vaults that still require a master password, store the master password as a protected SecureString in the provider settings. The password is encrypted with an AES key file and the vault is unlocked automatically during `Resolve-DSCConfigurationData`:
|
||||
|
||||
```powershell
|
||||
$masterPassword = Read-Host -Prompt 'KeePass Master Password' -AsSecureString
|
||||
|
||||
Register-DSCConfigurationDataCredentialProvider `
|
||||
-Provider SecretManagement `
|
||||
-Vault Contoso `
|
||||
-VaultType KeePass `
|
||||
-DatabasePath 'C:\DSC\Contoso\Secrets.kdbx' `
|
||||
-KeyPath 'C:\DSC\Contoso\Secrets.key' `
|
||||
-UseMasterPassword `
|
||||
-MasterPassword $masterPassword `
|
||||
-MasterPasswordKeyPath 'C:\DSC\Contoso\KeePass-MasterPassword.key' `
|
||||
-RegisterVault `
|
||||
-DefaultVault `
|
||||
-SettingsPath 'C:\DSC\Contoso'
|
||||
```
|
||||
|
||||
Generic SecretManagement vaults can be registered through the same entry point:
|
||||
|
||||
```powershell
|
||||
Register-DSCConfigurationDataCredentialProvider `
|
||||
@@ -174,131 +189,59 @@ Register-DSCConfigurationDataCredentialProvider `
|
||||
-SettingsPath 'C:\DSC\Contoso'
|
||||
```
|
||||
|
||||
SecretStore can also be configured for unattended local usage:
|
||||
|
||||
```powershell
|
||||
Register-DSCConfigurationDataCredentialProvider `
|
||||
-Provider SecretStore `
|
||||
-Vault LocalStore `
|
||||
-ConfigureSecretStore `
|
||||
-Authentication None `
|
||||
-Interaction None `
|
||||
-RegisterVault `
|
||||
-DefaultVault `
|
||||
-SettingsPath 'C:\DSC\Contoso'
|
||||
```
|
||||
|
||||
Azure Key Vault can be registered as a settings file without storing Azure credentials. Authentication is expected to come from the active Az context, managed identity, service principal login, or another external Azure authentication flow:
|
||||
|
||||
```powershell
|
||||
Register-DSCConfigurationDataCredentialProvider `
|
||||
-Provider AzureKeyVault `
|
||||
-Vault contoso-kv `
|
||||
-SubscriptionId '00000000-0000-0000-0000-000000000000' `
|
||||
-TenantId '11111111-1111-1111-1111-111111111111' `
|
||||
-SettingsPath 'C:\DSC\Contoso'
|
||||
```
|
||||
|
||||
Provider setup can be removed again:
|
||||
|
||||
```powershell
|
||||
Unregister-DSCConfigurationDataCredentialProvider `
|
||||
-Provider KeePass `
|
||||
-Provider SecretManagement `
|
||||
-Vault Contoso `
|
||||
-SettingsPath 'C:\DSC\Contoso' `
|
||||
-KeyPath 'C:\DSC\Contoso\KeePass-Contoso.key' `
|
||||
-RemoveKeyFile
|
||||
```
|
||||
|
||||
For SecretManagement or SecretStore vault registration:
|
||||
|
||||
```powershell
|
||||
Unregister-DSCConfigurationDataCredentialProvider `
|
||||
-Provider SecretStore `
|
||||
-Vault LocalStore `
|
||||
-SettingsPath 'C:\DSC\Contoso' `
|
||||
-UnregisterVault
|
||||
```
|
||||
|
||||
Use `-ResetSecretStore` only when you intentionally want to delete all secrets from the local SecretStore.
|
||||
|
||||
Then use it directly:
|
||||
|
||||
```powershell
|
||||
$resolved = Resolve-DSCConfigurationData `
|
||||
-ConfigurationData $merged `
|
||||
-ProviderSettingsPath 'C:\DSC\Contoso\ProviderSettings.KeePass.psd1'
|
||||
-ProviderSettingsPath 'C:\DSC\Contoso\ProviderSettings.SecretManagement.psd1'
|
||||
```
|
||||
|
||||
For portable unattended tests, use an AES key file with `ConvertFrom-SecureString -Key`:
|
||||
Inspect the configured provider and registered vault:
|
||||
|
||||
```powershell
|
||||
$resolved = Resolve-DSCConfigurationData -ConfigurationData $merged -ProviderSettings @{
|
||||
KeePass = @{
|
||||
DefaultVault = 'Test'
|
||||
MasterKey = @{
|
||||
ProtectedValue = '76492d1116743f0423413b16050a5345...'
|
||||
KeyPath = 'F:\Secrets\KeePass-Test.key'
|
||||
}
|
||||
}
|
||||
}
|
||||
Get-DSCConfigurationDataCredentialProvider `
|
||||
-Provider SecretManagement `
|
||||
-SettingsPath 'C:\DSC\Contoso' `
|
||||
-TestVault
|
||||
```
|
||||
|
||||
`MasterKey` also supports:
|
||||
Update an existing KeePass-backed SecretManagement provider registration, for example to enable master-password based unlocks:
|
||||
|
||||
```powershell
|
||||
MasterKey = @{
|
||||
EnvironmentVariable = 'KEEPASS_TEST_MASTERKEY'
|
||||
}
|
||||
$masterPassword = Read-Host -Prompt 'KeePass Master Password' -AsSecureString
|
||||
|
||||
Set-DSCConfigurationDataCredentialProvider `
|
||||
-Provider SecretManagement `
|
||||
-SettingsPath 'C:\DSC\Contoso' `
|
||||
-UseMasterPassword `
|
||||
-MasterPassword $masterPassword `
|
||||
-MasterPasswordKeyPath 'C:\DSC\Contoso\KeePass-MasterPassword.key' `
|
||||
-VaultParameters @{
|
||||
ShowFullTitle = $true
|
||||
} `
|
||||
-RegisterVault `
|
||||
-AllowClobber `
|
||||
-Force
|
||||
```
|
||||
|
||||
### Secret Provider Files
|
||||
### Secret Provider
|
||||
|
||||
Secret providers are loaded automatically from the module folder `Providers`.
|
||||
The naming convention is:
|
||||
Only one built-in provider is registered:
|
||||
|
||||
```text
|
||||
Providers\Provider.<Name>.ps1
|
||||
```
|
||||
|
||||
Each provider registers itself with the same schema:
|
||||
|
||||
```powershell
|
||||
$MyProvider = @{
|
||||
Name = 'MyProvider'
|
||||
SupportedTypes = @(
|
||||
'credential',
|
||||
'securestring',
|
||||
'string'
|
||||
)
|
||||
Resolver = {
|
||||
param(
|
||||
[System.Collections.IDictionary] $Reference,
|
||||
[string] $ExpectedType,
|
||||
[hashtable] $ProviderSettings
|
||||
)
|
||||
|
||||
# Return a PSCredential for ExpectedType = credential,
|
||||
# a SecureString for ExpectedType = securestring,
|
||||
# or a string for ExpectedType = string.
|
||||
}
|
||||
}
|
||||
|
||||
Register-ConfigurationDataSecretProvider @MyProvider
|
||||
```
|
||||
|
||||
The KeePass provider is implemented in:
|
||||
|
||||
```text
|
||||
Providers\Provider.KeePass.ps1
|
||||
```
|
||||
|
||||
Built-in providers:
|
||||
|
||||
- `KeePass`: uses `PoShKeePass` / `Get-KeePassEntry`
|
||||
- `SecretManagement`: uses `Microsoft.PowerShell.SecretManagement` / `Get-Secret`
|
||||
- `SecretStore`: convenience provider for local SecretStore vaults through `Get-Secret`
|
||||
- `AzureKeyVault`: uses `Az.KeyVault` / `Get-AzKeyVaultSecret`
|
||||
|
||||
Backend-specific behavior belongs to the registered SecretManagement vault extension. For example, KeePass is handled by `SecretManagement.KeePass`, SecretStore by `Microsoft.PowerShell.SecretStore`, and Azure Key Vault by the matching SecretManagement vault extension.
|
||||
|
||||
SecretManagement example:
|
||||
|
||||
@@ -315,7 +258,7 @@ SetupCredential = @{
|
||||
}
|
||||
```
|
||||
|
||||
SecretStore example:
|
||||
SecretStore example through SecretManagement:
|
||||
|
||||
```powershell
|
||||
FarmPassphrase = @{
|
||||
@@ -323,14 +266,14 @@ FarmPassphrase = @{
|
||||
Required = $true
|
||||
Sensitive = $true
|
||||
Value = @{
|
||||
Provider = 'SecretStore'
|
||||
Provider = 'SecretManagement'
|
||||
Vault = 'LocalStore'
|
||||
Name = 'SharePointFarmPassphrase'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Azure Key Vault example:
|
||||
Azure Key Vault example through SecretManagement:
|
||||
|
||||
```powershell
|
||||
SetupCredential = @{
|
||||
@@ -338,7 +281,7 @@ SetupCredential = @{
|
||||
Required = $true
|
||||
Sensitive = $true
|
||||
Value = @{
|
||||
Provider = 'AzureKeyVault'
|
||||
Provider = 'SecretManagement'
|
||||
Vault = 'contoso-kv'
|
||||
Name = 'app-setup-password'
|
||||
UserName = 'CONTOSO\svc-app-setup'
|
||||
@@ -350,7 +293,7 @@ FarmPassphrase = @{
|
||||
Required = $true
|
||||
Sensitive = $true
|
||||
Value = @{
|
||||
Provider = 'AzureKeyVault'
|
||||
Provider = 'SecretManagement'
|
||||
Vault = 'contoso-kv'
|
||||
Name = 'farm-passphrase'
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user