Using External Credential Services

Download this manual as a PDF file

This section provides instructions on how to use external credential services in SL1.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all of the menu options, click the Advanced menu icon ().

CyberArk

CyberArk is not provided with SL1. You must purchase and manage the CyberArk Vault independently.

SL1 can source credential data from external CyberArk vaults using a credential gateway service. This service allows you to download the CyberArk Credential Provider—sometimes referred to as the CyberArk Credential Agent—from your instance of CyberArk and install the agent on SL1 Data Collectors. This agent syncs with credentials on the CyberArk vault server and uses those credentials to collect data from SL1-monitored devices when necessary. When an SL1 system has been set up with the CyberArk Agent and the credential gateway service, you can enter vault tags in any secret/encrypted credential field in SL1 instead of entering the password or secret value itself.

CyberArk credentials are stored in the memory of the CyberArk Agent, not in SL1 Data Collectors.

The CyberArk credential gateway service integration is incompatible with SL1's Concurrent PowerShell feature. If you are using the CyberArk credential integration, you must have Concurrent PowerShell disabled. To disable Concurrent PowerShell, go to the Behavior Settings page (System > Settings > Behavior), ensure that the Enable Concurrent PowerShell Collection checkbox is not selected, and click Save.

Installing the CyberArk Credential Agent on Every Collector

Install the CyberArk Credential Provider (Agent) by following the instructions outlined in CyberArk’s knowledge base article: Install the Credential Provider.

The CyberArk Agent must be installed on your SL1 Data Collectors. These appliances retrieve credential data from the CyberArk vaults.

Reinstalling the CyberArk Credential Agent on a Rebuilt Data Collector

In cases where you need to rebuild your Data Collector, you will first need to remove the previous Data Collector from the CyberArk Credential Agent. After rebuilding the Data Collector, you will then need to reinstall the agent on that rebuilt appliance.

To reinstall the agent, follow the steps outlined in CyberArk's knowledge base article: Install the Credential Provider.

Defining a Custom CyberArk Delimiter

You can define a custom CyberArk delimiter when sourcing credential data from external CyberArk vaults. If you want to use a custom CyberArk delimiter, you must do so before starting the Credential Gateway Service:

  1. Use the SSH protocol to connect to the Data Collector.

  2. Enter the following commands

  3. sudo vi /opt/em7/lib/python3/sl_credential_gateway/sl_credential_gateway.sh

  1. Uncomment the line #export CYBERARK_DELIMITER='!' and change the ""!"" character to a different delimiter character.

  2. Save and exit the sl_credential_gateway.sh file.

Starting the Credential Gateway Service on Every Data Collector

The Credential Gateway Service is the method SL1 uses to interact with the CyberArk Credential Provider (Agent). You must complete the following steps for every Data Collector you are utilizing:

  1. Use the SSH protocol to connect to the Data Collector.
  2. Enter the following commands:

    3. cd /opt/em7/lib/python3/sl_credential_gateway

    sudo bash sl_credential_gateway.sh

  3. A message appears indicating that the "Credential Gateway Service environment has been created and the service is running."

    4. If you already have a running Credential Gateway Service and then rerun this script, the service will stop and start a new one. Future development includes integrating this service into systemd instead of using this script so all systemd service functionality is supported.

Troubleshooting Credential Gateway Service Issues

If you are encountering errors while running the sl_credential_gateway.sh script, perform the following actions:

  • Check that the directory /opt/em7/lib/python3/sl_credential_gateway/venv/ exists. If it does, try to activate it with the command source /opt/em7/lib/python3/sl_credential_gateway/venv/bin/activate and see if it gives you any errors. You can also delete the venv directory and re-run sl_credential_gateway.sh.

  • Check whether the gunicorn process runs with the command pgrep -x "gunicorn". You should see two process IDs. If you see anything other than two IDs, kill them with the command ps -ef | grep gunicorn | grep -v grep | awk '{print $2}' | xargs kill and then re-run sl_credential_gateway.sh.

    • If gunicorn is not running, check to see if /var/run/em7/cgs.sock exists. If it does, delete it and re-run sl_credential_gateway.

  • Check /var/log/sl1/cgs-error.log for additional error information and search for troubleshooting guidance.

Setting Up Vault Tags in Your Credential

When an SL1 system has been set up with the CyberArk Credential Provider (Agent) and the SL1 Credential Gateway service, you can enter vault tags in any secret/encrypted credential field instead of entering the password/secret itself. Any time you use the credential in discovery or collections, SL1 will detect the vault tag, use the provided query string to retrieve a secret from the CyberArk credential provider, and then use it in this field.

You can set up vault tags only in the classic SL1 user interface.

  1. Go to the Credential Management page (System > Manage > Credentials).
  2. Click the Actionsbutton and then select the type of credential you want to create. The Credential Editor modal appears.
  3. If there's a secret/encrypted credential field, enter the appropriate vault tag instead of entering the password/secret itself.

    4. The vault tag entered should be in the following format: <vault id>:<appid>;<safe>;<object>

    For example, a query string for an SNMP Credential might appear as the following: vault:123:appid=testappid;safe=Test;object=snmp_v2.

For CyberArk, the query string contains the following parameters:

  • appid. The ID of the application registered in the CyberArk vault for SL1.
  • safe. The ID of the safe in which the object resides.
  • object. The ID of the object that holds the secret/encrypted data.

These parameters must be lowercase in the vault tag.

The vault ID value indicates which CyberArk vault SL1 should check first for the credential information. For SL1 12.1.0, any numeric value can be entered for the vault ID.

Example: Vault Tags

In this example, any time the EM7 Default V2 Tag credential is used in the Profile Name field, SL1 will retrieve the secret from the object snmp_v2 contained in the Test safe as application testappid, from the CyberArk credential provider. Then, this secret will be used for the SNMP Community (Read-Only) field value.