Configure DPA to use credentials stored in CyberArk

DPA can use credentials stored in CyberArk for authentication to:

• The DPA repository
• Monitored database instances
• Monitored VMware ESX/ESXi Hosts or vCenter Servers
• LDAP/AD servers
• Mail servers

You can configure DPA to use CyberArk credentials globally, for authentication to all of the entities listed above. Or you can configure DPA to use CyberArk credentials for certain types of authentication. For example, DPA could use CyberArk credentials for authentication to the DPA repository and monitored instances, but not to VMware, LDAP/AD, or mail servers.

DPA uses the REST API to call the CyberArk Central Credential Provider (CCP) and client certificates authentication to authenticate to it, which means that your CyberArk CCP must be configured to use SSL.

Complete the following tasks to configure DPA to use CyberArk to as a credential provider:

Gather the required information

To configure CyberArk integration in DPA, you must have the following information:

• The URL of the CyberArk Central Credential Provider
• The client certificate that will be used to authenticate to the CyberArk CCP
• The CA root certificate of CyberArk CCP server if you are using a private Certification Authority to create trust between DPA and CyberArk CCP

If your client certificate is in PEM format, convert it to PKCS12 format

DPA does not support PEM format. If your client certificate is in PEM format, complete the following steps to convert it to PKCS12 format.

1. Download and install the OpenSSL toolkit. For Windows you can download it from here.

2. Open a command prompt and run the following command, where yourClientCertificate.pem is your client certificate file in PEM format.

   openssl pkcs12 -export -inkey yourClientCertificate.pem -in yourClientCertificate.pem -out CA_keystore.p12

3. When prompted, enter the password protecting the PEM file (if there is one).

4. When prompted, set a password for the new PKCS12 file. This is the password you will use for the keystore.password and key.password properties in the cyberark.properties file.

   OpenSSL uses the same password for both the keystore and the key itself.

A new file called CA_keystore.p12 is created. It stores the converted client certificate in PKCS12 format. Specify this file as the keystore.location property in the cyberark.properties file.

Configure the cyberark.properties file

1. Open the following file in a text editor:

   DPA-install-dir\iwc\tomcat\ignite_config\idc\cyberark.properties

2. Enter the values for the following properties, and save the file.

base.uri

The common part of requests to get credentials from the CyberArk CCP. All requests made by DPA to the CCP consist of this URL concatenated with a suffix specific to the given connection. For example, if your CCP URL is https://cyberark.prod.com and your AppID for DPA is DPA, the base.uri is specified as:

base.uri=https://cyberark.prod.com/AIMWebService/api/Accounts?AppID=DPA

When you register database instances for monitoring (for example), you will use the suffix query that is specific to the monitored instance. This type of query might look like this:

&safe=mondb&object=sqlserverprod1

In this example, DPA would use the following URL to get the credentials for this monitored instance:

https://cyberark.prod.com/AIMWebService/api/Accounts?AppID=DPA&safe=mondb&object=sqlserverprod1

DPA provides flexibility for structuring your CCP requests. You can use any field documented by CyberArk.

request.timeout.millis

The connection timeout of the CCP requests in milliseconds. If this value is not specified, the default value of 30000 (30 seconds) is used. If you are using the ConnectionTimeout property as part of the CCP URL, the lower value of the two properties is used.

disable.hostname.verification

Disables hostname verification. If set to true, DPA does not verify that the CyberArk CCP server certificate matches the CyberArk CCP hostname. DPA recommends the default of false (hostname verification is enabled).

keystore.location

The path to the keystore that holds your client certificate used to authenticate DPA requests to the CyberArk CCP. Be aware that if your location string contains a backslash (\) you must escape it with another backslash, as shown in the following example:

keystore.location= C:\\security\\ca_keystore.p12

keystore.type

The type of keystore. Valid values are jks and pkcs12.

DPA supports the following file types:

• PKCS12: The file usually has a .p12 extension.
• JKS: The file usually has a .jks extension.

If your file is in a different format, take one of the following actions:

• PEM: If your client certificate is in PEM format, convert it to PKCS12 format.
• PXF: A file in PXF format can be used as-is, because the PXF and PKCS12 formats are generally interchangeable. Enter pkcs12 as the keystore.type.

keystore.password

The password to the keystore. After DPA starts, this value is encrypted based on the settings specified in DPA password encryption settings.

key.password

The password to the client certificate in the keystore. After DPA starts, this value is encrypted based on the settings specified in DPA password encryption settings.

Establish trust between DPA, the CyberArk CCP, and the client certificate

Because your CyberArk deployment is using SSL, you must ensure that DPA is configured to trust the CyberArk CCP server certificate. To do this, import the CA certificate of the CyberArk CCP into the DPA trust store.

Enable auto-invalidation of monitored instance connections when credentials have changed

DPA polls credentials from CyberArk every 10 minutes (by default). If new credentials are detected, all connections created after the change will respect the new credentials.

If CyberArk stops providing the credentials (for example, because the account name in CyberArk changed so the query is no longer valid, or CyberArk is down for some reason), DPA will postpone the connection invalidations to help you overcome short CyberArk outages. By default, the delay in connection invalidations is 30 minutes. You can configure this value for every connection type by setting following properties in the system.properties file, with the value in minutes:

• For the repository connection:

  com.solarwinds.dpa.cyberark.checker.repo.periodicClearCredentialsMinutes=30

• For monitored database instance connections:

  com.solarwinds.dpa.cyberark.checker.periodicClearCredentialsMinutes=30

• For monitored VMware ESX/ESXi Host or vCenter Server connections:

  com.solarwinds.dpa.cyberark.checker.vsphere.periodicClearCredentialsMinutes=30

• For an LDAP/AD server connection:

  com.solarwinds.dpa.cyberark.checker.ldap.periodicClearCredentialsMinutes=30

• For a mail server connection:

  com.solarwinds.dpa.cyberark.checker.mail.periodicClearCredentialsMinutes=30

A value of 30 minutes means that DPA will invalidate existing connections if CyberArk is not able to provide credentials for a period longer than 30 minutes.

To reschedule the DPA credentials polling job (which runs every 10 minutes by default), set the following properties in the system.properties file, with the value in milliseconds:

• For the repository connection:

  com.solarwinds.dpa.cyberark.checker.repo.periodicIntervalMillis=600000

• For monitored database instance connections:

  com.solarwinds.dpa.cyberark.checker.periodicIntervalMillis=600000

• For monitored VMware ESX/ESXi Host or vCenter Server connections:

  com.solarwinds.dpa.cyberark.checker.vsphere.periodicIntervalMillis=600000

• For an LDAP/AD server connection:

  com.solarwinds.dpa.cyberark.checker.ldap.periodicIntervalMillis=600000

• For a mail server connection:

  com.solarwinds.dpa.cyberark.checker.mail.periodicIntervalMillis=600000

Enter connection credentials into CyberArk and test them

Add all connection credentials used by DPA into CyberArk. SolarWinds recommends using the DPA REST API to test the connection queries before you enable the integration.

Domain names

If a domain needs to be specified during authentication, DPA uses the value in either the LogonDomain field or the UserName field of the CyberArk object:

• If the UserName field includes a backslash (\), DPA uses the value in that field as the DOMAIN_NAME\Username. (The LogonDomain field is ignored.) For example, if the CyberArk object includes:

  "UserName": "MYDOMAIN\MyUserName",

  DPA uses MYDOMAIN\MyUserName for authentication.

• If the LogonDomain field contains a value and the UserName field does not contain a backslash, DPA prepends the domain name and a backslash to the user name. For example, if the CyberArk object includes:

  "LogonDomain": "MYDOMAIN",
  "UserName": "MyUserName",

  DPA prepends the LogonDomain value to the UserName value, and the value used for authentication is MYDOMAIN\MyUserName.

Enable the DPA CyberArk integration

After you have edited the cyberark.properties file and updated the DPA trust store with the required certificates, complete the following steps to enable CyberArk mode so that DPA will start to use those settings.

1. Open the following file in a text editor:

   DPA-install-dir\iwc\tomcat\ignite_config\idc\system.properties

2. Uncomment or add one of the following, and save the file:

   • If all credentials that DPA uses for authentication are stored in CyberArk, uncomment or add the following line:

     com.solarwinds.dpa.credentials.provider.type=CYBERARK_REMOTE

     The general property com.solarwinds.dpa.credentials.provider.type is the default and includes all credential types. If you include both com.solarwinds.dpa.credentials.provider.type and one or more of the type-specific properties listed below, the value for the type-specific property takes precedence.

   • If only some of the credentials that DPA uses are stored in CyberArk, uncomment or add the following lines as needed. Enter a value of either DPA or CYBERARK_REMOTE to specify where the credentials are stored:

     com.solarwinds.dpa.credentials.provider.type.database = [DPA || CYBERARK_REMOTE]

     com.solarwinds.dpa.credentials.provider.type.repository = [DPA || CYBERARK_REMOTE]

     com.solarwinds.dpa.credentials.provider.type.vsphere = [DPA || CYBERARK_REMOTE]

     com.solarwinds.dpa.credentials.provider.type.mail = [DPA || CYBERARK_REMOTE]

     com.solarwinds.dpa.credentials.provider.type.ldap = [DPA || CYBERARK_REMOTE]

3. Restart DPA.

   After the restart, the affected DPA wizards and other interfaces display a field for the CyberArk credentials query instead of the user name and password fields.

   

Update an existing DPA installation to use credentials stored in CyberArk

If any of the following were configured before the CyberArk integration, you must update the configurations to use credentials stored in CyberArk:

• The DPA repository database
• Monitored database instances
• Monitored VMware ESX/ESXi Hosts or vCenter Servers
• AD or LDAP server
• Your company mail server that is used to send emails from DPA

For new installations without a repository database, see Create a DPA repository that uses CyberArk for authentication.

1. To configure the DPA repository database to use credentials stored in CyberArk:

   1. Open the following file in a text editor:

      DPA-install-dir\iwc\tomcat\ignite_config\idc\repo.properties

   2. Remove the repo.user and repo.password properties.

   3. Add the following setting, where cyberArkQueryForRepoCredentials is the CyberArk query that DPA will use to obtain the credentials to connect to the repository database:

      repo.cyberarkQuery=cyberArkQueryForRepoCredentials

      For example:

      repo.cyberarkQuery=&safe=mondb&object=dparepo

   4. Save the file.

   5. Restart DPA for the changes to take effect.

2. For each monitored database instance, use the Update Connection Wizard to enter the CyberArk credentials query. Or use the cyberArkQuery parameter in the DPA REST API to update existing monitored database instances.
3. For each monitored VMware ESX/ESXi Host or vCenter Server, open the Update VMware Connection page and enter the CyberArk credentials query.

4. If DPA uses your company's mail server to send email, update the mail server configuration and enter the CyberArk credentials query.

   If DPA uses the default mail server or the embedded mail server, no changes are needed.

5. If DPA is configured to use AD or LDAP user authentication, use the Configure AD/LDAP wizard to enter the CyberArk credentials query. Then restart DPA for the changes to take effect.

Register additional database instances for monitoring

When DPA is started in CyberArk mode, you must specify the CyberArk query instead of entering a user name and password when you register monitored database instances. You can use the Register Database Instance wizard, mass registration, or the REST API to register instances:

• To use the Register Database Instance wizard, follow the instructions in one of the following topics for creating the monitoring user and completing the wizard:

  • Register an Oracle database instance
  • Register a SQL Server database instance
  • Register a Sybase database instance
  • Register a Db2 database instance
  • Register a MySQL, Percona, or Maria database instance
  • Register a PostgreSQL database instance and prepare for monitoring
  • Register an Amazon RDS for Oracle database instance
  • Register an Amazon RDS for SQL Server database instance
  • Register an Amazon RDS for MySQL or MySQL-compatible Aurora database instance
  • Register an Azure SQL database
  • Register an Azure SQL Managed Instance

• To use mass registration or the REST API:

  1. Follow the instructions in one of the topics listed above to create the monitoring user.

  2. Access the REST API, or open the Mass registration page and choose All database types.

  3. See the following table for API parameters or registration file template values.

If you use mass registration or the REST API, enter the required values in the mass registration form or in the REST API call. Values specific to CyberArk implementation are described in the following table.

Mass registration field	REST API parameter	Value
Monitoring User Monitoring User Password Privileged User Privileged User Password SYS Password	monitoringUser monitoringUserPassword sysAdminUser sysAdminPassword sysPassword	Do not enter a value.
CyberArk query	cyberArkQuery	Enter information that can be concatenated with the base.uri value from the cyberark.properties file to create a valid request to the CyberArk CCP. For example: &safe=mondb&object=oracleprod1 DPA uses values in the UserName field, the Content field, and (in some cases) the LogonDomain field from the CyberArk response as credentials for monitoring the database.
Create Monitoring User	monitoringUserIsNew	Enter N on the mass registration form. Enter false as the REST API parameter value.

The following example shows a REST API request to register Oracle instance:

{   "databaseType": "ORACLE",
    "serverName": "127.0.0.1",
    "serviceNameOrSID": "DPA_ORA11R1",
    "port": "1521",
    "monitoringUserIsNew": false,
    "displayName": "DPA_ORA11R1",
    "cyberArkQuery: "&safe=mondb&object=oracleprod1"
}

Secure your CyberArk integration

SolarWinds strongly recommends securing information used to authenticate to CyberArk.

Use a strong encryption algorithm and passphrase

Password fields in cyberark.properties are automatically encrypted after DPA startup. To use a strong encryption algorithm and passphrase:

1. Open DPA in your browser.
2. From the DPA menu in the upper-right corner, click Options.
3. Under Administration > Configuration, click Password Encryption Settings.
4. Under Choose an encryption scheme, select AES 256-bit.

5. Enter your Encryption Passphrase.

   Do not share the passphrase with anyone.

6. Click Update.

   Passwords stored in DPA configuration files or in the DPA repository are re-encrypted using your selection.

Limit access to the files storing sensitive information

Make sure that, except for the user running DPA service (Windows) or process (Linux), no one has read permission to the CyberArk configuration file (cyberark.properties) and CyberArk client certificate (referenced from cyberark.properties).

For the user running the DPA service or process, read permission is sufficient for the CyberArk client certificate. Both read and write permissions are needed for the cyberark.properties file (so DPA can encrypt the password fields).

When you install DPA on a Linux server, make sure you do not install DPA under the root user. Using a dedicated DPA user instead of the root user gives you flexibility to set the permissions as described above.

When you install DPA on a Windows server, the Ignite_PI service runs under the "Local System Account" by default. To use a dedicated DPA user instead, complete the following steps:

1. Open a command prompt, and enter services.msc.
2. Right-click the Ignite PI Server service and select Properties.
3. On the Log On tab, click This Account and enter the credentials for the account you want to use.

Be aware that after you upgrade DPA, the Ignite_PI service is recreated and "Local System Account" is used again. You must manually update the service after every DPA upgrade.