Creating an HTTPS endpoint requires a certificate bound to the IIS endpoint. If you already have an Active Directory Certificate authority and other means for generating a certificate, go ahead to the next steps for creating an IIS site and binding the certificate to it. If not, you can create a self-signed certificate and install it on the system on which the pull service is being configured. You can use the Get-ChildItem cmdlet to see the thumbprint associated with the certificate on the web server. Note that you will require a web server certificate that is capable of server authentication, and not the client authentication certificate, as we saw in Chapter 6. So, if you are using the instructions given in Chapter 6 to create a self-signed certificate using makecert.exe, make sure that you change the Enhanced Key Usage (EKU) value to 1.3.6.1.5.5.7.3.1, which represents server authentication.
#Use a Web Server certificate and not a client authentication cert
$ServerCert = (Get-ChildItem Cert:\LocalMachine\my).Where({$_.EnhancedKeyUsageList.FriendlyName -eq 'Server Authentication'})
if ($ServerCert) {
$certificate = $ServerCert.Thumbprint } else {
throw "there is no server authentication certificate"
}
Once we have the certificate thumbprint, we can create an IIS site and bind the certificate to it.
$webSite = New-WebSite -Name $site -Id $siteID -Port $port -IPAddress "*" -PhysicalPath $path -ApplicationPool $appPool -Ssl
Remove-Item IIS:\SSLBindings\0.0.0.0!$port -ErrorAction Ignore
$null = Get-Item CERT:\LocalMachine\MY\$certificate | New-Item IIS:\SSLBindings\0.0.0.0!$port
We now have to create a web application for the IIS site we created. The steps from here onward are same for both HTTP and HTTPS endpoints.
$null = New-WebApplication -Name $app -Site $site -PhysicalPath $path -ApplicationPool $appPool Once we have the web application created, we can start configuring the other aspects of the IIS endpoint.
We start by allowing different authentication methods.
$Auths = "anonymous","basic","windows"
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.Web.Administration") | Out-Null foreach ($auth in $Auths) {
$webAdminSrvMgr = new-object Microsoft.Web.Administration.ServerManager $appHostConfig = $webAdminSrvMgr.GetApplicationHostConfiguration() $authenticationType = "$($auth)Authentication"
$appHostConfigSection = $appHostConfig.GetSection("system.webServer/security/authentication/$aut henticationType", $Site)
$appHostConfigSection.OverrideMode="Allow"
$webAdminSrvMgr.CommitChanges() Start-Sleep 4
}
The final few steps in configuring the pull service endpoint are to set up the device inventory database for the pull clients, set up the directories for configuration and module distribution, and update the IIS web.config file to ensure we have the right database provider settings. The devices.mdb file available at the $PathPullServer is used for the device inventory.
Copy-Item "$pathPullServer\Devices.mdb" $rootDataPath -Force
We have to create the folders in which we intend to store the configuration MOF and resource modules files for distribution to the pull clients.
$null = New-Item -path "$ConfigurationPath" -itemType "directory" -Force
$null = New-Item -path "$ModulePath" -itemType "directory" -Force
To conclude the configuration, we have to update the web.config of the IIS endpoint. We will use a hash table that contains the keys and values that we have to add to the web.config file.
[hashtable] $PullSettingHash = [Ordered] @{
dbprovider = $jet4provider dbconnectionstr = $jet4database ConfigurationPath = $ConfigurationPath ModulePath = $ModulePath
}
We must use the Jet DB provider for the pull service endpoint. Also, the configuration and module paths have to be added to the web.config file, so that the endpoint can use that for distribution to the pull clients. We will use a function (derived from the xPSDesiredStateConfiguration resource) to update the web.config file. Here is the function definition:
function Set-AppSettingsInWebconfig {
param (
# Physical path for the IIS Endpoint on the machine (possibly under inetpub/wwwroot) [parameter(Mandatory)]
$webconfig = Join-Path $path "web.config"
[bool] $Found = $false
$nameAtt2 = $xml.CreateAttribute("value") $nameAtt2.psbase.value = $value;
$null = $newElement.SetAttributeNode($nameAtt2)
$null = $xml.configuration["appSettings"].AppendChild($newElement) }
}
$xml.Save($webconfig) }
We will now iterate over the hash table and update the web.config file, using the Set-AppSettingsInWebConfig function. Here is how we do it:
foreach ($key in $PullSettingHash.Keys) {
Set-AppSettingsInWebconfig -path $Path -key $key -value $PullSettingHash[$key]
}
That’s it. We should have a functional pull server endpoint at this stage, and we can verify it by accessing the URL represented by some of the default variable values we defined earlier. For example, based on the values I showed in this section, the URL to the pull service will be either
http://wsr2-1.dscdemo.lab:8080/PullSvc/PSDSCPullServer.svc/
or
https://wsr2-1.dscdemo.lab:8080/PullSvc/PSDSCPullServer.svc/
based on the type of endpoint you created. When we access this endpoint in a browser, we should see XML output with the available methods Action and Module.
The XML output you see must be similar to what is shown in Figure 7-10. The Action and Module methods shown in the output represent the service methods available to the pull clients. We will discuss more about this when we look at configuring a pull client and enacting configuration in Pull mode.
Figure 7-10. Successful configuration of the DSC pull service
So far, we have looked at creating representational state transfer (REST)-based pull service endpoints that either use HTTP or HTTPS. As you have seen in this section, the configuration of these endpoints is complex and requires separate services deployed for each protocol. The pull service can also be deployed to support an SMB (Server Message Block) file share too. The next section shows you how to configure this.