web security appliance and identity services engine …...user template and alter the properties to...

© 2018 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. of 31

Web Security Appliance and Identity Services Engine Passive

Identity Connector Integration

Guide


Contents

About this document ............................................................................................................................................... 3

Prerequisites ............................................................................................................................................................ 4

ISE-PIC Installation .................................................................................................................................................. 4

Configure Domain and Groups (ISE-PIC) .............................................................................................................. 5

Configure WMI (ISE-PIC) ......................................................................................................................................... 6

Enabling ERS (ISE-PIC) ........................................................................................................................................... 6

CA-Signed Certificates ............................................................................................................................................ 8

Creating the pxGrid Certificate Template (AD) ...................................................................................................... 9

Import Trusted Root Certificate (ISE-PIC) ............................................................................................................ 12

Import Trusted Root Certificate (WSA) ................................................................................................................ 13

pxGrid Certificate Creation (ISE-PIC) ................................................................................................................... 14

ERS Certificate Creation (ISE-PIC) ....................................................................................................................... 16

pxGrid Certificate Creation (WSA)........................................................................................................................ 16

Configure ERS and Test Connectivity (WSA) ...................................................................................................... 19

Self-Signed Certificates ......................................................................................................................................... 21

pxGrid Certificate Creation (WSA)........................................................................................................................ 21

Configure ERS and Test Connectivity (WSA) ...................................................................................................... 23

WSA Policy Configuration .................................................................................................................................... 25

Identification Profile .............................................................................................................................................. 25

Decryption Policy .................................................................................................................................................. 26

Access Policy ......................................................................................................................................................... 27

Verification ............................................................................................................................................................. 29

Conclusion ............................................................................................................................................................. 31


About this document

This document is for Cisco engineers and customers who will deploy the Cisco® Identity Services Engine Passive

Identity Connector (ISE-PIC) and Cisco Web Security Appliance (WSA) in their environments and wish to integrate

the two solutions. ISE-PIC enables the deployment of the WSA without the need for direct authentication with

Active Directory (AD) servers. ISE-PIC can learn about domain user authentication events from AD, and this

information can be shared with the WSA to enable Single Sign-on (SSO) functionality for the users.

This document covers:

● ISE-PIC virtual machine installation and domain configuration

● Deployment using certificates signed by a certificate authority

● Deployment using self-signed certificates

● WSA policy configuration using ISE group information


Prerequisites

Before beginning with this guide, a few basic configuration steps must be completed on the Web Security

Appliance (WSA). Basic network settings must be in place (IP address, gateway, Domain Name System [DNS] and

Network Time Protocol [NTP] servers), as well as any required licenses installed. The System Setup Wizard should

be completed and the HTTPS proxy enabled.

The versions used in this guide are as follows:

WSA: 11.7.0

ISE-PIC: 2.4.0.357

Windows Server: 2016 Standard

ISE-PIC Installation

ISE-PIC is available as both an OVA template and ISO image for installation in VMWare or Linux KVM

environments. The administrator should refer to the Cisco ISE-PIC Administrator’s Guide and the Cisco Identity

Services Engine Installation Guide for the specific resource requirements of each of these image deployment

types. Once the image is ready to boot, follow these instructions:

1. At the console, the following message is displayed:

[1] Cisco ISE-PIC Installation (Keyboard/Monitor)

[2] Cisco ISE-PIC Installation (Serial Console)

[3] System Utilities (Keyboard/Monitor)

[4] System Utilities (Serial Console)

2. Type 2 and press Enter. The following prompt will appear:

**********************************************

Please type 'setup' to configure the appliance

**********************************************

3. Type setup to begin the configuration.

4. Follow the prompts to configure the appliance per the network requirements. Once completed, the appliance

will reboot automatically.

5. When the appliance completes the reboot cycle, verify that all processes have started using the show

application status ise command:

ise-pic/admin# show application status ise

ISE PROCESS NAME STATE PROCESS ID

--------------------------------------------------------------------

Database Listener running 5072

Database Server running 90 PROCESSES

Application Server running 9117

AD Connector running 14187

Certificate Authority Service running 9947

M&T Session Database running 6408

M&T Log Collector running 10166

M&T Log Processor running 10057

pxGrid Infrastructure Service running 22303


pxGrid Publisher Subscriber Service running 22575

pxGrid Connection Manager running 22516

pxGrid Controller running 22625

PassiveID WMI Service running 10498

PassiveID Syslog Service running 11483

PassiveID API Service running 12176

PassiveID Agent Service running 13046

PassiveID Endpoint Service running 13557

PassiveID SPAN Service running 13993

6. The administrator can now access the ISE-PIC Graphical User Interface (GUI) using HTTPS.

Configure Domain and Groups (ISE-PIC)

ISE-PIC provides a wizard that walks through the initial configuration of the Active Directory provider and group

selection. This wizard is available at Home > Passive Identity Wizard. In order to configure these options

manually (without the wizard), follow these steps:

1. Navigate to Providers > Active Directory.

2. Click Add.

3. Provide a name for the join point and for the domain to be joined.

4. Confirm and provide credentials with permission to join the domain.

5. Verify that the domain is shown as Operational.

6. Click on the Groups tab.

7. Click on Add and Select Groups From Directory.


8. Use the Name Filter and Retrieve Groups button to search the directory for the desired groups.

9. Click OK and Save.

Configure WMI (ISE-PIC)

The Windows Management Instrumentation service (WMI) on the domain controller must be correctly

configured to allow ISE-PIC to retrieve the required information. In order to complete any required changes, follow

these steps:

1. Navigate to Providers > Active Directory.

2. Check the box next to the domain join point and click Edit.

3. Click on the PassiveID tab, check the box next to the domain name, and click Config WMI.

4. When completed, click OK.

Note: If the WMI procedure fails, ensure that the account used to join the domain has sufficient privileges to make

changes to the WMI configuration on the server.

Enabling ERS (ISE-PIC)

The External RESTful API Service (ERS) is an API that can be queried by the WSA for group information. ERS is

also disabled by default in ISE-PIC. Once it is enabled, clients may query the API if they authenticate as members

of the ERS Admin group on the ISE-PIC node. To enable the service on ISE-PIC and add an account to the

correct group, follow these steps:

1. Navigate to Settings > ERS Settings.

2. Select the option Enable ERS for Read/Write.


3. Click Save and confirm with OK.

4. Navigate to Administration > Admin Access > Admin Users.

5. Click Add and select Admin User from the drop-down.

6. Enter a username and password in the appropriate fields.

7. In the Admin Groups field, use the drop-down to select ERS Admin.


8. Click Submit.

CA-Signed Certificates

Certificates are central to all communication between the WSA and ISE-PIC. The Platform Exchange Gird

(pxGrid) service is mutually authenticated using both a client and server certificate, and the ERS service is

authenticated using a server certificate. In most cases, an administrator will have a certificate authority in their local

domain that is integrated with Active Directory (AD). This section will provide steps for configuring the required

certificate template for pxGrid in Windows Server 2016, as well as generating and signing the Certificate Signing

Requests (CSRs).

Note: If the intention is to use the built-in certificate authority provided by ISE-PIC, the administrator should

proceed to the next section.


Creating the pxGrid Certificate Template (AD)

A template must be specified when issuing a certificate from the Active Directory certificate authority. The template

to be used in signing the pxGrid certificates must include both Client Authentication and Server Authentication

key usage parameters. The simplest way to create a template with the required parameters is to copy the built-in

User template and alter the properties to fit the requirements of pxGrid. To do this using the Active Directory

certificate authority, follow these steps:

1. Using the Certificate Authority snap-in, click on Certificate Templates.

2. In the center pane, right-click and select Manage.

3. In the center pane, right-click on the User template and click Duplicate Template.


4. In the General tab, change the name to pxGrid or any other unique name.

5. On the Request Handling tab, uncheck Allow public key to be exported.


6. On the Extensions tab, click on Application Policies and click on Edit.

7. Click Add and add Server Authentication to the list of policies.

8. Remove any other application policies except for Server Authentication and Client Authentication.

9. On the Subject Name tab, select Supply in the request.


10. Save and close the template.

11. In the Certificate Templates snap-in, right-click and select New > Certificate Template to Issue.

12. Click the new pxGrid template and click OK.

To sign the CSR with the new template, save the CSR in a directory that is accessible by the signing server and

use the certreq.exe utility to sign it and save the resulting certificate. In the following example, the CSR is located

at Z:\Certs\picpxGrid.csr:

certreq.exe -submit -attrib certificatetemplate:pxgrid Z:\Certs\picpxGrid.csr

Import Trusted Root Certificate (ISE-PIC)

The root certificate and any intermediate certificates must also be trusted by ISE-PIC in order to complete the trust

chain. Follow these steps to install the root Certificate Authority (CA) certificate in the ISE-PIC Trusted Root

Authorities Store:

1. Navigate to Certificates > Trusted Certificates.

2. Click Import.

3. Click Browse to locate the CA certificate file in PEM format.

4. Optionally enter a Friendly Name to identify the certificate.

5. Ensure that both Trust for authentication with ISE and Trust for client authentication and Syslog are

checked.


6. Click Submit.

Import Trusted Root Certificate (WSA)

If the integration design uses an internal certificate authority as the root of trust for the connection between the

WSA and ISE-PIC, then this root certificate must be installed on both appliances. Follow these steps to install the

root CA certificate in the WSA Trusted Root Authorities Store:

1. Navigate to Network > Certificate Management > Manage Trusted Root Certificates.

2. Click on Import.

3. Use Browse to locate the certificate (in PEM format) and click Submit.

Note: If any intermediate certificates are present between the root CA and the certificates issued to clients, they

must also be uploaded here.

4. Submit and Commit changes.


pxGrid Certificate Creation (ISE-PIC)

The pxGrid service utilizes client-side certificates for mutual authentication. Next, the client-side certificates will

need to be generated and signed by the root CA. To generate the key pair and certificate signing request on ISE-

PIC, follow these steps:

1. Navigate to Certificates > Certificate Signing Requests.

2. Click on Generate Certificate Signing Requests.

3. In the Usage section, use the drop-down menu to select pxGrid.

4. In the Node(s) section, select the desired ISE-PIC node for pxGrid services.

5. Complete the certificate fields as required and select the desired key length.

6. Click Generate and Export.

To sign the CSR with the pxGrid template, save the CSR in a directory that is accessible by the signing server and


at Z:\Certs\picpxGrid.csr:

certreq.exe -submit -attrib certificatetemplate:pxgrid Z:\Certs\picpxGrid.csr


Follow the resulting prompts to save the certificate. To bind the certificate to the CSR in ISE, follow these steps:

1. Navigate to Certificates > Certificate Signing Requests.

2. Select the CSR that was generated previously and click Bind Certificate.

3. Use Choose Certificate to locate the certificate file.

4. Optionally provide a Friendly Name.

5. Ensure that the Usage section specifies pxGrid.

6. Click Submit.

At this point, ISE-PIC should be using the CA-signed certificate for pxGrid communication. You can confirm this by

navigating to Certificates > System Certificates and checking the Used By column.


ERS Certificate Creation (ISE-PIC)

The ERS service is accessed over a Transport Layer Security (TLS) tunnel, and is authenticated with a server-

side certificate. The ISE-PIC node will use the same Admin certificate used for its web management interface to

authenticate the ERS connection. This certificate must also be trusted by the WSA. The process for generating this

certificate is the same as is documented in the previous section, with two important differences. The first difference

is that Admin should be selected in the Usage section.

The second difference is that the CSR should be signed using the built-in WebServer certificate template in

Windows Server:

certreq.exe -submit -attrib certificatetemplate:webserver Z:\Certs\iseAdmin.csr

pxGrid Certificate Creation (WSA)

In the WSA, the creation of the key pair and certificate for use by pxGrid is completed as part of the ISE services

configuration. To complete the configuration, follow these steps:

1. Navigate to Network > Identity Services Engine.

2. Click Enable and Edit Settings.

3. Enter the ISE server name in the Primary ISE pxGrid Node field.

4. Click Choose File in the ISE pxGrid Node Certificate section.

5. Locate the root CA certificate in PEM format and click Upload File.


Note: A common misconfiguration is to upload the ISE-PIC pxGrid certificate in this section. The root CA

certificate must be uploaded to the ISE pxGrid Node Certificate field.

Note: In WSA 11.7, all references to the monitoring node have been removed from the ISE settings page. Any

previous references have also been removed from the Command Line Interface (CLI).

6. You may optionally configure a secondary pxGrid node on this page.

7. In the WSA Client Certificate section, select Use Generated Certificate and Key.

8. Click Generate New Certificate and Key and complete the required certificate fields.

9. Click Download Certificate Signing Request.

Note: At this point, it is a good idea to use the Submit button to commit the changes to the ISE configuration. If

the session is left to timeout before the changes are submitted, the keys and certificate that were generated will

be lost, even if the CSR was downloaded.


To sign the CSR with the new template, save the CSR in a directory that is accessible by the signing server and


at Z:\Certs\wsapxGrid.csr:

certreq.exe -submit -attrib certificatetemplate:pxgrid Z:\Certs\wsapxGrid.csr

Follow the resulting prompts to save the certificate. To bind the certificate to the CSR in the WSA, follow these

steps:


2. Click Edit Settings.

3. In the WSA Client Certificate section, use the Choose File option to locate the file in PEM format.

4. Click Upload File.

5. Submit and Commit.

At this point, the WSA should be attempting to communicate with ISE-PIC over pxGrid. With default settings,

pxGrid clients must be manually approved. To manually approve the WSA as a pxGrid client, follow these steps:

1. Navigate to Subscribers.

2. Check the box next to the WSA and click Approve.

3. Confirm by clicking OK.


Additionally, it is possible to allow all certificate-authenticated clients to be auto-approved by following these steps:

1. Navigate to Subscribers > Settings.

2. Check the box for Automatically approve new certificate-based accounts.

3. Click Save.

4. Confirm by clicking Yes.

Note: The auto-approve setting cannot be set if there are pending clients. Approve any pending requests before

changing the setting.

Configure ERS and Test Connectivity (WSA)



3. Check the box next to Enable External Restful Service (ERS).

4. In the ERS Administrator Credentials field, enter the user information that was configured on ISE.

5. If the node is the same as the pxGrid node, check the box for Server name same as ISE pxGrid Node.

Otherwise, enter the required information there.


The administrator can now test the connection from the WSA to ISE-PIC over both pxGrid and ERS. This test can

be run by navigating to Network > Identity Services Engine > Edit Settings and clicking on Start Test at the

bottom of the page. Successful output will resemble the following:

Checking DNS resolution of ISE pxGrid Node hostname(s)...

Success: Resolved 'ise-pic.chclasen.lab' address: 192.168.0.201

Validating WSA client certificate...

Success: Certificate validation successful

Validating ISE pxGrid Node certificate(s)...



Checking connection to ISE pxGrid Node(s)...

Trying primary PxGrid server...

Preparing TLS connection...

Completed TLS handshake with PxGrid successfully.

Trying download user-sessions...

Failure: Failed to download user-sessions.

Trying download SGT...

Able to Download 17 SGTs.

Trying connecting to primary ERS service...

Trying download user-groups...

Able to Download 9 user-groups.

Success: Connection to ISE pxGrid Node was successful

Test completed successfully.

The status of the pxGrid and ERS connection, as well as a list of Security Group Tags (SGTs) and groups that

have been pulled from ISE-PIC, can be checked using the isedata CLI subcommands:

- STATISTICS - Show the ISE server status and ISE statistics.

- CACHE - Show the ISE cache or check an IP address.

- SGTS - Show the ISE Secure Group Tag (SGT) table.

- GROUPS - Show the ISE Groups table.


Self-Signed Certificates

If the administrator does not wish to use an in-house certificate authority, it is possible to complete the

configuration using the built-in self-signed certificate provided by ISE-PIC. This is done by leveraging the built-in

certificate authority on the ISE-PIC node. This section is not necessary if the previous section was used to install

CA-signed certificates.

pxGrid Certificate Creation (WSA)

The pxGrid service utilizes client-side certificates for mutual authentication. ISE-PIC provides a means to generate

a PKCS12 file that contains the ISE-PIC certificate chain, as well as the key pair and certificate to be used by the

WSA pxGrid client. To generate this file and extract the key and certificates, follow these steps:

1. On ISE, navigate to Subscribers > Certificates.

2. In the I want to field, use the drop-down to choose Generate a single certificate (without a certificate

signing request).

3. Complete the certificate fields as required.

4. In the Certificate Download Format section, use the drop-down to choose PKCS12 Format.

5. Enter a password.

6. Unzip the archive file that is downloaded.

7. Use openSSL to extract the certificates and private key from the PKCS file (in the example, the file is

wsa2.p12):

Extract the ISE-PIC CA certificate chain:

openssl pkcs12 -in wsa2.p12 -cacerts -nokeys -out ise-ca.cer

Extract the WSA pxGrid certificate:

openssl pkcs12 -in wsa2.p12 -clcerts -nokeys -out wsa2.cer

Extract the WSA pxGrid private key:

openssl pkcs12 -in wsa2.p12 -nocerts -nodes -out wsa2.key


8. On the WSA, navigate to Network > Certificate Management > Manage Trusted Root Certificates.

9. Click on Import.

10. Use Browse to locate the ISE CA certificate chain and click Submit.



13. In the WSA Client Certificate section, use the Choose File options to locate the exported key and certificate.

14. Click Upload Files.


At this point, the WSA should be attempting to communicate with ISE-PIC over pxGrid. With default settings,

pxGrid clients must be manually approved. To manually approve the WSA as a pxGrid client, follow these steps:

1. Navigate to Subscribers.

2. Check the box next to the WSA and choose click Approve.

3. Confirm by clicking OK.

Additionally, it is possible to allow all certificate-authenticated clients to be auto-approved by following these steps:

1. Navigate to Subscribers > Settings.

2. Check the box for Automatically approve new certificate-based accounts.


3. Click Save.

4. Confirm by clicking Yes.

Note: The auto-approve setting cannot be set if there are pending clients. Approve any pending requests before

changing the setting.

Configure ERS and Test Connectivity (WSA)



3. Check the box next to Enable External Restful Service (ERS).

4. In the ERS Administrator Credentials field, enter the user information that was configured on ISE.

5. If the node is the same as the pxGrid node, check the box for Server name same as ISE pxGrid Node.

Otherwise, enter the required information there.


The administrator can now test the connection from the WSA to ISE-PIC over both pxGrid and ERS. This test can

be run by navigating to Network > Identity Services Engine > Edit Settings and clicking on Start Test at the

bottom of the page. Successful output will resemble the following:

Checking DNS resolution of ISE pxGrid Node hostname(s)...

Success: Resolved 'ise-pic.chclasen.lab' address: 192.168.0.201

Validating WSA client certificate...


Validating ISE pxGrid Node certificate(s)...


Checking connection to ISE pxGrid Node(s)...

Trying primary PxGrid server...

Preparing TLS connection...


Completed TLS handshake with PxGrid successfully.

Trying download user-sessions...

Failure: Failed to download user-sessions.

Trying download SGT...

Able to Download 17 SGTs.

Trying connecting to primary ERS service...

Trying download user-groups...

Able to Download 9 user-groups.

Success: Connection to ISE pxGrid Node was successful

Test completed successfully.

The status of the pxGrid and ERS connection, as well as a list of SGTs and groups that have been pulled from ISE-

PIC, can be checked using the isedata CLI subcommands:






WSA Policy Configuration

Identification Profile

In order to use ISE group information in the WSA policies, an identification profile must first be created that utilizes

ISE-PIC as a means to transparently identify users. To create such a policy, follow the steps below:

1. Navigate to Web Security Manager > Identification Profiles.

2. Click Add Identification Profile.

3. Name the profile appropriately.

4. In the Identification and Authentication section, use the drop-down to choose Transparently identify users

with ISE.



Decryption Policy

Once the identification profile has been created, the decryption policies can be configured to use this profile and to

use group information. To configure a decryption policy to use those attributes, follow the steps below:

1. Navigate to Web Security Manager > Decryption Policies.

2. Click Add Policy.


4. In the Identification Profiles and Users section, use the drop-down to choose Select One or More

Identification Profiles.

5. In the Identification Profiles section, use the drop-down to choose the name of the ISE identification profile.

6. In the Authorized Users and Groups section, select the radio button next to Selected Groups and Users.

7. Click the hyperlink next to ISE Groups.

Note: In instances where AD authentication is used in addition to transparent ISE-PIC authentication, there will

be two distinct types of groups that may be configured in a policy element. One will be named “Groups” and

represents AD groups that are obtained through the authentication realms configured on the WSA. The other will

be named “ISE Groups” and represents groups obtained from ISE-PIC.


8. Highlight the desired group in the search pane and click Add.

9. Click Done to return.

10. The group will now be present in the policy.


Access Policy

Group information can also be employed in access policies. To configure an access policy to use those attributes,

follow the steps below:

1. Navigate to Web Security Manager > Access Policies.

2. Click Add Policy.


4. In the Identification Profiles and Users section, use the drop-down to choose Select One or More

Identification Profiles.


5. Click the hyperlink next to ISE Groups.

6. Highlight the desired group in the search pane and click Add.


7. Click Done to return.

8. The group will now be present in the policy.


Verification

In order to confirm that the configured policies have taken effect, the administrator may examine the access logs to

ensure that traffic is being matched accordingly. Additional custom fields can be added to this log to indicate group

membership and authentication method. The following table describes the two custom fields that are most relevant

to ISE-PIC authentication:

Format specifier in access logs Description

%g The groups associated with a transaction.

Example: “domain.lan/Domain Users”

%m The authentication mechanism used on the transaction.

Example: SSO_TUI

The full list of available custom fields is available in the WSA GUI at System Administration > Log

Subscriptions > accesslogs > Custom Fields Reference.

Example access log entry with both %g, %m, and %X#11# custom fields (highlighted):

1543519369.674 205 192.168.0.50 TCP_MISS/200 5258 GET http://www.blue.com/

"cisco" DIRECT/www.blue.com text/html DEFAULT_CASE_12-DefaultGroup-ISE_Auth-NONE-

NONE-NONE-DefaultGroup-NONE <IW_pers,-3.0,1,"-",0,0,0,1,"-",-,-,-,"-",0,0,"-","-

",-,-,IW_pers,-,"Unknown","Personal Sites","-","Unknown","Unknown","-","-

",205.19,0,-,"Unknown","-",-,"-",-,-,"-","-",-,-,"-",-> -

"chclasen.lab/Builtin/Users,chclasen.lab/Users/Domain Users" SSO_ISE

Information about the ISE engine in the WSA is found in the ise_service_log. When troubleshooting, it can be

useful to change the logging level for this log to debug.

The isedata CLI command provides various subcommands for verifying the status of the ISE connection as well

the state of the authentication cache. Below are examples of the output of these commands:

> isedata

Choose the operation you want to perform:





[]> statistics

PxGrid Connection Status: CONNECTED

PxGrid Hostname: ise-pic.chclasen.lab

PxGrid Time of Connection: 2018-11-30T09:04:03.732827

ERS Connection Status: CONNECTED

ERS Hostname: ise-pic.chclasen.lab:9060


ERS Time of Connection: 2018-11-30T10:49:34.333146

Session Bulk Download: 4

Group Bulk Download: 6

SGT Bulk Download: 17

Session Update: 63

Group Update: 0

Memory Allocation: 105

Memory Deallocation: 34






[]> cache


- SHOW - Show the ISE ID cache.

- CHECKIP - Query the local ISE cache for an IP address

[]> show

IP Name SGT#

192.168.0.165 Administrator 0

192.168.0.50 cisco 0

192.168.0.100 Administrator 0


- SHOW - Show the ISE ID cache.

- CHECKIP - Query the local ISE cache for an IP address

[]>






[]> groups

GROUPS#

chclasen.lab/Users/Domain Users

chclasen.lab/Builtin/Users


Conclusion

The Cisco Identity Service Engine Passive Identity Connector serves as a valuable tool for tracking user logon

events in an Active Directory environment. Integrating ISE-PIC with the Cisco Web Security Appliance enables an

administrator to leverage this user identity information available over pxGrid and the ERS API to enrich their policy

enforcement and reporting. This guide has covered the basic configuration of both ISE-PIC and the WSA to allow

for this exchange of information using both CA-signed and self-signed certificates. It has also explained the basic

WSA policy configuration and verification steps required to leverage the integrated solution. The administrator

should have all of the tools required to confidently deploy the solution and configure the required policy elements to

meet their needs.

Printed in USA C07-741643-00 12/18

web security appliance and identity services engine …...user template and alter the properties to...

Documents