The xCertificate module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources. This module includes DSC resources that simplify administration of certificates on a Windows Server, with simple declarative language.
The xCertificate module contains the following resources:
- xCertReq
- xPfxImport
- xCertificateImport
- xCertificateExport
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Please check out common DSC Resources contributing guidelines.
[String]Subject: Provide the text string to use as the subject of the certificate. Key.[String]CAServerFQDN: The FQDN of the Active Directory Certificate Authority on the local area network. Leave empty to auto-discover in an Active Directory environment.[String]CARootName: The name of the certificate authority, by default this will be in format domain-servername-ca. Leave empty to auto-discover in an Active Directory environment.[String]KeyLength: The bit length of the encryption key to be used. Optional. { 1024 | 2048 | 4096 | 8192 }.[Boolean]Exportable: The option to allow the certificate to be exportable, by default it will be true. Optional. Defaults to$true.[String]ProviderName: The selection of provider for the type of encryption to be used. Optional. Defaults to"Microsoft RSA SChannel Cryptographic Provider".[String]OID: The Object Identifier that is used to name the object. Optional. Defaults to1.3.6.1.5.5.7.3.1.[String]KeyUsage: The Keyusage is a restriction method that determines what a certificate can be used for. Optional. Defaults to0xa0[String]CertificateTemplate The template used for the definiton of the certificate. Optional. Defaults toWebServer[String]SubjectAltName The subject alternative name used to create the certificate. Optional.[PSCredential]Credential: The credentials that will be used to access the template in the Certificate Authority. Optional.[Boolean]AutoRenew: Determines if the resource will also renew a certificate within 7 days of expiration. Optional.[Boolean]UseMachineContext: Indicates whether or not the flag -adminforcemachine will be used when requesting certificates. Necessary for certain templates like e.g. DomainControllerAuthentication. Optional.[String]CAType The type of Certificate Authority in use. Optional. Defaults toEnterprise[String]CepURL The URL to a Certificate Enrollment Policy Web Service. Optional.[String]CesURL The URL to a Certificate Enrollment Web Service. Optional.
[String]Thumbprint (Key): The thumbprint (unique identifier) of the PFX file you're importing.[String]Path (Required): The path to the PFX file you want to import.[String]Location (Key): The Windows Certificate Store Location to import the PFX file to. { LocalMachine | CurrentUser }[String]Store (Key): The Windows Certificate Store Name to import the PFX file to.[Boolean]Exportable (Write): Determines whether the private key is exportable from the machine after it has been imported. Defaults to$false.[PSCredential]Credential (Write): A[PSCredential]object that is used to decrypt the PFX file. Only the password is used, so any user name is valid.[String]Ensure (Write): Specifies whether the PFX file should be present or absent. { Present | Absent }.
[String]Thumbprint (Key): The thumbprint (unique identifier) of the certificate you're importing.[String]Path (Required): The path to the CER file you want to import.[String]Location (Key): The Windows Certificate Store Location to import the certificate to. { LocalMachine | CurrentUser }[String]Store (Key): The Windows Certificate Store Name to import the certificate to.[String]Ensure (Write): Specifies whether the certificate should be present or absent. { Present | Absent }.
[String]Path (Key): The path to the file you that will contain the exported certificate.[String]Thumbprint (Write): The thumbprint of the certificate to export. Certificate selector parameter.[String]FriendlyName (Write): The friendly name of the certificate to export. Certificate selector parameter.[String]Subject (Write): The subject of the certificate to export. Certificate selector parameter.[String]DNSName (Write): The subject alternative name of the certificate to export must contain these values. Certificate selector parameter.[String]Issuer (Write): The issuer of the certiicate to export. Certificate selector parameter.[String[]]KeyUsage (Write): The key usage of the certificate to export must contain these values. Certificate selector parameter.[String[]]EnhancedKeyUsage (Write): The enhanced key usage of the certificate to export must contain these values. Certificate selector parameter.[String]Store (Write): The Windows Certificate Store Name to search for the certificate to export from. Certificate selector parameter. Defaults to 'My'.[Boolean]AllowExpired (Write): Allow an expired certificate to be exported. Certificate selector parameter.[Boolean]MatchSource (Write): Causes an existing exported certificate to be compared with the certificate identified for export and re-exported if it does not match.[String]Type (Write): Specifies the type of certificate to export. { Cert | P7B | SST | PFX }[String]ChainOption (Write): Specifies the options for building a chain when exporting a PFX certificate. { BuildChain | EndEntityCertOnly }[PSCredential]Password (Write): Specifies the password used to protect an exported PFX file.[String[]]ProtectTo (Write): Specifies an array of strings for the username or group name that can access the private key of an exported PFX file without any password.[Boolean]IsExported (Read): Returns true if the certificate file already exists and therefore has been exported.
- Added mandatory properties for xPfxImport resource example.
- xCertReq:
- Fixed issue where xCertReq does not identify when DNS Names in SANs are incorrect.
- Added Certificate Authority auto-discovery to resource xCertReq.
- Added SAN and certificate template name to xCertReq's Get-TargetResource
- Added new parameter UseMachineContext to be able to use CA templates that try to fill the subject alternative name
- CertificateDSc.Common:
- Added function Get-CertificateTemplateName to retrieve template name
- Added function Get-CertificateSan to retrieve subject alternative name
- Added function Find-CertificateAuthority to enable auto-discovery
- Fixed issue where xCertReq does not process requested certificate when credentials parameter set and PSDscRunAsCredential not passed. See issue
- Converted AppVeyor build process to use AppVeyor.psm1.
- Correct Param block to meet guidelines.
- Moved shared modules into modules folder.
- xCertificateExport:
- Added new resource.
- Cleanup xCertificate.psd1 to remove unneccessary properties.
- Converted AppVeyor.yml to use DSCResource.tests shared code.
- Opted-In to markdown rule validation.
- Examples modified to meet standards for auto documentation generation.
- xCertReq:
- Added additional parameters KeyLength, Exportable, ProviderName, OID, KeyUsage, CertificateTemplate, SubjectAltName
- Fixed most markdown errors in Readme.md.
- Corrected Parameter decoration format to be consistent with guidelines.
- Converted appveyor.yml to install Pester from PSGallery instead of from Chocolatey.
- Moved unit tests to correct folder structure.
- Changed unit tests to use standard test templates.
- Updated all resources to meet HQRM standards and style guidelines.
- Added .gitignore file
- Added .gitattributes file to force line endings to CRLF to allow unit tests to work.
- xCertificateCommon:
- Moved common code into new module CertificateCommon.psm1
- Added standard exception code.
- Renamed common functions Validate-* to use acceptable verb Test-*.
- Added help to all functions.
- xCertificateImport:
- Fixed bug with Test-TargetResource incorrectly detecting change required.
- Reworked unit tests for improved code coverage to meet HQRM standards.
- Created Integration tests for both importing and removing an imported certificate.
- Added descriptions to MOF file.
- Removed default parameter values for parameters that are required or keys.
- Added verbose messages.
- Split message and error strings into localization string files.
- Added help to all functions.
- xPfxImport:
- Fixed bug with Test-TargetResource incorrectly detecting change required.
- Reworked unit tests for improved code coverage to meet HQRM standards.
- Created Integration tests for both importing and removing an imported certificate.
- Added descriptions to MOF file.
- Removed default parameter values for parameters that are required or keys.
- Added verbose messages.
- Split message and error strings into localization string files.
- Added help to all functions.
- xCertReq:
- Cleaned up descriptions in MOF file.
- Fixed bugs generating certificate when credentials are specified.
- Allowed output of certificate request when credentials are specified.
- Split message and error strings into localization string files.
- Created unit tests and integration tests.
- Improved logging output to enable easier debugging.
- Added help to all functions.
- xPDT:
- Renamed to match standard module name format (MSFT_x).
- Modified to meet 100 characters or less line length where possible.
- Split message and error strings into localization string files.
- Removed unused functions.
- Renamed functions to standard verb-noun form.
- Added help to all functions.
- Fixed bug in Wait-Win32ProcessEnd that prevented waiting for process to end.
- Added Wait-Win32ProcessStop to wait for a process to stop.
- Removed unused and broken scheduled task code.
- Fixed xCertReq to support CA Root Name with spaces
- Breaking Change - Updated xPfxImport Store parameter is now a key value making it mandatory
- Updated xPfxImport with new Ensure support
- Updated xPfxImport with support for the CurrentUser value
- Updated xPfxImport with validationset for the Store parameter
- Added new resource: xCertificateImport
- Added new resource: xPfxImport
- Minor documentation updates
- Initial public release of xCertificate module with following resources
- xCertReq
Request and Accept a certificate from an Active Directory Root Certificate Authority.
This example is allowing storage of credentials in plain text by setting PSDscAllowPlainTextPassword to $true. Storing passwords in plain text is not a good practice and is presented only for simplicity and demonstration purposes. To learn how to securely store credentials through the use of certificates, please refer to the following TechNet topic: https://technet.microsoft.com/en-us/library/dn781430.aspx
configuration Example
{
param
(
[Parameter()]
[string[]]
$NodeName = 'localhost',
[Parameter(Mandatory = $true)]
[ValidateNotNullorEmpty()]
[PSCredential]
$Credential
)
Import-DscResource -ModuleName xCertificate
Node 'localhost'
{
xCertReq SSLCert
{
CARootName = 'test-dc01-ca'
CAServerFQDN = 'dc01.test.pha'
Subject = 'foodomain.test.net'
KeyLength = '1024'
Exportable = $true
ProviderName = '"Microsoft RSA SChannel Cryptographic Provider"'
OID = '1.3.6.1.5.5.7.3.1'
KeyUsage = '0xa0'
CertificateTemplate = 'WebServer'
AutoRenew = $true
Credential = $Credential
}
}
}Request and Accept a certificate from an Active Directory Root Certificate Authority. This certificate is issued using an subject alternate name with multiple DNS addresses.
This example is allowing storage of credentials in plain text by setting PSDscAllowPlainTextPassword to $true. Storing passwords in plain text is not a good practice and is presented only for simplicity and demonstration purposes. To learn how to securely store credentials through the use of certificates, please refer to the following TechNet topic: https://technet.microsoft.com/en-us/library/dn781430.aspx
configuration Example
{
param
(
[Parameter()]
[string[]]
$NodeName = 'localhost',
[Parameter(Mandatory = $true)]
[ValidateNotNullorEmpty()]
[PSCredential]
$Credential
)
Import-DscResource -ModuleName xCertificate
Node 'localhost'
{
xCertReq SSLCert
{
CARootName = 'test-dc01-ca'
CAServerFQDN = 'dc01.test.pha'
Subject = 'contoso.com'
KeyLength = '1024'
Exportable = $true
ProviderName = '"Microsoft RSA SChannel Cryptographic Provider"'
OID = '1.3.6.1.5.5.7.3.1'
KeyUsage = '0xa0'
CertificateTemplate = 'WebServer'
SubjectAltName = 'dns=fabrikam.com&dns=contoso.com'
AutoRenew = $true
Credential = $Credential
}
}
}Import a PFX into the My store.
Configuration Example
{
param
(
[Parameter()]
[string[]]
$NodeName = 'localhost',
[Parameter(Mandatory = $true)]
[ValidateNotNullorEmpty()]
[PSCredential]
$Credential
)
Import-DscResource -ModuleName xCertificate
Node $AllNodes.NodeName
{
xPfxImport CompanyCert
{
Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
Path = '\\Server\Share\Certificates\CompanyCert.pfx'
Store = 'My'
Location = 'LocalMachine'
Credential = $Credential
}
}
}Import a PFX into the WebHosting store and bind it to an IIS Web Site.
Configuration Example
{
param
(
[Parameter()]
[string[]]
$NodeName = 'localhost',
[Parameter(Mandatory = $true)]
[ValidateNotNullorEmpty()]
[PSCredential]
$Credential
)
Import-DscResource -ModuleName xCertificate
Import-DscResource -ModuleName xWebAdministration
Node $AllNodes.NodeName
{
WindowsFeature IIS
{
Ensure = 'Present'
Name = 'Web-Server'
}
xPfxImport CompanyCert
{
Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
Path = '\\Server\Share\Certificates\CompanyCert.pfx'
Store = 'WebHosting'
Credential = $Credential
DependsOn = '[WindowsFeature]IIS'
}
xWebsite CompanySite
{
Ensure = 'Present'
Name = 'CompanySite'
State = 'Started'
PhysicalPath = "B:\Web\CompanySite"
ApplicationPool = "CompanyPool"
BindingInfo =
MSFT_xWebBindingInformation {
Protocol = 'HTTPS'
Port = 443
CertificateThumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
CertificateStoreName = 'WebHosting'
HostName = "www.example.com"
}
DependsOn = '[WindowsFeature]Web-Server','[xPfxImport]CompanyCert'
}
}
}Import public key certificate into Trusted Root store.
Configuration Example
{
param
(
[Parameter()]
[string[]]
$NodeName = 'localhost'
)
Import-DscResource -ModuleName xCertificate
Node $AllNodes.NodeName
{
xCertificateImport MyTrustedRoot
{
Thumbprint = 'c81b94933420221a7ac004a90242d8b1d3e5070d'
Location = 'LocalMachine'
Store = 'Root'
Path = '\\Server\Share\Certificates\MyTrustedRoot.cer'
}
}
}Exports a certificate as a CERT using the friendly name to identify it.
Configuration Example
{
param
(
[Parameter()]
[string[]]
$NodeName = 'localhost'
)
Import-DscResource -ModuleName xCertificate
Node $AllNodes.NodeName
{
xCertificateExport SSLCert
{
Type = 'CERT'
FriendlyName = 'Web Site SSL Certificate for www.contoso.com'
Path = 'c:\sslcert.cer'
}
}
}Exports a certificate as a PFX using the friendly name to identify it.
Configuration Example
{
param
(
[Parameter()]
[string[]]
$NodeName = 'localhost',
[Parameter(Mandatory = $true)]
[ValidateNotNullorEmpty()]
[PSCredential]
$Credential
)
Import-DscResource -ModuleName xCertificate
Node $AllNodes.NodeName
{
xCertificateExport SSLCert
{
Type = 'PFX'
FriendlyName = 'Web Site SSL Certificate for www.contoso.com'
Path = 'c:\sslcert.cer'
Password = $Credential
}
}
}