initializeNewAcmeCertificate - RIT-ITS/CertifiCat-PS GitHub Wiki

Requests a new certificate (if needed), and then performs additional optional downstream steps with IIS and the Windows Certificate store.

Initialize-NewACMECertificate [-DomainList <String []>] [-FriendlyName <String>] 
    [-UpdateBindings <Switch>] [-BindingPorts <String[]>] [-SkipImport <Switch>] 
    [-StoreName <String>] [-StoreLocation <String>] [-SkipCentralize <Switch>]
    [-CentralDirectory <String>] [-SkipRenewalCheck <Switch>] 
    [-RenewalMethod <String>] [-RenewalDirectory <String>] 
    [-SkipDomainValidation <Switch>] [-RenewalThreshold <int>]
    [-debugEnabled] [-debugLogDirectory <string>] [-debugMode <string>]
    [-jitter <int>] [-CertKeyLength <string>] [@otherArguments]

Fundamentally, this function mirrors the Posh-ACME New-PACertificate and Install-PACertificate functions, which are used to request (and import into the certificate store) new certificates.

However, this function augments the Posh-ACME functions with additional functionality not available in the module, including:

• Verifying the expiration of a certificate using multiple methods beyond just getting the active certificate from the Posh-ACME cache including: verifying the certificate on one or more IIS Site bindings and finding .cer certificate files in a specified directory.
• Copying the new certificate from the Posh-ACME working directory (by default, in the user's users AppData directory) to a more convenient, central directory
• Updating existing IIS HTTPS site bindings with the new certificate

Unless the -SkipRenewalCheck switch is applied to the function, certificates will not be renewed until they are less than 14 days from expiration.

⚠️ Warning: Certain parameter combinations cannot be run on versions of PowerShell above 6 at this time. For more information, see the PowerShell Requirements section in the System Requirements page.

If the function detects that it is being used in a PowerShell 7+ console, it will suspend, and output a command that can be run in a legacy PowerShell console instead. See the Parameters list below for affected parameters and parameter values (generically, this applies to anything related to IIS or bindings).

Initialize-NewACMECertificate -DomainList app1.example.com -UpdateBindings

This command will create verify that the existing certificate in the Posh-ACME working directory is eligible for renewal, requests a new certificate with app1.example.com as the subject, imports it into the LocalMachine\WebHosting store, copies it to a central location, and then updates all IIS HTTPs Site Bindings with the new certificate.

Initialize-NewACMECertificate -DomainList app1.example.com, app2.example.com -UpdateBindings -BindingPorts 443 -SkipCentralize

This command will create verify that the existing certificate in the Posh-ACME working directory is eligible for renewal, requests a new certificate with app1.example.com as the subject (and app2.example.com as a SAN), imports it into the LocalMachine\WebHosting store, and then updates only the IIS binding for port 443.

Initialize-NewACMECertificate -DomainList app1.example.com -UpdateBindings -BindingPorts 443 -RenewalMethod IIS

This command performs the same steps as Example 1, except that it looks at the certificate assigned to the binding on port 443. (With the idea being that the certificate may have been changed from the previous Posh-ACME-issued certificate)

Initialize-NewACMECertificate -DomainList app1.example.com -SkipRenewalCheck

This command ignores any existing certificates and requests a new certificate with app1.example.com as the subject, imports it into the LocalMachine\WebHosting store, and copies it to a central location.

A list of domain names to associate with the certificate. The first domain in the list becomes the "Main" domain and subject of the certificate, and the others will be added as SANs.

Type: String[]
Position: Named
Default Value:  False
Required: True

The friendly name to assign to the PFX certificate file that will optionally be imported into the Windows certificate store.

Type: String
Position: Named
Default Value:  <Hostname portion of main domain> (Posh-ACME <MM-dd-YYYY>)
Required: False

When applied, the function will update the relevant HTTPS IIS bindings with the new certificate.

Type: Switch
Position: Named
Default Value:  ACME Challenge Proxy
Required: False

⚠️ Warning: The switch cannot be run on versions of PowerShell above 6 at this time. For more information, see the PowerShell Requirements section in the System Requirements page.

If the function detects this parameter value being used in a PowerShell 7+ console, it will suspend, and output a command that can be run in a legacy PowerShell console instead.

A comma separates list of ports that are used in conjuntion with the -UpdateBindings parameter, as well as the -RenewalMethod parameter.

When this parameter is added, only the ports provided are updated (and analyzed for renewal). When omitted, all HTTPS ports/bindings are considered for update and renewal.

Type: String[]
Position: Named
Default Value:  False
Required: False

⚠️ Warning: The parameter cannot be run on versions of PowerShell above 6 at this time. For more information, see the PowerShell Requirements section in the System Requirements page.

If the function detects this parameter value being used in a PowerShell 7+ console, it will suspend, and output a command that can be run in a legacy PowerShell console instead.

When applied, the resulting certificate file will not be imported into the Windows Certifiate Store

Type: Switch
Position: Named
Default Value:  False
Required: False

The name of the Windows Certificate Store into which the resulting certificate is imported.

Type: String
Position: Named
ValidateSet: WebHosting, My, Root
Default Value:  WebHosting
Required: False

The name of the Windows Certificate location into which the resulting certificate is imported.

Type: String
Position: Named
ValidateSet: LocalMachine, My
Default Value:  LocalMachine
Required: False

When applied, the resulting certificate files will not be copied from the Posh-ACME working directory to a central location.

Type: Switch
Position: Named
Default Value:  False
Required: False

When the -SkipCentralize parameter is omitted, this directory specifies where the new certificate files will be copies.

Type: String
Position: Named
Default Value:  %PROGRAMDATA%\certificat-ps\certificates\<main domain>\<date as: MM-dd-yyyy-HH-mm-ss>
Required: False

When applied, the function will not analyze any existing certificates for expiration, instead forcing the request of a new certificate.

Type: Switch
Position: Named
Default Value:  False
Required: False

Specifies how the function will determine whether a certificate is ready for renewal using:

• PA: The Posh-ACME working directory (via Get-PACertificate)
• IIS: Using the certificates associated with either all HTTPS bindings, or the binding(s) as specified by the -BindingPorts parameter
• Directory: Recursively uses a directory, as specified by the -RenewalDirectory parameter below, to find any .cer files issued by "InCommon" contaiing the main domain in the subject.

Type: String
Position: Named
Default Value:  PA
Required: False

⚠️ Warning: The "IIS" RenewalMethod cannot be run on versions of PowerShell above 6 at this time. For more information, see the PowerShell Requirements section in the System Requirements page.

If the function detects this parameter value being used in a PowerShell 7+ console, it will suspend, and output a command that can be run in a legacy PowerShell console instead.

Used in conjunction with the "Directory" RenewalMethod above, specifies the directory in which the function will recursively look for existing certificate files issued by InCommon and containing the main domain in the subject.

Type: String
Position: Named
Default Value:  c:\its\certs\posh-acme
Required: False

By default, the function will review all of the domains specified in the -DomainList and throw an exception if any do not match a known domain pattern (by default, this being (.)*.rit.edu). This switch allows this check to be bypassed. Users can also change the domain validation pattern using the Set-CertifiCatDomainValidation function.

Type: String
Position: Named
Default Value:  False
Required: False

Specifies the number of days prior to the expiration of the current certificate that this function will trigger a request for a new certificate.

Type: String
Position: Named
Default Value:  14
Required: False

This switch must be present to cause the function in question to output the contents of the object to a file or event log

Type: Switch
Position: Named
Required: False

Specifies where the CertifiCat-PS debug logs are written, when the debugMode option is EVT or Both.

Type: String
Position: Named
Required: False

Controls where the CertifiCat-PS debug informaiton is written: EVT (the windows event log), File (a text file on disk), or Both (a text file on disk and the Windows Event Log)

Type: String
Position: Named
Required: False
Default Value: EVT
ValidateSet: EVT, File, Both

Specifies a maximum number of seconds that the function will randomly wait for (between 1 and the provided value) before making a call to Posh-ACME to request a new certificate. This is useful when this function is being scheduled across multiple servers in an environment and there is a desire to randomly stagger the calls for a new certificate. When this value is 0 (or the parameter is omitted), jitter is not introduced.

Type: Int
Position: Named
Default Value:  0
Required: False

Specifies the key size and type of the newly generated certificate. The CertifiCat-PS module provides a different default value (4096) as compared to the Posh-ACME default (2048, as of April 2025).

Type: String
Position: Named
Default Value:  4096
Required: False
ValidateScript: Must be either 'ec-256,' 'ec-384', or an integer value from 2048 to 4096 which is also divisible by 128.

The Initialize-NewACMECertificate function aims to provide parameters for a variety of options available when requesting a new certificate via Posh-ACME. However, there may be options that are necessary, or desired, that aren't directly exposed via this function.

Additional parameters can be specified in this function that are directly passed to the Posh-ACME New-PACertificate function.

Returns a custom PowerShell object with properties about the function and the account that was set up. The object has the following properties:

• Posh-ACME: Get-PACertificate
• Background on IIS in PowerShell 7
• Get-WebBinding