Add a connector

This topic describes how to establish a connection with your environment.

Overview

To establish a secure connection to your environment, you need to run an installation script on a Windows instance that is used for hosting the connector in your company environment. The installation script deploys the CyberArk Management Agent that is then used to manage components. The Management Agent manages installations, transfers secured messages, invokes jobs, and reports telemetry from on-prem.

The connector installation script includes the Management Agent setup files, certificate, and ID file.

The connector installation script contains a secret token for authentication, which expires after five minutes, for security reasons. If the security token expires, you can reload the script, which contains a new security token.

Prerequisites

Check the following prerequisites for your connector machine operating system, drive settings, and user permissions.

Machine specifications

The following machine specifications refer to the host machine running the Connector management agent, and do not refer to the service-specific requirements that apply to specific service connectors.

Component

Specification

Operating system

Microsoft Windows

  • Management agent: Microsoft Windows 2016, 2019, and 2022

  • CPM: Microsoft Windows 2016, 2019, and 2022

  • PSM: Microsoft Windows 2016, 2019*, and 2022*

Note:

Connector machine hardware requirements

Component

Specification

Processor

8 core processor, Intel-compatible

RAM

8 GB

Network adapter

1 GB

Drives

Drive

Min. available space

C:

or other drive which includes
:\Program Files

The Connector Managemnet is installed by default in the C:\Program Files folder.
If your :\Program Files folder is located in any other drive, it can be installed there.

When installing, enter the full path of the alternative installation folder, in English.

The Management Agent is installed in a subfolder in the specified parent folder.

Min. available space: 10GB to support CPM/PSM initial download.

Min available space: 500 MB

User

You must be a local administrator user in the Windows instance that will be used as the connector host.

Set firewall allowlist for network traffic

Set up outbound allowlist firewall rules for approved network FQDNs, ports and hostnames.

Dynamic configuration

It is recommended to use wildcard-based dynamic firewall rules. These will cover all outbound communication interfaces.

FQDNs:

  • https://*.cyberark.cloud

  • https://*-<Region>.s3.amazonaws.com

  • https://*.<Region>.amazonaws.com

  • https://component-registry-store-490081306957.s3.amazonaws.com/

where <Region> refers to the AWS region where the CyberArk service is available.

Static configuration

If you are unable to use dynamic wildcard-based addresses, add the following hostnames to your allowlist.

FQDNs:

  • https://<Subdomain>.connectormanagement.cyberark.cloud

  • https://connector-management-scripts-490081306957-<Region>.s3.amazonaws.com

  • https://connector-management-assets-490081306957-<Region>.s3.amazonaws.com

  • https://a3vvqcp8z371p3-ats.iot.<Region>.amazonaws.com

  • https://component-registry-store-490081306957.s3.amazonaws.com/

where <Region> refers to the AWS region where the CyberArk service is available.

Add a connector

To deploy a new connector, you first generate the installation script and then run it on the connector host machine.

To perform the following steps, your user must be assigned to the System Administrator role in Identity Administration.

  1. Sign in to the CyberArk Identity Security Platform Shared Services using the link provided in the CyberArk email.

  2. Click the service picker, and select Connector Management.

  3. On the Connectors page, click Add a connector.

  4. In the Add connector wizard > Define installation details tab define the following details for the Management Agent in the host machine:

    Installation location

    Define the installation location in the host machine.

    • Default location. This is the default installation location in the host machine. The Management Agent is installed by default in C:\Program Files. If your \Program Files folder is located in any other drive, it is installed there.

      The agent is installed in a subfolder \CyberArk\Management Agent.

      The folder name must be in English.

      In the Installation path field, enter the full path in English, including drive and folder path, for example, D:\Program.

    • Custom location. The Management Agent is installed by default in C:\Program Files. If your \Program Files folder is located in any other drive, it is installed there.

      • Optionally, enter a full path to an alternative installation folder.

      • The agent is installed in a subfolder \CyberArk\Management Agent.

      • The folder name must be in English.

      The Management Agent is installed in the selected location, in subfolder \CyberArk\Management Agent.

    Pool configuration

    In the Advanced settings section, the Connector is assigned by default to the Connector pool. This will enable high availability for components that support this option, are assigned to the pool, and are assigned to the same network targets.

    • For Secrets Hub with Azure: Cancel the default pool assignment.

    • For other services: Retain the pool assignment.

  5. Click Next.

  6. In the Copy installation script tab, review the connector settings you defined:

    Defined agent installation details

    Installation location

    The default /Program Files folder

    or

    A custom installation folder.

    Assigned to pool

    Yes/No

  7. Click Copy script to later copy it to the connector host machine.

    The script is available for 5 minutes.

    Optionally:

    • Click Renew to renew the script availability for an additional 5 minutes

    • Click Preview to view the script format

    Click Close.

  8. On the Windows instance you are using as the connector host, copy the installation script into a PowerShell command window, and run it.

    The installation script is valid for 5 minutes.

  9. In the Connector Management service, click Connectors. The Connector list displays all Connectors in the system and their details. Click a filter to display a shortlist of the required connectors.

    You can filter the Connector list based on the main characteristics

    In the connector list, click the newly added connector. Verify that the Management Agent is installed.

View connector status and details

  1. In the Connector Management service, click Connectors to view all installed connectors in your environment.

  2. Select the row of the required connector. The connector components are displayed together with a status indicator.

  3. Check the Status column to verify successful and active components, and check for failed components.

  4. For more information about the component, click the component row.

Remove a connector

  1. In Connector Management > Connectors list, select the row of the connector you want to remove, and from the additional options menu, click Remove.

    When you remove a connector, the related connector client is disabled and cannot be used.

    The associated components are no longer managed by this connector. If you want to remove the components, make sure you manually delete them from the host machine.

  2. In your Windows server, launch the Services application and stop the CyberArk Management Agent service.

  3. Open a command prompt as admininistrator and run the following command:

    sc delete CyberArkManagementAgent
  4. In File Explorer, access the installation folder where you installed the Connector Management agent (this can be \Program Files\ folder wherever it is located in the host machine or in a dedicated folder you defined) and delete the Management Agent folder.

Reinstall a connector

To reinstall a connector, remove it as described in Remove a connector, and then install it again as described in Run the connector installation script.