Press "Enter" to skip to content

Replacing the Sitecore client certificate on Azure in 5 steps

These instructions are for a Sitecore 9.0.1. XP1 Topology – on Azure.

For using X-connect there is a need of using client certificates.
In Azure these certificates are named private certificates.
Since these certificates expire there is a need to replace them.

To make life easier I will describe this process in the 5 steps underneath:

Step 1
Upload the new certificate (pfx) to Azure using ARM template or portal.

Step 2
Get the thumbprint of the new certificate using powershell or portal:


 $ResourceGroupName = "resourcegroup"
 Get-AzureRmWebAppCertificate -ResourceGroupName $ResourceGroupName

When there are multiple certificates, check the name for the new certificate and add to the $authCertificateName variable below.


 $authCertificateName - "newuploadedcertificatename"
(Get-AzureRmWebAppCertificate -ResourceGroupName $ResourceGroupName | Where-Object {$_.name -eq "$authCertificateName"}).Thumbprint

The thumbprint for the new certificate will be used in all configurable items described below.

Step 3:
App_Config\AppSettings.config

Change the value for the validateCertificateThumbprint key to the new thumbprint for the following roles:

  • xConnect Collection (xc-collect)
  • Marketing Automation Operations (ma-ops)
  • Marketing Automation Reporting (ma-rep)
  • xConnect Reference Data (xc-refdata)
  • xConnect Search Service (xc-search)

<add key=”validateCertificateThumbprint” value=”VALUEOFNEWTHUMBPRINT” />

Note that for the “Marketing Automation Operations (ma-ops)” role there is a webjob, that can  be found here: “\App_Data\jobs\continuous\AutomationEngine\App_Config” – change your thumbprint in the corresponding connectionstrings.config there as well.

Step 4
App_Config\Connectionstrings.config

Change the thumbprint(s) within the connectionstrings.config for the following roles:

  • Content Delivery

    xconnect.collection.certificate
    xdb.referencedata.client.certificate
    xdb.marketingautomation.operations.client.certificate

  • Content Management

    xconnect.collection.certificate
    xdb.referencedata.client.certificate
    xdb.marketingautomation.reporting.client.certificate
    xdb.marketingautomation.operations.client.certificate

  • Email Experience Manager – Dedicated Delivery Service

    xconnect.collection.certificate
    xdb.referencedata.client.certificate
    xdb.marketingautomation.reporting.client.certificate
    xdb.marketingautomation.operations.client.certificate

  • Marketing Automation Operations

    xconnect.collection.certificate

  • Processing

    xconnect.collection.certificate

Step 5
App Settings Azure App Services

Within the Azure App Service Application Settings you should define the
new thumbprint as well. This needs to be done for the following server role services:

Content Delivery
Content Management
Email Experience Manager – Dedicated Delivery Service
Marketing Automation Operations
Marketing Automation Reporting
Processing

Change the app setting:
WEBSITE_LOAD_CERTIFICATES —–>  VALUEOFNEWTHUMBPRINT


ERRORS and WARNINGS
that you will/might notice while the certificate and/or configuration has not been set correct:

WARN Could not load device ‘xxx-xxx-xxxx-xxxx’ from the device dictionary.
Message: Ensure definition type did not complete successfully. StatusCode: 401, ReasonPhrase: ‘Invalid certificate’, Version: 1.1, Content: System.Net.Http.StreamContent, Headers:

ERROR Cannot process ‘ProcessSubscriptions’ processor because of internal error
Message: Ensure definition type did not complete successfully. StatusCode: 401, ReasonPhrase: ‘Invalid certificate’, Version: 1.1, Content: System.Net.Http.StreamContent, Headers:

ERROR Cannot start analytics Tracker
Ensure definition type did not complete successfully. StatusCode: 401, ReasonPhrase: ‘Invalid certificate’, Version: 1.1, Content: System.Net.Http.StreamContent, Headers:

ERROR Cannot process ‘ProcessSubscriptions’ processor because of internal error
Message: The certificate was not found


5 Comments

  1. Bart Bart

    Hi Bram.

    Nice article!

    I have the issue that you describe at the end “ERROR Cannot process ‘ProcessSubscriptions’ processor because of internal error
    Message: Ensure definition type did not complete successfully. StatusCode: 401, ReasonPhrase: ‘Invalid certificate’, Version: 1.1, Content: System.Net.Http.StreamContent, Headers:”
    But all the other settings check out.

    Do you know maybe more precise where this issue could come from?

    Thanx

    • Not sure Bart, my guess would be a mismatch on thumbprints and/or an invalid certificate.

  2. Also need to update
    We went to the location: {Path-To-XConnect-Website}\App_Data\jobs\continuous\AutomationEngine\App_Config and opened the ConnectionStrings.Config

    • Thanks, I will add that instruction to the role that is serving the webjob. [Marketing Automation Operations (ma-ops)]

  3. Shafiq Shafiq

    Thanks for summing up the tasks to update cert. Just want to share my experience if this helps other anyway. After follwoing above steps we got following exception in our logs in huge number.

    This configuration has not been initialized. Please call the initialize method before using it.
    Sitecore.XConnect.Client.XConnectClientConfiguration.CheckInitialized. Failed to instantiate a processor of type ‘”Sitecore.Xdb.MarketingAutomation.Processing.EventProcessor”‘

    After some googling, found following link that suggested some extra config to update for ma-ops and ma-rep app services. Adding WEBSITE_LOAD_CERTIFICATES with new cert thumbprint in configuration section for those roles even did not stopped exception until we RESTARTed those 2 services.

    https://azure.microsoft.com/en-us/blog/using-certificates-in-azure-websites-applications/

    Hope it helps

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.