Upgrade the Privilege Cloud Connector v12.6 and earlier

This topic describes the Privilege Cloud Connector upgrade for versions 12.6 and earlier.

 

Upgrading the CPM and PSM components requires downtime (typically a few minutes). We recommend performing the upgrade at a time that will have the least impact on your operations.

Perform the following steps:

Step 1: Before you begin

Before you begin the upgrade, perform the following steps:

  1. Check .NET Framework 4.8 is installed on the Connector.

    For any Connector versions previous to 12.1 you will need to install .NET Framework 4.8.

  2. Prepare user credentials.

    • Privilege Cloud admin credentials

    • Local Admin user, with full Admin rights. For In-domain deployments, this must be a domain user.

  3. Prepare the Privilege CloudConnector machine:

    #

    Step

    Action
    a Take a snapshot of the Connector machine before upgrading. Stop the server, take a snapshot, reboot the server and log in again.
    b Generate a Group Policy report of the Connector server.

    In the CMD line or PowerShell, run

    Gpresult /h C:\PolicyBeforeUpgrade.html

    c

    Check the current CPM and PSM versions

    Right-click Start menu > Application and Features

    Note the PSM and CPM versions

    d

    Check the CPM mode

    Check Services.msc > CyberArk Password Manager

    If the service is running, this is the primary CPM.

    If the service is not running, this is the DR CPM.
    e Download the latest Privilege Cloud software package

    From the CyberArk marketplace software area download:

    • Privileged Session Manager-Rls-[latest release].zip

    • Central Policy Manager-RI[latest release].zip

    • Privilege Cloud Connector Unified Hardening GPO-v2.2.0.zip

    • Privilege Cloud Connector Unified Hardening GPO-v2.2.0.txt
    f Check the zip files are not blocked

    Check Properties > General, Security field.

    Or, in the folder storing the CyberArk files, run the PowerShell command:

      
    dir -r | Unblock-File

    g

    Extract the CPM and PSM zip packages

    Save the extracted files in the installation root drive, in a folder path that adheres to Windows 8.3 formatting. For example: C:\Temp\Cyberark[latest release]

    Do not run the upgrade from your user desktop due to Microsoft maximum file path length limitations.

    h

    Copy the GPO Hardening package to the domain server and extract the zip package.

    For both CPM and PSM:

    Copy the Unified GPO hardening zip package downloaded in #e above and extract it.

    Only PSM:

    Extract Privileged Session Manager zip file downloaded in #e above, copy over the CyberArk Hardening - In Domain - PSM.zip file and extract it.

  4. Disable the antivirus agent if it is installed on your server.

  5. Before upgrading PSM perform the following steps:

    #

    Step

    Action

    a

    Back up these files:

    • PSM\Hardening\PSMHardening.ps1

    • PSM\Hardening\PSMConfigureAppLocker.xml

    • PSM\basic_psm.ini

    • All logs from PSM\Logs folder in previous step

    b

    For domain users PSMConnect/PSMAdminConnect:

    • Check that the local PSMConnect and PSMAdminConnect users are in the Built-in\Users group on the Connector:

      From MMC or lusrmgr.msc > Users and Groups > either view PSMConnect/PSMAdminConnect users and add to Built-in\Users group, or view Built-in\Users group and add PSMConnect/PSMAdminConnect users.

    • Apply secrets management to the PSMConnect and PSMAdminConnect users and ensure they are managed by CPM.

      CyberArk strongly recommends this step.
    c Check the PSMConfigureAppLocker.xml file, which contains tailored rules for your organization's executable files.

    • If you have an edited PSMConfigureAppLocker.xml file that contains tailored rules for your executable files, retain your current file.

    • Validate all custom changes in the customized PSMConfigureAppLocker.xml file before running the hardening script.

    During the upgrade, the AppLocker file automatically merges all custom changes you’ve applied to the configuration of your AppLocker from previous versions.

    • If you have any executable files that have been added to your environment and you want to define them in the file, do it now.

    d

    Optional:

    If PSM Health Check is installed and is a version older than v1.2, update the PSM Health Check version to the latest version.

    See Upgrade PSM Health Check.

  6. For systems with PSM high availability, ensure minimal downtime by temporarily diverting traffic from the upgrading PSM.

    When diverting a platform that is defined for a specific PSM to a different PSM, any targets that are defined to connect with the specific PSM will not be accessible.

    1. In the Privilege Cloud Portal, access each Windows platform and redirect it to an alternate non-upgrading PSM ID:

      Go to Administration > Platform management and in each platform select Manage PSM connector.

    2. Select the pencil icon at the top of the window and from the list of PSMs, select a non-upgrading PSM. This directs the platform to that PSM.

    3. Upgrade the PSM which currently should not have any mapped platforms.

    4. Repeat steps a-b and now remap the platforms to the newly upgraded PSM.

    5. Repeat this process for all other PSM servers that require upgrading.

    6. Revert to your original PSM policies.

  7. Stop the following services:

    • PSM: Cyber-Ark Privileged Session Manager

    • CPM: CybeArk Password Manager

    • Scanner: CyberArk Central Policy Manager Scanner

Step 2: Upgrade the CPM component

The CPM upgrade process upgrades both the CPM and the Scanner.

The procedure for upgrading an active CPM and a passive CPM (DR mode) is slightly different. Make sure to follow the instructions accordingly.

In systems with multiple CPMs, upgrade each of the CPMs in your system.

To upgrade the CPM component:

  1. Open the CPM installation package you created in Prepare the Privilege CloudConnector machine:.

     

    Make sure the location of the upgrade files on the Connector machine does not contain any spaces in the full path and folder name.

  2. In the CPM\InstallationAutomation\Installation folder, right-click > Edit the InstallationConfig.xml file.

  3. In the InstallationConfig.xml file, specify the following parameters, and make sure that you set the isUpgrade parameter to True. After editing, save the file.

    Parameter

    Description

    Username

    The name of the user running the installation.

    Valid values: Username

    Default value: Windows user

    Company

    The name of the company running the installation.

     

    Use only alpha-numeric characters and spaces. Do not include special characters in the company name.

    Valid values: Company name

    Default value: My Company

    CPMInstallDirectory

    The path where CPM is installed.

    Valid values: Pathname

    Default value: C:\Program Files (x86)\CyberArk\

    isUpgrade

    Indicates if this is a CPM upgrade or a new CPM installation.

    Valid values: True/False

    Default value: False

    Make sure you set this parameter to True.

  4. In a PowerShell window, go to CPM\InstallationAutomation\Installation and run the CPMInstallation.ps1 script as Administrator.

  5. Continue the upgrade steps according to type of CPM:

    Consider your next steps according to your CPM component mode, if active or passive. See Upgrade the Privilege Cloud Connector v12.6 and earlier.

    For active CPM:

    1. In the CPM\InstallationAutomation\Registration folder, right-click > Edit the CPMRegisterComponentConfig.xml file.

    2. In the CPMRegisterComponentConfig.xml file, specify the following parameters, and make sure that you set the isUpgrade parameter to True..

      After editing, save the file.

      Parameter

      Description

      Set/Enter

      accepteula

      Acceptance of the end user License agreement.

      Valid values: Yes/No

      Yes

      vaultIP

      The FQDN or specific IP of the Vault server, provided to you by CyberArk support.

      Can be found in the following file:

      C:\Program Files (x86)\CyberArk\Password Manager\Vault\Vault.ini

      Valid values: FQDN or IP address.

      FQDN: vault-<subdomain>.privilegecloud.cyberark.com

      vaultuser

      The name of the Privilege Cloud admin user performing the installation.

      Valid values: Username

      <subdomain>_admin

      username

      The CPM user name that you defined during the installation process.

      Can be found in the following file:

      C:\Program Files (x86)\CyberArk\Password Manager\Vault\user.ini

      Default value: PasswordManager

      Note: If you have multiple CPMs, each CPM will have a different app user name. For example, PasswordManager, PasswordManager1, PasswordManager2, and so on.

      Make sure to use the user name that is relevant to the specific CPM.

       

      isUpgrade

      Indicates whether the registration is for a clean installation or an upgrade.

      Valid values: True\False

      Default value: False

      True

    3. Go to CPM\InstallationAutomation\Registration and In a PowerShell window run the CPMRegisterComponent.ps1 script as Administrator. When prompted, enter the Privilege Cloud admin password:

        
      CD “<installation package Path>InstallationAutomation\Registration” .\CPMRegisterComponent.ps1

    4. In the CPM/InstallationAutomation folder, right-click > Edit the CPM_Hardening_Config.xml file, set the following parameters, and save the file:

      • In parameter PasswordManagerServicesLocalUser, set Enable=Yes

      • For three (3) instances of the parameter IsPSMInstalled, set the parameter to True

      Note the parameter settings are case-sensitive and should be entered with care.

    5. In a PowerShell window, run the CPM_Hardening.ps1 script as Administrator.

    For passive CPM:

    1. In a DR CPM, the PluginManagerUser must be added manually according to the user permissions described in Creates Local Windows Service users and configures permissions, in the topic on CPM hardening description.

      After the PluginManagerUser is added, continue to next step of hardening the CPM.

    2. In the CPM/InstallationAutomation folder, right-click > Edit the CPM_Hardening_Config.xml file, set the following parameters, and save the file:

      • In parameter PasswordManagerServicesLocalUser, set Enable=Yes

      • For three (3) instances of the parameter IsPSMInstalled, set the parameter to True

      Note the parameter settings are case-sensitive and should be entered with care.

    3. In CPM\InstallationAutomation\ open a PowerShell window and run the CPM_Hardening.ps1 script as Administrator.

      In case of an error about starting the CPM services, ignore and continue.

Step 3: Upgrade the PSM

Upgrade the PSM component using the installation wizard.

Before you upgrade the PSM component:

  • Make sure you have performed the preparatory steps described in Before you begin, in this topic.

  • Note that as part of the upgrade, legacy PSM logs are grouped in a zip file and copied to internal archive folders for future access if necessary.

To upgrade the PSM component:

  1. Open the PSM installation package you created in Prepare the Privilege CloudConnector machine:.

  2. Right-click Setup.exe, and then select Run as Administrator.

  3. The installation wizard appears. Click Next and follow these steps within the wizard:

    Tab/event

    Step
    Microsoft Visual C++ 2013 Redistributable Package (x64) error Ignore and click Yes to Continue

    If Connector machine is domain-joined, and you logged on with a local user, the following message appears:

    • Click Yes if you are not using the RemoteApp user experience capability.

    • Click No to stop the upgrade, log on with a domain user who is a local administrator, and start the upgrade again.

    Password Vault Web Access Environment page

    Retain the default settings and click Next .

    Vault's Connection Details page

    Retain the default settings and click Next .
    Vault's Username and Password details page

    Enter the same Privilege Cloud admin credentials used for the Connector installation (<subdomain>_admin) and click Next.

    API Gateway connection details page

    Optionally, to apply the PSM automatically unlock accounts capability, enter the Privilege Cloud portal hostname in the Host field:

    <subdomain>.privilegecloud.cyberark.com

    Otherwise, click Next .

    PKI Authentication configuration page

    Optionally, to benefit from the Smart Card authentication for RDP connection capability, select Enable PKI authentication for PSM.

    Otherwise, click Next .

    If message appears, click Yes

  4. In the Hardening page, click Advanced and enter the following selections, depending on in-domain or out-of-domain hardening solution:

    Option

    Setting

    Post-installation list

    Clear all the checkboxes

    Hardening list:

    • Run the Hardening Script

    • Post hardening tasks

    • Set up AppLocker Rules

    Retain the check marks

    Hardening list:

    • TLS hardening

    		Ensure the checkbox is selected

    Retain the checkbox setting that is automatically assigned by the installer.

    Click Next .

  5. On the Update Complete page, click Finish.

     

    You can restart the Connector machine at a later stage. In any case, you must restart the Connector machine before you can use it.

  6. For In Domain Connector machines, update the GPO hardening package as described in the following step.

Step 4: Update the GPO hardening

To update the GPO hardening, you can deploy the updated GPO hardening package, or, manually set the GPO settings.

Deploy the updated GPO hardening package

  1. Download the version's Privilege Cloud Unified Hardening GPO file as described in Prepare your machinePrepare the Privilege CloudConnector machine:.

  2. Import the GPO file to your Active Directory domain.

    1. Open the Group Policy Management Console (GPMC.msc).

    2. Create a new GPO:   

      1. Expand Group Policy Management> <yourDomain>, then right-click Group Policy Objects and select New. The New GPO window appears.

      2. In the Name field, specify a name for the Unified GPO indicating the purpose and current version (for example, Unified Hardening vN.N), and click OK.

    3. In the list of Group Policy Objects, right-click the new Hardening GPO and select Import Settings.

    4. In the Welcome to the Import Settings Wizard window, click Next, and define the following:

      Tab/field

      Action

      Backup GPO window

      Click Next.

      Backup location screen

      Click Browse and select the location where you stored the version's unified Hardening GPO settings, for example Privilege Cloud Connector Unified Hardening GPO and click OK.

      The folder path appears in the Backup Location window.

      Click Next.

      Source GPO window

      Click Next.

      Scanning Backup window

      Click Next.

      Completing the Import Settings Wizard window

      Click Finish.

      The Import window appears indicating the progress of the GPO import.
    5. When the GPO import process has completed. Click OK.
    6. After import, select the GPO and in the Settings tab verify the settings have been imported successfully.

  3. Link the GPO file to the dedicated CyberArk OU containing CyberArk servers.

    1. Make sure all Connector servers are located under the dedicated OU, so the GPO will not affect any other server.

    2. Delete the previous GPO links according to the following steps:

      • In the Group Policy Management Console, click the OU to which the current PSM and CPM GPOs are linked.

      • Right-click each of the links and select Delete. Click OK to approve.

      • If upgrading from a version prior to v13.0, click the OU to which the legacy CPM and PSM GPO files are linked and delete each of the links. The legacy CPM and PSM GPO files are no longer relevant from v13.0 onward.

        In case of customizations to the default CyberArk CPM/PSM GPO such as added Active Directory security groups or user objects, note these changes and reapply them to the Group Policy after the upgrade.

    3. In the Group Policy Management Console, right-click the OU, then select Link an Existing GPO.

    4. Select the Unified Hardening GPO and click OK. The Unified Hardening GPO policy appears in the Linked Group Policy Objects tab.

  4. It is time to restart the Connector machine. Restart the machine so it will pull the updated GPO

    -Or-

    run gpupdate /force on the upgraded machines.

  5. Optionally, to support the following functions in Privilege Cloud, customize the GPO settings according to these guidelines:

    To support

    GPO update guidelines

    Direct RDP connections

    Add the following setting to the Group Policy with the appropriate Domain Security Group(s) or Users.

    Select Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies/User Rights Assignment > Access this computer from the network (NT AUTHORITY\NETWORK SERVICE, BUILTIN\Administrators, Domain\RDPUserGroup).

    See Connect using RDP.

    Domain-level PSMConnect/PSMAdminConnect

    See Move PSM application users to the domain level.

    Take care when adding any domain-specific settings to the GPO and configure domain-specific settings according to CyberArk guidelines and documentation.

Manually add CPM and PSM hardening settings

If you want to retain customized GPO settings applied to the Connector machine, add the following hardening settings, that are part of this version. For full details about the Connector's GPO hardening parameters, see Connector GPO parameters.

  1. Open the Group Policy Management Console (GPMC.msc).
  2. Click the OU that stores your legacy CPM and PSM hardening setup.

  3. Apply the following changes, which are the updates made to the GPO settings in this version:

    Go to User Rights Assignment:

    Location: Computer Configuration\Policies\Windows Settings\Security Settings\LocalPolicies\User Rights Assignment

    Apply the following:

Policy

Setting
Adjust memory quotas for a process

NT AUTHORITY\LOCAL SERVICE, NT AUTHORITY\NETWORK SERVICE, BUILTIN\Administrators, PasswordManagerUser
Allow log on locally

BUILTIN\Administrators, PSMShadowUsers, PluginManagerUser
Log on as a service

NT AUTHORITY/LOCAL SERVICE, NT AUTHORITY/NETWORK SERVICE, PasswordManagerUser, ScannerUser
Replace a process level token

NT AUTHORITY\NETWORK SERVICE, NT AUTHORITY\LOCAL SERVICE, PasswordManagerUser

Step 5: Verify the Connector upgrade is completed successfully

  1. Review installation logs.

    Review the installation logs to make sure that there are no errors in the upgrade process.

    You can find the logs in the following locations:

    Component

    Location

    CPM

    		%USERPROFILE%\AppData\Local\Temp\CPMInstall.log

    PSM

    v13.1 and later: <Windows installation directory>\Temp\PSM\PSMInstall.log

    v13.0 and earlier: <Windows installation directory>\Temp\PSMInstall.log

  2. Verify all services are running on the Connector:

    • CPM

    • Scanner (a CPM service)

    • PSM

  3. Test PSM connectors.

    Test a few sample components, for example, Standard Windows server, Web App connection, or SSH connection.

    In the event that any of the PSM connectors are not functioning properly, ensure the relevant executables are included in the PSMConfigureApplocker.xml file. See details in Check Privilege Cloud Connector functionality.

  4. Test CPM

    On the CPM that you updated, test the password verify/change/reconcile for a managed account.

  5. Enable the existing antivirus agent, or install an industry standard antivirus software.