PingIntelligence

Installing the PingIntelligence Dashboard

Learn how to install the PingIntelligence Dashboard.

Before you begin

Ensure that the following prerequisites are met:

  • Server: 8 core CPU, 16 GB, 1 TB HDD

  • Operating system: RHEL 7.9 or Ubuntu 18.04 LTS

  • OpenJDK: 11.0.2

  • SSL certificate: One private key and certificate. By default, PingIntelligence Dashboard uses the private key and certificate shipped with the binary.

  • Password: If you want to change the default password, set a minimum 8 character password.

  • API Behavioral Security (ABS): ABS URL, access, and secret key. Make sure that ABS is reachable from the PingIntelligence Dashboard machine.

  • API Security Enforcer (ASE): ASE management URL, access, and secret key. Make sure that ASE is reachable from the PingIntelligence Dashboard machine.

Connecting the Dashboard to ASE is optional. Functionality, such as adding discovered APIs to ASE and attack management, will be limited.

Make sure the following default port numbers are available:

  • PingIntelligence Dashboard (WebGUI) server: 8030. Port number 8030 should be exposed to public internet. Make sure that your organization’s firewall allows access to this port.

  • Elasticsearch: 9200

  • Dataengine: 8040

  • H2 database: 9092. The H2 database is installed and runs as a part of the PingIntelligence Dashboard.

Make sure you have one of the following supported browsers installed. The following table shows the compatibility of PingIntelligence for APIs Dashboard with different browsers and their versions.

Operating System Google Chrome Mozilla Firefox Apple Safari Microsoft Edge

Mac OS Mojave -10.14

Version 56.0 and later

Version 69.0 and later

Version 12.0 and later

Mac OS Sierra -10.12

Version 56.0 and later

Version 69.0 and later

Version 10.1 and later

Mac OS High Sierra - 10.13

Version 56.0 and later

Version 69.0 and later

Version 11.1 and later

Mac OS Catalina -10.15

Version 56.0 and later

Version 69.0 and later

Version 13.0 and later

Windows 8.1

Version56.0 and later

Version 69.0 and later

Windows 10

Version 56.0 and later

Version 69.0 and later

Version 79.0 and later

Ensure you have completed the following configuration for the operating system:

  • Increase the ulimit to 65536:

    # sudo sysctl -w fs.file-max=65536
# sudo sysctl -p

  • Increase the vm.max_map_count limit to 262144:

    # sudo echo "vm.max_map_count=262144" >> /etc/sysctl.conf
# sudo sysctl -p

  • Set JAVA_HOME to the <jdk_install> directory and add <jdk_install>/bin to the system PATH variable. <jdk_install_dir> is the directory where JDK is installed.

  • Choose the <pi_install_dir> directory. The <pi_install_dir> directory is the directory where the PingIntelligence Dashboard is installed. This directory should be readable and writable by the logged in user.

About this task

Installing the PingIntelligence for APIs Dashboard automatically installs Elasticsearch.

There are two preconfigured login users in PingIntelligence Dashboard:

  • admin

  • ping_user

Multiple admin and ping_user can simultaneously sign on to PingIntelligence Dashboard. The admin user has full access toPingIntelligence Dashboard. An admin can view the dashboard of various APIs as well as tune threshold and unblock a client identifier. ping_user can only view the API dashboard. A total of 25 admin and ping_user can sign on simultaneously.

To install the PingIntelligence Dashboard:

Steps

  1. Create a <ping_install_dir> directory on your host machine.

    Make sure that the user has read and write permissions for the <ping_install_dir> directory.

  2. Download the PingIntelligence Dashboard binary.

    1. Under Download AI Engine and Tools, click Dashboard 5.1.0.1.

  3. Download Elasticsearch 6.8.1 (macOS/RHEL).

  4. Change the directory to ping_install_dir:

    # cd pi_install_dir

  5. Untar the PingIntelligence Dashboard:

    # tar -zxf pi-api-dashboard-5.1.tar.gz

  6. Add the MongoDB IP address in webgui.properties.

  7. Copy the MongoDB certificate to the Dashboard virtual machine (VM).

  8. Import the MongoDB certificate to webgui.jks using the following command:

    keytool -import -keystore dataengine.jks -storetype JKS -storepass changeme -alias mongo -file mongo.crt -noprompt

  9. Change the directory to pingidentity/webgui/:

    # cd pingidentity/webgui/

  10. Install the PingIntelligence Dashboard by entering the following command and follow the instructions displayed on the prompt:

    # ./bin/pi-install-ui.sh
    # ./bin/pi-install-ui.sh

elasticsearch-7.13.4.tar.gz file path >
Use bundled ssl key and self signed certificate for ui server [y/n]?  >[y]
Use default password [changeme] for all components and users [y/n]?  >[y]
ABS url  >[https://127.0.0.1:8080]
ABS access key  >[abs_ak]
ABS secret key  >[abs_sk]
API Service URL  >[https://127.0.0.1:8050]
Kafka Host:Port >[127.0.0.1:9093]
Kafka Authentication username  >[pi4api_de_user]
Kafka Group ID  >[pi4api.data-engine]
ASE management url  >[]
extracting elasticsearch package
creating elasticsearch config keystore
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
Created elasticsearch keystore in <pi_install_dir>/pingidentity/elasticsearch/config/elasticsearch.keystore
elasticsearch config keystore created
Generating a 2048 bit RSA private key
..........................................+++
........................+++
writing new private key to 'config/ssl/autogen_es.key'
-----
creating password protected pkcs#12 keystore for elasticsearch private key and certificate
pkcs#12 keystore created at config/ssl/elastic-certificates.p12
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
configuring elasticsearch. Please wait 15 seconds
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
OpenJDK 64-Bit Server VM warning: Option UseConcMarkSweepGC was deprecated in version 9.0 and will likely be removed in a future release.
elasticsearch config is completed
configuring dataengine
configuring webgui
starting webgui for configuration update
WebGUI configured for UTC timezone.
WebGUI 5.1 starting...
please see <pi_install_dir>/pingidentity/webgui/logs/admin/admin.log for more details
success: password updated.
Note: All active sessions for this user are invalidated. Login with new credentials
success: password updated.
Note: All active sessions for this user are invalidated. Login with new credentials
WebGUI 5.1
WebGUI is stopped.
webgui configuration done

UI configuration done
writing internal credentials to <pi_install_dir>/pingidentity/webgui/install/webgui_internal.creds
Start UI [y/n]?  >[y]
starting elasticsearch...
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
warning: usage of JAVA_HOME is deprecated, use ES_JAVA_HOME
OpenJDK 64-Bit Server VM warning: Option UseConcMarkSweepGC was deprecated in version 9.0 and will likely be removed in a future release.
elasticsearch started
starting dataengine
Data Engine configured for UTC timezone.
PingIntelligence Data Engine 5.1 starting...
Data-Engine started
starting webgui
WebGUI configured for UTC timezone.
WebGUI 5.1 starting...
please see <pi_install_dir>/pingidentity/webgui/logs/admin/admin.log for more details
Please access WebGUI at https://<pi_install_host>:8030

<pi_install_host> can be ip address, hostname or fully qualified domain name of this server.
<pi_install_host> should be reachable from your computer.

Credentials:
  1) Username: admin
     Password: changeme
  2) Username: ping_user
     Password: changeme

Important Actions:
1) Credentials for all internal components are available in <pi_install_dir>/pingidentity/webgui/install/webgui_internal.creds file.
    Move this file from this server and securely keep it elsewhere.
    For any debugging purposes you will be asked to get credentials for a component from this file.
2) Following obfuscation master keys are auto-generated
      <pi_install_dir>/pingidentity/webgui/config/webgui_master.key
      <pi_install_dir>/pingidentity/dataengine/config/dataengine_master.key

    The ASE management url is an optional parameter.

  11. Verify installation by checking the process IDs (pid) of each component in the following locations:

    1. Elasticsearch: <pi_install_dir>/elasticsearch/logs/elasticsearch.pid

    2. Dataengine: <pi_install_dir>/dataengine/logs/dashboard.pid

    3. Web GUI: <pi_install_dir>/webgui/logs/webgui.pid

  12. Tune the Dashboard performance parameters by configuring the following three parameters for better performance.

    Note the following tuning parameters if you have your setup of Elasticsearch. If you have used PingIntelligence automated deployment or the pi-install-ui.sh script to deploy the Dashboard, the tuning of the parameters below is done as part of installation.
    Parameter Description Location

    Elasticsearch

    -Xms and -Xmx

    • -Xms: Defines the minimum heap size of Elasticsearch. Set to 4 GB as Xms4g.

    • -Xmx: Defines the maximum heap size of Elasticsearch. Set to 4 GB as Xmx4g.

    $ES_HOME/config/jvm.options

    thread_pool.search.size

    Defines thread pool size for count/search/suggest operations in Elasticsearch. Configure to 50% of total CPUs allocated.

    $ES_HOME/config/elasticsearch.yml

    Troubleshooting:

    To detect and mitigate attacks such as cross-site scripting (XSS), the PingIntelligence Dashboard implements Content Security Policy (CSP). The following are the configuration details:

    Response header - Content-Security-Policy
    Response header value - default-src ‘self’; font-src ‘self’ use.typekit.net; script-src ‘self’ use.typekit.net; style-src ‘self’ ‘unsafe-inline’ use.typekit.net p.typekit.net; img-src ‘self’ data: p.typekit.net;