Implement Microsoft.PowerShell.SecretManagement extension

[Gijsreyn]

PR Summary

This pull request adds the Microsoft.PowerShell.SecretManagement extension.

PR Context

[Gijsreyn]

@SteveL-MSFT Testing out the changes, I encountered the fact that most secret vault require some pre-authentication. In this case, it spawns another process and mentions:

2025-08-22T07:28:15.409628Z TRACE dsc_lib::dscresources::command_resource: 935: PID 14876: Get-Secret: C:\source\DSCv3\bin\debug\microsoft.powershell.secret.ps1:22:15 2025-08-22T07:28:15.409779Z TRACE dsc_lib::dscresources::command_resource: 935: PID 14876: Line | 2025-08-22T07:28:15.409804Z TRACE dsc_lib::dscresources::command_resource: 935: PID 14876: 22 | $secret = Get-Secret @secretParams -ErrorAction Ignore 2025-08-22T07:28:15.409945Z TRACE dsc_lib::dscresources::command_resource: 935: PID 14876: | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2025-08-22T07:28:15.410091Z TRACE dsc_lib::dscresources::command_resource: 935: PID 14876: | A valid password is required to access the Microsoft.PowerShell.SecretStore vault. Use the Unlock-SecretStore cmdlet to provide the required password to access the store.

Does it make sense to add an additional argument to be passed along as secureString in the config and use Unlock-SecretStore from the script? Or are there other ideas?

[michaeltlombardi]

I'm not sure I can think of a clean way to do this from within the existing data model for a configuration document to avoid requiring the user to perform initialization steps and documenting those.

Arguably, we could specify something like extensions as a field in Microsoft.DSC under the metadata section of the configuration document, where you can provide options for the extension (such as passing it the credential required to unlock a vault). This would require more in-depth thinking around how extensions should surface their options/behaviors so we can expose those coherently to the user.

The following snippet is just an example, not fully thought out:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
metadata:
  Microsoft.DSC:
    extensions: # map where keys must be the extension type
      Microsoft.PowerShell/SecretManagement:
        enabled: true # default, users can explicitly disable
        version: 1.2  # optionally pin to specific version
        # Other DSC-specific stuff goes at the top-level of the map,
        # so we can do validation/interpretation.
        # 
        # Everything under options comes from the extension, which
        # probably has to publish them as a JSON Schema in the manifest.
        options:      # map of options to pass to the extension
          unlockCredential: "[parameters('secretStoreCred')]"

This would enable in-document control / options for extensions. If we require extensions to publish their options as a JSON Schema, we can also use this model for incorporating extension options into your DSC settings/policy. I think we probably need to resolve extension options sooner than later, but I wouldn't block this PR on it.

Probably, the correct (current) model would be to document that this extension requires you to invoke DSC from a PowerShell session where you have already used the Unlock-SecretStore command before invoking DSC. Maybe the extension could handle this case as a known semantic exit code and surface a useful error message to the user when the vault isn't already unlocked.

[michaeltlombardi]

I filed #1080 for handling extension options separately from this PR.

[Gijsreyn]

Thanks, Mikey, for always providing well-explained and possible solutions to tackle the issue. Let's keep it open for now and see what the others think about it :)