Forcepoint User ID Service and Cisco Identity Services Engine pxGrid

Table of contents

Forcepoint User ID Service and Cisco Identity Services Engine pxGrid
Summary
Demo
Source Code
Caveats
Requirements
Create Forcepoint User ID Service API user
Verify Cisco ISE hostname is resolvable
Implementation options
1. Implementation – Docker
2. Implementation - Traditional
Troubleshooting
1. Docker Implementation
2. Traditional Implementation

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	20 April 2021	Dlo Bagari	First draft
0.2	22 April 2021	Mattia Maggioli	Review
0.3	29 April 2021	Neelima Rai	Added Troubleshooting chapter

Summary

This guide provides step by step instructions to integrate Cisco Platform Exchange Grid (pxGrid) with Forcepoint User Identity Service (FUID), in order to make FUID capable of receiving user information from Cisco pxGrid by using Cisco pxGrid REST API, and use this information for identity-based access control in Forcepoint NGFW security policies.

The code and instructions provided enable system administrators to automatically:

Register FUID as pxGrid service consumer for ISE session events (AUTHENTICATED/DISCONNECTED)
Add/Remove IP address information associated to user entities inside FUID database

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

Demo

Source Code

fp-bd-fuid-cisco-pxgrid

Caveats

The integration described in this document was developed and tested with the following products:

Forcepoint User ID Service v2
Cisco Identity Services Engine v2.7
Golang 1.15
Docker version version 20.10.6
Docker Compose version 1.29.1

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.

configuration of appropriate hygiene procedures to handle logs produced during any step of the solution workflow
monitoring of the scripts, services, and applications involved in the solution

Requirements

Two implementation options are provided in this document

Docker – leverages docker images where the integration component is already installed with all necessary dependencies.
Traditional – requires the manual deployment of the integration component inside a Centos server 7.3 host-machine.

Create Forcepoint User ID Service API user

Enter the following command:
```
fuid-cfg api add-user
```
Enter a username for the API user
Enter a password for the API user

the API user is added to the configuration.

Verify Cisco ISE hostname is resolvable

The machine hosting the integration must be able to reach the Cisco ISE Server over the network, therefore its hostname must be resolvable into an IP address. In order to do this, either configure an entry in your local DNS server, or manually add an entry into the /etc/hosts file of the machine.

Open /etc/hosts in the integration host machine.
Scroll down to the end of the file and add a new entry in this format: IP_ADDRESS HOSTNAME
- replace IP-ADDRESS: with the Ip address of your Cisco ISE Server
- replace HOSTNAME: with the hostname of your Cisco ISE Server.
Save the changes

Implementation options

Two implementation options are provided in this document

Docker – leverages a docker image where the integration component is already installed with all necessary dependencies: the user must only edit the configuration files and run the container on an existing docker setup
Traditional – requires manual deployment of the integration component inside a clean host machine (recommended) or an existing one, provided all requirements are satisfied.

Implementation – Docker

The solution described in this chapter requires

A Linux machine (Centos 7.3 recommended) with at least 20GB free disk space and 2 GB RAM. This machine will be referenced in the rest of this document as the docker-host machine.
Docker Engine must be installed on the docker-host machine, visit docker-installation-docs to install Docker Engine on docker-host
Docker-compose must be installed on the docker-host machine, visit docker-compose-installation-docs to install docker-compose on docker-host machine

Step 1: Download Docker Compose files

Download fp-fuid-cisco-pxgrid-docker.tar.gz file
Decompress the fp-fuid-cisco-pxgrid-docker.tar.gz file with the following command:
```
tar -zxvf fp-fuid-cisco-pxgrid-docker.tar.gz 
```

The output of the above command is a directory named fp-fuid-cisco-pxgrid-docker

Step 2: Creating the pxGrid client Account

The initial pxGrid client account will be created and the username/password returned will be used to perform further REST calls.

Use the following command and credentials to login into the Docker registry hosting the containers needed for this integration
```
root@linux:~# docker login docker.frcpnt.com
Username: fp-integrations
Password: t1knmAkn19s
```
Change your current directory to fp-fuid-cisco-pxgrid-docker
```
cd fp-fuid-cisco-pxgrid-docker  
```
Execute the following command to create a pxGrid Client Account.
- replace ISE-HOST with the DNS-Name or the IP address of your Cisco ISE server
- replace USERNAME with a username. this username will be used as username for client account. for example: pxgrid-client
```
docker-compose run pxgrid-service fuid-ise pxgrid create-client -i --server ISE-HOST --username USERNAME
```

the output of the above command will contain Username & Password for pxGrid REST API. These values will be stored in .env file which is explained in Step 4 of this document.

 INFO[0000] Created  pxGrid client ccount with name 'pxgrid-client'                                          
 INFO[0003] pxgrid client account 'pxgrid-client' has been activated                                         
 WARN[0003] Contact your ISE Administrator to approve the created account                                    
 ********* pxGrid API login Information are ********                                                         
 UserName:  pxgrid-client                                                                                    
 Password:  gsd5T0KbHg7uKaSw                                                                                 
                                                                                                             
 save your ISE API login information in somewhere save.                                                      
 Created client account status is PENDING, the ISE Administrator needs to approve the created client account

Step 3: Approve the client account for Username & Password

Login to your Cisco ISE Portal and navigate to Administration > pxGrid Services, note that the client account is in the pending state, select the client account and click on Approve to approve the client account for username & password.

Once the created client account has been approved, make sure the client account has permission to do operation on com.cisco.ise.session service. if the client account does not have that permission, assign the permission to a client group and add the client account to that group.

Step 4: Define the required environment variables

In the fp-fuid-cisco-ise-pxgrid-docker directory, open .env file
```
vi .env 
```

Change the value of the environment variables inside .env. The following table explains each variable and defines if they need to be changed

Variable Name	Description	Requires to be changed
PXGRID_CLIENT_ACCOUNT_NAME	The name of pxGrid API Client which is created in Step 2	YES
PXGRID_CLIENT_ACCOUNT_PASSWORD	The password for pxGrid API Client which is created in Step 2	YES
PXGRID_HOST_ADDRESS	The DNS Name or IP address for Cisco ISE server	YES
FUID_API_USERNAME	Forcepoint User ID Service API username which is created in section 'Create Forcepoint User ID Service API user'	YES
FUID_API_PASSWORD	Forcepoint User ID Service API password is created in section 'Create Forcepoint User ID Service API user'	YES
FUID_IP_ADDRESS	Ip address for Forcepoint User ID Service API	YES
AD_LDAP_USER_DN	The LDAPs user DN, to bind LDAPs connection with this user. for example: CN=Username,CN=Users,DC=domaincontroller,DC=local	YES
AD_LDAP_PASSWORD	The LDAPs user password	YES
AD_LDAP_HOST	The IP address for the machine which hosts your Windows Active Directory Domain Controller	YES
AD_DOMAIN_NAME	Your Active Directory Domain Name	YES
SESSION_LISTENER_INTERVAL_TIME	This parameter defines how frequently to ask pxGrid if there is any new session events, the default value is 3 seconds	NO
SAVE_LOGS	Save the integration logs into the integration host machine in file /root/fuid-ise-logs/logs.	NO
DISPLAY_INFO	To display information about the process flow.	NO
IGNORE_UNKNOWN_SESSIONS	Ignore sessions where the user is not a member of the Active directory. default value is true	NO

Save and close .env

Step 3: Start Services

Run the following command to start the docker container and run the integration service

docker-compose run pxgrid-service fuid-ise pxgrid consumer

Once the pxgid-service has started, you will see the following output:

INFO[0000] PxGrid API Client Account pxgrid-client is Activated and Enabled 
INFO[0000] service lookup: found 1 services                                 
INFO[0000] Using restBaseUrl: https://ise.iselab.local:8910/pxgrid/mnt/sd   

Now the fuid-pxgid-service is ready and watching for any ‘AUTHENTICATED’ or ‘DISCONNECTED’ session events.

for AUTHENTICATED events: the integration will add IP address information to the corresponding user by using FUID API.
for DISCONNECTED events : the integration will remove the IP address information from the corresponding user by using FUID API.

Note: the docker-compose service will create the following directories under docker host-machine root directory:

/root/fuid-ise-logs: this directory will store logs

/root/latest-timestamp: this directory will be used to store sessions timestamp

IMPORTANT: DO NOT REMOVE THE ABOVE DIRECTORIES FROM YOUR DOCKER HOST

Implementation - Traditional

The solution described in this chapter requires:

Centos 7.3 machine with at least 20GB free disk space and 2 GB of RAM. This machine will be referenced in the rest of this document with the name host-machine.

Step 1: Download the source code

Download fp-fuid-cisco-pxgrid-tr.tar.gz file which contains the following file:

fuid-ise: a service to subscribe to Pxgrid session
fuid-ise.yml: the config file for fuid-ise service
fuid-ise.service: a systemd service file for fuid-ise service
fp-fuid-ise-installer.sh: bash script which configures the host-machine for this integration.

Step 2: Creating the pxGrid client Account

The initial pxGrid client account will be created and the username/password returned will be used to perform further REST calls.

Decompress the source code file: this will create a directory with the name fp-fuid-cisco-pxgrid-tr which contains all required files for this implementation
```
tar -zxvf fp-fuid-cisco-pxgrid-tr.tar.gz
```
Change your current directory to fp-fuid-cisco-pxgrid-tr
```
cd fp-fuid-cisco-pxgrid-tr
```
make fuid-ise executable:
```
chmod +x fuid-ise
```
Execute the following command to create a pxGrid Client Account.
- replace ISE-HOST with the DNS-Name or the IP address of your Cisco ISE server
- replace USERNAME with a username. this username will be used as username for client account. for example: pxgrid-client
```
./fuid-ise pxgrid create-client -i --server ISE-HOST --username USERNAME
```

the output of the above command will contain Username & Password for pxGrid REST API. These values will be stored in fuid-ise.yml file which is explained in Step 4.

 INFO[0000] Created  pxGrid client ccount with name 'pxgrid-client'                                          
 INFO[0003] pxgrid client account 'pxgrid-client' has been activated                                         
 WARN[0003] Contact your ISE Administrator to approve the created account                                    
 ********* pxGrid API login Information are ********                                                         
 UserName:  pxgrid-client                                                                                    
 Password:  gsd5T0KbHg7uKaSw                                                                                 
                                                                                                             
 save your ISE API login information in somewhere save.                                                      
 Created client account status is PENDING, the ISE Administrator needs to approve the created client account

Step 3: Approve the client account for Username & Password

Step 4: Edit fuid-ise.yml file

Edit fuid-ise.yml config file
```
vi fuid-ise.yml 
```

Change the value of parameters inside fuid-ise.yml. The following table explains each parameter and defines if they need to be changed.

Variable Name	Description	Requires to be changed
PXGRID_CLIENT_ACCOUNT_NAME	The name of pxGrid API Client which is created in the step 2	YES
PXGRID_CLIENT_ACCOUNT_PASSWORD	The password for pxGrid API Client which is created in the step 2	YES
PXGRID_HOST_ADDRESS	The DNS Name or IP address for Cisco ISE server	YES
FUID_API_USERNAME	Forcepoint User ID Service API username which is created in section 'Create Forcepoint User ID Service API user'	YES
FUID_API_PASSWORD	Forcepoint User ID Service API password is created in section 'Create Forcepoint User ID Service API user'	YES
FUID_IP_ADDRESS	Ip address for Forcepoint User ID Service API	YES
AD_LDAP_USER_DN	The LDAPs user DN, to bind LDAPs connection with this user. for example: CN=Username,CN=Users,DC=domaincontroller,DC=local	YES
AD_LDAP_PASSWORD	The LDAPs user password	YES
AD_LDAP_HOST	The IP address for the machine which hosts your Windows Active Directory Domain Controller	YES
AD_DOMAIN_NAME	Your Active Directory Domain Name	YES
SESSION_LISTENER_INTERVAL_TIME	This parameter defines how frequently to ask pxGrid if there is any new session events, the default value is 3 seconds	NO
SAVE_LOGS	Save the integration logs into the integration hosted machine in file /root/fuid-ise-logs/logs	NO
DISPLAY_INFO	To display information about the process flow	NO
IGNORE_UNKNOWN_SESSIONS	Ignore sessions where the user is not a member of the Active directory. default value is true	NO

Save fuid-ise.yml

Step 5: Run installation script

Make fp-fuid-pxgrid-installer.sh executable
```
chmod +x fp-fuid-pxgrid-installer.sh 
```
Execute fp-fuid-pxgrid-installer.sh script
```
./fp-fuid-pxgrid-installer.sh 
```

Step 6: Reboot the host-machine

Reboot the host-machine and the integration will start automatically, to verify execute the following command:

systemctl status fuid-ise.service

the status of the fuid-ise service must be Active (running).

Note: the integration logs are stored in /var/fuid-ise/fuid-ise-logs/logs

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 User ID Service and Cisco ISE in use are listed as compatible
```
Forcepoint User ID Service v2
Cisco Identity Services Engine v2.7
```

Docker images for this integration have been tested with

Docker version version 20.10.6
Docker Compose version 1.29.1

The docker implementation has been tested on a CentOS 7.3 machine with at least 2 GB RAM, 20 GB of storage and docker engine installed
User needs to be root in the docker host machine to install this integration
If the user uses pxgrid or FUID with hostnames instead of IP addresses, verify the hostnames can be resolved correctly
Check the user can download the file with the below command:

wget –content-disposition https://github.com/Forcepoint/fp-bd-fuid-cisco-pxgrid/blob/master/source_code/fp-fuid-cisco-pxgrid-docker.tar.gz

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 docker host machine has connectivity to the ISE server: execute the following command on docker host machine:

ping -c 2 <PXGRID_HOST_ADDRESS>

Once done check the result is similar to below:

PING <PXGRID_HOST_ADDRESS> (10.10.120.12) 56(84) bytes of data.
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=179 ms
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=181 ms

Check the docker host machine has connectivity to the FUID_IP_ADDRESS: execute the following command on docker host machine:

ping -c 2 <FUID_IP_ADDRESS>

Once done check the result is similar to below:

PING <FUID_IP_ADDRESS> (10.10.120.12) 56(84) bytes of data.
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=179 ms
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=181 ms

Check dependencies are installed

Make sure the software dependencies needed by the components involved into this integration are installed:

Check the host machine has docker installed: Execute the following command on the host machine:

docker –version

Check the output is similar to below:

Docker Version 20.10.06, biuld c 370c289

Check the host machine has docker-compose installed: Execute the following command on the host machine:

docker-compose –version

Check the output is similar to below:

docker-compose version 1.26.0, biuld d4451659

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 there are no errors after running the command:

docker-compose run pxgrid-service fuid-ise pxgrid consumer

the output of the above should look like below:

Traditional Implementation

Validate the prerequisites

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

Check the versions of Forcepoint User ID Service and Cisco ISE in use are listed as compatible
```
Forcepoint User ID Service v2
Cisco Identity Services Engine v2.7
```
Verify the integration is correctly operating on a CentOS 7.3 machine with at least 2 GB RAM and 20 GB of storage
User needs to be root in the host machine to install this integration
If the user uses pxgrid or FUID with hostnames instead of IP addresses, verify the hostnames can be resolved correctly
Check the user can download the file with the below command:

wget –content-disposition https://github.com/Forcepoint/fp-bd-fuid-cisco-pxgrid/blob/master/source_code/fp-fuid-cisco-pxgrid-tr.tar.gz

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 docker host machine has connectivity to the ISE server: execute the following command on docker host machine:

ping -c 2 <PXGRID_HOST_ADDRESS>

Once done check the result is similar to below:

PING <PXGRID_HOST_ADDRESS> (10.10.120.12) 56(84) bytes of data.
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=179 ms
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=181 ms

Check the docker host machine has connectivity to the FUID_IP_ADDRESS: execute the following command on docker host machine:

ping -c 2 <FUID_IP_ADDRESS>

Once done check the result is similar to below:

PING <FUID_IP_ADDRESS> (10.10.120.12) 56(84) bytes of data.
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=179 ms
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=181 ms

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 systemd service fuid-ise is running without any problem by executing this command:

systemctl status fuid-ise.service

the status of the fuid-ise service must be Active (running).