Modules/AzureDevOpsDsc.Common/Api/Functions/Private/Helper/Resolve-AzDoSecretReference.ps1
|
<#
.SYNOPSIS Turns a secret reference from a configuration into the secret it names. .DESCRIPTION A configuration document is a file: it is committed, copied and compiled into a MOF. A secret written into it as a literal travels with it. Wherever a resource takes a secret, the configuration can give a reference instead, and the secret is fetched on the machine applying it: @{ SecretEnvironmentVariable = 'AZDO_API_KEY' } The value of that environment variable in the process running DSC. @{ SecretName = 'ApiKey' } @{ SecretName = 'ApiKey'; SecretVault = 'Production' } The secret of that name from Microsoft.PowerShell.SecretManagement, from the named vault or from the default one. The module has to be installed and the vault registered for the account running DSC. Anything that is not a reference is returned unchanged, so literal values keep working. A reference that cannot be resolved (variable not set, secret not found, SecretManagement missing) throws: silently storing an empty secret would be worse. The resolved value is passed to Register-AzDoSecretValue, so it is redacted from logs and errors. .PARAMETER Value A literal value, or a reference: a hashtable or object whose only keys are SecretEnvironmentVariable, or SecretName and optionally SecretVault. .PARAMETER IsReference Returns whether -Value is a reference, without resolving it. .EXAMPLE Resolve-AzDoSecretReference -Value @{ SecretEnvironmentVariable = 'AZDO_API_KEY' } #> function Resolve-AzDoSecretReference { [CmdletBinding()] param ( [Parameter(Position = 0)] [AllowNull()] $Value, [Parameter()] [System.Management.Automation.SwitchParameter] $IsReference ) # Read the keys of a hashtable or of a property bag (what a deserialized configuration gives). $reference = $null if ($Value -is [System.Collections.IDictionary]) { $reference = @{} foreach ($key in $Value.Keys) { $reference[[System.String]$key] = $Value[$key] } } elseif ($Value -is [System.Management.Automation.PSCustomObject]) { $reference = @{} foreach ($property in $Value.PSObject.Properties) { $reference[$property.Name] = $property.Value } } $isSecretReference = $false if (($null -ne $reference) -and ($reference.Count -gt 0)) { # Hashtable keys are matched without regard to case. $unknown = @($reference.Keys | Where-Object { $_ -notin @('SecretEnvironmentVariable', 'SecretName', 'SecretVault') }) $isSecretReference = ($unknown.Count -eq 0) -and ($reference.ContainsKey('SecretEnvironmentVariable') -or $reference.ContainsKey('SecretName')) } if ($IsReference.IsPresent) { return $isSecretReference } if (-not $isSecretReference) { return $Value } if ($reference.ContainsKey('SecretEnvironmentVariable')) { if ($reference.Count -ne 1) { throw "[Resolve-AzDoSecretReference] A secret reference names either SecretEnvironmentVariable, or SecretName (with an optional SecretVault), not both." } $variableName = [System.String]$reference['SecretEnvironmentVariable'] $secret = [System.Environment]::GetEnvironmentVariable($variableName) if ([System.String]::IsNullOrEmpty($secret)) { throw "[Resolve-AzDoSecretReference] The environment variable '$variableName' named by a secret reference is not set for the process running DSC." } } else { $secretName = [System.String]$reference['SecretName'] if ($null -eq (Get-Command -Name 'Get-Secret' -ErrorAction Ignore)) { throw "[Resolve-AzDoSecretReference] The secret reference '$secretName' needs the Microsoft.PowerShell.SecretManagement module, which is not installed for the account running DSC." } $getSecretParameters = @{ Name = $secretName; AsPlainText = $true; ErrorAction = 'Stop' } if (-not [System.String]::IsNullOrEmpty([System.String]$reference['SecretVault'])) { $getSecretParameters.Vault = [System.String]$reference['SecretVault'] } try { $secret = Get-Secret @getSecretParameters } catch { throw "[Resolve-AzDoSecretReference] The secret '$secretName' could not be read from the secret vault. $(Protect-AzDoSecretString -InputString ([System.String]$_))" } if ($secret -isnot [System.String] -or [System.String]::IsNullOrEmpty($secret)) { throw "[Resolve-AzDoSecretReference] The secret '$secretName' is empty or is not a text secret." } } Register-AzDoSecretValue -Value $secret return $secret } |