Create a Microsoft Windows (PowerShell) machine¶

Create a Microsoft Windows (PowerShell) machine so Certificate Manager - SaaS can provision certificates to a Windows server and then run a PowerShell function you write, for example, to bind the certificate to a Windows service. Certificate Manager - SaaS connects to the server through Windows Remote Management (WinRM) from a VSatellite. This machine type supports provisioning only.

Before you begin¶

The System Administrator, PKI Administrator, or Resource Owner role. If you have the Resource Owner role, you must own or belong to at least one team.
An active VSatellite that can reach the Windows server on its WinRM port and, if you use Kerberos authentication, the Key Distribution Center.
WinRM set up on the server for the authentication method you plan to use, and an HTTPS listener if you plan to connect over HTTPS. See To prepare the Windows server.
An account that's a member of the local Administrators group on the server. For Kerberos authentication, use an Active Directory domain account. For Basic authentication, use a local account.
For Kerberos authentication, the server's Active Directory domain name, the address of a Key Distribution Center (domain controller) for the domain, and the server's WinRM service principal name (SPN). To find the SPN, see To prepare the Windows server.
If you want Certificate Manager - SaaS to run a PowerShell function after it installs a certificate, a script and server setup that meet the requirements in PowerShell function contract later on this page.

Make sure the required Windows Remote Management (WinRM) ports are open from the VSatellite to the target Windows server. Firewalls or network security controls that block these ports stop certificate provisioning and discovery, where the machine type supports it.

Required ports

Purpose	Protocol	Port	When required
WinRM over HTTP	TCP	5985	When the machine uses WinRM over HTTP (for example, Kerberos over HTTP).
WinRM over HTTPS	TCP	5986	When the machine uses WinRM over HTTPS (for example, Kerberos over HTTPS or Basic Authentication over HTTPS).
Kerberos authentication	TCP and UDP	88	Whenever the machine uses Kerberos authentication. The VSatellite must reach the Kerberos service of a domain controller.

Important

Confirm that TCP 5985, TCP 5986, or both are reachable if you use the default WinRM listener configuration.
When you use Kerberos authentication, verify that TCP/UDP 88 is open between the VSatellite and your domain controller.
If your environment uses custom WinRM ports, make sure those ports are reachable.
Blocked ports often cause Test Access failures or authentication errors during machine creation or certificate provisioning.

To prepare the Windows server¶

Certificate Manager - SaaS connects to the Windows server through Windows Remote Management (WinRM). Run these commands on the server in a PowerShell window that you open with Run as administrator. Which sections apply depends on the Authentication Type you plan to choose and on whether you plan to enable Use TLS for WinRM.

Turn on WinRM¶

All machines need this section. Turn on the WinRM service and create the default HTTP listener on port 5985. If WinRM is already turned on, you can skip this command.

winrm quickconfig -quiet

Turn on the authentication method¶

Turn on the authentication method you plan to choose for the WinRM service.

Kerberos authentication. Kerberos is turned on by default. This command makes sure it's still turned on:

winrm set winrm/config/service/auth '@{Kerberos="true"}'

Over HTTP, Certificate Manager - SaaS encrypts Kerberos traffic itself, so you don't need to change the WinRM AllowUnencrypted setting.

Basic authentication. Basic is turned off by default. To turn it on, run this command:

winrm set winrm/config/service/auth '@{Basic="true"}'

With Basic authentication, Certificate Manager - SaaS doesn't encrypt the traffic itself. Create an HTTPS listener, as described in the next section, and enable Use TLS for WinRM on the machine.

Create an HTTPS listener¶

You need this section only if you plan to enable Use TLS for WinRM.

Install a TLS server certificate on the server. The certificate needs the Server Authentication extended key usage, and it must be in the local computer's Personal store (LocalMachine\My, or Local Computer > Personal in the Certificates snap-in).

Certificate Manager - SaaS doesn't verify the listener's certificate, so a self-signed certificate works. The connection is still encrypted.

Find the certificate's thumbprint:

Get-ChildItem -Path Cert:\LocalMachine\My

Create the HTTPS listener on port 5986. Replace <thumbprint> with the certificate's thumbprint:

winrm create winrm/config/Listener?Address=*+Transport=HTTPS '@{CertificateThumbprint="<thumbprint>"}'

If Windows Defender Firewall is turned on, allow inbound connections to port 5986. The winrm quickconfig command opens only port 5985.

New-NetFirewallRule -DisplayName "Windows Remote Management (HTTPS-In)" -Direction Inbound -Protocol TCP -LocalPort 5986 -Action Allow

Find the service principal name¶

You need this section only if you plan to choose Kerberos Authentication. List the server's service principal names (SPNs), where <hostname> is the server's computer name:

setspn -L <hostname>

Use the entry in the format WSMAN/<fqdn>, for example, WSMAN/server.example.com, as the machine's Service Principal Name. Use the same SPN whether or not you enable Use TLS for WinRM.

To create a Microsoft Windows (PowerShell) machine¶

Sign in to Certificate Manager - SaaS.
Click Installations > Machines.
Click New, and then select Microsoft Windows (PowerShell).
On the Properties step, in Name, enter a name for the machine.
For Owning Team, choose the team that owns the machine. System Administrators and PKI Administrators can choose any team. Resource Owners can choose only a team they own or belong to.
For VSatellite, choose a VSatellite that can reach the machine. A VSatellite that's the primary of a high availability group shows its number of active replicas, and Certificate Manager - SaaS can run the machine's operations on any healthy VSatellite in the group.
For Authentication Type, choose Basic Authentication or Kerberos Authentication. To compare them, see Authentication options later on this page.
In Microsoft Server Hostname, enter the hostname, fully qualified domain name (FQDN), or IP address of the Windows server.
(Optional) In Windows Remote Management (WinRM) Port, enter the port of the server's WinRM listener. If you leave it empty, Certificate Manager - SaaS uses 5985, the default HTTP port. If you enable Use TLS for WinRM, enter the HTTPS listener port, which is usually 5986.
(Optional) To connect to the server over HTTPS, enable Use TLS for WinRM.

Note

Certificate Manager - SaaS doesn't verify the TLS certificate of the server's WinRM listener. The connection is still encrypted.
If you chose Kerberos Authentication, under Kerberos Details, in Domain Name, enter the Active Directory domain name of the server, for example, example.com.
If you chose Kerberos Authentication, in Key Distribution Center Address/Hostname, enter the hostname or IP address of a domain controller for the domain.
If you chose Kerberos Authentication, in Service Principal Name, enter the server's WinRM SPN in the format WSMAN/<fqdn>, for example, WSMAN/server.example.com.
For Credential Type, choose how to provide the credentials:
- Enter Credentials to enter the credentials in the next step. This is the default.
- Select Credentials to use shared credentials from a credential manager integration. Then, for Credential, choose the credential.
Note

Select Credentials requires the credential manager capability, which requires additional licensing. Without it, Credential shows No credentials are available. System Administrators and PKI Administrators can choose any credential. Resource Owners can choose only the credentials that belong to their teams.
If you chose Enter Credentials, enter the Username and Password of the Windows account. For Kerberos authentication, enter the username without the domain, for example, jsmith instead of jsmith@example.com. If you chose Select Credentials, the stored account needs the same access on the server.

Non-ASCII characters aren't supported in the username or password.

Note

Certificate Manager - SaaS encrypts the credentials you enter and doesn't display them again. On the machine's Properties tab, they appear masked. To keep a stored credential when you edit the machine, leave its masked value unchanged. Keep your own secure record of the credentials in case you need them again.
Click Test Access. After the connection succeeds, click Continue. The Provisioning step opens.

Note

A successful test confirms that Certificate Manager - SaaS can reach the server's WinRM listener, sign in, and run a command. It doesn't check your PowerShell script, the server's execution policy, or whether the server trusts the Palo Alto Networks code-signing certificate.
(Optional) To provision certificates on a schedule, enable Schedule. For Repeat every, choose Day, Week, or Month, and then in At, enter the time. For Week, select the days of the week. For Month, enter the days in Day of month. Times are in Coordinated Universal Time (UTC).

Scheduled provisioning pushes only certificates that are queued for deployment, such as renewed certificates, so renewals install during the window you choose.
Click Finish.

PowerShell function contract¶

When you provision a certificate with Invoke a PowerShell script function, which will consume the provisioned certificate enabled, Certificate Manager - SaaS installs the certificate and then runs a function from a script on the server. The script and the server must meet these requirements:

The script exists on the server at the absolute path you enter in Script Path, and the path ends in .ps1. Certificate Manager - SaaS doesn't copy the script to the server.
The server's effective PowerShell execution policy, as Get-ExecutionPolicy returns it for the machine's account, is AllSigned. If it returns any other value, Certificate Manager - SaaS doesn't run the script and provisioning fails. If you can't set AllSigned for the whole computer, you can set it for the machine's account only, at the CurrentUser scope.
The script is signed with a code-signing certificate that the server trusts. Import your code-signing certificate into the local computer's Trusted Publishers store.

The server trusts the Palo Alto Networks code-signing certificate. Certificate Manager - SaaS installs certificates with its own PowerShell script, which is signed with a DigiCert code-signing certificate issued to Palo Alto Networks, Inc. Under AllSigned, that script runs only if you import this certificate into the local computer's Trusted Publishers store. Active Directory administrators usually distribute trusted publisher certificates through Group Policy.

Palo Alto Networks code-signing certificate (PEM)

The script contains a function named bind-certificate that takes these string parameters. Certificate Manager - SaaS passes them by name.
- certificateStore: the name of the certificate store under the local computer account where Certificate Manager - SaaS installed the certificate: my (Personal), webhosting (Web Hosting), or Remote Desktop.
- thumbprint: the certificate's SHA-1 thumbprint, in uppercase hexadecimal.

Certificate Manager - SaaS treats the function as successful when it finishes with exit code 0 and no error output. A non-zero exit code, or error output, means the function failed, and Certificate Manager - SaaS reports the error text. Output from a successful run isn't shown. To report a failure, use throw.

Warning

You're responsible for writing, managing, and securing your script. Make sure it does only what you intend and doesn't exhaust system resources. To limit exposure, use a dedicated account for the machine instead of a shared account. Script signing protects the script's integrity after deployment, but it doesn't guarantee the security of its source or development environment.

Example script:

<##################
.NAME
    bind-certificate
.DESCRIPTION
    Consumes a certificate from a local computer certificate store, for example, to bind it to a Windows service
.PARAMETER certificateStore
    The name of the certificate store under Cert:\LocalMachine (my, webhosting, or Remote Desktop)
.PARAMETER thumbprint
    The SHA-1 thumbprint of the certificate
.NOTES
    Throw to report a failure. Certificate Manager - SaaS shows the error text.
##################>

function bind-certificate (
    [string]$certificateStore,
    [string]$thumbprint
)
{
    $cert = Get-Item "Cert:\LocalMachine\$certificateStore\$thumbprint" -ErrorAction SilentlyContinue
    if ($null -eq $cert) {
        throw "Certificate $thumbprint not found in Cert:\LocalMachine\$certificateStore"
    }

    # Use the certificate here, for example, bind it to a Windows service.

    return "Success"
}

Authentication options¶

How Certificate Manager - SaaS protects the WinRM connection depends on the Authentication Type you choose and on whether you enable Use TLS for WinRM. Use the most secure option your environment allows. This list goes from most to least secure.

Kerberos Authentication over HTTPS: TLS encrypts the traffic. Certificate Manager - SaaS sends a Kerberos channel binding token, so you can keep the WinRM CbtHardeningLevel setting at Strict.
Kerberos Authentication over HTTP: Certificate Manager - SaaS encrypts all WinRM traffic with Kerberos message encryption, whatever the server's WinRM AllowUnencrypted setting, so you can keep AllowUnencrypted at false. Message encryption supports the AES encryption types aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96, and it refuses RC4 and DES. If authentication fails because of the encryption type, make sure the domain issues AES tickets for the account.
Basic Authentication over HTTPS: TLS encrypts the traffic, including the username and password. Use it for a server that isn't joined to a domain.

Warning

Use Basic Authentication only with Use TLS for WinRM enabled. Without TLS, the username and password cross the network unencrypted.

What's next?¶

After you create the machine, provision a certificate to it. This machine type doesn't support discovery.