Implementing a service certificate replacement

This article explains how to execute a service certificate replacement for Content Manager's web service application ISHWS.

Acknowledgements

Content Manager is installed on ish.example.com, and ISHWS is installed on ish.example.com/ISHWS. This deployment is integrated with a third party security token service installed on sts.example.com.

Let’s assume that the deployment was implemented on the 1st January 2016 and the service certificate thumbprint was 20160101.Thumbprint.

The service certificate expires in one year, on the 1st January 2017.

On the 1st December 2016, the owner of the certificate receives an expiration reminder and creates a new certificate.

When the service certificate expires, there is no true rollover and a downtime period is expected. The reasons are:

  • The manner that the service certificate is used to identify the ISHWS soap endpoints.
  • On the security token service, the encryption certificate on the ISHWS relying parties must also be replaced.
  • Once a change is made, all established client sessions will become invalid.

Certificate rollover execution

A new service certificate becomes available

On the 1st December 2016, a new certificate becomes available on the store with the 20161201.Thumbprint thumbprint, but it is not used because it is not being referenced.

Day of scheduled replacement

On the 15th December 2016 the following sequence is executed:

  1. All users sign out.
  2. The current service certificate with 20160101.Thumbprint is replaced by the newer 20161201.Thumbprint. The cmdlet for this step is Set-ISHAPIWCFServiceCertificate.
  3. Users sign in.

The following script replaces the existing certificate with the new one:

#Service certificate thumbprint
$serviceCertificateThumbprint="20161201.Thumbprint"

# Set service certificate
Set-ISHAPIWCFServiceCertificate -ISHDeployment $deploymentName -Thumbprint $serviceCertificateThumbprint

The integration with any security token service is discussed in Integrating with Security Token Service. Use Save-ISHIntegrationSTSConfigurationPackage to extract all necessary information from the deployment.

The integration with ADFS is discussed in Integrating with ADFS. Use Save-ISHIntegrationSTSConfigurationPackage to extract all necessary information and a PowerShell script from the deployment. The script will update all relying party entries when executed against the integrated ADFS.

Remove the old certificate

The certificate with 20161201.Thumbprint is removed from the store. This step has not impact because that certificate is not referenced.