InitializeACMEProxyRedirect - RIT-ITS/CertifiCat-PS GitHub Wiki
Configured a URL Rewrite rule on a secondary web server in a load balanced environment to forward ACME challenges to a primary server.
Initialize-ACMEProxyRedirect [-PrimaryServer <String>]
[-IISSiteName <String>>] [-URLRerwiteRuleName <String>]
[-URLRewriteInstallerLog <String>] [-URLRewriteInstaller <String>]
[-URLRewriteDownloadURL <String>] [-URLRewriteInstallerExpectedHash <String>]
[-debugEnabled] [-debugLogDirectory <string>] [-debugMode <string>]Configures IIS on a secondary server node in a load balanced environment to forward ACME Challenge quests to the primary node. The primary node is the node indicated in the main domain/first domain in the certificate.
This function takes the following actions:
- Verifies the existence of the IIS URL Rewrite module, downloading and installing it if needed
- Checks for (or creates) a Virtual Directory (or Application) called ".well-known" in the main site (this ensures proper isolation of the configuration and redirects related to ACME from other applications on the server)
- Checks for / creates a URL Rewrite rule on the .well-known virtual directory that forwards all requests to the primary server
- Disables the "Require SSL" setting on the .well-known virtual directory
- Checks for (and creates, if needed) a Site binding for HTTP/port 80
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.
❗ Please be aware that, while this function effectively only needs to be run one-time on each secondary server in a load balanced environment / pool, its actions may be impactful to current connections (for example, resulting from the installation of the URL Rewrite module).
It is recommended that this function be run off-hours, during a maintenance window, or other non-impactful time, or, on one server at a time, if the environment supports true load balancing.
Initialize-ACMEProxyRedirect -PrimaryServer appA.example.comThis command will create the .well-known virtual directory in the "Default Web Site" site with a URL Rewrite Rule called "ACME Challenge Proxy"
Initialize-ACMEProxyRedirect -PrimaryServer appA.example.com -IISSiteName "Administrative Site" -URLRewriteRuleName "ACME Proxy"This command will create the .well-known virtual directory in the "Administrative Site" web site with a URL Rewrite Rule called "ACME Proxy"
The FQDN of the primary server in the farm, to which all ACME Challenge Requests will be forwarded
Type: String
Position: Named
Default Value: False
Required: True
The IIS Website into which the .well-known virtual directory will be created and configured
Type: String
Position: Named
Default Value: Default Web Site
Required: False
The name of the URL Rewrite Rule that will be created
Type: String
Position: Named
Default Value: ACME Challenge Proxy
Required: False
The path to the log file that will be written if the URL Rewrite Module is not present and needs to be downloaded and installed
Type: String
Position: Named
Default Value: c:\its\logs\urlRewriteInstaller.log
Required: False
The location into where the URL Rewrite installer will be downloaded, if needed
Type: String
Position: Named
Default Value: $env:temp\rewrite_amd64_en-US.msi
Required: False
The URL from where the URL Rewrite module will be downloaded
Type: String
Position: Named
Default Value: https://download.microsoft.com/download/1/2/8/128E2E22-C1B9-44A4-BE2A-5859ED1D4592/rewrite_amd64_en-US.msi
Required: False
The SHA-256 value of the URL Rewrite installer that is expected when downloaded from the URL above. This is added as an extra security measure to ensure that the installer was not compromised.
Type: String
Position: Named
Default Value: 37342FF2F585F263F34F48E9DE59EB1051D61015A8E967DBDE4075716230A32A
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
Returns a custom PowerShell object with properties about the function and the account that was set up. The object has the following properties:
| Property | Details |
|---|---|
| FunctionName | Name of the function that was run |
| RunningPSVersion | The version of the PowerShell console used to run the function |
| PS5Command | A full string containing the commands needed to run the same command in PowerShell 5 |
| FunctionArguments | A list of the arguments passed to the function |
| FunctionSuccess | True/False indicating if the function succeeded. When false, this typically indicates a larger issue (e.g. no admin rights, etc) |
| Errors | A string containing details about any errors that were encountered |
| URLRewriteDownloadURL | The URL from where the URL Rewrite module was downloaded (if needed) |
| URLRewriteExpectedHash | The expected hash of the URL Rewrite module (if needed) |
| URLRewriteRuleName | The name of the URL Rewrite Module rule that was created |
| URLRewriteInstallerLocation | The location of the URL Rewrite module installer that was downloaded (if needed) |
| URLRewriteInstallerLog | The log file for the URL Rewrite module, if installed |
| IISSiteName | The name of the IIS Website in which the .well-known virtual directory was created. |
| ProxyRedirectConfiguredSuccessfully | True/False indicating if the server was set up successfully with the URL Rewrite configuration and is ready to proxy ACME challenge requests. |
| debugEnabled | Boolean indicating whether debug logging was enabled |
| debugLogDirectory | String indicating the location of the debug log file, if file logging mode is enabled |
| debugMode | String indicating the logging mode (i.e. EVT, File, or Both) |