Forcepoint Behavioral Analytics and Ping Identity

Table of contents
  1. Forcepoint Behavioral Analytics and Ping Identity
  2. Summary
    1. Demo
    2. Source Code
    3. Caveats
    4. Implementation
  3. Step 1 – Setup Risk Exporter
    1. Implementation – Docker
  4. Step 2 – Setup Ping Federate
  5. Step 3 – Ingesting failed login attempts
    1. Implementation – Traditional
    2. Implementation – Docker
  6. Troubleshooting
    1. Docker Implementation
      1. Validate the prerequisites
      2. Check network connectivity
      3. Check all components are configured and running properly
  7. Appendix – Sample events from different types of login failures
License

These contents are licensed under Apache License, Version 2.0. http://www.apache.org/licenses/LICENSE-2.0

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SITE AND ITS CONTENT IS PROVIDED TO YOU ON AN “AS IS,” “AS AVAILABLE” AND “WHERE-IS” BASIS. ALL CONDITIONS, REPRESENTATIONS AND WARRANTIES WITH RESPECT TO THE SITE OR ITS CONTENT, WHETHER EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT OF THIRD PARTY RIGHTS, ARE HEREBY DISCLAIMED

Document Revision
Version Date Author Notes
0.1 22 October 2019 Mattia Maggioli First draft
0.2 23 October 2019 Mattia Maggioli Updated with risk level mapping to IdP policies
0.3 23 October 2019 Jonathan Knepher Review
0.4 24 October 2019 Audra Simons Review
0.5 24 October 2019 Jonathan Knepher Review
0.6 25 October 2019 Mattia Maggioli Updated Risk Export chapter
0.7 21 November 2019 Mattia Maggioli Added MFA policy with PingID, instructions to ingest failed login attempts and examples
0.8 22 January 2020 Rabih Abou Fakher Updated package names
0.9 28 February 2020 Rabih Abou Fakher Updated risk exporter chapter and Ingesting failed logins chapter
1.0 09 April 2020 Neelima Rai Updated with contents for Ping Federate 10
1.1 04 September 2020 Mattia Maggioli Minor updates
1.2 26 May 2021 Rabih Abou Fakher Update commands and URL’s

Summary

This guide provides step by step instructions to configure Forcepoint Behavioral Analytics and Ping Federate to pass risk level and login / event information.

The code and instructions provided enable administrators to automatically:

  • Export events from Ping Federate into Forcepoint Behavioral Analytics

  • Provide the risk level calculated by Forcepoint Behavioral Analytics for each user to Ping Federate

  • Adjust authentication policies applied by Ping Federate to users based on their risk level

This interoperability enriches visibility into user activities, enhances risk scoring, and enables risk-adaptive authentication policy for Ping Federate users based on the intelligence provided by Forcepoint Behavioral Analytics.

A description of the workflow between the components involved in this POC is depicted in this diagram:

Demo

Source Code

fp-bd-riskscore-ping-api

fp-bd-fba-pingfederate-log-monitor

Caveats

These implementation instructions are tested with the following product versions:

  • Forcepoint Behavioral Analytics 3.1.0

  • Ping Federate 9.2 and 10.0

This interoperability is based on

  • an Identity Adapter provided by Ping Identity, which exports successful events from Ping Federate to Forcepoint Behavioral Analytics via the Forcepoint Streaming Ingest Public API

  • a script which parses audit logs of Ping Federate to extract information of failed login attempts and sends them to Forcepoint Behavioral Analytics

    Audit logs of Ping Federate only provide information related to known users (i.e. users who belong to the directory being used in the customer environment), so verbosity is limited to relevant information for ingestion into Forcepoint Behavioral Analytics.

The following activities are out of the scope of this document and therefore left to the system administrator, as part of ordinary maintenance procedures to be put in place within the existing infrastructure:

  • monitoring of the scripts, services and applications involved in the solution

Implementation

  • Docker – leverages a docker image where the integration component is already installed with all necessary dependencies: the user only has to edit one configuration file and run the container on an existing docker setup

The docker image for exporting risk level information has been tested working with the following requirements

  • Docker 19.03.5

  • The docker host machine should meet the minimum hardware requirements of 2GB RAM, 20GB free storage, 64bit version only for the operating system

    The files needed to setup the integration are available at the following links:

  • fp-fba-failed-logins-importer-ping-v1.tar.gz and ping-connector.tar.gz are available at https://github.com/Forcepoint/fp-bd-fba-pingfederate-log-monitor/releases/latest

Step 1 – Setup Risk Exporter

Risk Exporter provides a REST API endpoint used by the Ping connector to retrieve the risk level calculated by Forcepoint Behavioral Analytics.

Risk Exporter is deployed to a Linux machine with a working network connectivity to Forcepoint Behavioral Analytics and from Ping Federate, typically within the same infrastructure hosting both components.

Implementation – Docker

  1. Login into docker repository, you’ll be asked to enter your username and password (provided below):

    docker login docker.frcpnt.com

      $ Username: fp-integrations
  $ Password: t1knmAkn19s

  2. Create the SSL certificate, Note the command below is only being provided for demo purposes and not to be used for production, it’s your own responsibility to provide and manage the SSL certificate, you need a public certificate and it’s private key in order to proceed with setting up the API, the command below will create the public certificate and it’s private key for the API in the ./certs directory.

     HOSTNAME=$(hostname); \
 SUBJECT="/C=IE/ST=Cork/L=Cork/O=Forcepoint/CN=$HOSTNAME"; \
 LOCAL_DIR="./certs"; \
 mkdir -p ${LOCAL_DIR}; \
 docker run --rm --entrypoint /bin/ash frapsoft/openssl \
 -c "openssl req \
   -newkey rsa:4096 \
   -days 3650 \
   -nodes \
   -x509 \
   -subj $SUBJECT \
   -keyout server.key \
   -out server.crt; \
   cat server.crt server.key" > ${LOCAL_DIR}/certs; \
 cat ${LOCAL_DIR}/certs | sed '/END CERTIFICATE/q' > ${LOCAL_DIR}/${HOSTNAME}.crt; \
 cat ${LOCAL_DIR}/certs | sed -n '/BEGIN PRIVATE KEY/, /END PRIVATE KEY/p' > ${LOCAL_DIR}/${HOSTNAME}.key; \
 rm -rf ${LOCAL_DIR}/certs; \
 openssl x509 -noout -certopt no_sigdump,no_pubkey -text -in ${LOCAL_DIR}/${HOSTNAME}.crt; \
 unset HOSTNAME SUBJECT LOCAL_DIR;
  3. In order to get kafka to trust the API you need to upload the API public certificate into the Kafka server and import it into the Kafka truststore, then restart the kafka service, fill and change the values for the varaibles below:
    1. KAFKA_USER
    2. KAFKA_SERVER
    3. TRUSTSTORE_DIR
    4. TRUSTSTORE_NAME
    5. TRUSTSTORE_PASS
     KAFKA_USER=""; \
 KAFKA_SERVER=""; \
 TRUSTSTORE_DIR="/etc/kafka/conf"; \
 TRUSTSTORE_NAME="kafka-lab-truststore.p12"; \
 TRUSTSTORE_PASS="changeme"; \
 HOSTNAME=$(hostname); \
 LOCAL_DIR="./certs"; \
 scp ${LOCAL_DIR}/${HOSTNAME}.crt ${KAFKA_USER}@${KAFKA_SERVER}:~/. && \
 ssh -t ${KAFKA_USER}@${KAFKA_SERVER} "sudo keytool -keystore ${TRUSTSTORE_DIR}/${TRUSTSTORE_NAME} -alias ${HOSTNAME} -storepass ${TRUSTSTORE_PASS} -delete &>/dev/null; sudo keytool -keystore ${TRUSTSTORE_DIR}/${TRUSTSTORE_NAME} -alias ${HOSTNAME} -import -file ${HOSTNAME}.crt -storepass ${TRUSTSTORE_PASS} -noprompt ; rm -f ${HOSTNAME}.crt; sudo service kafka restart"; \
 unset KAFKA_USER KAFKA_SERVER TRUSTSTORE_DIR TRUSTSTORE_NAME TRUSTSTORE_PASS HOSTNAME LOCAL_DIR;
  4. In order to get the API to trust kafka, you need to export the kafka certificate authority (CA) into the riskscore API server, it is usually found in the /etc/pki/ca-trust/source/anchors directory, if it’s not found there, it needs to be extracted out of kafka truststore, fill and change the values for the varaibles below:
    1. KAFKA_USER
    2. KAFKA_SERVER
    3. CA_DIR
    4. CA_CERT_NAME
     KAFKA_USER=""; \
 KAFKA_SERVER=""; \
 CA_DIR="/etc/pki/ca-trust/source/anchors"; \
 CA_CERT_NAME="ueba-ca.crt"; \
 HOSTNAME=$(hostname); \
 LOCAL_DIR="./certs"; \
 scp ${KAFKA_USER}@${KAFKA_SERVER}:${CA_DIR}/${CA_CERT_NAME} ${LOCAL_DIR}/${CA_CERT_NAME}; \
 unset KAFKA_USER KAFKA_SERVER CA_DIR CA_CERT_NAME HOSTNAME LOCAL_DIR;

  5. Create a new file named cfg.yml and insert the following content, filling the values for the below 3 variables:

    1. ssl_password (Note: This is the private key password for the ssl cert, the demo command in step 2 above has no private key password.)
    2. kafka_server_name
    3. kafka_server_ip
    # API port number, default 5000
api_port: 5000
# SSL private key password if exists
ssl_password:
# Set to True if this API is being setup for FBA Risk Score
fba_risk_score_fetch_enable: True
kafka_server_name: 
kafka_server_ip:
  6. Run the container with either one of the following commands, depending on your scenario
  • if cfg.yml file is located locally, then run the command below, replacing:
    1. <cfg.yml-full-path> with the full path of the cfg.yml
    2. <server.crt-full-path> with the full path of the SSL public certifcate server.crt
    3. <server.key-full-path> with the full path of the SSL private key server.key
    4. <kafka-ca.crt-full-path> with the full path of the SSL private key kafka-ca.crt
      docker run --detach \
  --name fp-riskexporter-api \
  --publish 5000:5000 \
  --restart always \
  --volume <cfg.yml-full-path>:/app/fp-riskexporter-api/cfg.yml \
  --volume <server.crt-full-path>:/app/fp-riskexporter-api/certs/server.crt \
  --volume <server.key-full-path>:/app/fp-riskexporter-api/certs/server.key \
  --volume <kafka-ca.crt-full-path>:/app/fp-riskexporter-api/certs/kafka-ca.crt \
  --volume RiskScoreDBVolume:/app/fp-riskexporter-api/db \
  --volume RiskScoreApiLogs:/app/fp-riskexporter-api/logs \
  docker.frcpnt.com/fp-riskexporter-api
  • if cfg.yml file is hosted in a remote location, then run the command below, replacing:
    1. <config-file-url> with the URL of the cfg.yml file to download
    2. <server.crt-full-path> with the full path of the SSL public certifcate server.crt
    3. <server.key-full-path> with the full path of the SSL private key server.key
    4. <kafka-ca.crt-full-path> with the full path of the SSL private key kafka-ca.crt
      docker run --detach \
  --name fp-riskexporter-api \
  --publish 5000:5000 \
  --restart always \
  --env CONFIG_FILE_URL_LOCATION=<config-file-url> \
  --volume <server.crt-full-path>:/app/fp-riskexporter-api/certs/server.crt \
  --volume <server.key-full-path>:/app/fp-riskexporter-api/certs/server.key \
  --volume <kafka-ca.crt-full-path>:/app/fp-riskexporter-api/certs/kafka-ca.crt \
  --volume RiskScoreDBVolume:/app/fp-riskexporter-api/db \
  --volume RiskScoreApiLogs:/app/fp-riskexporter-api/logs \
  docker.frcpnt.com/fp-riskexporter-ap

Step 2 – Setup Ping Federate

Ping Federate normally uses Identity Provider (IdP) as system entities that authenticate users and provide identity attributes to Ping. In our case, we will leverage an IdP to communicate with Forcepoint Behavioral Analytics in both ways (sending event data to Forcepoint Behavioral Analytics, passing risk level back to Ping Federate).

  1. Download the ping-connector.tar.gz package and extract its contents into the /opt/ directory by executing the command below:

    PUBLIC_REPO_NAME=fp-bd-fba-pingfederate-log-monitor; \
DEPLOYMENT_NAME=ping-connector.tar.gz; \
LATEST_VERSION=$(curl -sL "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/latest" | grep "$DEPLOYMENT_NAME" | head -1 | grep -E -o "/v.{0,5}" | cut -c 3-); \
wget --content-disposition "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/download/v$LATEST_VERSION/$DEPLOYMENT_NAME" && \
sudo tar -zxvf $DEPLOYMENT_NAME -C /opt/ && rm -f ./$DEPLOYMENT_NAME*

  2. Place the files located in the /opt/ping-connector/ directory in the location specified in the following table (change <pingfed-home> path to match your setup)

    File Target location
    pf.plugins.generic-device-risk-adapter.jar /<pingfed-home>/pingfederate/server/default/deploy
    devicerisk.html.form.login.template.html /<pingfed-home>/pingfederate/server/default/conf/template
    devicerisk.min.capture.template.html /<pingfed-home>/pingfederate/server/default/conf/template
    client.min.js /<pingfed-home>/pingfederate/server/default/conf/template/assets/scripts

  3. Edit the file /<pingfed-home>/pingfederate/server/default/data/config-store/org.sourceid.common.ExpressionManager.xml and change “evaluateExpressions” to true

  4. Restart the Ping service to load the new files, see this page on Ping website for options available: https://support.pingidentity.com/s/document-item?bundleId=pingfederate-92&topicId=gettingStartedGuide%2Fpf_t_startAndStopPingfederate.html

  5. Login to the Ping Federate console

  6. Select Identity Provider > Integration > Adapters

  7. Select the existing HTMLFormSimplePCV adapter

  8. Select Extended Contract and add pf.envdata in Extend the Contract field, then select Done to save the configuration of this IdP. Click Save on the next page to save these changes.

  9. Go to Identity Provider > Integration > Adapters > HTMLFormSimplePCV > Adapter Contract Mapping, then click Configure Adapter Contract

  10. Click on Adapter Contract Fulfillment, change the Source for pf.envdata to Expression (as shown in the screenshot below) and add the following expression into the Value area as one line.

      #result = #this.get("context.HttpRequest").getObjectValue().getParameter("pf.envdata") != null ? #this.get("context.HttpRequest").getObjectValue().getParameter("pf.envdata").toString() : null

  11. Click Done to save the new value. On the next page that appears, click Done again. Click Save on the next screen to finally save these changes.

    Next, we create a new IdP that will be used by Ping Federate to action authentication policies

  12. Click Identity Provider > Adapters > Create New Instance and fill the relevant fields using the following values so they match the instructions in the rest of this document:

    Instance Name: DeviceRiskAdapter

    Instance ID: DeviceRiskAdapter

    Type: Device Risk Adapter

    Once done click Next.

  13. In the page that follows fill the relevant fields with the following values, making sure to change the path and ports to match the ones used in your current setup:

    Event ingest endpoint: https://<Forcepoint Behavioral Analytics Streaming Ingest Public API hostname or IP>:9000/event

    Risk score endpoint: https://<Risk Exporter hostname or IP>:5000/fba/risk/level

    Note: The certs for the two URLs above need to be trusted by ping host machine.

    Once done click Next.

  14. Click Next again and once on Adapter Attributes tab and tick the checkboxes Pseudonym for both “risk_level” and “username”. Once done click Next in the next two pages that appear and once Summary page is reached, Click Done and in the next page click Save to save the changes.

  15. In the Identity Provider page go to Integration > Adapters, click HTMLFromSimplePCV then IdP Adapter

  16. Scroll to the bottom of the page and click Show Advanced Fields

  17. Find the Login Template field and replace the existing value with

    devicerisk.html.form.login.template.html

    Once done click Done. In the next page, click Save

    The next step is to define Policy Contracts: this will be used by Ping Federate to oppose different

    authentication steps to each user based on his risk level provided by Forcepoint Behavioral Analytics.

  18. Click Identity Provider > Authentication Policies > Policy Contracts > Create New Contract

  19. Enter a name in the Contact Name field (e.g. “Simple” in the rest of this document), then Next > Next > Done > Save

  20. Click OAuth Server > Grant Mapping > Authentication Policy Contract Mapping and select from the drop-down menu the contract created in the previous step, then click Add Mapping > Next which takes you to the Contract Fulfillment tab

  21. For both USER_KEY and USER_NAME contracts select Authentication Policy Contract from the drop-down menus; select subject as value

    Once done click Next, do nothing in Issuance Criteria in the next screen but click Next then Save

    Click Identity Provider > Authentication Policies > Policies, and make sure that IDP AUTHENTICATION POLICIES checkbox is selected.

  22. Click Identity Provider > Authentication Policies > Policies > Add Policy, use the following values

    Name: Device Risk Policy

    Policy: pick HTMLFormSimplePCV from IdP Adapters in the drop-down menu

    For the Fail case click Done, while for the Success case click on the drop-down menu and select DeviceRiskAdapter from the IdP Adapters menu

  23. Under the top Success drop-down menu click Options and pick the following entries for each drop-down menu

    Source: Adapter (HTMLFormSimplePCV)

    Attribute: username

    Click Done once finished

  24. Under the top Success drop-down now click Rules and add one line for each possible value returned by Forcepoint Behavioral Analytics as in the picture below, each of these lines will be assigned with a different action so that Ping will oppose different challenges based on the risk_level value. User can add a new entry (rule) by clicking Add button.

    The Risk Exporter returns risk_level -1 for entities that have no risk level. This can be configured as a policy rule to utilize a specific risk level, or by ticking the Default to success box will let users authenticate normally if their risk level has not been calculated yet.

    Please note that Ping Federate does not provide inequality operators for the risk_level value, therefore the system administrator must create a policy rule for each possible case (e.g. it is not possible to configure a rule for the case “risk_level > 2”)

    Once finished, click Done

  25. Typically, a system administrator may configure:

    • Standard authentication steps for low risk users (e.g. risk_level = 1 or 2)

    • Multi-factor authentication for medium risk users (e.g. risk_level = 3 or 4)

    • More complex, or deny authentication for the most risky users (e.g. risk_level = 5)

    • A custom action or one of the above options for users whose risk level has not been calculated yet (risk_level = -1)

      The choice of how to map risk_level values to authentication steps is left to the system administrator, since there might already be in place custom authentication policies, and more importantly because the mapping decision differs from customer to customer based on their security policies.

      For system administrators with no previous authentication policies in place, here is an example of how to configure Ping Federate based on the risk level provided by Forcepoint Behavioral Analytics.

The configuration described in the next pages

  • Allows standard access with username/password for users whose risk level is 1 to 4, and for users whose risk level has not been calculated yet

  • Denies access to users whose risk_level equals to 5

    The process to configure this is as follows:

    1. Click Expand All to see all rules as a tree.

    2. For the Fail case under DeviceRiskAdapter click Done.

    3. Under Risk Level 1, click on the drop-down menu and on the next drop-down menu select Policy Contracts, select Simple (created earlier in step 18 of Step 2 – Setup Ping Federate)

    4. Click Contract Mapping

    5. Click Next in the Attribute Source & User Lookup page and in the Contract Fulfillment page use the following choices in the drop-down menus then click Next

      Source: Adapter (HTMLFormSimplePCV)

      Value: username

    6. In Issuance Criteria page, pick the following values in each drop-down menu:

      Source: Adapter (DeviceRiskLevel)

      Attribute Name: risk_level

      Condition: equal to

      Value: 1

      Error Result: Low – Risk Level 1

      Once done click Add then Next. Click Done.

      Repeat steps 2 to 4 for each Risk Level 1 to 4.

    7. For Risk Level 5 click Contract Mapping then Next in the Attribute Source & User Lookup page since no changes are to be made in this page. In the Contract Fulfillment page use the following choices in the drop-down menus then click Next

      Source: Adapter (HTMLFormSimplePCV)

      Value: username

    8. In the Issuance Criteria page, select the values in the drop-down menus as follows

      Source: Adapter (DeviceRiskLevel)

      Attribute Name: risk_level

      Condition: not equal to

      Value: 5

      Error Result: High – Risk Level 5

      Once done click Add then Next. Click Done.

      By doing this, when Ping Federate processes the policy for a user with risk_level = 5, will route the user to the “RISK LEVEL 5” rule. This rule would authorize the login only if the Issuance Criteria is met, but since we configured not equal to as Condition, this will never be met thus no authentication for the user whose risk level is 5.

For Success under DeviceRiskAdapter, click on the drop-down menu and on the next drop-down menu select Policy Contracts, select Simple (created earlier in step 18 of Step 2 – Setup Ping Federate).

  1. Click Contract Mapping then Next in the Attribute Source & User Lookup page since no changes are to be made in this page. In the Contract Fulfillment page use the following choices in the drop-down menus then click Next

    Source: Adapter (HTMLFormSimplePCV)

    Value: username

Once done click Next then Next. Click Done.

Once all the risk levels are mapped correctly, Click Done at the bottom of the page.

In the next screen, Click Save to save the configuration for the Device Risk Policy

Step 3 – Ingesting failed login attempts

This step is provided in two different implementation, choose the traditional implementation or the docker implementation.

Information of failed login attempts are available from the audit.log file stored inside the Ping Federate host. In order to provide Forcepoint Behavioral Analytics with data of failed login attempts, log files must be accessible to the machine where the Failed Logins Importer component is installed. Typically, this is achieved by

  • mapping an NFS share to the PingFederate audit logs directory in read-only mode

  • configuring the NFS share so that is available only to the machine where the Failed Logins Importer component is installed

    Once the audit logs folder is reachable from the machine hosting the Failed Logins Importer, proceed with the implementation of the actual component.

Implementation – Traditional

  1. Download the fp-fba-failed-logins-importer-ping-v1.tar.gz package and extract its contents into the /opt/ directory by executing the command below:

    PUBLIC_REPO_NAME=fp-bd-fba-pingfederate-log-monitor; \
DEPLOYMENT_NAME=fp-fba-failed-logins-importer-ping-v.*.tar.gz; \
LATEST_VERSION=$(curl -sL "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/latest" | grep "$DEPLOYMENT_NAME" | head -1 | grep -E -o "/v.{0,5}" | cut -c 3-); \
CODE_VERSION=$(curl -sL "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/latest" | grep -E -o "$DEPLOYMENT_NAME" | head -1 | rev | cut -c 8- | awk -F\v- '{print $1}'); \
DEPLOYMENT_NAME_WITH_VERSION=$(echo "${DEPLOYMENT_NAME::-9}$CODE_VERSION.tar.gz"); \
wget --content-disposition "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/download/v$LATEST_VERSION/$DEPLOYMENT_NAME_WITH_VERSION" && \
sudo tar -zxvf $DEPLOYMENT_NAME_WITH_VERSION -C /opt/ && rm -f ./$DEPLOYMENT_NAME_WITH_VERSION*

  2. Install script below will install the system prerequisites, run with a user with administrative privileges.

    /opt/fp-fba-failed-logins-importer-ping/deploy/install.sh

  3. Move to the /opt/fp-fba-failed-logins-importer-ping-v1/ folder and edit the file user-config.sh and change the values to match the hostnames/IP addresses, ports, paths, filenames, and credentials in your current environment relevant to your setup.

    The exact value for the Adapter ID entries can be found logging into web console of Ping Federate > Identity Provider > Integration > Adapters

    If _ENABLE_LOGGING_ is set to true, logs files are created inside /opt/fp-fba-failed-logins-importer-ping/logs/

    Note: The Forcepoint Behavioral Analytics event API and Risk Exporter API SSL certificates need to be trusted.

  4. Setup script below will install the program prerequisites and run the program, run with a user with administrative privileges.

    /opt/fp-fba-failed-logins-importer-ping/deploy/setup.sh

Implementation – Docker

Please note: an NFS Server is required on the PingFederate Server.

  1. Login into docker repository, you’ll be asked to enter your username and password (provided below):

    docker login docker.frcpnt.com

      $ Username: fp-integrations
  $ Password: t1knmAkn19s

  2. Create a new file named user-config.sh and insert the following contents:

    #!/usr/bin/env bash
    
# Location of Ping Identity logs that will be mounted to the container, leave this value below as it is
_PING_AUDIT_LOG_DIR='/mnt/ping/logs'    
# Forcepoint Behavioral Analytics Event API e.g. https://fba-event-api-hostname:9000
_FBA_EVENT_API=''
# Forcepoint Behavioral Analytics Risk Exporter API e.g. https://risk-exporter-api-hostname:5000
_RISK_EXPORTER_API=''
# Forcepoint Risk Score Source e.g. fba or casb
_FORCEPOINT_RISK_SCORE_SOURCE=''
# HTML Identity Provider Adapter ID e.g. HTMLFormSimplePCV
_IDP_HTML_FORM_ID=''
# MFA Identity Provider Adapter ID if it's available, otherwise it can stay empty
_IDP_MFA_ID=''
# Enable logging for this service e.g. true or false
_ENABLE_LOGGING=true

    The exact value for the Adapter ID entries can be found logging into web console of Ping Federate > Identity Provider > Integration > Adapters

    Add the relevant values to each line before saving.

  3. Run the container with either one of the following commands, depending on your scenario

  • if user-config.sh file is located locally, then run the command below, replacing:
    1. <user-config.sh-full-path> with the full path of the user-config.sh
    2. <ping-server-host-name:nfs_log_dir> with the hostname or IP address of the machine hosting PingFederate and the audit log directory path. Note the hostname and the log directory path are separated by :
      docker run --detach --cap-add=SYS_ADMIN --security-opt apparmor:unconfined \
  --env PING_NFS_MAPPING=<ping-server-host-name:nfs_log_dir> \
  --name fp-fba-failed-logins-importer-ping \
  --restart always \
  --volume <user-config.sh-full-path>:/usr/fp-fba-failed-logins-importer-ping/user-config.sh \
  docker.frcpnt.com/fp-fba-failed-logins-importer-ping
  • if user-config.sh file is accessed by a URL, then run the command below, replacing:
    1. <config-file-url> with URL of the user-config.sh
    2. <ping-server-host-name:nfs_log_dir> with the hostname or IP address of the machine hosting PingFederate and the audit log directory path. Note the hostname and the log directory path are separated by :
      docker run --detach --cap-add=SYS_ADMIN --security-opt apparmor:unconfined \
  --env CONFIG_FILE_URL_LOCATION=<config-file-url> \
  --env PING_NFS_MAPPING=<ping-server-host-name:nfs_log_dir> \
  --name fp-fba-failed-logins-importer-ping \
  --restart always \
  docker.frcpnt.com/fp-fba-failed-logins-importer-ping

Troubleshooting

Follow these steps to identify issues impacting the normal operation of the integration described in this document.

Docker Implementation

Validate the prerequisites

Make sure the prerequisites described in the Summary chapter are all satisfied:

  • Check the versions of Forcepoint Behavioral Analytics and Ping Federate in use are listed as compatible

    Forcepoint Behavioral Analytics 3.1.0
  
Ping Federate 9.2 or 10.0

  • Verify the integration component correctly operates on a linux based machine with an existing docker setup and meets the minimum hardware requirements of 2GB RAM, 20GB free storage and the system needs to be 64-bit

  • The Forcepoint Behavioral Analytics event API and Risk Exporter API SSL certificates need to be trusted by the ping host machine

Check network connectivity

Make sure firewalls or other security appliances are not impacting the network connectivity necessary for the operation of all components involved into this integration:

  • Check the host machine (which has ping Federate appliance) has network connectivity to the Risk Exporter API and Forcepoint Behavioral Analytics API.

    Execute the following commands on the host machine:

    curl -I https://<Risk Exporter hostname or IP>:5000

    curl -I https://<Forcepoint Behavioral Analytics Streaming Ingest Public API Hostname>:9000

    Replacing the Risk Exporter hostname and Forcepoint Behavioral Analytics Streaming Ingest Public API Hostname with the ones in use. Please check the first line of the result of both the commands above is:

    HTTP/1.0 200 OK

Check all components are configured and running properly

Make sure the products and services involved into this integration are configured as expected and they are running:

  • Check the risk exporter API is configured and running properly: Check there are no errors on the following page:

    Replacing the <ping federate host machine ip> with the one in use. Check that the following messages appear on the healthcheck URL:

    https://<ping federate host machine ip>:5000/casb/healthcheck

    casb-url available - OK

    casb-url connection is successful - OK

  • Check the logs for fp-fba-failed-logins-importer-ping container:

      docker logs fp-fba-failed-logins-importer-ping | tail

    Check the output is similar to the one below and has no errors:

    crond\[41\]: line
/usr/fp-fba-failed-logins-importer-ping/source/run-fba-ping-mfa-batch-events.sh  
crond\[41\]: wakeup dt=60  
crond\[41\]: file root:  
crond\[41\]: line run-parts /etc/periodic/15min  
crond\[41\]: line run-parts /etc/periodic/hourly  
crond\[41\]: line run-parts /etc/periodic/daily  
crond\[41\]: line run-parts /etc/periodic/weekly  
crond\[41\]: line run-parts /etc/periodic/monthly  
crond\[41\]: line
/usr/fp-fba-failed-logins-importer-ping/source/run-fba-ping-batch-events.sh  
crond\[41\]: line
/usr/fp-fba-failed-logins-importer-ping/source/run-fba-ping-mfa-batch-events.sh

  • Check the logs for fp-riskexporter-api container:

      docker logs fp-riskexporter-api | tail

    Check the output is similar to the one below and has no errors:

    Configs Initialized

Appendix – Sample events from different types of login failures

  • Failed login event from authentication attempt with username and password

  • Failed to verify during MFA stage after username and password authentication is successful, two events are sent:

    First, an event from a success login with username and password (data provided by the Identity Adapter):

    Then, an event from the failed attempt at MFA stage (from the audit.log file):

    In the case of MFA, failure is derived from two scenarios: the wrong response to the

    Authentication challenge, or the lack of response (e.g. the case of a malicious user who desists

    from logging in once opposed with MFA).

  • Failed authentication due to lockout after multiple failed attempts (please note the events are listed from the most recent to the last recent one)