Microsoft services (Windows)¶

Agent 1.5.0 and later include bundled templates that install a renewed certificate in the Windows machine store and bind it to a Microsoft server role: Exchange, Remote Desktop, Routing and Remote Access, DirectAccess, SQL Server, Reporting Services, AD FS, Web Application Proxy, NPS and WinRM. In the desktop app they are listed under Microsoft services in Workflows → + New certificate workflow; they can also be assigned from the dashboard. Agent 1.15.0 and later add a template for LDAPS on a domain controller, and Agent 1.18.0 and later one that uses one certificate for several services.

How the templates work¶

Every template has the same shape:

1. Obtain certificate - the certificate the Agent issued or renewed.
2. Install in LocalMachine\My - the certificate and its key go into the machine Personal store, not exportable. Where a service runs as its own account, the step also grants that account read access to the private key (see Service accounts).
3. Bind to <service> - the new windows_service.bind step runs a fixed PowerShell script that is bundled with the Agent for that service.
4. Inspect the TLS endpoint and Confirm new certificate - only for the templates with a verification port, and only when Verification hostname (optional) is set: the Agent connects to the endpoint and checks that it serves the new certificate. A mismatch rolls the binding back.

The bind step runs elevated as the Agent service. The scripts are part of the signed Agent; there is no way to change them or add your own. The settings of a workflow are passed to the script as data on standard input, never pasted into the script or the command line, so a value cannot change what the script runs. The script reports the previous certificate it replaced; when a later step fails, rollback binds that previous certificate again. The script may run for 120 seconds (600 seconds for Exchange), and the bind step allows 60 seconds more.

A template description in the desktop app and in the dashboard says what it changes, what it restarts and how rollback works, and ends with Not verified on a live server: the role commands were tested only against a mocked PowerShell boundary.

Templates¶

Microsoft has deprecated DirectAccess; plan a move to Always On VPN. The DirectAccess template is there for existing deployments.

Setup fields¶

Templates with an endpoint check (Exchange, RD Gateway, RDS deployment, RRAS SSTP, DirectAccess, SSRS, AD FS, Web Application Proxy: port 443; WinRM HTTPS: port 5986; Active Directory LDAPS: port 636) also have Verification hostname (optional) - a hostname the service presents on TLS and the certificate covers; leave it empty to skip the check - and Verification port (for SSRS HTTPS port, the port of the existing HTTPS binding, which the check uses too). A Restart … after a change switch restarts the service at once (connections drop briefly); off means the service uses the certificate after its next restart.

Service accounts and private key access¶

Some services read the private key under their own account rather than as LocalSystem. Their templates fill the store installation step's new read_principals input from Account that reads the private key, so the account gets read access to that one key. Nothing is guessed: enter a Windows account name such as DOMAIN\name, NT SERVICE\name or NT AUTHORITY\NETWORK SERVICE. The desktop app checks the value as a Windows account name when you save, and the Agent checks it again when the step runs.

In your own workflows, windows_cert_store.install accepts read_principals (up to 16 account names; see step action inputs).

LDAPS on a domain controller¶

(Agent 1.15.0+) Active Directory LDAPS (domain controller) is for a domain controller that serves LDAPS with a certificate CertIntel issues, for example one from a public CA, instead of one from your own AD CS.

What the certificate must cover. Clients check the name they connect to, so the certificate must cover it: usually the domain controller's full name, such as dc01.corp.example.com, plus any shared name clients use, such as ldap.example.com. A public CA issues only for names under a public domain you control, so this works for an Active Directory domain like corp.example.com and cannot work for corp.local. A domain controller is normally not reachable from the internet, so use DNS-01 validation.

One workflow per domain controller. Install the Agent on every domain controller that serves LDAPS and give each its own workflow and certificate. Each Agent (1.16.0+) reports its own domain controller to CertIntel with the certificate it serves now, so the dashboard can fill the workflow form in for you; see Domain controllers.

What the workflow does. AD DS reads its own service certificate store, NTDS\Personal, before the machine Personal store, and when a store holds several usable certificates its choice cannot be predicted. The workflow therefore:

1. installs the certificate in LocalMachine\My;
2. copies it into NTDS\Personal;
3. takes every other certificate out of NTDS\Personal, so that the new one is the only one there;
4. asks AD DS to load its certificate again (the rootDSE operation renewServerCertificate). Nothing is restarted. LDAPS on port 636 and the global catalog on port 3269 use the same certificate.

No certificate and no private key is deleted. A certificate taken out of NTDS\Personal stays in LocalMachine\My; one that was only in NTDS\Personal is copied to LocalMachine\My first. Certificates that are already in LocalMachine\My, such as a domain controller certificate from AD CS, are left alone.

Set the verification hostname. With Verification hostname (optional) set to the domain controller's name and Verification port 636, the workflow connects afterwards and checks that the domain controller serves the new certificate; if it does not, the binding is rolled back. Without it the workflow does not check what the domain controller serves.

One certificate for several services¶

(Agent 1.18.0+) One certificate for several Windows services (windows-shared-certificate) issues one certificate, installs it once in LocalMachine\My (not exportable) and binds it to every service you select on that computer, for example LDAPS, Remote Desktop and NPS on a domain controller. Without it, each service needs a workflow and a certificate of its own.

Each service has a Use for … switch, off by default, followed by the same settings as its own template above, named with the service in front (for example Network Policy Server: network policy). What each service does, restarts and rolls back is what its own template does.

• One of each. A workflow binds one of each service: one Remote Desktop listener, one NPS network policy. A second one needs its own workflow.
• The names. The certificate must cover every name the selected services are reached by, for example the domain controller's full name for LDAPS and Remote Desktop.
• Private key access. Only the accounts of the selected services can read the key. The settings of a service that is not selected are saved empty.
• A failure rolls back the earlier services. When a service, or the check of its verification hostname, fails, that service and the services bound before it get their previous certificate back.
• What is required. At least one service, and for each selected service the settings its own template requires. Otherwise the Agent and the dashboard refuse with, for example, No service is selected. Select at least one of: … or Network Policy Server is selected, so its network policy is required.
• Not included: IIS, which has its own template and store rules, and the services not listed in the table. Give those their own workflow.

In the dashboard, Also use this certificate for fills this template in from the servers the Agent detected. On the Agent:

certintel workflows create --template windows-shared-certificate --certificate-id dc01 --domains dc01.corp.example.com --set use_ldaps=true --set ldaps_host=dc01.corp.example.com --set use_rdp=true --set use_nps=true --set nps_policy="Secure Wireless Connections" --issue

Like the other templates on this page it has not been run on a live server.

Prerequisites¶

• Exchange: run the Agent on the Exchange server; the script loads the Exchange Management Shell snap-in.
• Remote Desktop Services deployment: run it on the RD Connection Broker, or name the broker.
• RRAS and DirectAccess: the role must already be installed and configured (The Routing and Remote Access VPN role is not installed and configured. / DirectAccess is not installed and configured on this server.). For IKEv2, clients must trust the issuing CA and match the server name, and the certificate needs the Server Authentication EKU.
• SSRS: the HTTPS URL must already exist (add it in Report Server Configuration Manager first); otherwise the step fails with Reporting Services has no SSL binding on IP:PORT.
• WinRM: an existing HTTPS listener whose Hostname matches the certificate; the template does not create one (There is no WinRM HTTPS listener at address X.).
• AD FS: run a workflow on every AD FS server of the farm.
• Active Directory LDAPS: run the Agent on the domain controller itself (This computer is not a domain controller.). The certificate needs the Server Authentication EKU, which certificates for TLS servers have.

Known limits¶

• RDS deployment restores a single previous thumbprint, and only when all selected roles shared it.
• SQL Server without a previous certificate is not restored to "no certificate" by rollback.
• Exchange rollback timing: the Agent allows a rollback step 2 minutes, less than the 600 seconds an Exchange binding may take.
• NPS: the policy export also holds the RADIUS shared secrets. It is kept in a folder only SYSTEM and Administrators can open and deleted afterwards.
• RRAS IKEv2 binds nothing and has no rollback.
• Active Directory LDAPS: when NTDS\Personal was empty before the first run, rollback does not empty it again; the new certificate stays there. When it held several certificates, rollback restores the one that expires last.
• Active Directory LDAPS: if AD DS cannot be asked to load the certificate, the step fails with The certificate is in the AD DS certificate store, but AD DS could not be asked to load it (renewServerCertificate) and the certificate stays in NTDS\Personal.

Finding the right template¶

In the desktop app, Detect servers on this computer… in the new-workflow template dialog lists the Remote Desktop, RD Gateway, Remote Access and WinRM bindings it finds and, from Agent 1.18.0, the NPS network policies that use a certificate, the SQL Server instances, and the Reporting Services, AD FS and Web Application Proxy bindings, and pre-fills the matching template (read-only, no administrator prompt). The account that reads the private key is not detected; enter it yourself. See Server detection and SQL Server, Reporting Services and AD FS.

On a domain controller (Agent 1.16.0+) the list also holds Active Directory LDAPS (domain controller), with the domain controller's name and the certificate it serves now, and the Agent reports it to CertIntel: Create workflow under Detected on this server in the dashboard opens the workflow form with the template, the names and the verification hostname and port filled in. See Domain controllers. With an older Agent, choose Active Directory LDAPS (domain controller) yourself.

Related pages¶

• Workflow studio & usage
• Modular workflows
• Certificate stores & files
• Dashboard-assigned workflows
• Windows Agent