Dynamics CRM / Dynamics 365 CE (IFD)

Setup

Recommended: a wildcard certificate validated by DNS

CRM with IFD is reached on several names in the same domain: one per organisation (contoso.crm.example.com), auth. for sign-in, dev. for discovery, and the internal address for claims-based sign-in (for example internal.crm.example.com). A new organisation adds a name. A wildcard certificate, *.crm.example.com, covers all of them, now and later. A wildcard can only be validated by DNS (DNS-01), so set the domain up for FairSSL AutoDNS or pre-validate it before you start.

Step 1: Download and Install simple-acme client

Download the FairSSL edition of simple-acme and extract it to C:\simple-acme on the CRM server (the server running the CRM website). It is pre-configured with the correct ACME server and renewal settings, so there is nothing to edit.

The FairSSL edition also includes a small notification script that reports each renewal and installation result (domain, certificate thumbprint, machine name, success or error details) back to FairSSL, so you can monitor your certificates and receive alerts in the control panel. It never sends private keys or certificates. See fairssl-readme.txt in the download for the full field list and how to disable it.

Step 2: Prepare your environment

• Request the wildcard for the domain your CRM addresses use, for example *.crm.example.com. It must cover every host name in the CRM website's https bindings and the internal address; add a name with a comma in the host list if one lies outside the wildcard.
• Sign in to the CRM server as a CRM Deployment Administrator (for example the account that installed CRM) and open an elevated PowerShell window in C:\simple-acme. The first run usually changes the certificate's subject, and only a Deployment Administrator can tell CRM the new one (ClaimsSettings). Renewals keep the subject and run unattended as SYSTEM.
• Plan downtime: the script restarts IIS (iisreset), on the first run and at every renewal. Renewals run at night by default.

Step 3: Install the certificate in CRM

Run the following command in PowerShell as Administrator. It requests the certificate with an RSA key, stores it in the Windows certificate store, and ImportDynamicsCRM.v1.ps1 then: gives the CRMAppPool account read access to the private key, sets the claims encryption certificate when the subject changes, moves every https binding of the CRM website to the certificate, archives the previous certificate with the same subject (CRM cannot find the certificate with duplicate subjects), runs iisreset, and waits until CRM publishes the new certificate in its federation metadata. When AD FS runs on the same server it refreshes the CRM relying party trusts too.

.\wacs.exe `
  --verbose `
  --baseuri "https://fairssl.dk/acme" `
  --eab-key-identifier YOUR_EAB_KID `
  --eab-key YOUR_EAB_HMAC `
  --accepttos `
  --source manual `
  --host "*.crm.example.com" `
  --csr rsa `
  --certificatestore My `
  --validation none `
  --installation script `
  --script ".\Scripts\ImportDynamicsCRM.v1.ps1" `
  --scriptparameters "'{CertThumbprint}'" `
  --friendlyname "fairssl-acme-*.crm.example.com"

Step 4: AD FS on another server

AD FS encrypts every sign-in to CRM's certificate, so until AD FS has read the new one from CRM's federation metadata, internal and external sign-ins fail. On its own server AD FS does that at its next metadata check, which is every 24 hours by default. Run this once on the AD FS server to check every 15 minutes instead (the CRM relying party trusts must have monitoring and automatic update on, which is the default when they were created from CRM's metadata address):

Set-AdfsProperties -MonitoringInterval 15

Refresh AD FS at once

On the AD FS server, this refreshes every relying party trust that reads federation metadata, the CRM relying party trusts among them, right after a renewal. The script prints the same command with the previous thumbprint in its log when AD FS is not on the CRM server.

Get-AdfsRelyingPartyTrust | Where-Object { $_.MetadataUrl -like '*/FederationMetadata/2007-06/FederationMetadata.xml' } | ForEach-Object { Update-AdfsRelyingPartyTrust -TargetName $_.Name }

AD FS and Web Application Proxy certificates

This script changes only CRM and the CRM relying party trusts. AD FS's own TLS certificate, and a Web Application Proxy in front of IFD, are renewed with the FairSSL guides Microsoft Active Directory Federation Services and Microsoft Web Application Proxy (ImportADFS-WAP.v1.ps1). With AD FS on the CRM server, give AD FS's renewal its own name, for example sts.crm.example.com, not the CRM wildcard: two certificates with the same subject on one server stop CRM's sign-ins.

See the AD FS and Web Application Proxy guidance.

Step 5: Check

Sign in to CRM both on the internal address and on the organisation address from outside. The simple-acme log ends with SUCCESS: Dynamics CRM certificate ... installed.

When a renewal fails

If any step fails, the script puts CRM back on the previous certificate (bindings, ClaimsSettings, archive flags, iisreset), exits with an error and leaves the reason in the simple-acme log. CRM keeps working on the previous certificate. simple-acme 2.4 still records that renewal as done, so it does not try again by itself and its report to FairSSL says success: read the log, fix the cause and run .\wacs.exe --renew --force. A renewal whose subject changed stops with Only a CRM Deployment Administrator can change that: run .\wacs.exe --renew --force once as a Deployment Administrator, as in Step 2.

Private key in a CSP

CRM uses only a certificate whose private key is stored with the legacy CryptoAPI (CSP), which is how simple-acme stores keys by default. A key in a CNG key storage provider is refused before anything changes; then remove "UseNextGenerationCryptoApi": true from settings.json and renew again.