Replace a Sitecore client certificate in Azure

Abstract

How to replace a Sitecore client certificate in Azure.

XP service roles require client certificates, known as private certificates in Azure. If a client certificate expires, you must replace the certificate and update all references to that certificate.

Replace the certificate

To replace an expired certificate:

In the Azure Portal, click the TLS/SSL settings option, click the Private Key Certificates tab, and click Upload certificate:
Upload your certificate (a *.pfx file).
Ensure that the uploaded certificate is healthy:
Copy the value of the Thumbprint column.
Navigate to the Configuration tab, change the WEBSITE_LOAD_CERTIFICATES app setting to use the copied thumbprint of the new certificate.
To apply the changes, click Save.

Update the certificate thumbprint

Roles that expose a web service reference the certificate thumbprint. To update the certificate thumbprint:

Replace the value of the validateCertificateThumbprint key in the <wwwroot>\App_Config\AppSettings.config file:
```
<?xml version="1.0" encoding="utf-8"?>
<appSettings>
  <add key="validateCertificateThumbprint" value="31163F08D549CBD401BFFA83D6B7C5074971BACC" />
</appSettings>
```
This step must be performed on the following roles:

Support self-signed certificates

To support self-signed certificates:

Set the AllowInvalidClientCertificate setting to true in the <wwwroot>\App_Config\AppSettings.config file for all XP service roles where this setting exists.
Set the AllowInvalidClientCertificate setting to true in the <wwwroot>\App_Config\AppSettings.config file for all Core roles where this setting exists.

Update connections strings

Roles that connect to a web service such as xConnect Collection include a certificate connection string. That connection string includes a thumbprint, which must match the validateCertificateThumbprint setting of the service. The following example shows the xconnect.collection connection string and the matching xconnect.collection.certificate connection string.

<add name="xconnect.collection" connectionString="https://tut4xconnect.dev.local" /> 
<add name="xconnect.collection.certificate" connectionString="StoreName=My;StoreLocation=LocalMachine;FindType=FindByThumbprint;FindValue=5496B9D84850AFE5A3554B7B2D23F3B5C79CA53A" />

To update connection strings:

Update certificate connection strings for all XP service roles. Refer to individual role pages for a complete list of certificate connection strings.
Note
Your implementation might not include the complete list of certificate connection strings. If this is the case, update the ones that do exist.
- For all web services, connection strings are configured in <wwwroot>\App_Settings\ConnectionStrings.config
- For the Marketing Automation Engine, connection strings are configured in <wwwroot>\App_Data\jobs\continuous\AutomationEngine\App_Config\ConnectionStrings.config. The <wwwroot> is either the Marketing Automation Operations web service (XP Scaled) or the standalone role that combines all XP Services (XP Single).
- For the Processing Engine, connection strings are configured in <wwwroot>\App_Data\jobs\continuous\ProcessingEngine\App_Config\ConnectionStrings.config. The <wwwroot> is either the Processing web service (XP Scaled) or the standalone role that combines all XP Services (XP Single).
Update certificate connection strings for all Core roles. Connection strings are located in <wwwroot>\App_Config\ConnectionStrings.config.

Troubleshooting

You might see the following exception in the logs after updating a certificate, where 83DCC21BBF54D76F71D7B67EA2319273BCDA8E19 is the thumbprint of the old certificate:

Message: The certificate was not found. Store: My, Location: CurrentUser, FindType: FindByThumbprint, FindValue: 83DCC21BBF54D76F71D7B67EA2319273BCDA8E19, InvalidAllowed: True.

To resolve the issue, restart the web applications.