Changing the xDB Certificate on Sitecore 10 XP (Azure PaaS)
Rotating certificates in a distributed enterprise CMS environment like Sitecore XP on Azure PaaS takes quite some steps. Maybe this can be automized, maybe not... I just know we never did as this only happens very often. But when it does, whether you are dealing with an upcoming certificate expiration date or a mandatory security rotation, missing even a single configuration file or setting will cause xDB communication to fail.
In a Sitecore xDB setup, services talk to each other securely over https using certificate thumbprints. If you miss a role, update the wrong configuration file, or forget to update the website_load_certificates environment variable, the App Service won't be able to access the certificate. Communication will fail and errors will occur.
Certificate errors
Roles like Content Management (CM) or Content Delivery (CD) will fail to communicate securely with xDB Collection, Reference Data, or Marketing Automation services. Your visitors might not notice as the website will probably be still running, but visitors' interaction data will fail to be recorded or processed, leading to faulty analytics dashboards and broken visitor profiles.
However, if you check your logs (Application Insights and/or Sitecore log files) you will quickly notice a flood of messages like:
- "X509Certificate" exceptions
- "The certificate with thumbprint [...] could not be found"
- "A call was made on a closed Stream"...
- ...
Checklist
To make life easier for my team and anyone else tackling this task, I’ve put together this checklist for updating the xDB communication certificate on a Sitecore 10 XP Azure PaaS setup. Note that this is a checklist for one of our setups. Other setups might (probably will) need some adjusting - not in the locations as such but mainly on the environments as you can have more servers, slots and so on. The main idea however will stay the same: make sure not to forget any location on any environment.
Prerequisites / Global Setup
First of all, you'll need to install the new certificate into your Azure App Service Certificate store and/or Key Vault.
At the end (once everything is switched, restarted and verified) remove the old certificate. This might seem unnecessary but it isn't. Just make sure everything is tested before you do so.
Role-by-Role Update Checklist
Connectionstrings
- in Azure in the KeyVault - referenced in the App environment variables : in this case you need to update the value in the vault and make sure the app is restarted
- in Azure in the App service environment variables connection strings section : use the bulk edit - in this case the edits will trigger a restart
- a connectionstrings.config file in the app_config : this is the default in the Sitecore setup but normally on apps where you desploy your own code this should not be used
1. Content Management (CM)
- Update the certificate thumbprint in your connection strings. This might trigger an App Service restart - depending on the location.
- Update the `WEBSITE_LOAD_CERTIFICATES` app environment variable with the new thumbprint.
Without this, the App Service won't mount the certificate into the local machine store, resulting in "certificate not found" errors so it's rather crucial. - If the certificate is also used for SSL, bind the certificate to the CM App Service
- Restart.
2. Content Delivery (CD)
- Update the certificate thumbprint in the connection strings.
- Update the thumbprint on `WEBSITE_LOAD_CERTIFICATES`.
- Assign the SSL certificate for each custom domain that uses this certificate bound to the CD instances (restarts).
- In case you have one or more deployment slots: don't forget to repeat all the steps above for your each slot. Not all might be needed, but check to be sure.
- Restart (all needed slots)
3. Experience Analytics / Collection (XC-collect)
- Update validateCertificateThumbprint in AppSettings.config in the App_Config folder
- Restart
4. Experience Analytics / Reference Data (XC-RefData)
- Update validateCertificateThumbprint in AppSettings.config.
- Restart
5. Marketing Automation Operations (MA-Ops)
- Update validateCertificateThumbprint in AppSettings.config.
- Update the certificates in ConnectionStrings.config.
- Update the thumbprint on WEBSITE_LOAD_CERTIFICATES in the environment variables.
- Update the certificates in the connectionstrings.config of the automation job in App_Data\jobs\continuous\AutomationEngine\App_Config
- Restart
6. Marketing Automation Reporting (MA-Rep)
- Update validateCertificateThumbprint in AppSettings.config.
- Update the thumbprint on WEBSITE_LOAD_CERTIFICATES.
- Restart
7. Processing (PRC)
- Update the thumbprint on WEBSITE_LOAD_CERTIFICATES.
- Update the thumbprint in the connection strings.
- Restart
8. Experience Analytics Search (XC-Search)
- Update validateCertificateThumbprint in AppSettings.config.
- Restart
9. Sitecore Identity Server (IS)
- Update the thumbprint in wwwroot\Config\production\Sitecore.IdentityServer.Host.xml.
- Update the thumbprint on WEBSITE_LOAD_CERTIFICATES.
- Restart
10. Cortex Reporting (Cortex-Rep)
- Update the thumbprint on WEBSITE_LOAD_CERTIFICATES.
- Update validateCertificateThumbprint in AppSettings.config
- Update the certificates in the connectionstrings.config for the processing job in App_Data\jobs\continuous\ProcessingEngine\App_Config.
- Restart
Infrastructure / Code Base Updates (ARM / Bicep / Terraform)
Whatever you are using for deployment, your templates or variable files might include the thumbprint. To make sure your next automated deployment does not overwrite your fixes, update your infrastructure-as-code files.
- Update the thumbprints in your setup templates (`environmentsettings.json`).
- Replace the physical certificate file/reference in your repository if stored or referenced directly.
Post-Update Verification Checklist
Once all roles have been updated and restarted, check the logs (Application Insights probably) and make sure you do not have any certificate exceptions.
You can also verify the Experience Analytics dashboard in Sitecore to ensure graphs are populating correctly.
Keep an eye on the logs for the next 24h just to be sure...
And then convince your customer to move to SitecoreAI so you do not have to do this again. I know tis is easier said than done - the fact that I am writing blogs on Sitecore XP is the best proof :)


