xPfxImport DSC Resource for Importing Certificates and Keys

Comments

I’m very proud to have contributed the xPfxImport DSC Resource to Microsoft’s xCertificate module. This resource is included in version 1.1.0.0 of xCertificate which was released on .

xCertificate on GitHub
xCertificate on PowerShell Gallery
ServerFault thread that pushed me to publish (thanks in particular to jscott).

The purpose is to distribute SSL certificates (and optionally the private key) to nodes via PowerShell Desired State Configuration. The PFX is loaded from a network share or file path, and is typically encrypted with a password. DSC Encrypted Credentials are used to store the PFX extraction password securely in the configuration.

My primary use case in writing this concerned distribution of commercially purchased SSL certificates; particularly something like a wildcard cert which needs to be distributed to many nodes and will be need to be updated periodically as renewals happen.

This will also be nice for use with shorter term certificates like 90-day certs offered for free by Let’s Encrypt.

Documentation

The README on GitHub is the canonical source of documentation.

Check there for the most up-to-date info; I probably won’t update this.

xPfxImport resource has following properties:

  • Thumbprint: The thumbprint (unique identifier) of the certificate you’re importing.
  • Path: The path to the PFX file you want to import.
  • Location: Currently the only valid value here is LocalMachine.
  • Store: Defaults to My (the personal store) but can be any store that is valid on the machine (for example, WebHosting).
  • Exportable: Defaults to $false. Determines whether the private key is exportable from the machine after you import it.
  • Credential: A [PSCredential] object that is used to decrypt the PFX file. Only the password is used, so any user name is valid.

Simple Usage

xPfxImport CompanyCert
{
    Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
    Path = '\\Server\Share\Certificates\CompanyCert.pfx'
    Credential = $PfxPassword
}

Used with xWebAdministration Resources

xPfxImport CompanyCert
{
    Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
    Path = '\\Server\Share\Certificates\CompanyCert.pfx'
    Store = 'WebHosting'
    Credential = $PfxPassword
    DependsOn = '[WindowsFeature]IIS'
}

This is my first somewhat major open source contribution, and I hope to make more of these, especially to the DSC resources. I’m really glad Microsoft is embracing this approach.

Please let me know if you’re using this, how you’re using it, any feedback you might have (bugs and feature requests can be submitted via GitHub).