Updating or Replacing a Web Server Certificate

This section explains how to update and replace the web server certificate after it has expired. Before you continue, make sure that you have the new certificate.

Only an experienced HSPAS Admin should perform these steps. For more information about HSPAS, see Introduction to Hyper-scalable Privileged Access Service.

Back Up Before Installing

Before upgrading the certificate, follow the steps below to back up your data (as a precautionary measure): 

  1. Back up the HSPAS database.

  2. Store a copy of the currently deployed certificate on the Management Node.

    1. C:\Centrify\installations\<installation name>\Config

    2. Make sure the copy is stored where it can be retrieved and not overwritten during an upgrade.

  3. Perform a full backup of each node listed below: 
    • Web
    • Background
    • Relay
    • Logging
    • Management

      There may be multiple of each of the above nodes that may need to be backed up.

  4. If a full backup of each node is not possible, copies of the following data on each node is recommended: 

    1. Use Regedit.exe to backup the registry folder on each node: HKLM:\Software\Centrify.

    2. Backup the following folders on each node: 

      1. C:\Centrify

      2. C:\CentrifyNode

        Backing up these folders will also include copies of old deployment packages. The config.json files and current certificate in use should be part of the management node backup.

  5. Copy and save the following value for later use: 
    • Current HSPAS host name: Go to C:\Centrify\installations\<Current HSPAS Host Name>.

Installing the New Certificate

The following steps cover how to install a new web server certificate after the previous certificate has expired.

To see the prerequisites for certificates see Certificates for Privileged Access Service Authentication.

Verifying Your Certificate

First you need to make sure that your certificate is going to work. You can do that by making sure the filename extension is correct and the subject matches your hostname. Then you will need to save the private key somewhere safe. The steps below show how to verify that your certificate is correct.

  1. Capture both the file name and the file extension of the certificate: 

    • The extension can either be .pfx or .p12.

  2. Open the certificate and look for Subject under Details.

    • Verify that the current HSPAS host name matches the Subject name. The new certificate will not work if they do not match.

  3. Save the password associated with the certificate for future use.

Upgrading the Certificate

The following steps will walk you through how to upgrade the web server certificate.

Run this only during a maintenance window or downtime.

  1. Ensure that the PostgreSQL and Redis servers are turned on.

  2. Log in to the management node as an admin.

  3. Copy <New Certificate>.pfx to the C:\ folder on the management node.

  4. Open an elevated PowerShell Session by clicking Start Menu > Windows PowerShell > Run as Administrator.

  5. In PowerShell, change the current directory to C:\Centrify

  6. Validate that the file 'Centrify-Pas-ModifyInstallation.ps1' exists in the directory.

  7. Run the following PowerShell command: 

    .\Centrify-Pas-ModifyInstallation.ps1 -HostName <Current Host Name> -Certificate <New Certificate path and filename> -CertificatePassword <Certificate password>

    For example:

     Centrify-Pas-ModifyInstallation.ps1 -HostName XYZ.location.current -Certificate C:\NewCertificate.pfx -CertificatePassword 'newPassword'

    After the command runs successfully, the following message appears:
    Operations Completed: Host certificate <old Certificate> replaced with certificate <new certificate>..

    The above message signifies that the Centrify-Pas-ModifyInstallation.ps1 command succeeded and the installation is now ready to use the new certificate.

    • When providing the certificate password, place single quotes on either side of it.
      For example:
      'Password'
      Otherwise, the password may fail if it contains special characters.

    • You must run all commands from a single PowerShell window.

    • The host name must match the subject name in the certificate. The command above updates the installation configuration with the appropriate certificate information.

    • You may receive a warning when running the PowerShell command, and here's an example of that warning:
      You've chosen to modify the hostname of the installation for 'pas.my.hspas-dev.net' to the new name of 'change.my.hspas-dev.net' This will mark your current installation under 'pas.my.hspas-dev.net' as deprecated and create a new installation under the name 'change.my.hspas-dev.net' The host certificate and install configuration of your old installation will be copied over to the new installation Finally, this change will update configurations in persistent storage and the FQDN of your installation to the new hostname If you want to proceed with this change, please type 'proceed'.

      After this warning message displays, just enter 'proceed' and hit the Enter key.

  8. Verify that the new certificate file now exists in the following location:

    9. C:\Centrify\Installations\<Host Name>\config

  9. In the same PowerShell window, run the following command to create a new deployment package with the new certificate:

    .\Centrify-Pas-NewDeployment.ps1 -HostName <HostName> -ID <Deployment File Name>.

  10. Confirm that the new deployment folder and package exists under the following folder. A deployment package is a zip file:

     C:\Centrify\Installations\<Host Name>\Deployments\YYYY-MM-DD ID <Deployment File Name>.

    Here's an example of the deployment folder's name: 2023-02-28 ID 2023CertUpdateDelinea.

Updating Nodes

The following steps cover how to update different kinds of nodes for your web server certificate.

For each web node you are updating, complete the following steps: 

  1. Open an RDP connection to the node.

  2. Copy and paste the <Deployment File Name> zip file to the C:\ drive on the node.

    For example: 2023CertUpdateDelinea.zip.

  3. Unzip the deployment file in the C:\ drive.
  4. Right-click the deployment file and select Extract all.
  5. Confirm that the deployment file has been extracted by checking for the new .pfx or .p12 file.
  6. Open an elevated PowerShell command on the node: 
    1. Start Menu > Windows PowerShell > Run as administrator.
    2. Change the folder to the C:\<Deployment File Name> folder.

  7. Run the following script:

    .\Centrify-Pas-Deploy.ps1 -WebNode -RemoveNode.

    This command removes the node specified on that VM and database reference to the node.

  8. Run the following script:

    .\Centrify-Pas-Deploy.ps1 -WebNode.

    This process will take several minutes and it will deploy a web node and will set up everything that is needed for the service, including IIS. The script will register this node and add the reference of this node to the database. If you receive an error message stating Failed to establish a trust relationship, it means that either the certificate is not trusted, or the hostname does not match the certificate subject name. If this happens, stop the upgrade and fix the certificate.

  9. Exit PowerShell.
  10. Verify that the process succeeded by going to the website and ensuring it's reachable.
    • Open a web browser and enter the hostname as the URL. If you can see the admin portal login screen, the web node is working successfully.

Updating Different Types of Nodes

  1. For each background node you are updating, repeat the above steps and replace mentions of 'WebNode' with 'BackgroundNode'.

    • Verify that the background node is running by pressing the Windows key, selecting Services, and confirming the service 'Centrify Vanguard Background Role' is listed there and running.
  2. For each relay node you are updating, repeat the above steps and replace mentions of 'WebNode' with 'RelayNode'.
    • Verify that the relay node is running by pressing the Windows key, selecting Services, and confirming the service 'Centrify TCP Relay Service' is listed there and running.
  3. For each logging node you are updating, repeat the above steps and replace mentions of 'WebNode' with 'LoggingNode'.
    • Verify that the logging node is running by pressing the Windows key, selecting Services, and confirming the service 'Centrify TCP Relay Service' is running.
  4.  After you have updated the above nodes, you must log in to the management node as an administrator and complete the following steps:
    1. Open PowerShell command window by going to Start Menu > Windows PowerShell > Run as administrator.
    2. Change the current working directory to C:\Centrify.

    3. Run the following:

      .\Centrify-Pas-SetActiveDeployment.ps1 -HostName <Host Name> -ID <Deployment File Name>

      This decommissions the nodes running the old deployment and sets the new deployment to active. New nodes will not respond until their deployment is set as active.

    4. Run the following:

      C:/Centrify/Centrify-Pas-NodeList.ps1

      The above command will list all nodes in the system as well as what deployment they're a part of and if they are active or not.

  5. Exit PowerShell.

Verifying the Certificate Works

The following steps will show how to verify your new web server certificate is working properly.

  1. Log in to the Admin Portal as an administrator.
  2. Enter the hostname in the browser.
    • For example: if cps-test is your hostname, you would enter https://portal.cps-test.com/ into your browser.
  3. Confirm that the SetActiveDeployment worked. You will not be able to login into a nonactive deployment.
  4. Verify that the certificate is valid.
    1. Click the lock icon on the top left of the browser's address bar.
    2. Select Connection is secure and then select Certificate is valid.
    3. Check that the common name is the same name as the new certificate.
  5. Run a simple job to verify the background nodes, such as changing your password.

    The job will fail if the background nodes are not working properly.

  6. Verify that the connectors can reach and communicate with the system to ensure relays are working properly.

    1. Identify all connectors in use by going to Portal settings: Settings > Network > Centrify > Connectors.
    2. Restart all connectors.