Integrations

• 1: Certificate Management
• 1.1: Certificate Enrollment Manager
• 2: Endpoint Compliance
• 2.1: Tanium
• 2.2: BigFix
• 2.3: CrowdStrike Falcon
• 3: Firewall Context Sharing
• 3.1: Juniper SRX Integration
• 4: OT/ICS/IIoT/MIoT
• 4.1: SOTI Connect
• 5: Unified Endpoint Management
• 5.1: Jamf Pro
• 5.2: Jamf School
• 5.3: Meraki System Manager
• 5.4: Microsoft Intune
• 5.5: VMware Workspace ONE (Airwatch)
• 5.6: Ivanti MDM (formerly MobileIron)
• 5.7: Mosyle
• 5.8: SOTI MobiControl
• 6: Visitor Management / Webhook Processing
• 6.1: Envoy
• 6.2: SinePro
• 6.3: Teem LobbyConnect
• 6.4: Skyhook Generic Processor
• 7: Multi Factor Authentication
• 7.1: PingID MFA
• 8: Asset Management
• 8.1: Service Now CMDB
• 9: ClearPass Extension
• 9.1: Common Appendices for Extensions
• 9.2: Common Extension Attributes
• 9.3: Installing Extensions
• 9.4: List of active ClearPass Extensions
• 9.5: Skyhook Introduction
• 9.6: Skyhook Self Service Portal
• 9.7: Skyhook Token Refresh

1 - Certificate Management

1.1 - Certificate Enrollment Manager

Public TLS certificate lifetimes have been steadily decreasing as part of an industry-wide effort to strengthen internet security and improve the reliability of certificate management. Historically, publicly trusted TLS certificates could be issued with lifetimes of several years, but these limits have been progressively reduced through policies defined by the CA/Browser Forum and enforced by major browser vendors such as Apple, Google, and Mozilla. As of March 2026, the maximum validity period for publicly trusted TLS certificates has been reduced to 200 days, reflecting an ongoing industry trend toward shorter certificate lifecycle to reduce the risk associated with compromised keys, outdated cryptographic parameters, or changes in domain ownership. The CA/Browser Forum has officially set a schedule for shortening the lifetime of TLS certificates as shown in the table below.

A ClearPass deployment typically relies on server certificates for multiple services, including management access to ClearPass over HTTPS, captive portal logins over HTTPS, 802.1X authentication using different EAP methods like EAP-TLS, PEAP, etc., and secure RADIUS (RadSec) transport using RADIUS over TLS. Especially the HTTPS certs in most cases are publicly trusted so that devices connecting to guest network can validate the identity of the ClearPass servers without requiring custom trust configuration. As certificate lifetimes become shorter, the frequency with which these server certificates must be renewed and redeployed across ClearPass clusters correspondingly increases.

Managing these certificate renewals manually can introduce operational risk. If a certificate expires or is not updated consistently across all nodes in a ClearPass cluster, services such as administrative HTTPS access, guest portals, or certificate-based network authentication may fail. In environments that use RadSec to securely transport RADIUS traffic between network devices and authentication servers, an expired certificate could also disrupt authentication requests between network access devices and the RADIUS infrastructure.

For this reason, implementing an automated certificate lifecycle management process is becoming increasingly important for systems like ClearPass. Automated mechanisms allow certificates to be requested, renewed, and deployed before expiration, reducing the risk of service interruptions. Modern certificate automation protocols such as Automated Certificate Management Environment(ACME), Enrollment over Secure Transport(EST), Secure Certificate Enrollment Protocol(SCEP), and enterprise certificate lifecycle platforms can help organizations maintain valid certificates across HTTPS, RADIUS, and RadSec services while minimizing operational overhead and ensuring compliance with evolving public certificate lifetime requirements.

Certificate Enrollment Manager (CEM) Extension

Certificate Enrollment Manager (CEM) Extension provides an extensible way to integrate with different enterprise certificate lifecycle management platforms using EST / SCEP protocols and REST APIs to automatically renew the server certificates in ClearPass. Although the enrollment protocols like EST and SCEP are standardized, the implementation between different vendors have differences in terms of the URLs, authentication methods and types of certificates issued. Hence support for each CA vendor has to be validated separately.

The extension only needs to be installed on any one of the ClearPass nodes in the cluster and it can monitor the HTTPS / RADIUS / RadSec certificates on all the cluster nodes and trigger enrollment / re-enrollment appropriately. The extension can be installed on any ClearPass node in the cluster regardless of whether its the publisher, standby publisher, subscriber or dedicated insight node.

How integration with DigiCert TLM works

DigiCert Trust Lifecycle Manager is a digital trust solution for CA-agnostic certificate management and PKI services. Trust Lifecycle Manager centralizes visibility and control over an organization’s certificate landscape, reduces risk of business disruption from certificate expiration or human error, streamlines operations with automation and configurable workflows, and increases agility for fast remediation or adaptation to changes in cybersecurity standards.

DigiCert Trust Lifecycle Manager supports EST to provide secure, automated certificate enrollment across diverse devices and applications. With EST, organizations gain standards-based enrollment, renewal, and revocation workflows, reducing human error while ensuring scalable trust management in hybrid IT environments. Trust Lifecycle Manager’s EST protocol implementation is based on IETF’s RFC7030 EST standard.

With EST based enrollment, all operations are submitted over HTTPS and DigiCert TLM supports the issuance of both RSA and ECDSA certificates. The EST service supports the following operations/client requests:

cacerts: To obtain the CA certificates and establish the trust anchor.

simpleenroll: To enroll new end-entity certificates.

simplereenroll: To renew existing end-entity certificates.

CEM extension uses EST protocol to enroll new certificates and to renew existing ones. It can be configured to enroll / re-enroll the certificates at startup or based on certificate validity checks done periodically.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

Configuring DigiCert TLM

These are the configuration steps required on DigiCert TLM to setup auto enrollment for certificates. Log into DigiCert ONE and open Digicert Trust Lifecycle Manager to complete the configuration steps below.

Add Trusted Root CA

EST enrollment uses either an enrollment code or client certificate for authentication. The re-enroll functionality mandates using a client certificate for authentication and hence a certificate with EKU TLS Client Authentication is required to authenticate the enrollment request. This client certificate can be created in many different ways. Some options are:

1. Generate a client certificate from DigiCert TLM
2. Generate a client certificate from ClearPass Onboard
3. Generate a client certificate using openssl

The root CA that issued the client certificate needs to be uploaded to Digicert TLM as a trust certificate authority.

Navigate to Account > Root CAs and add the CA certificate.

Configure Certificate Profile

Navigate to Policies > Certificate Profiles and Create profile from template

Select the appropriate template like “Generic Private Server Certificate”. Note that not all templates support EST based enrollment. The first release only supports EST and hence only the EST based templates are supported. Support for REST API and SCEP will be added later.

Within the profile, select the enrollment method as EST, select the Trusted CA added in previous step.

Select the appropriate renewal period and Subject common name

Select the server authentication EKU and other extensions as needed

Configure appropriate seat ID mapping

Configuring CEM Extension

The extension needs to be configured to make simple enroll and simple re-enroll requests to DigiCert TLM. First we need to convert the client certificate created for EST enrollment into base 64 format. This can be done using openssl or other tools. Openssl command to convert certificate into base 64 is given below. Note that the pkcs12 file containing the certificate and private key should be converted to base64 and used within the extension config.

openssl base64 -in certificate.p12 -out certificate.txt

Sample output showing base64 encoded pkcs12 certificate:

Listed below are the extension configuration items specific to CEM Extension

Figure 12: Extension configuration parameters

Note that by default key type is automatically derived from certType attribute with “HTTPS(ECC)” using Elliptic Curve keys and All others (HTTPS(RSA), RADIUS, RadSec, Database) using RSA keys. If you wish to specify the key type manually, use these additional attributes within csrConfig

rsakeySize: Supported values ‘2048’, ‘3072’, ‘4096’

ecCurve: Supported values ‘prime256v1’, ‘secp384r1’, ‘secp521r1’ 

Example:

Validation

CEM extension log print details messages about each step of the enrollment / renewal process as shown below. If certRenewalOnStart is true, a renewal / enrollment is attempted when the extension starts. Otherwise its attempted at the scheduled cron interval.

Confirm that the certificate has been installed / renewed on ClearPass

2 - Endpoint Compliance

2.1 - Tanium

Introduction and Overview

Tanium platform provides unified endpoint security and management with modules that can discover and inventory assets, manage endpoints, track risk and compliance and help investigate and remediate threats. The endpoint context from Tanium is leveraged by ClearPass Policy Manager to make network access decisions.

This integration guide covers the deployment and configuration of a ClearPass Extension to interface with both cloud and on-prem instances of Tanium. The Extension integrates with Tanium Gateway which provides API access to endpoint attributes including risk and compliance obtained from scan results.

Extension uses APIs that query data stored in Tanium Data Service (TDS). TDS is a near real-time cached data store that maintains historical query results for both online and offline machines. This enables users to get precise, near real-time visibility on all machines in their environment, regardless of whether an endpoint is online or not.

Tanium APIs allow the Extension to provide the following integration capabilities.

• Poll Tanium periodically for endpoint information which is then added to ClearPass endpoint repository

• Real time query against Tanium to fetch endpoint attributes at the time of authentication which can then be used as part of policy evaluation

Pictorial view of the Integration

The diagram below shows a pictorial overview of the components and how they interact with each other.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

Configuration Steps

These are the main steps involved in configuring this integration:

1. Create custom role in Tanium with required permissions

2. Create Tanium API Token

3. Install Tanium extension on ClearPass

4. Configure extension to fetch information from Tanium Data Service

Create Tanium Custom Role

It is recommended to create a custom role and a service account for the integration so that the API token is created using an account that has the minimum permissions required for syncing endpoint attributes. Navigate to Administration > Permissions > Roles and click on “New Role”

Assign “read” permissions for Asset and “execute” permissions for Gateway as shown below:

Scroll down to Sensor permissions, click on the orange button, and watch it turn green to enable the sensors as shown below. Once this is done you can proceed to add appropriate content sets.

Under Content Sets, click on “Apply Content Sets” and select “Interact” and “Tanium Data Service”. In one of the examples described later, we will be fetching risk scores which requires selecting the “Risk” content set as well. If you wish to fetch additional attributes or sensor readings, appropriate content sets must be enabled under the role.

Next, the role should be mapped to the appropriate service account created for ClearPass integration from Administration > Permissions > Users as shown below:

The user should also be given permissions to appropriate Computer Groups as shown below:

Create Tanium API token

ClearPass uses APIs to fetch endpoint attributes from Tanium Data Service. The Tanium Gateway solution must be at a minimum version of 1.8 and an API token must be created for API Authentication.

Log into Tanium using the service account and navigate to Administration > Permissions > API Tokens and click on “New API Token” button.

Create API token by entering ClearPass IP addresses or subnets. Tanium supports using 0.0.0.0/0 as allow all IPs. For production setups, it is strongly recommended to lock down access to the specific ClearPass IP addresses.

Click “Save”, copy the token displayed and store it in a safe location to be used later while configuring the extension on ClearPass.

By default, the token is valid for 7 days. ClearPass will rotate the tokens automatically. If you have to re-install the extension after 7 days, the original token would have expired, and you would have to rotate the old token manually and use the new one.

Installing Tanium Extension

A Graphical User Interface (GUI) is available to make the process of interacting with the extension framework easier. To access the extension GUI, from the Guest System, under Administration find the Extension user interface as shown below.

From here, click on ‘Install Extension’, and the search box below appears. Enter the keyword “Tanium” and click on Search.

Click on the Extension and then the Install option.

Set a specific IP address for the extension if required. It will automatically pick an IP address if not assigned.

Configuring the Tanium Extension

It is important to set the configuration within the Extension to meet your needs. The extension can be configured to sync data in multiple ways as well as be used as for “real-time” authorization against Tanium. As shown on the previous page there are several parameters required to configure this extension. Not all configuration settings need to be set but some are mandatory. We have divided the parameters into two tables, one for Tanium Extension-specific configuration parameters and the other for Extension framework configuration parameters that are common across multiple vendor Extensions.

Table 1: Tanium Extension-specific configuration parameters

Mandatory fields are: taniumHost and taniumApiToken

Table 2: Extension framework configuration parameters (common configuration)

Configuration of syncAllSchedule is covered in more detail in Appendix D at the end of this documentation, this is used to control the frequency of when the sync process runs. syncUpdatedOnly when set to true, will only ingest changes for managed endpoints. syncAllOnStart determines if when the extension is started or restarted should it immediately run the sync process or wait until the syncAllSchedule job is run.

The two attributes enableEndpointCache and endpointCacheTimeSeconds are specifically used in the extension to retrieve real-time data for a known endpoint. Then these switches will ensure that if the extension is asked to refresh data, it will check the endpointCacheTimeSeconds to decide if the data currently held is fresh or stale.

Leave syncPageSize, verifySSLCerts and logLevel at their default else otherwise advised.

An example of Tanium extension configuration is below. Include appropriate values for your environment based on the information gathered before, select Restart, and click on Save Changes to start the extension.

Following the restart, click on “Show Logs”. If contact is made, and access is granted based upon the configuration above with your Tanium credentials, you should see something like shown below:

Use Cases

The extension can serve multiple use cases as described in the Introduction section as well as the Pictorial. Each use case would require some further configuration based on the requirement. Some example configurations are shown below for each use case.

Periodic Poll

This is a commonly used method where the extension is configured to sync all the endpoints to begin with. Once finished, the extension is configured to periodically gather updated data at fixed intervals based on the configuration parameters as discussed in the table in previous section.

Below is the list of attributes fetched by the default extension configuration:

Additional attributes and sensor values can be fetched by editing “taniumEndpointAttributes” and “taniumEndpointNameValuesSensors” in the extension configuration. Following is a sample configuration used to fetch additional attributes like lastLoggedInUser, ipAddresses, os.language, os.name and additional sensor readings like “USB Storage Devices”, “Username” etc.

Note that the example below fetches risk attributes like riskLevel and totalScore. This requires Benchmark module in Tanium. If you wish to fetch additional attributes or sensor values, ensure that the appropriate solutions are enabled in Tanium.

{

“logLevel”: “INFO”,

“verifySSLCerts”: false,

“taniumHost”: “tanium.nacsecurity.net”,

“taniumApiToken”: “********”,

“taniumEndpointAttributes”: [

“lastLoggedInUser”,

{

“os”: [

“language”,

“name”

]

},

“ipAddresses”,

{

“risk”: [

“riskLevel”,

“totalScore”

]

}

],

“taniumEndpointNameValuesSensors”: [

“Username”,

“Tanium Client Version”,

“Total Memory”,

“Free Memory”,

“Logged In Users”,

“Last Logged In User”,

“USB Storage Devices”

],

“endpointCacheTimeSeconds”: 300,

“enableSyncAll”: true,

“syncAllSchedule”: “*/30 * * * *”,

“syncPageSize”: 100,

“syncAllOnStart”: true,

“syncUpdatedOnly”: true,

“syncUpdatedField”: “lastLoggedInUser,ipAddresses,Client Version,risk.riskLevel,risk.totalScore”,

“syncUpdatedSensor”: “Last Logged In User”,

“ignoreEndpointDifferences”: “EID Last Seen”,

“enableEndpointLookupCache”: false,

“macAddressSeparator”: “:”,

“bypassProxy”: false,

“enableStats”: false,

“statsUsername”: “statsadmin”,

“statsPassword”: “********”

}

The above configuration enables periodic sync every 30 minutes. This could be aggressive and should be configured based on the requirement for each scenario to ensure that Tanium is not inundated with requests and to manage the resource utilization on ClearPass Policy Manager.

A parameter that further helps with optimization is syncUpdatedOnly. Set this value to true to get updates only if there is a change associated with the endpoint. The value of pageSize should not be changed unless recommended by customer support.

Validation of the endpoint context being updated after the initial sync can be done by navigating to Configuration > Identity > Endpoints. Filter using the attribute Source = Tanium as shown below.

Shown below is a sample of parameters obtained from Tanium for an endpoint, these attributes can be evaluated by the enforcement policy within ClearPass Policy Manager. The full list of endpoint attributes is documented in Appendix C.

A sample enforcement policy leveraging the endpoint attributes which can be used in a service is shown below.

Tanium as an Authorization Source

With Tanium as an Authorization Source, ClearPass Policy Manager can query Tanium Data Service in real time to determine if the endpoint is managed by Tanium at the time of Authorization and grant access. It can leverage other endpoint attributes returned by Tanium within the enforcement policy. For example, a device with high-risk score can be denied access, a device with Last Update or EID Last Seen timestamps lower than the expected value can be quarantined etc.

This use case requires further configuration which includes an addition of Authentication Source which will be used for Authorization. It also necessitates modification of a service to use this new source for Authorization and a modification of role mapping to use this Authorization source which will be covered below.

To add Tanium as an Authorization source can be done under Configuration > Authentication > Sources, click “Add”.

Click on Next. This will advance to the Primary Tab which requires connection details. First an internal POST is made to the extension. The extension then calls Tanium APIs to retrieve the attributes associated with the endpoint.

The Base URL is http://<Extension IP>. The extension IP is highlighted in extension installation section. The Login Username and Login Password are mandatory fields but never used here since the contents are posted internally to an extension. Please use dummy values for username and password.

Click on “Next”. This will advance you to the Attributes Tab where you need to provide the authorization attributes. Click on “Add More Filters”. Provide a Name for the filter and then a Filter Query. It’s extremely important that the Filter Query is defined correctly. This is the query string that is sent to the Tanium extension asking for context about the endpoint. The query can be indexed off the mac-address or any other endpoint attribute like serial number, UUID etc. of the authenticating endpoint using the following syntax:

/{Tanium attribute name}/%{ClearPass attribute name}

For completeness, few sample filter queries are provided below.

To lookup based on MAC Address in RADIUS request:

/macAddresses/%{Connection:Client-Mac-Address-Colon}

To lookup based on device serial number embedded in client certificate attribute like Subject-AltName-DirName-OnboardDeviceSerial

/serialNumber/%{Certificate:Subject-AltName-DirName-OnboardDeviceSerial}

To lookup based on device UUID embedded in client certificate attribute like Subject-AltName-DirName-OnboardDeviceUDID

/systemUUID/%{Certificate:Subject-AltName-DirName-OnboardDeviceUDID}

Next build out the definitions of the attributes that will be returned from the Filter Query. These attributes will subsequently be used within policy-evaluation and ultimately the enforcement policy applied.

Once the HTTP authorization source is defined, the returned attributes can be leveraged in a service using an enforcement policy or role mapping. A sample role mapping is shown below. Remember to add the newly added Authorization Source under the Authorization tab of the service.

The above policy assigns appropriate role to an endpoint based on the attributes fetched real time from Tanium.

A point to note is that ClearPass Policy Manager would query the Authorization Source every time the client authenticates. The downside with this approach is that if there is a latency in the response from Tanium, it would result in a delay in authentication and if the delay was beyond an acceptable limit, it would result in timeouts. For best performance it is always recommended to leverage the ability of ClearPass to cache the attributes for a configurable time. This is particularly useful in scenarios where clients roam frequently triggering frequent authentication requests. Use these parameters in customer environment based on their requirements.

The parameters of interest are enableEndpointLookupCache and enableCacheTimeSeconds. The values are explained in the table under the section “Configuration Steps”.

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“taniumHost”: “”,

“taniumApiToken”: “********”,

“taniumEndpointAttributes”: null,

“taniumEndpointNameValuesSensors”: null,

“ignoreEndpointDifferences”: “EID Last Seen”,

“enableEndpointLookupCache”: true,

“endpointCacheTimeSeconds”: 300,

“enableSyncAll”: false,

“syncAllSchedule”: “0 3 * * *”,

“syncPageSize”: 100,

“syncAllOnStart”: false,

“syncUpdatedOnly”: false,

“syncUpdatedField”: “”,

“syncUpdatedSensor”: “”,

“macAddressSeparator”: “:”,

“bypassProxy”: false,

“enableStats”: false,

“statsUsername”: “”,

“statsPassword”: “********”

}

The access tracker results with the Authorization attributes are shown below.

Appendix A – Troubleshooting and Support

Here we list some basic troubleshooting steps. If you need any help beyond this, please reach out to HPE Aruba Networking Support.

Check API Access Application Control restrictions

If you’ve previously hardened your ClearPass deployment with Application Access Controls, it’s possible that the Extension will not work. Reviewing the Extension Log might show something like the following after immediately starting the Extension. This likely indicates the ClearPass Application API’s are in place.

Example of Extension authorization failure due to Policy Manager Application Control:

[2020-03-16T15:42:21.083] [INFO] Intune - Server listening on port 80.

[2020-03-16T15:42:21.243] [DEBUG] Intune - Request “GET ‘https://172.17.0.1/api/server/version’” took 51.91ms.

[2020-03-16T15:42:21.245] [DEBUG] Intune - <!DOCTYPE html><html>

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

var locHref = window.location.protocol + “//” + window.location.hostname;

window.location.href = locHref;

}

</script>

To resolve this issue, add the IP address of the Extension to the list of nodes permitted to access the API by navigating to Administration > Server Manager > Server Configuration {choose your node} > Network

Checking on the Extension Service

The ClearPass Extensions are supported by a system service which must be running.

Restarting this service will affect all deployed and running extensions.

To check on the state of the Extension Service, or to restart the service, go to Administration > Server Manager > Server Configuration > [SERVER] > Service Control. By default this service is automatically started.

Extensions and web proxy / firewall whitelisting

If ClearPass Policy Manager has been configured with a proxy, it’s still possible that domain whitelists are required, the same for some datacenter firewall to allow the installation of Extensions. Some enterprise customers maintain a whitelist of domain that are allowed to transit the proxy/firewall. The underlying docker configuration process uses standard docker registry access to pull images (hosted in docker hub). In general, the following hosts are used:

This is all also geo dependent to some degree and based on various AWS services, so AWS redirects and geo location services will vary. Finally, this all runs via standard HTTPS (port 443).

Extension Logs/Enable Debugging

If you have a requirement to access and view the logs from the Extension, you can turn on different logging levels from the Extension GUI. Adjust the logLevel to ‘DEBUG’ and restart the extension as shown below.

Logs can then be viewed from the ‘Show Logs’.

Remember after changing the logging level, as with any extension configuration change the extension will need to be restarted for this change to take effect.

Accessing the extension logs using ‘Collect Logs’ system function

In addition to viewing the logs as shown above, logs can also be collected and examined via the Policy Manager Collect Logs system function (Administration > Server Manager > Server Configuration > [Select SERVER] > Collect Logs). This is extremely useful should you have a need to call for technical assistance.

If the support team needs to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. By default the “logLevel” is set to INFO, but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set as required. Any of the levels will display the information for the selected state and lower; if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the logs have been collected, downloaded and expanded, you can locate the extension logs in the following location in the folder structure PolicyManagerLogs > extension > your-extension-id as shown below. Note the file-name is the same as the running instance ID of the extension.

Monitoring extension statistics

There is a way to monitor extension’s critical resource statistics with the configurable parameter added as part of the extension’s configuration. To enable extension statistics set the “enableStats” parameter to true. Remember a restart of the extension is need to activate the change anytime the config is modified.

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

Since we are authorizing against an external system, it could be relevant to monitor the performance of these transactions as you setup and deploy. If you suspect there is a performance issue, ClearPass provides a way to monitor the authorization processing time. The graph below shows an example of this data, navigate to Monitoring > Live Monitor > System Monitor [click on ClearPass Tab, then select [Authorization]….

Appendix B – Considerations for Installing in a Cluster

Extensions are not synced between ClearPass cluster members, and thus must be installed on each member separately.

Some Extensions can run in two modes: Periodic Sync Mode and Authorization Source Mode.

Periodic Sync Mode

If you are configuring the extension to poll external system periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

HTTP Authorization Source Mode

In this mode we configure an HTTP Auth source that results in a HTTPS call to external system during endpoint authorization. In this deployment model the extension must be installed on every cluster node that process authentications. Also in this scenario every cluster member’s extension must be set to the exact same IP address during installation time, as the HTTP Auth source configuration is propagated globally across all cluster members.

For example, if the extension IP range is 172.17.0.0/16, we would set the extension to 172.17.0.5 on every cluster member during installation of the extension.

While we normally want to avoid duplicate IP addresses in a network, this is not a concern with ClearPass extensions. Each ClearPass node communicates internally only with its own extension, and this traffic is not routed outside of ClearPass.

Subscriber nodes support the same ability as publishers to install an Extension from the Extension store.

Appendix C – endpoint sync schedule settings

The syncSchedule and similar scheduling parameters sets how often ClearPass executes certain actions like syncing or pushing endpoints. This setting is based on a slightly modified version of the CRON job scheduler found in Unix-like operating systems. It can be used to schedule jobs to run periodically at fixed times, dates or intervals.

A ‘cron’ is a job scheduler. Any scheduled task is called a ‘cron job’. The syntax for a cron job schedule is as follows:

In our use of the cron scheduler, we’ve dropped the use of the last instruction ≤command to execute> and use only the time/date functions, see below for a number of examples of scheduling a sync process.

• Schedule a sync to run at 2am daily:- 0 2 * * *

• Schedule a sync to run twice a day at 5am and 5pm:- 0 5,17 * * *

• Schedule a sync to run on every Sunday at 5pm:- 0 17 * * sun

• Schedule a sync to run every 30 minutes:- */30 * * * *

• Schedule a sync to run at 5pm on selected days:- 0 17 * * sun,fri

You can see from the above that the scheduling process is extremely flexible, alternatively https://crontab.guru/ is a great page for learning more about CRON scheduling.

Appendix D – Extension performance optimizations

Extensions are a critical part of ClearPass deployments today and with the increased dependency on extension interactions that involve periodic polling or real-time lookups, here are some of the best practice recommendations around optimizing overall performance when using extensions:

• If the extension is used to periodically poll external systems and populate endpoint repository, ensure that it is not installed in all the nodes in the cluster. Ideally these type of extensions should only be installed on the publisher node since only publisher node can add endpoint entries to the database. For redundancy, it can be installed on another additional node but it is recommended to stagger the polling interval so that both do not attempt to poll and update endpoint database at the same time.

  Example: 0 * * * *, This cron job runs at minute 0 of every hour (e.g., 00:00, 01:00, 02:00, etc.).

    30 * * * *, This cron job runs at minute 30 of every hour (e.g., 00:30, 01:30, 02:30, etc.).
  

• If the extension is used for looking up attributes from external systems in real time during authentication, it should be installed in all the nodes handling authentication. Note that the context server config is replicated from the publisher. When using extension for real time lookup, ensure that the extension has the same IP address in all the cluster nodes.

• If the extension is expected to do both real-time lookup and periodic polling, ensure that polling is enabled only on the publisher while the extension in subscribers can have the polling disabled by setting the “enableSyncAll” attribute to false.

     "enableSyncAll": false,
  

• Some 3rd party systems support fetching delta updates vs fetching all of the device information every polling cycle. The extensions that support fetching delta updates are: Workspace ONE Crowdstrike Falcon Microsoft Intune Mosyle SentinelOne Service Now

  For these extensions, the syncUpdatedOnly attribute should be set to true in extension config so that the number of DB updates in ClearPass is minimized

    "syncUpdatedOnly": true,
  

  For extensions that do not support syncUpdatedOnly, ensure that the sync interval is not aggressive. We recommend syncing at most twice a day and that too during off peak hours whenever a full sync is performed.

• Some 3rd party systems can be very noisy in terms of attribute updates. There could be certain attributes that keep changing every sync interval like “Free Memory in Bytes”, “Last Check in Time” etc. There is no value in updating endpoints when such trivial attributes change for the device. Hence it is recommended to use “ignoreEndpointDifferences” attribute in extension configuration to ignore change in attributes that you do not care about in terms of ClearPass policies.

  You can review the Audit Viewer in ClearPass under Monitoring > Audit Viewer to see what attributes are being updated for endpoints to check if there are unnecessary updates.

  Sample for JAMF extension:

    "ignoreEndpointDifferences": "Last Update, Report Date UTC, Last Contact Time UTC, Last Inventory Update UTC, Last Reported IP, IP Address",
  

  Default for Microsoft Intune extension:

    "ignoreEndpointDifferences": "Last Sync Date Time, Free Storage Space in Bytes",
  

• To further optimize the number of endpoints being updated in ClearPass, you can specify which attributes are being used in the ClearPass policies so that only changes to those attributes would trigger an update to the endpoint. This is done by listing out the specific attributes under endpointAttributes in extension configuration.

  Sample for JAMF extension:

    "endpointAttributes": "Group names, MDM Enabled, Managed, Remote Managed, Supervised, Serial Number",
  

• Setup extension to restart unless it was intentionally stopped. A restart policy can be defined in extension configuration to ensure that the extension starts up automatically after server reboots and such. Restart policy of “unless-stopped” would ensure the extension always starts up unless it was manually stopped.

  “restartPolicy”: “no” — The extension will not be automatically restarted after the server is restarted.

  “restartPolicy”: “always” — The extension will always be restarted after the server is restarted.

  “restartPolicy”: “unless-stopped” — The extension will be restarted unless it was stopped prior to the server restart, in which case it will maintain that state.

  “restartPolicy”: “on-failure:N” — If the extension fails to restart, the value for “N” specifies the number of times the extension should try to restart. If you do not provide a value for “N”, the default value will be “0”.

  The “restartPolicy” parameter is not present by default in extension configurations. When it is not present, if the system is restarted a default policy is applied to the extension to maintain the state it was in before the restart. If the “restartPolicy” parameter is added to the configuration but later removed, the extension will then revert to the default restart policy.

Appendix E – Default attributes fetched from Tanium

Following is the sample list of the attributes fetched from Tanium using the default configuration.

{

“Source”: “Tanium”

“Tanium EID First Seen”: “Thu, 09 Mar 2023 07:53:07 +0000”

“Tanium EID Last Seen”: “Sun, 26 Nov 2023 20:00:45 +0000”

“Tanium Last Update”: “2023-11-26 20:33:12”

“Tanium System Found”: true

“Tanium computerID”: 695858940

“Tanium domainName”: “tmelab.com”

“Tanium id”: 6

“Tanium ipAddress”: 172.16.10.190

“Tanium macAddresses”: “30:03:C8:49:7C:BB”

“Tanium manufacturer”: “LENOVO”

“Tanium model”: “Lenovo V14 G3 ABA”

“Tanium name”: “tme-win-11.tmelab.com”

“Tanium os.generation”: “Windows 11”

“Tanium os.name”: “Windows 11 Pro”

“Tanium os.platform”: “Windows”

“Tanium serialNumber”: “PF3TG7DQ”

“Tanium systemUUID”: “AE90C181-ED53-11EC-80F2-6C2408C2965C”

}

2.2 - BigFix

Introduction and Overview

BigFix is one of the leading endpoint management and security platforms. It quickly identifies and discovers information about endpoints, patches operating systems and monitors the inventory continuously to ensure compliance of endpoints in the infrastructure. BigFix aims at keeping the endpoints secure by ensuring they are patched on the network. Unpatched systems are a big threat to organizations as hackers frequently look for ways to leverage known vulnerabilities for malicious activities. It has a rich set of device attributes gathered from the agents running on an endpoint. These attributes can be used by ClearPass Policy Manager to get more context for the endpoint trying to connect onto the network. Unpatched or non-compliant systems can be sent to a Quarantine zone to ensure they do not have access to valuable assets on the network. This integration guide covers the deployment and configuration of a ClearPass Extension to interface with BigFix. The Extension leverages BigFix APIs to obtain attributes associated with an endpoint. This allows the Extension to provide the following integration capabilities.

1. Periodic Poll: enable periodic polling of endpoints in BigFix with a valid mac address. This allows Policy Manager to access a number ofendpoint attributes which can be leveraged for creating policies. For example

   a. Check if the endpoint is known to BigFix

   b. Check if the Last Update was less than 7 days

   c. Check if the endpoint has been locked by BigFix

2. Authorization source: Trigger the Extension to get the attributes for the authenticated endpoint, this query can be based upon the mac-address or the IP address of the endpoint.

Pictorial View of the Integration

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

The default configuration used for v3 of the extension is below.

{

"logLevel": "INFO",

"verifySSLCerts": true,

"bigFixHost": "",

"bigFixPort": 52311,

"bigFixUserName": "",

"bigFixPassword": "********",

"bigFixAdditionalProperties": [],

"bigFixIncludePatchSummary": false,

"enableEndpointCache": false,

"cacheExpirationMinutes": 30,

"enableCacheSync": false,

"cacheSyncSchedule": "0 5 * * 1",

"syncOnStart": false,

"cppmUserName": "",

"cppmPassword": "********",

"bypassProxy": false,

"enableStats": false

}

Each of the attributes are explained in the table below in detail.

When leveraging the sync capabilities of the Extension to get the device attributes from BigFix, use the attribute enableCacheSync and specify cacheSyncSchedule. These 2 attributes are leveraged for periodic poll of endpoints from BigFix. The syncOnStart attribute can be leveraged as well to sync everything upon the start or re-start of the extension.

When doing single device lookups by MAC Address, if enableEndpointCache is true, the mac address will be looked up in ClearPass to see if the information for the computer is in the database and up-to-date as determined by the cacheExpirationMinutes, this being the amount of time an endpoints data will be considered "fresh" when using the enableEndpointCache option. If false, all requests will be sent to BigFix.

The bigFixUserName and bigFixPassword are credentials of the operator on BigFix which will give access to endpoints discovered by BigFix via REST APIs. A default administrator account can be used for this setup or a separate local operator can be created. For steps on creating this operator on BigFix, see next page.

The cppmUserName and cppmPassword should be for an Administrator account. The device profiling attributes obtained from BigFix need to be written into the endpoint repository leveraging a profiling APIs which requires an Administrator account.

A ClearPass Network Administrator account can be created under Administration > Users and Privileges > Admin Users. Click on Add. A user with the following Privilege Level needs to be created.

A Network Administrator privilege level is sufficient for the action of adding device profiling information into the endpoint database of ClearPass.

A copy of the BigFix Extension with the desired configuration is shown below, this has to be modified for your as a minimum. Include the bigFixHost, bigFixPort, bigFixUserName, bigFixPassword, cppmUserName and cppmPassword that will be specific to your environment.

Change or include any other values based on the description of each in the above table as necessary to your deployment. Select Restart and click on Save Changes to restart the extension.

An optional but extremely powerful parameter to note is bigFixAdditionalProperties. By default, the parameter has the value of [] which basically indicates that the sync would only get the default attributes.

However, BigFix includes an extensive list of attributes from an endpoint. Some of these attributes might not be very useful or relevant for ClearPass and would increase the payload to be ingested from BigFix. Customization options are available with this parameter so that an administrator can identify and pull values apart from the default which are important in their environment. Navigate to the BigFix Extension and click on Show Details as shown below.

Click on the Extension URL under the details. This gives a list of all the attributes that can be fetched from BigFix. If the information is available for the endpoint on BigFix, ClearPass can pull it.

The URL above gives a long list of available attributes. The ones marked in bold are mandatory and fetched by default. If any of the other properties are useful in a particular environment, they can be fetched using the bigFixAdditionalProperties parameter. They can be then be leveraged in ClearPass Policy.

For example, here we have added BIOS and Client Settings to the list of additional attributes that need to be fetched from BigFix.

Following is the change in the Extension configuration. Remember this change is only required if additional attributes need to be fetched from BigFix. This can be totally skipped for the basic setup of this integration.

{ "bigFixHost": "10.2.98.40",

"bigFixPort": 52311,

"bigFixUserName": "admin",

"bigFixPassword": "********",

"bigFixAdditionalProperties": [

"Client Settings", "BIOS"

],

"bigFixIncludePatchSummary": true,

"enableEndpointCache": true,

"enableCacheSync": true,

"cacheSyncSchedule": "0 5 * * 1",

"syncOnStart": true,

"cppmUserName": "admin",

"cppmPassword": "********",

"verifySSLCerts": false,

"logLevel": "INFO",

"bypassProxy": false,

"enableStats": false

}

Ensure the Extension is restarted upon a configuration change. After the restart of the extension, click on Show Logs.

The above log states that the Extension has sync’d the endpoint data from BigFix. The above steps sync endpoint details at the time of starting the Extension and then regular updates are fetched at the interval specified by cacheSyncSchedule, see Appendix C for more information on configuring this value. Please note the IP address of the Extension. This will be used in the next section where we leverage BigFix Extension as an Authorization source. A sample of attributes fetched for an endpoint is shown below.

Configure ClearPass Policy Manager

Multiple methods exist for how ClearPass can utilize the returned data from HCL BigFix, such as:

Ensure that the endpoint is managed by BigFix. If not, perhaps restrict access for the device on the

Corporate Network with a role that only allows the user to remediate and install the BigFix endpoint agent. This provides a controlled environment where all endpoints are known to be in line with corporate security policy, around patching and OS updates.

Check if the endpoint has the latest BigFix agent installed. If not, perhaps quarantine the device with the option to remediate and install an updated client.

More importantly validate whether the endpoint is missing any patches, subdivided into Critical, Important, Low and Moderate, separate policy can be written against any of the counts.

Additionally, policy can be written against a wealth of additional endpoint attributes that are important to you, if for example you wanted to check the BiOS version of devices connecting, you can have BigFix return that data which can then be compared in policy to decide if an endpoint maybe vulnerable to a BiOS exploit.

As mentioned previously, the extension can be run in two modes.

Periodic Sync Mode: Using stored attributes

The Extension can sync data from BigFix periodically, write this data into the ClearPass EndpointDB, then use the EndpointDB as an authorization source. Be aware that this data will not be completely ‘real-time,’ but may be adequate for many if not all use cases.

Here’s an example of a ClearPass Role Mapping Policy that utilizes these BigFix Endpoint Attributes.

HTTP Authorization Source Mode: A Real-Time authorization check

In this mode we build an HTTP authorization source, add it to an existing Service Policy, then process the returned data from BigFix, typically utilizing a role-mapping or an enforcement profile action. Note that with an HTTP authorization source configured in a Service, ClearPass will make a call to BigFix every time an authenticating device matches this Service, unless the cacheExpirationMinutes timer for the endpoint is still qualifying the data as “fresh”. Making real-time API calls to BigFix every time a device authenticates may not be scalable if there are network delay constraints or you have a high number of authentications/sec.

The HTTP Authorization source is the conduit between the extension and ClearPass Policy Manager. It’s through the authorization source that we expose the BigFix endpoint attributes to Policy Manager so they can be used to perform role-mapping or an enforcement policy action.

Defining a BigFix HTTP Authorization Source

The first step is to add the authorization source. Under Configuration > Authentication > Sources, click Add and choose type HTTP.

Provide a Name for the Authentication Source and click Next. On the Primary Tab, provide the IP Address of the extension as discussed earlier. Ensure a trailing ‘/mac/’ is added after the extension IP address.

Click on Next. This will advance to the Attributes Tab where you must configure at least one attribute. Click on Add More Filters. Provide a Name for the filter and then a Filter Query. The query is indexed off the MAC Address of the endpoint. Copy the line below and paste into the Filter Query box.

%{Connection:Client-Mac-Address-Hyphen}

The data returned from BigFix can be extensive, but not all the data is relevant to making a security policy decision about the endpoint. Choose which attributes are required for your enforcement profile. As an example, the filter shown below has eleven attributes configured. Your filter may differ depending on the use-cases you are trying to meet. Remember if you want to check additional attributes via the HTTP authZ then they need to be added in the array un the extension under bigFixAdditionalProperties.

Using Results from the BigFix HTTP Auth Source

Below is an example of using these attributes in a ClearPass Role Mapping Policy.

This is just a simple configuration to show what you can do with the returned attributes.

Previously we discussed about an optional parameter called bigFixAdditionalProperties. It is used to fetch more attributes than the default ones available above. In order to use that attribute with Authorization source it is necessary to add the same using the option “Add More Filters”. Without doing this, it will not be available for use with Authorization.

Let’s look at the example below where the BigFix Missing Patches-Critical attribute fetched is mapped within the Authorization source as shown below.

Let’s look at the service configuration within ClearPass to see this HTTP source being leveraged as an Authorization source within a service. Ensure to check the option for enabling Authorization.

The next step is to add this source under Authorization. The Authorization tab for the service is shown below.

Finally, the authorization source is leveraged under Enforcement for the policies to be defined. A sample Enforcement Policy for this service is shown below.

In the above policy if BigFix marks an endpoint as Locked, the endpoint is assigned a Quarantine role with restricted Access. A full access role is granted only if the Endpoint “Is Found” by BigFix. If not, a default of [Deny Access Profile] is assigned.

Appendix A – Troubleshooting and Support

Here we list some basic troubleshooting steps. If you need any help beyond this, please reach out to HPE Aruba Networking Support.

Check API Access Application Control restrictions

If you’ve previously hardened your ClearPass deployment with Application Access Controls, it’s possible that the Extension will not work. Reviewing the Extension Log might show something like the following after immediately starting the Extension. This likely indicates the ClearPass Application API’s are in place.

Example of Extension authorization failure due to Policy Manager Application Control:

[2020-03-16T15:42:21.083] [INFO] Intune - Server listening on port 80.

[2020-03-16T15:42:21.243] [DEBUG] Intune - Request “GET ‘https://172.17.0.1/api/server/version’” took 51.91ms.

[2020-03-16T15:42:21.245] [DEBUG] Intune - <!DOCTYPE html><html>

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

var locHref = window.location.protocol + “//” + window.location.hostname;

window.location.href = locHref;

}

</script>

To resolve this issue, add the IP address of the Extension to the list of nodes permitted to access the API by navigating to Administration > Server Manager > Server Configuration {choose your node} > Network

Checking on the Extension Service

The ClearPass Extensions are supported by a system service which must be running.

Restarting this service will affect all deployed and running extensions.

To check on the state of the Extension Service, or to restart the service, go to Administration > Server Manager > Server Configuration > [SERVER] > Service Control. By default this service is automatically started.

Extensions and web proxy / firewall whitelisting

If ClearPass Policy Manager has been configured with a proxy, it’s still possible that domain whitelists are required, the same for some datacenter firewall to allow the installation of Extensions. Some enterprise customers maintain a whitelist of domain that are allowed to transit the proxy/firewall. The underlying docker configuration process uses standard docker registry access to pull images (hosted in docker hub). In general, the following hosts are used:

This is all also geo dependent to some degree and based on various AWS services, so AWS redirects and geo location services will vary. Finally, this all runs via standard HTTPS (port 443).

Extension Logs/Enable Debugging

If you have a requirement to access and view the logs from the Extension, you can turn on different logging levels from the Extension GUI. Adjust the logLevel to ‘DEBUG’ and restart the extension as shown below.

Logs can then be viewed from the ‘Show Logs’.

Remember after changing the logging level, as with any extension configuration change the extension will need to be restarted for this change to take effect.

Accessing the extension logs using ‘Collect Logs’ system function

In addition to viewing the logs as shown above, logs can also be collected and examined via the Policy Manager Collect Logs system function (Administration > Server Manager > Server Configuration > [Select SERVER] > Collect Logs). This is extremely useful should you have a need to call for technical assistance.

If the support team needs to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. By default the “logLevel” is set to INFO, but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set as required. Any of the levels will display the information for the selected state and lower; if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the logs have been collected, downloaded and expanded, you can locate the extension logs in the following location in the folder structure PolicyManagerLogs > extension > your-extension-id as shown below. Note the file-name is the same as the running instance ID of the extension.

Monitoring extension statistics

There is a way to monitor extension’s critical resource statistics with the configurable parameter added as part of the extension’s configuration. To enable extension statistics set the “enableStats” parameter to true. Remember a restart of the extension is need to activate the change anytime the config is modified.

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

Since we are authorizing against an external system, it could be relevant to monitor the performance of these transactions as you setup and deploy. If you suspect there is a performance issue, ClearPass provides a way to monitor the authorization processing time. The graph below shows an example of this data, navigate to Monitoring > Live Monitor > System Monitor [click on ClearPass Tab, then select [Authorization]….

Appendix B – Considerations for Installing in a Cluster

Extensions are not synced between ClearPass cluster members, and thus must be installed on each member separately.

Some Extensions can run in two modes: Periodic Sync Mode and Authorization Source Mode.

Periodic Sync Mode

If you are configuring the extension to poll external system periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

HTTP Authorization Source Mode

In this mode we configure an HTTP Auth source that results in a HTTPS call to external system during endpoint authorization. In this deployment model the extension must be installed on every cluster node that process authentications. Also in this scenario every cluster member’s extension must be set to the exact same IP address during installation time, as the HTTP Auth source configuration is propagated globally across all cluster members.

For example, if the extension IP range is 172.17.0.0/16, we would set the extension to 172.17.0.5 on every cluster member during installation of the extension.

While we normally want to avoid duplicate IP addresses in a network, this is not a concern with ClearPass extensions. Each ClearPass node communicates internally only with its own extension, and this traffic is not routed outside of ClearPass.

Subscriber nodes support the same ability as publishers to install an Extension from the Extension store.

Appendix C – endpoint sync schedule settings

The syncSchedule and similar scheduling parameters sets how often ClearPass executes certain actions like syncing or pushing endpoints. This setting is based on a slightly modified version of the CRON job scheduler found in Unix-like operating systems. It can be used to schedule jobs to run periodically at fixed times, dates or intervals.

A ‘cron’ is a job scheduler. Any scheduled task is called a ‘cron job’. The syntax for a cron job schedule is as follows:

In our use of the cron scheduler, we’ve dropped the use of the last instruction ≤command to execute> and use only the time/date functions, see below for a number of examples of scheduling a sync process.

• Schedule a sync to run at 2am daily:- 0 2 * * *

• Schedule a sync to run twice a day at 5am and 5pm:- 0 5,17 * * *

• Schedule a sync to run on every Sunday at 5pm:- 0 17 * * sun

• Schedule a sync to run every 30 minutes:- */30 * * * *

• Schedule a sync to run at 5pm on selected days:- 0 17 * * sun,fri

You can see from the above that the scheduling process is extremely flexible, alternatively https://crontab.guru/ is a great page for learning more about CRON scheduling.

Appendix D – Extension performance optimizations

Extensions are a critical part of ClearPass deployments today and with the increased dependency on extension interactions that involve periodic polling or real-time lookups, here are some of the best practice recommendations around optimizing overall performance when using extensions:

• If the extension is used to periodically poll external systems and populate endpoint repository, ensure that it is not installed in all the nodes in the cluster. Ideally these type of extensions should only be installed on the publisher node since only publisher node can add endpoint entries to the database. For redundancy, it can be installed on another additional node but it is recommended to stagger the polling interval so that both do not attempt to poll and update endpoint database at the same time.

  Example: 0 * * * *, This cron job runs at minute 0 of every hour (e.g., 00:00, 01:00, 02:00, etc.).

    30 * * * *, This cron job runs at minute 30 of every hour (e.g., 00:30, 01:30, 02:30, etc.).
  

• If the extension is used for looking up attributes from external systems in real time during authentication, it should be installed in all the nodes handling authentication. Note that the context server config is replicated from the publisher. When using extension for real time lookup, ensure that the extension has the same IP address in all the cluster nodes.

• If the extension is expected to do both real-time lookup and periodic polling, ensure that polling is enabled only on the publisher while the extension in subscribers can have the polling disabled by setting the “enableSyncAll” attribute to false.

     "enableSyncAll": false,
  

• Some 3rd party systems support fetching delta updates vs fetching all of the device information every polling cycle. The extensions that support fetching delta updates are: Workspace ONE Crowdstrike Falcon Microsoft Intune Mosyle SentinelOne Service Now

  For these extensions, the syncUpdatedOnly attribute should be set to true in extension config so that the number of DB updates in ClearPass is minimized

    "syncUpdatedOnly": true,
  

  For extensions that do not support syncUpdatedOnly, ensure that the sync interval is not aggressive. We recommend syncing at most twice a day and that too during off peak hours whenever a full sync is performed.

• Some 3rd party systems can be very noisy in terms of attribute updates. There could be certain attributes that keep changing every sync interval like “Free Memory in Bytes”, “Last Check in Time” etc. There is no value in updating endpoints when such trivial attributes change for the device. Hence it is recommended to use “ignoreEndpointDifferences” attribute in extension configuration to ignore change in attributes that you do not care about in terms of ClearPass policies.

  You can review the Audit Viewer in ClearPass under Monitoring > Audit Viewer to see what attributes are being updated for endpoints to check if there are unnecessary updates.

  Sample for JAMF extension:

    "ignoreEndpointDifferences": "Last Update, Report Date UTC, Last Contact Time UTC, Last Inventory Update UTC, Last Reported IP, IP Address",
  

  Default for Microsoft Intune extension:

    "ignoreEndpointDifferences": "Last Sync Date Time, Free Storage Space in Bytes",
  

• To further optimize the number of endpoints being updated in ClearPass, you can specify which attributes are being used in the ClearPass policies so that only changes to those attributes would trigger an update to the endpoint. This is done by listing out the specific attributes under endpointAttributes in extension configuration.

  Sample for JAMF extension:

    "endpointAttributes": "Group names, MDM Enabled, Managed, Remote Managed, Supervised, Serial Number",
  

• Setup extension to restart unless it was intentionally stopped. A restart policy can be defined in extension configuration to ensure that the extension starts up automatically after server reboots and such. Restart policy of “unless-stopped” would ensure the extension always starts up unless it was manually stopped.

  “restartPolicy”: “no” — The extension will not be automatically restarted after the server is restarted.

  “restartPolicy”: “always” — The extension will always be restarted after the server is restarted.

  “restartPolicy”: “unless-stopped” — The extension will be restarted unless it was stopped prior to the server restart, in which case it will maintain that state.

  “restartPolicy”: “on-failure:N” — If the extension fails to restart, the value for “N” specifies the number of times the extension should try to restart. If you do not provide a value for “N”, the default value will be “0”.

  The “restartPolicy” parameter is not present by default in extension configurations. When it is not present, if the system is restarted a default policy is applied to the extension to maintain the state it was in before the restart. If the “restartPolicy” parameter is added to the configuration but later removed, the extension will then revert to the default restart policy.

Appendix E BigFix configuration

It is assumed that a working BigFix environment is leveraged for this extension. The configuration of BigFix is beyond the scope of this guide.

The Extension configuration requires a valid BigFix administrator account to leverage BigFix APIs. This account can be created on BigFix as shown below.

Go to Tools Menu on top of your screen and click on Create Operator . Add a user with credentials as shown below.

The next step involves assigning permissions for this account. It is important that the account has the permissions for Can use REST API. Also, the account should have a list of Administered Computers". In our lab, a user with restricted permissions was used and should be preferred. For details on this, please contact your local BigFix representative. Under the “Details” tab for this account, provide restricted access as shown below.

If there are permission issues when trying to fetch computers, one can check or troubleshoot by giving this account the Master Operator permission as shown below or use an administrator account for testing only.

Navigate to the “Computer Assignments” tab. Add the computers in scope for this Extension or select all computers. It is important that after the settings are saved, the “Administered Computers” tab gets updated. An empty list of Administered Computers would always result in extension fetching no computers.

Further restrictions can be assigned to this account by granting a Reader permission only to the sites within the scope.

Appendix F XMLs

The Authentication Source can be easily imported into ClearPass so that it can be leveraged to use the BigFix

Extension as an Authorization source in a service. The XML file can be downloaded from https://github.com/aruba/clearpass-exchange-snippets/tree/master/extensions/ibm-bigfix

• Download the XML profile > “clearpass-extension_tenable-securitycenter_enf-profile.xml”.

• Open this file in your favorite editor.

• Use the Find and Replace feature of the editor to replace "<BigFix Extension IP>" with the actual IP address of the BigFix Extension configured. Refer Figure 24.

• Save the file and Import.

The file can be imported from Configuration > Enforcement >Profiles.

The above action will import an ‘basic’ HTTP Authentication Source in ClearPass which can be leveraged as an Authorization source for a service, you may want to add additional fields/attributes as previously discussed.

2.3 - CrowdStrike Falcon

Introduction and Overview

CrowdStrike Falcon Endpoint Protection is a cloud-based security platform that combines the capabilities of a next-gen Antivirus (NGAV) and Endpoint Detection and Response (EDR) using a single cloud-delivered agent. This release of document focuses on the new SDK based CrowdStrike Falcon extension in the ClearPass Policy Manager. A few enhancements that are added with the new SDK based extension help with the efficient integration of CrowdStrike Falcon Endpoint Protection and ClearPass Policy Manager with the existing methods.

• CrowdStrike Falcon Integration with ClearPass Policy Manager with the new SDK based extension now conform with the User Agent information that is used by CrowdStrike for internal tracking.

• The syncing of endpoints from CrowdStrike Falcon now provides the CrowdStrike device ID as well as attribute along with MAC. The authentication source and context server action URL’s can now leverage both MAC and Device ID in real-time lookup for authorization and context server action-based containments.

• The new extension now also supports bypassing proxy.

ClearPass Policy Manager integrates with CrowdStrike Falcon in multiple ways;

• Perform a real-time lookup of the device attributes which can be leveraged for Authorization.

• Bulk import of all the endpoints leveraging flexible polling definition based on crontab

• Trigger containment or lift the containment for the quarantined devices using the CrowdStrike Falcon agent.

The above use-cases are covered in this integration and documented in this Integration Guide.

What’s new in CrowdStrike v2.1 Extension? -Important Changes

Deprecation of GET /devices/entities/devices/v1(GetDeviceDetails) - CrowdStrike has announced the deprecation of v1 GET host details operation. Integrations leveraging the v1 endpoint API’s must be updated to use one of the new v2 versions by February 9, 2023. This means that all earlier versions of extensions will fail collecting device details causing the integration to break. This release v2.1.0 is updated to use the v2 version of the GET host details operation and is a go to version before February 9, 2023 without fail to continue using the integration between ClearPass and CrowdStrike.

Support for Zero Trust Assessment attributes – CrowdStrike has supported Zero Trust Assessment of endpoints for a while which can be leveraged by this version of extension to fetch the risk scores of an endpoint as endpoint attributes. There are numerous assessment items that CrowdStrike evaluates to give evaluated results like OS assessment, Sensor assessment and Overall assessment scores. We have added support for following Zero Trust assessment attributes in this version of extension which can be called into ClearPass policies for profile enforcements based on CrowdStrike Zero Trust Assessment scores in addition to the existing attributes that we have from past CrowdStrike extension versions.

• “CrowdStrike Assessment OS”

• “CrowdStrike Assessment Overall”

• “CrowdStrike Assessment Sensor Config”

A new configuration knob is added to this version of extension which can be set to true to fetch the Zero Trust scores of an endpoint. This option is set to false by default.

crowdStrikeSyncZeroTrust": true,

Pictorial View of the Integration

The diagram below shows a pictorial overview of the components and how they interact with each other.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

Configuration Steps in CrowdStrike to enable API communication

There are primarily 2 steps involved in getting this integration configured.

1. Configuration of CrowdStrike for Integration

2. Installation and Configuration of CrowdStrike extension using the ClearPass Policy Manager GUI

Getting API Credentials

Login to the CrowdStrike tenant, using your administrator credentials.

Create a new API Client. Navigate to Support > API Clients and Keys. Click on “Add new API client”.

Save the API Client ID and Client Key on a notepad. Client Key is not displayed again. This will be used while configuring the Extension in ClearPass Policy Manager.

Enter a Client Name. Under API Scopes, add the following permissions

1. Read/Write permissions for Hosts

2. Read for Event streams

Check for Managed Hosts

This configuration step is optional and is only required if there are no Endpoints managed by CrowdStrike.

Go to Hosts > Host Management. Ensure there are hosts being managed by CrowdStrike. These are the hosts that will be pulled by ClearPass Policy Manager, if the sync function is enabled in the Extension configuration.

If no hosts are managed by CrowdStrike, one needs to install the Falcon Sensor on the endpoints to be managed. These steps vary based on the endpoint Operating System. The installers are available under Hosts > Sensor Downloads.

Steps for sensor installation are available under the section “Sensor Deployment and Maintenance” here https://falcon.crowdstrike.com/support/documentation

CrowdStrike Extension Installation and Configuration on ClearPass

A Graphical User Interface (GUI) is available to make the process of interacting with the extension framework easier. To access the extension GUI, from the Guest System, under Administration find the Extension user interface as shown below.

From here, click on ‘Install Extension’, and the search box below appears. Enter the keyword “CrowdStrike” and click on Search.

Click on the Extension and then the Install option.

Set a specific IP address for the extension if required. It will automatically pick an IP address if not assigned.

After the extension has been installed, review the configuration and adjust as needed. Notice the options to Start, Delete, Reinstall or Show Logs and the option to edit and set the extension configuration.

The default configuration used for the extension is shown below

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“crowdStrikeApiHost”: “api.crowdstrike.com”,

“clientId”: “[Client ID]”,

“clientSecret”: “********”,

“crowdStrikeSyncZeroTrust”: false,

“enableEndpointCache”: false,

“endpointCacheTimeSeconds”: 300,

“syncAllOnStart”: false,

“enableSyncAll”: false,

“syncAllSchedule”: “0 2 * * 6”,

“syncUpdatedOnly”: true,

“syncPageSize”: 100,

“attributePrefix”: “”,

“bypassProxy”: false,

“enableStats”: true,

“statsUsername”: “”,

“statsPassword”: “********”

}

Each of the attributes are explained in the table below in detail.

Figure 12: Extension configuration parameters

A copy of the CrowdStrike Falcon extension with the desired configuration is shown below, this has to be modified for your deployment. Modify the clientId, clientSecret and other options that will be specific to your environment. Change or include any other values based on the description of each in the above table

Select Restart and click on Save Changes to restart the extension.

After completing the configuration, click on ‘Save Changes’ and restart of the extension, click on Show Logs.

The above log shows that the extension has been configured and has ingested endpoints from CrowdStrike leveraging sync on start. These logs can be seen in detail if the loglevel setting is changed to DEBUG.

Use Cases

The extension can serve multiple use cases as described in the Introduction section as well as the Pictorial. Each use case would require some further configuration based on the requirement. Some example configurations are shown below for each use case.

Periodic Poll

This is a commonly used method where the extension is configured to sync all the endpoints to begin with. Once finished, the extension is configured to periodically gather updated data at fixed intervals leveraging the configuration parameters as discussed in the table in previous section. Following is the sample configuration used.

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“crowdStrikeApiHost”: “api.crowdstrike.com”,

“clientId”: “[Client ID]”,

“clientSecret”: “********”,

“crowdStrikeSyncZeroTrust”: false,

“enableEndpointCache”: false,

“endpointCacheTimeSeconds”: 300,

“syncAllOnStart”: false,

“enableSyncAll”: false,

“syncAllSchedule”: “0 2 * * 6”,

“syncUpdatedOnly”: true,

“syncPageSize”: 100,

“attributePrefix”: “”,

“bypassProxy”: false,

“enableStats”: true,

“statsUsername”: “”,

“statsPassword”: “********”

}

The above configuration enables periodic sync and triggers it every 2 hours. This could be aggressive and should be changed based on the requirement in a particular scenario to ensure that CrowdStrike is not inundated with requests and also to manage the resource utilization on ClearPass Policy Manager.

A parameter that further helps with optimization is syncUpdatedOnly. Set this value to true to get updates only if there is a change associated with the endpoint. The value of pageSize should not be changed unless recommended by customer support.

Validation of the endpoint context being updated after the initial sync can be done by navigating to Configuration > Identity > Endpoints. Filter using the attribute Source = CrowdStrike as shown below.

Shown below is a sample of security contextual parameters obtained from CrowdStrike for an endpoint, these attributes can be evaluated by the enforcement policy within ClearPass Policy Manager. These attributes are obtained leveraging the default policy on CrowdStrike. The Falcon agent should be capable of capturing further attributes which could be leveraged as well. The full list of endpoint attributes is documented in Appendix C on Page 27.

A sample enforcement policy leveraging the endpoint attributes which can be used in a service is shown below.

Note that the common endpoint attributes related to Zero Trust Assessment would make sense in enforcement policies when they are of data-type integer. For example, if one needs to check if the overall Zero Trust Assessment score of an endpoint is greater than 20 then such policy conditions will need the attributes to be of type integer. By default, all the attributes sent by CrowdStrike get added as data-type String for an endpoint. Therefore, for certain use cases such attributes need to be deleted from the Dictionary attributes and re-added with the data-type set to integer manually.

To delete the attributes, one needs to first stop the extension, delete the existing endpoints from the ClearPass DB as the endpoints will be referencing these attributes from the dictionary preventing an administrator to delete them. After which these attributes can be added manually as shown below with the data-type set to integer.

Since the Zero Trust Assessment scores are available as endpoint attributes only starting version 2.1.0 of the extension one needs to first upgrade the extension. So, the step to delete the endpoints and dictionary attributes can be done prior to the upgrade which will prevent restarting the extension multiple times.

CrowdStrike as an Authorization Source

With CrowdStrike as an Authorization Source, ClearPass Policy Manager can query CrowdStrike Real-Time to determine if the endpoint is managed by CrowdStrike at the time of Authorization and grant access accordingly. It can leverage other security attributes returned by CrowdStrike within the enforcement policy. For example, a contained device can be denied access, a device with Last Update higher than the expected value can be quarantined etc.

This use case requires further configuration which includes an addition of Authentication Source which will be used for Authorization. It also necessitates modification of a service to use this new source for Authorization and a modification of Enforcement Policy to use this Authorization source which will be covered below.

The addition of Authentication source can be easily configured by importing the XML available on HPE Aruba Networking GitHub. Kindly refer Appendix B for details.

Adding CrowdStrike as an Authorization source can be done under Configuration > Authentication > Sources, click “Add”.

Click on Next. This will advance to the Primary Tab which requires connection details. Here an internally POST is made to the extension. The extension then calls CrowdStrike APIs to retrieve the security attributes associated with the endpoint.

The Base URL is http://<Extension IP>. The extension IP is highlighted in Figure 14. The Login Username and Login Password are mandatory fields but never used here since the contents are posted internally to an extension. This value has to be defined and could be anything.

Click on “Next”. This will advance you to the Attributes Tab where you need to provide the authorization attributes. Click on “Add More Filters”. Provide a Name for the filter and then a Filter Query. It’s extremely important that the Filter Query is defined correctly. This is the query string that is sent to the CrowdStrike extension asking for context about the endpoint. The query is indexed off the mac-address of the authenticating endpoint. For completeness, the filter query is provided here, copy it carefully.

/%{Connection:Client-Mac-Address-NoDelim}

Next build out the definitions of the attributes that will be returned from the Filter Query. These attributes will subsequently be used within our policy-evaluation and ultimately the enforcement policy applied.

For. Zero Trust Assessment Score attributes below are the definitions of the attributes from a second query that needs to be added.

/zero-trust/%{Endpoint:CrowdStrike Device ID}

Further attributes can be added here if necessary for the policy. Appendix C has a list of attributes captured by the extension.

Once the HTTP authorization source is defined, the returned attributes can be leveraged in a service using an enforcement policy or role mapping. A sample enforcement policy is shown below. Remember to add the newly added Authorization Source under the Authorization tab of the service.

The above policy grants full access to an endpoint if it is provisioned with a CrowdStrike Falcon agent and the agent has not contained the endpoint and the Zero Trust Overall Assessment score is greater than 20.

Let’s revisit the configuration parameters of the extension. The parameters of interest are enableEndpointLookupCache and enableCacheTimeSeconds. The values are explained in the table under the section “Configuration Steps”.

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“crowdStrikeApiHost”: “api.crowdstrike.com”,

“clientId”: “[Client ID]”,

“clientSecret”: “********”,

“crowdStrikeSyncZeroTrust”: false,

“enableEndpointCache”: false,

“endpointCacheTimeSeconds”: 300,

“syncAllOnStart”: false,

“enableSyncAll”: false,

“syncAllSchedule”: “0 2 * * 6”,

“syncUpdatedOnly”: true,

“syncPageSize”: 100,

“attributePrefix”: “”,

“bypassProxy”: false,

“enableStats”: true,

“statsUsername”: “”,

“statsPassword”: “********”

}

The access tracker results with the Authorization attributes are shown below.

Leverage the benefits of caching the attributes for faster authentication results. This is particularly useful in scenarios where clients roam frequently triggering frequent authentication requests. Use these parameters best suited in a customer environment based on their requirements.

Contain an endpoint using CrowdStrike APIs

ClearPass Policy Manager extension can call the CrowdStrike APIs to trigger containment on the endpoint leveraging the Falcon agent. APIs can also be leveraged to lift the containment.

Configuration for containment includes 3 steps on ClearPass Policy Manager. These steps can be ignored if the Enforcement Policies are exported directly as an XML. The steps are available in Appendix B.

1. Define Endpoint Context Server

2. Add Context Server Action

3. Create an Enforcement Profile to trigger the action

Endpoint Context Server

The first step is to define an Endpoint Context Server. This can be added under Administration > External Servers > Endpoint Context Servers click on Add and use the extension IP address highlighted in Figure 14.

Ensure you change this to http else the internal POST fails. Please note that this is an internal post within ClearPass from the Policy Manager to the Extension.

Context Server Action

The next step is to define a Context Server Action within ClearPass Policy Manager which will internally POST to the extension. The extension will trigger an API call to CrowdStrike and fetch the information associated with it which can be used for Authorization. The context server action allows us to define the HTTP Method, the URL and the JSON contents that will be used to post the mac address to the extension.

This can be added under Administration > Dictionaries > Context Server Actions. Click on Add and use the details shown below. All the other tabs are blank.

The URL used below has to match for the API calls to be successful. Kindly copy paste the URL from below

Contain: /contain/%{Connection:Client-Mac-Address-NoDelim}

Lift Containment: /lift-containment/%{Connection:Client-Mac-Address-NoDelim}

Similarly, a Context Server Action for lifting the containment is shown below.

Enforcement Profile

The next step involves using the Context Server Action in an Enforcement Profile as below. The Enforcement Profile for containing an endpoint leveraging CrowdStrike APIs action is shown below.

The Access Tracker result is shown below. CPPM triggers an internal API call to the extension configured.

Similarly, containment can be lifted from the hosts using the Lift Containment action or Enforcement Policy within CPPM.

Appendix A – Troubleshooting and Support

Here we list some basic troubleshooting steps. If you need any help beyond this, please reach out to HPE Aruba Networking Support.

Check API Access Application Control restrictions

If you’ve previously hardened your ClearPass deployment with Application Access Controls, it’s possible that the Extension will not work. Reviewing the Extension Log might show something like the following after immediately starting the Extension. This likely indicates the ClearPass Application API’s are in place.

Example of Extension authorization failure due to Policy Manager Application Control:

[2020-03-16T15:42:21.083] [INFO] Intune - Server listening on port 80.

[2020-03-16T15:42:21.243] [DEBUG] Intune - Request “GET ‘https://172.17.0.1/api/server/version’” took 51.91ms.

[2020-03-16T15:42:21.245] [DEBUG] Intune - <!DOCTYPE html><html>

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

var locHref = window.location.protocol + “//” + window.location.hostname;

window.location.href = locHref;

}

</script>

To resolve this issue, add the IP address of the Extension to the list of nodes permitted to access the API by navigating to Administration > Server Manager > Server Configuration {choose your node} > Network

Checking on the Extension Service

The ClearPass Extensions are supported by a system service which must be running.

Restarting this service will affect all deployed and running extensions.

To check on the state of the Extension Service, or to restart the service, go to Administration > Server Manager > Server Configuration > [SERVER] > Service Control. By default this service is automatically started.

Extensions and web proxy / firewall whitelisting

If ClearPass Policy Manager has been configured with a proxy, it’s still possible that domain whitelists are required, the same for some datacenter firewall to allow the installation of Extensions. Some enterprise customers maintain a whitelist of domain that are allowed to transit the proxy/firewall. The underlying docker configuration process uses standard docker registry access to pull images (hosted in docker hub). In general, the following hosts are used:

This is all also geo dependent to some degree and based on various AWS services, so AWS redirects and geo location services will vary. Finally, this all runs via standard HTTPS (port 443).

Extension Logs/Enable Debugging

If you have a requirement to access and view the logs from the Extension, you can turn on different logging levels from the Extension GUI. Adjust the logLevel to ‘DEBUG’ and restart the extension as shown below.

Logs can then be viewed from the ‘Show Logs’.

Remember after changing the logging level, as with any extension configuration change the extension will need to be restarted for this change to take effect.

Accessing the extension logs using ‘Collect Logs’ system function

In addition to viewing the logs as shown above, logs can also be collected and examined via the Policy Manager Collect Logs system function (Administration > Server Manager > Server Configuration > [Select SERVER] > Collect Logs). This is extremely useful should you have a need to call for technical assistance.

If the support team needs to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. By default the “logLevel” is set to INFO, but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set as required. Any of the levels will display the information for the selected state and lower; if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the logs have been collected, downloaded and expanded, you can locate the extension logs in the following location in the folder structure PolicyManagerLogs > extension > your-extension-id as shown below. Note the file-name is the same as the running instance ID of the extension.

Monitoring extension statistics

There is a way to monitor extension’s critical resource statistics with the configurable parameter added as part of the extension’s configuration. To enable extension statistics set the “enableStats” parameter to true. Remember a restart of the extension is need to activate the change anytime the config is modified.

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

Since we are authorizing against an external system, it could be relevant to monitor the performance of these transactions as you setup and deploy. If you suspect there is a performance issue, ClearPass provides a way to monitor the authorization processing time. The graph below shows an example of this data, navigate to Monitoring > Live Monitor > System Monitor [click on ClearPass Tab, then select [Authorization]….

Appendix B – Considerations for Installing in a Cluster

Extensions are not synced between ClearPass cluster members, and thus must be installed on each member separately.

Some Extensions can run in two modes: Periodic Sync Mode and Authorization Source Mode.

Periodic Sync Mode

If you are configuring the extension to poll external system periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

HTTP Authorization Source Mode

In this mode we configure an HTTP Auth source that results in a HTTPS call to external system during endpoint authorization. In this deployment model the extension must be installed on every cluster node that process authentications. Also in this scenario every cluster member’s extension must be set to the exact same IP address during installation time, as the HTTP Auth source configuration is propagated globally across all cluster members.

For example, if the extension IP range is 172.17.0.0/16, we would set the extension to 172.17.0.5 on every cluster member during installation of the extension.

While we normally want to avoid duplicate IP addresses in a network, this is not a concern with ClearPass extensions. Each ClearPass node communicates internally only with its own extension, and this traffic is not routed outside of ClearPass.

Subscriber nodes support the same ability as publishers to install an Extension from the Extension store.

Appendix C – endpoint sync schedule settings

The syncSchedule and similar scheduling parameters sets how often ClearPass executes certain actions like syncing or pushing endpoints. This setting is based on a slightly modified version of the CRON job scheduler found in Unix-like operating systems. It can be used to schedule jobs to run periodically at fixed times, dates or intervals.

A ‘cron’ is a job scheduler. Any scheduled task is called a ‘cron job’. The syntax for a cron job schedule is as follows:

In our use of the cron scheduler, we’ve dropped the use of the last instruction ≤command to execute> and use only the time/date functions, see below for a number of examples of scheduling a sync process.

• Schedule a sync to run at 2am daily:- 0 2 * * *

• Schedule a sync to run twice a day at 5am and 5pm:- 0 5,17 * * *

• Schedule a sync to run on every Sunday at 5pm:- 0 17 * * sun

• Schedule a sync to run every 30 minutes:- */30 * * * *

• Schedule a sync to run at 5pm on selected days:- 0 17 * * sun,fri

You can see from the above that the scheduling process is extremely flexible, alternatively https://crontab.guru/ is a great page for learning more about CRON scheduling.

Appendix D – Extension performance optimizations

Extensions are a critical part of ClearPass deployments today and with the increased dependency on extension interactions that involve periodic polling or real-time lookups, here are some of the best practice recommendations around optimizing overall performance when using extensions:

• If the extension is used to periodically poll external systems and populate endpoint repository, ensure that it is not installed in all the nodes in the cluster. Ideally these type of extensions should only be installed on the publisher node since only publisher node can add endpoint entries to the database. For redundancy, it can be installed on another additional node but it is recommended to stagger the polling interval so that both do not attempt to poll and update endpoint database at the same time.

  Example: 0 * * * *, This cron job runs at minute 0 of every hour (e.g., 00:00, 01:00, 02:00, etc.).

    30 * * * *, This cron job runs at minute 30 of every hour (e.g., 00:30, 01:30, 02:30, etc.).
  

• If the extension is used for looking up attributes from external systems in real time during authentication, it should be installed in all the nodes handling authentication. Note that the context server config is replicated from the publisher. When using extension for real time lookup, ensure that the extension has the same IP address in all the cluster nodes.

• If the extension is expected to do both real-time lookup and periodic polling, ensure that polling is enabled only on the publisher while the extension in subscribers can have the polling disabled by setting the “enableSyncAll” attribute to false.

     "enableSyncAll": false,
  

• Some 3rd party systems support fetching delta updates vs fetching all of the device information every polling cycle. The extensions that support fetching delta updates are: Workspace ONE Crowdstrike Falcon Microsoft Intune Mosyle SentinelOne Service Now

  For these extensions, the syncUpdatedOnly attribute should be set to true in extension config so that the number of DB updates in ClearPass is minimized

    "syncUpdatedOnly": true,
  

  For extensions that do not support syncUpdatedOnly, ensure that the sync interval is not aggressive. We recommend syncing at most twice a day and that too during off peak hours whenever a full sync is performed.

• Some 3rd party systems can be very noisy in terms of attribute updates. There could be certain attributes that keep changing every sync interval like “Free Memory in Bytes”, “Last Check in Time” etc. There is no value in updating endpoints when such trivial attributes change for the device. Hence it is recommended to use “ignoreEndpointDifferences” attribute in extension configuration to ignore change in attributes that you do not care about in terms of ClearPass policies.

  You can review the Audit Viewer in ClearPass under Monitoring > Audit Viewer to see what attributes are being updated for endpoints to check if there are unnecessary updates.

  Sample for JAMF extension:

    "ignoreEndpointDifferences": "Last Update, Report Date UTC, Last Contact Time UTC, Last Inventory Update UTC, Last Reported IP, IP Address",
  

  Default for Microsoft Intune extension:

    "ignoreEndpointDifferences": "Last Sync Date Time, Free Storage Space in Bytes",
  

• To further optimize the number of endpoints being updated in ClearPass, you can specify which attributes are being used in the ClearPass policies so that only changes to those attributes would trigger an update to the endpoint. This is done by listing out the specific attributes under endpointAttributes in extension configuration.

  Sample for JAMF extension:

    "endpointAttributes": "Group names, MDM Enabled, Managed, Remote Managed, Supervised, Serial Number",
  

• Setup extension to restart unless it was intentionally stopped. A restart policy can be defined in extension configuration to ensure that the extension starts up automatically after server reboots and such. Restart policy of “unless-stopped” would ensure the extension always starts up unless it was manually stopped.

  “restartPolicy”: “no” — The extension will not be automatically restarted after the server is restarted.

  “restartPolicy”: “always” — The extension will always be restarted after the server is restarted.

  “restartPolicy”: “unless-stopped” — The extension will be restarted unless it was stopped prior to the server restart, in which case it will maintain that state.

  “restartPolicy”: “on-failure:N” — If the extension fails to restart, the value for “N” specifies the number of times the extension should try to restart. If you do not provide a value for “N”, the default value will be “0”.

  The “restartPolicy” parameter is not present by default in extension configurations. When it is not present, if the system is restarted a default policy is applied to the extension to maintain the state it was in before the restart. If the “restartPolicy” parameter is added to the configuration but later removed, the extension will then revert to the default restart policy.

Appendix E – XMLs

The following steps are required to add CrowdStrike as an Authentication Source by importing it into ClearPass Policy Manager using the XML file available in our GitHub repository

https://github.com/aruba/clearpass-exchange-snippets/tree/master/extensions/CrowdStrike

• Download the XML profile > “clearpass-extension_crowdstrike_auth-source.xml”.

• Open the XML file using a simple editor and replace X.X.X.X with your EXTENSION IP ADDRESS (Refer Figure 14).

• You can also import the XML without making any edits and then change the “Base URL:” from “http://X.X.X.X” to your extension IP address using the ClearPass Policy Manager UI. This can be changed under the Primary tab of the imported Authentication Source (Refer 0).

• The XML file can be imported into ClearPass by navigating to Configuration > Authentication > Sources. Click on Import and use the file downloaded.

The Enforcement Profile, Context Server Action and the Endpoint Context Server configured in the section “Contain an endpoint using CrowdStrike APIs” can easily be imported using the XML available on HPE Aruba Networking GitHub

https://github.com/aruba/clearpass-exchange-snippets/tree/master/extensions/CrowdStrike

• Download the XML profile > “clearpass-extension_crowdstrike_enf-profile.xml”.

• Open this file in your favorite editor. Use the Find and Replace feature of the editor to replace “<<Extension IP>>” with the actual IP address of the extension configured. Refer Figure 14.

• The XML file can be imported into ClearPass by navigating to Configuration > Enforcement > Profiles. Click on Import and use the file downloaded.

Appendix F – Attributes Fetched from CrowdStrike

Following is the sample list of the default attributes fetched from CrowdStrike using the default policy. {

“CrowdStrike Cid”: “643b2392ec494d948e9c879c4fe11f3a”,

“CrowdStrike Status”: “normal”,

“CrowdStrike Hostname”: “B07D64852C5D-BG”,

“CrowdStrike Local IP”: “10.x.x.1x”,

“CrowdStrike OS Build”: “22000”,

“CrowdStrike Policies”: “prevention-6dfa63d7790446c4babf32db50e0810e”,

“CrowdStrike Device ID”: “27b832e592ab4e739583acfba1aaa004”,

“CrowdStrike Last Seen”: “2023-01-04T16:42:31Z”,

“CrowdStrike First Seen”: “2022-12-01T07:05:21Z”,

“CrowdStrike Group Hash”: “e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855”,

“CrowdStrike OS Version”: “Windows 11”,

“CrowdStrike External IP”: “49.205.32.38”,

“CrowdStrike Last Update”: “2023-01-04 16:45:00”,

“CrowdStrike MAC Address”: “b0-7d-64-85-2c-5d”,

“CrowdStrike Platform ID”: “0”,

“CrowdStrike BIOS Version”: “X571GT.311”,

“CrowdStrike Build Number”: “22000”,

“CrowdStrike Pointer Size”: “8”,

“CrowdStrike Product Type”: “1”,

“CrowdStrike System Found”: “true”,

“CrowdStrike Agent Version”: “6.48.16205.0”,

“CrowdStrike Assessment OS”: “78”,

“CrowdStrike Connection IP”: “10.x.10.x”,

“CrowdStrike Cpu Signature”: “591594”,

“CrowdStrike Major Version”: “10”,

“CrowdStrike Minor Version”: “0”,

“CrowdStrike Platform Name”: “Windows”,

“CrowdStrike Serial Number”: “M4N0CX12R927169”,

“CrowdStrike Config ID Base”: “65994753”,

“CrowdStrike Kernel Version”: “10.0.22000.1335”,

“CrowdStrike Config ID Build”: “16205”,

“CrowdStrike Device Policies”: “Prevention-6dfa63d7790446c4babf32db50e0810e, Sensor Update-b7178b018dcb4a8d83cec39401acfb5c, Device Control-5d3813ac29c44e54b48987b25c361bda, Global Config-67643d17e357489c8d6a08d38c07f1b4, Remote Response-22b6b4e42b6b4333bdb2f8112d1f7dea, Firewall-671577970e284f019faf83d9fa690842”,

“CrowdStrike Agent Load Flags”: “1”,

“CrowdStrike Agent Local Time”: “2023-01-04T19:36:42.247Z”,

“CrowdStrike Provision Status”: “Provisioned”,

“CrowdStrike BIOS Manufacturer”: “American Megatrends Inc.”,

“CrowdStrike Product Type Desc”: “Workstation”,

“CrowdStrike Assessment Overall”: “30”,

“CrowdStrike Assessment Version”: “3.5.1”,

“CrowdStrike Config ID Platform”: “3”,

“CrowdStrike Default Gateway IP”: “10.234.1.1”,

“CrowdStrike Modified Timestamp”: “2023-01-04T16:44:16Z”,

“CrowdStrike Sensor File Status”: “not deployed”,

“CrowdStrike Service Pack Minor”: “0”,

“CrowdStrike System Manufacturer”: “ASUSTeK COMPUTER INC.”,

“CrowdStrike System Product Name”: “VivoBook_ASUSLaptop X571GT_F571GT”,

“CrowdStrike Connection MAC Address”: “b0-7d-64-85-2c-5d”,

“CrowdStrike Assessment Modified Time”: “2022-12-30T07:55:03Z”,

“CrowdStrike Assessment Sensor Config”: “5”,

“CrowdStrike Reduced Functionality Mode”: “no”

}

3 - Firewall Context Sharing

3.1 - Juniper SRX Integration

Author: Zak Emerick, Herman Robers

Introduction and Overview

In preparation for the integration with the ClearPass Policy Manager certain minimum configuration is required on the SRX firewall to allow ClearPass and the SRX to communicate, share context and optionally allow the SRX to query ClearPass for session information.

The integration with the SRX supports two separate workflows:

1. Push model with webapi: ClearPass pushing context directly into the SRX.

2. Pull model with user-query: SRX to pull or query context from ClearPass. There are certain use cases when it is relevant for the SRX to query user context, such as when the SRX has been out of service for a software upgrade or when a new firewall comes online and needs to be aware of the current active network sessions.

Either workflows, or both, can be configured. Note that the pull model will add additional load to the ClearPass appliance.

Configuration of SRX webapi (Push Model)

Since SRX versions starting with 25.0 deprecated the WebUI, it’s currently recommended to configure the SRX via the CLI or configure the equivalent using Juniper Security Director.

Login to SRX using SSH to access the CLI. From the root prompt (for example, root@SRX650-TME%), enter the command cli to enter operational mode, then type configure or edit to enter configuration mode.

From configuration mode, configure the webapi service. Some of the information entered here will be used later when configuring ClearPass. The username and password will be used again when configuring ClearPass, so record them.

set system service webapi user <UserName> password <Password>

set system service webapi client <ClearPass IP>

NOTE: If you have multiple ClearPass instances, a client must be created for each IP address.

set system service webapi https port <8443>

set system service webapi http port <8080>

set system service webapi https default-certificate

Generating a custom certificate is outside the scope of this document but is strongly recommended for production deployments.

set system service webapi debug-level error

Confirming configuration.

matt@nac-srx.arubasecurity.net# show system services webapi 
user {
    cppm-api-user;
    password "$9$unNcOBESrvx-wp0BESeXxjHqmQF69A01R"; ## SECRET-DATA
}
client {
    10.127.208.77;
    10.127.208.76;
}
http {
    port 8080;
}
https {
    port 8443;
    default-certificate;
}
debug-level {
    error;
}

[edit]

Configuring ClearPass for SRX Integration (Push Model)

The following items are a prerequisite for the integration to function properly.

• Enable Insight at Administration -> Server Configuration -> Click Server -> Enable Insight

• Enable Interim Accounting-Update Packet logging at Administration -> Server Configuration -> Click Server -> Service Parameters -> Radius Server -> Log Accounting Interim-Update Packets

• Review Eager-Handler polling frequency setting at Administration -> Server Configuration -> Click Server -> Service Parameters -> Async network services -> Eager handler polling frequency. This defines how often updates are sent to SRX. Note that only true delta is sent which means if the device goes down and immediately comes up within the polling interval, the net effect is that nothing has changed and hence no update is sent.

Add the Juniper SRX as a Context Server

Navigate to Administration -> External Servers -> Endpoint Context Servers -> Add

Add the port to the URL that was configured on the SRX (for example,8443). Next, add the Username and Password as configured previously.

ClearPass Enforcement Policy and Profile

An Enforcement Profile and Enforcement Policy must now be created to send the context update to SRX based on specific policy conditions. For example if the use case is to apply specific firewall policies to IoT devices, the enforcement policy can be setup in such a way that the update is triggered only for such devices.

To create enforcement profile, navigate to Configuration -> Enforcement -> Profiles -> Add

Select the “Session Notification Enforcement” template.

Select Session-Notify as the type for each entry

Select Juniper Networks SRX as the Server-Type

Select Server-IP and the SRX host previously defined.

For the final two Session-Notify fields (“Login/Logout Action”), select the Juniper Networks SRX Login and Juniper Networks SRX Logout values respectively. If the expected Login/Logout server actions do not appear, verify the previous configuration steps.

To create an Enforcement Policy, navigate to Configuration -> Enforcement -> Policies -> Add

In the example below, there are different policy conditions that triggers the Post-Authentication Enforcement Profile “Update SRX” created above when the device is both compliant as well as non-compliant

The Enforcement policy must then be attached to the relevant Services.

Validating that the enforcement policy and profile is working correctly from ClearPass Access Tracker

Configuration of ClearPass for SRX Integration (Pull Model)

The HPE Juniper SRX can also query ClearPass to obtain authentication session information. Powered in part by REST and OAuth2, the SRX can query the ClearPass Insight Database to obtain the needed data for session context on the firewall. It is possible, though unlikely, that the SRX will not have context for an active network user. When the SRX is required to police a traffic flow and does not have the user’s context, it can query ClearPass. After receiving the query result, the SRX updates its auth-table and applies policy to the user appropriately.

The process to query a ClearPass appliance uses OAuth2 as the authentication method. This must be configured first to allow the user-authentication process.

Configure OAuth2 Client on ClearPass

The first part of this configuration is to set up OAuth2 as an API client. Log in to ClearPass and access the Guest module from the Menu in top right corner

Navigate to Administration -> API Services -> API Clients ->

Sample Operator Privileges Set the following permissions though Custom Access to the Operator Privileges Sections:

API Services > Allow API Access: Allow Access

Guest Manager > Active Sessions: Read Only

Guest Manager > Active Sessions History: Read Only

Policy Manager > Active Session for a MAC: Read

Policy Manager > Identity - Deny Listed Users: Read

Policy Manager > Identity – Endpoints: Read

Policy Manager > Insight – Endpoints: Read

Policy Manager > Insight – Alert: Read

All other settings should be set to: No Access.

Note that there is an option to generate an Access Token. This step is not required for this integration. The access token used by the SRX is generated dynamically by the SRX using the Client Secret.

No need to Generate Access-Token here

HPE Juniper SRX Configuration

Add ClearPass as a user identification authentication source. The name used is only a label. It is not tied to an FQDN, etc.

set services user-identification authentication-source aruba-clearpass
user-query web-server CPPM-Label

Define the connection method to be used (https or http).

set services user-identification authentication-source aruba-clearpass
user-query web-server connect-method https

set services user-identification authentication-source aruba-clearpass
user-query web-server address <ClearPass IP>

set services user-identification authentication-source aruba-clearpass
user-query client-id CPPM-SRX

set services user-identification authentication-source aruba-clearpass
user-query client-secret <Client Secret>

Define the token-api, this is always the same value.

set services user-identification authentication-source aruba-clearpass
user-query token-api api/oauth

set services user-identification authentication-source aruba-clearpass
user-query query-api api/v1/insight/endpoint/ip/$IP$

The commands above will generate the following configuration (the client secret will be encrypted):

root@SRX650-TME> show configuration services user-identification

authentication-source aruba-clearpass {

authentication-entry-timeout 100;

user-query {

web-server {

cppmserver160;

connect-method https;

address 10.2.100.160;

}

client-id CPPM-SRX;

client-secret
"$9$PTznCAuhSlaZqfzFtp8Lx7VYZUif5zZU9A0Bhc4oJUH.5QFn/tJGF6ApB1NdVwaG.P53n9jHORcyMWik.PTFREceMLRhv87-wsJZUj.f69ApORFncyre8LkqmPz69Ap";
\## SECRET-DATA

token-api api/oauth;

query-api "api/v1/insight/endpoint/ip/$IP$";

Configuring Ingress Event Processing for SRX

ClearPass can consume inbound syslog messages, parse them, and trigger an action such as an enforcement update for a user or endpoint. For example, an update regarding the posture or health of an endpoint can trigger an enforcement update for the device or user role, or it can trigger an update to a data center or internet access firewall based on the new context.

This feature allows event-driven, real-time enforcement within the enterprise network and enables a more effective protection framework.

Multiple steps are required to configure the Ingress Event Notification Framework. One of the more complex steps relates to the definition of the inbound parsing dictionary. Several dictionaries are supplied by default.

Note that Ingress Events Dictionaries can be added or created at any time. They do not require a ClearPass software release or patch.

Enable Ingress Events Processing

Navigate to Administration -> Server Manager -> Server Configuration -> [Your ClearPass Node] -> System

When enabling this feature a warning message is displayed as shown below which highlights and warns of the potential consequences. This feature can generate a significant CPU load on the ClearPass appliance.

Guidelines around enabling Ingress Event processing

Care must be taken when using this feature. While there are no exact deployments where it cannot be enabled, the following guidelines provide direction. The overriding resource issue is CPU cycles. It is possible for an appliance running at 80% CPU load to handle this feature without issue, while an appliance at 50% CPU load may experience problems. The key factor is not the current CPU load but the additional load that inbound syslog messages will generate. Appliances with multiple CPUs will perform better.

The intent behind this feature is for ClearPass to take a remediation action in response to a critical event seen in the network which typically does not happen in a constant stream. If the syslog messages received by ClearPass is highly curated and not a constant stream, it should be fine to enable this feature. ClearPass should be able to handle up to 1 event per second without issues. High rate of events or high load on the server can cause ingress event parsing to slow down considerably and even fail completely.

Hardware

Specific care needs to be taken when using C1000 / N1000 appliances. Especially if you plan to enable this on the older hardware, again the gating factor is “What CPU load will this generate on the appliance?”.

Virtual Machine

For virtual machines, it has always been difficult to control allocated resources, especially CPUs. Because this is a CPU-intensive workload, extra attention must be paid to the CPUs assigned to the virtual machine and current CPU usage.

General

In a cluster of multiple appliances or when the syslog messages might be numerous, it may be practical to dedicate an appliance to processing Ingress events.

If this feature is expected to be a major part of the deployment, a process should be undertaken to model the expected load and determine whether a dedicated appliance is required. If the deployment uses hardware appliances and a dedicated hardware appliance is not available for load modeling, deploy a temporary virtual machine to establish a baseline and better understand the demands of the Ingress workload. It is not recommended to deploy this feature on an appliance that is already running TCP Profiling. The combination of these two CPU-intensive tasks should be avoided.

Confirm Ingress Services are running

Start the services if they are stopped.

If the services do not start check under Monitoring -> Event Viewer for additional messages.

Configure Ingress port.

The logger service is responsible for listening on the defined port (default 514) and ingesting the syslog messages. Configure the TCP/UDP port at:
Administration -> Server Manager -> Server Configuration -> [Your ClearPass Appliance] -> Service Parameters [Ingress logger service]

Configuring the Ingress Events Dictionary

This file takes the structured or unstructured syslog messages and turns them into fields or attributes that can be referenced within a namespace.

Multiple Ingress Event Dictionaries are supplied by default. For the Juniper SRX integration, several dictionaries are available because the firewall can send syslog in multiple formats (primarily structured and traditional). By default, the SRX dictionaries are disabled and must be enabled. Only the required dictionaries should be enabled.

Enable the required dictionary at: Administration-> Dictionaries -> Ingress Events.

Click the desired dictionary and enable it.

Note the Attribute Names in the screenshot. These are the fields that parse the incoming syslog data. These fields can later be referenced in policy processing.

Add the Event Source

Define the event source at: Configuration -> Network -> Events Sources -> Add

Choose the correct vendor from the drop-down and make sure to enable the Event Source.

Building the Actions and Events

The following section describes how to add the necessary Enforcement Policies, Profiles, and Services to ClearPass. This configuration allows ClearPass to ingest the logs, parse the data, extract content and context from the syslog messages, and take action based on the received data.

The examples below may differ from the exact methods used in your environment to take advantage of the Ingress Events engine. However, they illustrate the framework and methodology offered by the Ingress engine and explain the core concept behind it.

Add the Enforcement Profile – Update Endpoint

Create a policy that is used to update an endpoint attribute when a “threat” has been detected. Create an Enforcement Policy under Configuration -> Enforcement -> Profiles -> Add and use the template ClearPass Entity Update Enforcement.

An endpoint attribute can be created or one that is supplied can be used. If a custom attribute is required, create it first in the Endpoint Attributes Dictionary. Depending on the logic used, an endpoint attribute may be updated or an attribute may be added to show the endpoint is in an unresolved state.

Consideration must be given to how these attributes will be removed or reset once the threat has been resolved or remediated.

Add the Event Enforcement Policy

Create an Event Enforcement Policy at: Configuration -> Enforcement -> Policies -> Add and confirm that the Enforcement Type is Event

The Rules tab is where the events to key off are defined. The available options depend on which Event Dictionaries have been enabled. For this example, two SRX dictionaries and one PANW dictionary were enabled. If a custom Ingress Events dictionary has been created and enabled, it will appear here.

Choosing ‘Juniper-SRX-SS’ and expanding the namespace ‘Name’ displays all fields configured in that Ingress Event Dictionary.

In the example a simple check is used to demonstrate the configuration. You can set the policy to trigger an update to the endpoint if the word “threat” is seen in the alert field.

Numerous fields are available and any field in the namespace ‘Name’ can be used to trigger an event with operators such as CONTAINS, EQUALS, EXISTS, BEGINS_WITH, NOT_EQUAL, NOT_CONTAINS, NOT_BELONGS_TO, etc.

Add the Event Service

Create this under Configuration -> Services -> Add with the type as Event-based Enforcement.

Setup is now complete to receive and parse syslog messages from an HPE Juniper SRX firewall. In the example, an endpoint in the Endpoint Database is marked as malicious or out-of-policy. ClearPass then triggers an enforcement action. Typically, for a device flagged as malicious, the desired outcome is to quarantine or isolate the device or user. A typical enforcement action is to issue a Change of Authorization (CoA) so that ClearPass can re-evaluate the device based on its updated status.

Tuning the Ingress Event Engine [IEE] Processing

The process of ingesting syslog messages, parsing the data, and writing it to the Event Database before triggering an event can take time. This process is heavily dependent on the physical resources available on the appliance, the number of dictionaries enabled, and the Batch Processing Interval.

The Batch Processing Interval determines how frequently the Event Engine checks the Event Database for new entries. On lower-powered or older hardware, the default of 30 seconds should suffice, but it may need to be increased.

For the C3010, N3001 hardware appliance, or an appliance dedicated to IEE processing, this parameter may need to be lowered to make the process more real-time.

Setting up Syslog on Juniper SRX

The syslog configuration on a Juniper SRX can be extensive. Logs can be stored locally or sent to an external syslog server. Events can be logged from the system and/or from traffic. The focus for this integration is data-plane traffic logs. These logs are generated by processes that control data flow, such as the firewall and IPS processes.

Below is a basic syslog configuration.

root@SRX650-TME> show configuration system syslog

archive size 100k files 3;

user \* {

any emergency;

}

file messages {

any critical;

authorization info;

}

file interactive-commands {

interactive-commands error;

}

To configure the SRX to forward data-plane syslog messages to a ClearPass appliance, several settings are required. The example below contains the core requirements to send to two syslog servers. It demonstrates the ability of the SRX to send syslog messages to multiple targets and to differentiate by syslog type, formatting, category, etc.

The configuration shows system/node-specific settings such as stream mode and source address, along with two ClearPass appliances (to_cppm and to_beta1) that can override system-level settings.

root@SRX650-TME> **show configuration security log**

mode stream;

format syslog;

source-address 10.2.51.132;

stream to\_cppm {

severity debug;

format sd-syslog;

filter threat-attack;

host {

10.2.51.210;

port 514;

}

}

stream to\_beta1 {

severity critical;

format syslog;

category idp;

host {

10.2.100.162;

port 514;

}

}

ClearPass Access Tracker Logs Examples

The following examples show the logs posted in the ClearPass Access Tracker when an Event occurs. The view is filtered to show only Events.

Validation

Monitoring user context under JUNOS webapi

To validate user authentication context is being received from ClearPass use the following command.

matt@nac-srx.arubasecurity.net> show services user-identification authentication-table authentication-source aruba-clearpass extensive 
Logical System: root-logical-system

Domain: GLOBAL
Total entries: 1
  Key: 10.127.209.150
    Username: host/oak-win-01
    Groups:posture-unhealthy, c2c_fullaccess, domain computers, [machine authenticated]
    State: Valid
    Source: Aruba ClearPass
    Access start date: 2026-05-15
    Access start time: 16:26:56
    Last updated timestamp: 2026-05-15 23:28:10
    Age time: 28

Validate user-query (Pull Method)

Use the commands below to validate the user-query method.

root@SRX650-TME> show services user-identification
authentication-table authentication-source aruba-clearpass extensive

Domain: ns-tme

Total entries: 1

Source-ip: 10.2.100.167

Username: djump

Groups:posture-unknown, \[user authenticated\], rooted

State: Valid

Source: Aruba ClearPass

Access start date: 2026-04-30

Access start time: 15:45:56

Last updated timestamp: 2026-04-30 23:45:15

Age time: 100

Clear the SRX Auth table

root@SRX650-TME> clear services user-identification
authentication-table authentication-source aruba-clearpass

Confirm the authentication-table is clear

root@SRX650-TME> show services user-identification
authentication-table authentication-source aruba-clearpass extensive

warning: "There is no authentication-table entry."

Force the SRX to request an update from ClearPass (It is actually querying ClearPass via Rest APIs)

root@SRX650-TME> request services user-identification
authentication-source aruba-clearpass user-query address 10.2.100.167

Confirm user is in authentication-table.

root@SRX650-TME> show services user-identification
authentication-table authentication-source aruba-clearpass extensive

Domain: GLOBAL

Total entries: 1

Source-ip: 10.2.100.167

Username: djump

Groups:posture-unknown, \[user authenticated\], rooted

State: Valid

Source: Aruba ClearPass

Access start date: 2026-04-30

Access start time: 15:47:37

Last updated timestamp: 2026-04-30 23:45:22

Age time: 100

Monitoring the user-query (Pull Method)

Using the below JUNOS CLI commands from operational-mode, you can check the status of the ClearPass to SRX connectivity.

root@SRX650-TME> show services user-identification
authentication-source aruba-clearpass user-query status

Authentication source: aruba-clearpass

Web server Address: 10.2.100.160  
Status: Online  
Current connections: 1

Monitoring the number of requests/responses between ClearPass and the SRX

root@SRX650-TME> show services user-identification
authentication-source aruba-clearpass user-query counters

Authentication source: aruba-clearpass

Web server Address: 10.2.100.160

Access token: 0f0d31e4bfcd4809d67535ecc68298f25d2ca036

Request sent number: 3

Total response received number: 3

Error response received number: 0

Time of last response: 2026-04-30 11:38:53

Appendix

SRX Query Rate to ClearPass for Session Data

In all SRX platforms, the max query rate is 600 queries / minute.

Additional Resources

Integrating ClearPass with Juniper Networks SRX Endpoint Context Server

The ClearPass RESTful API’s SRX is querying (Pull Method)

The following are the REST APIs that the SRX uses to pull user data.

Using the IP query, the API was tested via the Swagger interface. A wealth of data is returned for the endpoint 10.2.100.167.

4 - OT/ICS/IIoT/MIoT

4.1 - SOTI Connect

Introduction

SOTI Connect is an enterprise IoT device management solution that provides complete lifecycle management of connected devices — including industrial and mobile printers, IoT-enabled sensors, and other OT/ICS endpoints — from a single point of control. This integration guide covers the setup, configuration, and monitoring of the SOTI Connect ClearPass Extension within ClearPass Policy Manager. The extension enables ClearPass to retrieve endpoint data managed by SOTI Connect, enriching device profiles with up-to-date attributes for use in policy enforcement and access control decisions. Note that this integration supports periodic sync mode only, where ClearPass pulls managed endpoints and their associated attributes from SOTI Connect at configured intervals.

Pictorial View of the Integration

The extension can be configured to periodically sync device information from SOTI Connect.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

ClearPass SOTI Connect Extension Configuration

After installing the Extension, the default configuration will need to be updated.

Common extension attributes

Extension framework configuration parameters (common configuration)

SOTI Connect specific extension attributes

SOTI Connect Configuration

This extension communicates with your SOTI Connect tenant via publicly exposed and documented API’s. The only configuration needed on SOTI Connect is to create an API client.

Adding an API Client

To add an API client, you must have the required privileges on your SOTI Connect tenant.

Log in to the SOTI Connect tenant and navigate to SYSTEM ADMINISTRATION > Global Settings by clicking on the hamburger menu on the top left of your tenant UI.

Under Global Settings, click Security Access under General. On the right side of the screen, click the ADD A SECURITY ACCESS icon to create a new Client ID and Client Secret.

Click GENERATE to create a new Client ID and Client Secret, then click SAVE. You can click the view button in the Client Secret field to see the secret value. Copy the Client ID and Client Secret temporarily to use them while setting up the extension on ClearPass.

Using the information returned by SOTI Connect into ClearPass Policies.

The endpoint attributes returned by SOTI Connect can be used to make policy decisions in ClearPass when an endpoint authenticates on the network. These attributes can be used in Role Mapping policies to assign various roles to endpoints based on the SOTI Connect attributes and later use those roles to make access control decisions. They can also be used directly in enforcement policies to evaluate policy conditions built on these attributes and make access control decisions as needed. Let’s look at an example of building Role Mapping policies using these attributes.

Appendix A – Troubleshooting and Support

Here we list some basic troubleshooting steps. If you need any help beyond this, please reach out to HPE Aruba Networking Support.

Check API Access Application Control restrictions

If you’ve previously hardened your ClearPass deployment with Application Access Controls, it’s possible that the Extension will not work. Reviewing the Extension Log might show something like the following after immediately starting the Extension. This likely indicates the ClearPass Application API’s are in place.

Example of Extension authorization failure due to Policy Manager Application Control:

[2020-03-16T15:42:21.083] [INFO] Intune - Server listening on port 80.

[2020-03-16T15:42:21.243] [DEBUG] Intune - Request “GET ‘https://172.17.0.1/api/server/version’” took 51.91ms.

[2020-03-16T15:42:21.245] [DEBUG] Intune - <!DOCTYPE html><html>

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

var locHref = window.location.protocol + “//” + window.location.hostname;

window.location.href = locHref;

}

</script>

To resolve this issue, add the IP address of the Extension to the list of nodes permitted to access the API by navigating to Administration > Server Manager > Server Configuration {choose your node} > Network

Checking on the Extension Service

The ClearPass Extensions are supported by a system service which must be running.

Restarting this service will affect all deployed and running extensions.

To check on the state of the Extension Service, or to restart the service, go to Administration > Server Manager > Server Configuration > [SERVER] > Service Control. By default this service is automatically started.

Extensions and web proxy / firewall whitelisting

If ClearPass Policy Manager has been configured with a proxy, it’s still possible that domain whitelists are required, the same for some datacenter firewall to allow the installation of Extensions. Some enterprise customers maintain a whitelist of domain that are allowed to transit the proxy/firewall. The underlying docker configuration process uses standard docker registry access to pull images (hosted in docker hub). In general, the following hosts are used:

This is all also geo dependent to some degree and based on various AWS services, so AWS redirects and geo location services will vary. Finally, this all runs via standard HTTPS (port 443).

Extension Logs/Enable Debugging

If you have a requirement to access and view the logs from the Extension, you can turn on different logging levels from the Extension GUI. Adjust the logLevel to ‘DEBUG’ and restart the extension as shown below.

Logs can then be viewed from the ‘Show Logs’.

Remember after changing the logging level, as with any extension configuration change the extension will need to be restarted for this change to take effect.

Accessing the extension logs using ‘Collect Logs’ system function

In addition to viewing the logs as shown above, logs can also be collected and examined via the Policy Manager Collect Logs system function (Administration > Server Manager > Server Configuration > [Select SERVER] > Collect Logs). This is extremely useful should you have a need to call for technical assistance.

If the support team needs to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. By default the “logLevel” is set to INFO, but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set as required. Any of the levels will display the information for the selected state and lower; if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the logs have been collected, downloaded and expanded, you can locate the extension logs in the following location in the folder structure PolicyManagerLogs > extension > your-extension-id as shown below. Note the file-name is the same as the running instance ID of the extension.

Monitoring extension statistics

There is a way to monitor extension’s critical resource statistics with the configurable parameter added as part of the extension’s configuration. To enable extension statistics set the “enableStats” parameter to true. Remember a restart of the extension is need to activate the change anytime the config is modified.

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

Since we are authorizing against an external system, it could be relevant to monitor the performance of these transactions as you setup and deploy. If you suspect there is a performance issue, ClearPass provides a way to monitor the authorization processing time. The graph below shows an example of this data, navigate to Monitoring > Live Monitor > System Monitor [click on ClearPass Tab, then select [Authorization]….

Appendix B – Considerations for Installing in a Cluster

Extensions are not synced between ClearPass cluster members, and thus must be installed on each member separately.

Some Extensions can run in two modes: Periodic Sync Mode and Authorization Source Mode.

Periodic Sync Mode

If you are configuring the extension to poll external system periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

HTTP Authorization Source Mode

In this mode we configure an HTTP Auth source that results in a HTTPS call to external system during endpoint authorization. In this deployment model the extension must be installed on every cluster node that process authentications. Also in this scenario every cluster member’s extension must be set to the exact same IP address during installation time, as the HTTP Auth source configuration is propagated globally across all cluster members.

For example, if the extension IP range is 172.17.0.0/16, we would set the extension to 172.17.0.5 on every cluster member during installation of the extension.

While we normally want to avoid duplicate IP addresses in a network, this is not a concern with ClearPass extensions. Each ClearPass node communicates internally only with its own extension, and this traffic is not routed outside of ClearPass.

Subscriber nodes support the same ability as publishers to install an Extension from the Extension store.

Appendix C – endpoint sync schedule settings

The syncSchedule and similar scheduling parameters sets how often ClearPass executes certain actions like syncing or pushing endpoints. This setting is based on a slightly modified version of the CRON job scheduler found in Unix-like operating systems. It can be used to schedule jobs to run periodically at fixed times, dates or intervals.

A ‘cron’ is a job scheduler. Any scheduled task is called a ‘cron job’. The syntax for a cron job schedule is as follows:

In our use of the cron scheduler, we’ve dropped the use of the last instruction ≤command to execute> and use only the time/date functions, see below for a number of examples of scheduling a sync process.

• Schedule a sync to run at 2am daily:- 0 2 * * *

• Schedule a sync to run twice a day at 5am and 5pm:- 0 5,17 * * *

• Schedule a sync to run on every Sunday at 5pm:- 0 17 * * sun

• Schedule a sync to run every 30 minutes:- */30 * * * *

• Schedule a sync to run at 5pm on selected days:- 0 17 * * sun,fri

You can see from the above that the scheduling process is extremely flexible, alternatively https://crontab.guru/ is a great page for learning more about CRON scheduling.

Appendix D – Extension performance optimizations

Extensions are a critical part of ClearPass deployments today and with the increased dependency on extension interactions that involve periodic polling or real-time lookups, here are some of the best practice recommendations around optimizing overall performance when using extensions:

• If the extension is used to periodically poll external systems and populate endpoint repository, ensure that it is not installed in all the nodes in the cluster. Ideally these type of extensions should only be installed on the publisher node since only publisher node can add endpoint entries to the database. For redundancy, it can be installed on another additional node but it is recommended to stagger the polling interval so that both do not attempt to poll and update endpoint database at the same time.

  Example: 0 * * * *, This cron job runs at minute 0 of every hour (e.g., 00:00, 01:00, 02:00, etc.).

    30 * * * *, This cron job runs at minute 30 of every hour (e.g., 00:30, 01:30, 02:30, etc.).
  

• If the extension is used for looking up attributes from external systems in real time during authentication, it should be installed in all the nodes handling authentication. Note that the context server config is replicated from the publisher. When using extension for real time lookup, ensure that the extension has the same IP address in all the cluster nodes.

• If the extension is expected to do both real-time lookup and periodic polling, ensure that polling is enabled only on the publisher while the extension in subscribers can have the polling disabled by setting the “enableSyncAll” attribute to false.

     "enableSyncAll": false,
  

• Some 3rd party systems support fetching delta updates vs fetching all of the device information every polling cycle. The extensions that support fetching delta updates are: Workspace ONE Crowdstrike Falcon Microsoft Intune Mosyle SentinelOne Service Now

  For these extensions, the syncUpdatedOnly attribute should be set to true in extension config so that the number of DB updates in ClearPass is minimized

    "syncUpdatedOnly": true,
  

  For extensions that do not support syncUpdatedOnly, ensure that the sync interval is not aggressive. We recommend syncing at most twice a day and that too during off peak hours whenever a full sync is performed.

• Some 3rd party systems can be very noisy in terms of attribute updates. There could be certain attributes that keep changing every sync interval like “Free Memory in Bytes”, “Last Check in Time” etc. There is no value in updating endpoints when such trivial attributes change for the device. Hence it is recommended to use “ignoreEndpointDifferences” attribute in extension configuration to ignore change in attributes that you do not care about in terms of ClearPass policies.

  You can review the Audit Viewer in ClearPass under Monitoring > Audit Viewer to see what attributes are being updated for endpoints to check if there are unnecessary updates.

  Sample for JAMF extension:

    "ignoreEndpointDifferences": "Last Update, Report Date UTC, Last Contact Time UTC, Last Inventory Update UTC, Last Reported IP, IP Address",
  

  Default for Microsoft Intune extension:

    "ignoreEndpointDifferences": "Last Sync Date Time, Free Storage Space in Bytes",
  

• To further optimize the number of endpoints being updated in ClearPass, you can specify which attributes are being used in the ClearPass policies so that only changes to those attributes would trigger an update to the endpoint. This is done by listing out the specific attributes under endpointAttributes in extension configuration.

  Sample for JAMF extension:

    "endpointAttributes": "Group names, MDM Enabled, Managed, Remote Managed, Supervised, Serial Number",
  

• Setup extension to restart unless it was intentionally stopped. A restart policy can be defined in extension configuration to ensure that the extension starts up automatically after server reboots and such. Restart policy of “unless-stopped” would ensure the extension always starts up unless it was manually stopped.

  “restartPolicy”: “no” — The extension will not be automatically restarted after the server is restarted.

  “restartPolicy”: “always” — The extension will always be restarted after the server is restarted.

  “restartPolicy”: “unless-stopped” — The extension will be restarted unless it was stopped prior to the server restart, in which case it will maintain that state.

  “restartPolicy”: “on-failure:N” — If the extension fails to restart, the value for “N” specifies the number of times the extension should try to restart. If you do not provide a value for “N”, the default value will be “0”.

  The “restartPolicy” parameter is not present by default in extension configurations. When it is not present, if the system is restarted a default policy is applied to the extension to maintain the state it was in before the restart. If the “restartPolicy” parameter is added to the configuration but later removed, the extension will then revert to the default restart policy.

Appendix E – Sample List of returned SOTI MobiControl endpoint attributes

{

“Active IP Address”,

“Active Protocol”,

“Approval Date”,

“Approved”,

“Certificate Action Permissions”,

“Compliance Status”,

“Connection Status”,

“Deactivated Type”,

“Deleted”,

“Description”,

“Device Type ID”,

“Device Type Internal ID”,

“Device Type Name”,

“Discover Date”,

“ID”,

“Last Connection Check Time”,

“Last Connection Update Time”,

“Last Seen Time”,

“Last Update”,

“Name”,

“New Firmware Available”,

“Normal Action Permissions”,

“Protocol Adapter Name”,

“Protocol Instance Name”,

“Protocol Name”,

“Remote Control Capability”,

“Status”,

“Supported Protocols”

}

5 - Unified Endpoint Management

5.1 - Jamf Pro

Change Log

What’s new in Jamf v5.0?

In this release v5.0, support for the Jamf Pro API’s has been added to the JAMF extension. This update is introduced in response to JAMF’s announcement of the deprecation of Jamf Classic APIs, which will no longer be supported in the future. To ensure continued functionality and compatibility with JAMF’s supported interfaces, the integration now supports the Jamf Pro API while continuing to retain support for the Jamf Classic APIs. Once JAMF fully deprecates the Jamf Classic APIs, enabling the use of the Jamf Pro API will no longer be optional. Additional details regarding the Jamf Classic API deprecation can be found in JAMF’s official notice- https://developer.jamf.com/jamf-pro/docs/deprecation-of-classic-api-computer-inventory-endpoints.

A new configuration parameter, enableV2Api, has been added to control API usage. Setting this parameter to true enables the use of the Jamf Pro API, while setting it to false retains the use of the Jamf Classic APIs. Once the Jamf Classic APIs are fully deprecated, the extension will no longer function if this parameter remains set to false. Customers are therefore strongly recommended to switch to using the Jamf Pro API at their earliest convenience by setting enableV2Api to true. A restart of the extension is required for the new configuration to take effect.

There are differences in attribute naming conventions between the Jamf Classic APIs and the Jamf Pro API. As a result, it is important to review the Jamf attributes currently used within ClearPass policies and verify whether any policy logic relies on attribute names that have changed in the Jamf Pro API. Where applicable, policies must be updated to reference the new Jamf Pro API attribute names to ensure continued and correct policy evaluation. Failure to update affected policies may result in unintended behavior or service disruption due to attribute name changes between the Jamf Classic and Jamf Pro APIs. The reference table below provides a mapping of attributes between the Jamf Classic API and the Jamf Pro API to assist in identifying any required policy updates.

Please note that, depending on specific customer use cases and any custom modifications or additional attributes in use, not all Jamf attributes may be included in the provided reference list. The list primarily covers attributes returned in standard API responses. For any attributes that are not listed, it is recommended to contact Jamf Support to confirm whether there are differences in attribute naming conventions between the Jamf Classic APIs and the Jamf Pro API.

What’s New in Jamf Extension v4.3?

Starting release v4.3.1 we have added support for data-types like Date-time, Integer and Boolean for attributes synced from Jamf to ClearPass. In the earlier releases all attributes were stored in ClearPass Policy Manager as Strings. However some attributes from Jamf are needed to be processed as Date-time, Integer and Boolean data-type attributes e.g “Jamf Last Contact Time UTC”. ClearPass policlies that use these attributes should be able to support these attributes with the correct data-type. Upgrading to extension version 4.3.1 will now update the Dictionary Attributes on ClearPass synced from Jamf with the correct data-type. This gives customers option to build policies using date and time based attributes like Jamf Last Contact Time UTC, Jamf Last Inventory update or other Integer and Boolean attributes like Jamf Managed etc with the correct operators in policies which best suits to evaluate an attribute.One such example of an enforcement policy to check whether an endpoints last contact time with Jamf is not more than a week is shown below.

Upgrading to this release requires a pre-requsite step to first delete the Date-time, Integer and Boolean attributes that have already been added with the string data-type so that the extension can then update these attributes in the endpoint database with correct data-types. It is recommended that this step is followed before upgrading the extension to avoid running into errors while updating these attributes in the endpoint database during the re-sync process. The steps to follow before upgrading the extension are detailed below.

• Stop the older version of the extension running.
• Go to Configuration > Identity > Endpoints and set filter as shown in below image to see all the endpoints synced from Jamf.
• Select all endpoints synced from Jamf. Click on ‘Bulk Delete’ and add the attributes to be deleted from the below list.

Date-Time
Initial Entry Date UTC
Last Contact Time UTC
Report Date UTC
Last Inventory Update UTC
Last Update

Boolean
Remote Managed
Managed
Supervised
System Found
User Approved Enrollment
Data Protection
Activation Lock Enabled
Block Level Encryption Capable
File Level Encryption Capable
Passcode Compliant
Passcode Present
Lost Mode Enabled

Integer32
Room
Hardware Encryption

• Once the attributes are deleted. Go to the extensions page and upgrade to / install the new extension.
• You should now be able to see the updated Dictonary attributes from Jamf and the updated attributes in the correct Data-type format in endpoint DB.

What's New in Jamf Extension v4.2?

Beginning version 10.49.0 of Jamf Pro, the Classic API will now support Client Credentials based authorization. To conform with this, the Jamf Extension v4.2 has been updated to support Access Tokens that can be used to interact with the Jamf Pro API endpoints. The new vesion of extension has two additional fields “ClientID” and “ClientSecret”. Simlar to obtaining a bearer token using a username and password in earlier releases. The client ID and client secret will be exchanged by the extension for generating access tokens to interface with the Jamf Pro API’s. Jamf has already announced that basic authentication in the Classic API will no longer be enabled by default for the new Jamf Pro instances for enhanced security and will be deprecated after 31^st^ March 2024. All customers are recommened to update to v4.2 Extension for better security practices and to maintain best combatibility with Jamf. This release will continue to offer both the jamfUsername / jamfPassword and ClientId / ClientSecret fields in the default extension configuration to allow customers migrate smoothly as the new auth mechanism will need the API roles and clients functionality configured on the Jamf Pro side. More details on this is available in Jamf Pro documentation https://learn.jamf.com/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html

The privileges required to support the API endpoints needed to interact with Jamf Pro for the integration are as follows.

Privileges

Read Mobile Devices, Read Computers, Read Computer Extension Attributes, Create Computer Extension Attributes.

Read Computer Extension Attributes and Create Computer Extension Attributes are needed only when the “createMacExtensionAttribute” is set to true.

If createMacExtensionAttribute is set to true, Jamf will scan all MAC addresses on a device and string them together, ClearPass will interpret each MAC address as a separate endpoint with the same name and create separate endpoints in the ClearPass endpointDb

INFO

ClientId / ClientSecret takes precedence over jamfUserName / JamfPassword when both are configured.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

Pictorial View of the Integration

The extension can be configured in one mode of operation.

Periodic Sync Mode

In this mode ClearPass polls Jamf periodically and updates the ClearPass Endpoint database with attributes obtained from Jamf. These attributes can be utilized in ClearPass during endpoint Authorization. This mode has a simpler configuration demand, however, the data provided may not be completely up to date at authentication time and is dependent upon Jamf running a script on their side which is not well documented.

ClearPass Jamf Extension Configuration

After installing the Extension, the default configuration will need to be updated. The configuration parameters are divided into two tables, one for Jamf Extension-specific configuration parameters and the other for Extension framework configuration parameters that are common across multiple vendor Extensions.

Table 1: Jamf Extension-specific configuration parameters

Common extension attributes

Extension framework configuration parameters (common configuration)

Additional Configuration Notes

At a minimum, you’ll need to set these attributes:

• jamfHost

• jamfUserName

• jamfPassword

If using the extension to sync device information to the endpoint database, set the enableSyncAll and syncAllSchedule attributes, and optionally the syncAllOnStart attribute. Note that enableSyncAll and syncAllOnStar both default to “false”, so to enable they need to be changed to “true”. Also note that in the v4 Extension the syntax for these sync attributes changed compared to previous versions, but the functionality remains the same.

If createMacExtensionAttribute is set to true, Jamf will scan all MAC addresses on a device and string them together, ClearPass will interpret each MAC address as a separate endpoint with the same name and create separate endpoints in the ClearPass endpointDb.

The logLevel, verifySSLCerts and enableStats should be left as their default settings unless advised by ClearPass TAC or your HPE Aruba Networking SE/Partner. Once you configure these parameters, you can start your extension. Any subsequent reconfiguration requires a restart of the extension.

Jamf Pro Configuration

The ClearPass Jamf Extension communicates with your Jamf/Jamf Pro tenant via publicly exposed and documented API’s.

Jamf / Jamf Pro Configuration

Collecting all mac-addresses macOS devices in Jamf-pro

When the extension is installed in ClearPass Guest, and the “createMacExtensionAttribute” attribute is set to true, the extension attribute “cppm-all-mac-addresses” will be created within the Jamf environment only if the supplied “jamfUserName” and “jamfPassword” are correct, and only if the provided “jamfUserName” has the appropriate level of access within Jamf to create the extension. If not, manual creation of the Extension Attribute will need to occur by a Jamf administrator.

Follow the below steps to validate that the Extension Attribute has been created within Jamf / Jamf Pro. After login, click on the gear at the top right of the page.

Then click Computer Management > Extension Attributes on the Jamf nav-bar as shown below.

Next, click on Extension Attributes in the Computer Management – Management Framework section.

If you do not see the “cppm-all-mac-addresses” Extension Attribute listed, the Jamf account that was configured within the ClearPass Extension does not have the appropriate level of access to create an Extension Attribute. You will need to have the customer contact their Jamf administrator for support of this issue.

Configuring ClearPass Policy Manager

Multiple methods exist for how ClearPass can utilize the returned data from Jamf, such as:

• Ensure that the endpoint is managed by Jamf. If not, perhaps restrict access for the device on the Corporate Network with a role that only allows the user to remediate and install the Jamf endpoint agent. This provides a controlled environment where all endpoints are protected.

• Check if the endpoint has the latest Jamf agent installed. If not, perhaps quarantine the device with the option to remediate and install and updated Jamf client.

• Another very powerful use case is to check if the actual Jamf agent is running.

• If you’re using the macExtensionAttributeName attribute “cppm-all-mac-addresses”, all mac-address will be collected on the MAC. This is useful to ensure all-mac-addresse are reported to ClearPass so individual records for each interface are created to ensure that regardless of the mac-address used to authenticate, ClearPass has knowledge of it*.*

As mentioned previously, the extension supports only a single mode of use, “Sync endpoint data from Jamf Pro into the ClearPass EndpointDb.

Periodic Sync Mode: Using stored attributes

The Extension will sync data from Jamf based upon a configurable schedule, write this data into the ClearPass EndpointDB, this data is then used in policy as an authorization source. Be aware that this data is not ‘real-time’. Here’s an example of a ClearPass Role Mapping Policy that utilizes these Jamf Pro Endpoint attributes.

Appendix A – List of returned Jamf Pro endpoint attributes

RootElement.ChildElement1.ChildElement2.ChildElement3.ChildElement4.ChildElement5

Example: If you wanted to pull mdm_capable and gatekeeper_status from Jamf, your extention configuration variable “additionalAttributeMapping” would look like this:

Appendix A – Troubleshooting and Support

Here we list some basic troubleshooting steps. If you need any help beyond this, please reach out to HPE Aruba Networking Support.

Check API Access Application Control restrictions

If you’ve previously hardened your ClearPass deployment with Application Access Controls, it’s possible that the Extension will not work. Reviewing the Extension Log might show something like the following after immediately starting the Extension. This likely indicates the ClearPass Application API’s are in place.

Example of Extension authorization failure due to Policy Manager Application Control:

[2020-03-16T15:42:21.083] [INFO] Intune - Server listening on port 80.

[2020-03-16T15:42:21.243] [DEBUG] Intune - Request “GET ‘https://172.17.0.1/api/server/version’” took 51.91ms.

[2020-03-16T15:42:21.245] [DEBUG] Intune - <!DOCTYPE html><html>

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

var locHref = window.location.protocol + “//” + window.location.hostname;

window.location.href = locHref;

}

</script>

To resolve this issue, add the IP address of the Extension to the list of nodes permitted to access the API by navigating to Administration > Server Manager > Server Configuration {choose your node} > Network

Checking on the Extension Service

The ClearPass Extensions are supported by a system service which must be running.

Restarting this service will affect all deployed and running extensions.

To check on the state of the Extension Service, or to restart the service, go to Administration > Server Manager > Server Configuration > [SERVER] > Service Control. By default this service is automatically started.

Extensions and web proxy / firewall whitelisting

If ClearPass Policy Manager has been configured with a proxy, it’s still possible that domain whitelists are required, the same for some datacenter firewall to allow the installation of Extensions. Some enterprise customers maintain a whitelist of domain that are allowed to transit the proxy/firewall. The underlying docker configuration process uses standard docker registry access to pull images (hosted in docker hub). In general, the following hosts are used:

This is all also geo dependent to some degree and based on various AWS services, so AWS redirects and geo location services will vary. Finally, this all runs via standard HTTPS (port 443).

Extension Logs/Enable Debugging

If you have a requirement to access and view the logs from the Extension, you can turn on different logging levels from the Extension GUI. Adjust the logLevel to ‘DEBUG’ and restart the extension as shown below.

Logs can then be viewed from the ‘Show Logs’.

Remember after changing the logging level, as with any extension configuration change the extension will need to be restarted for this change to take effect.

Accessing the extension logs using ‘Collect Logs’ system function

In addition to viewing the logs as shown above, logs can also be collected and examined via the Policy Manager Collect Logs system function (Administration > Server Manager > Server Configuration > [Select SERVER] > Collect Logs). This is extremely useful should you have a need to call for technical assistance.

If the support team needs to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. By default the “logLevel” is set to INFO, but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set as required. Any of the levels will display the information for the selected state and lower; if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the logs have been collected, downloaded and expanded, you can locate the extension logs in the following location in the folder structure PolicyManagerLogs > extension > your-extension-id as shown below. Note the file-name is the same as the running instance ID of the extension.

Monitoring extension statistics

There is a way to monitor extension’s critical resource statistics with the configurable parameter added as part of the extension’s configuration. To enable extension statistics set the “enableStats” parameter to true. Remember a restart of the extension is need to activate the change anytime the config is modified.

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

Since we are authorizing against an external system, it could be relevant to monitor the performance of these transactions as you setup and deploy. If you suspect there is a performance issue, ClearPass provides a way to monitor the authorization processing time. The graph below shows an example of this data, navigate to Monitoring > Live Monitor > System Monitor [click on ClearPass Tab, then select [Authorization]….

Appendix B – Considerations for Installing in a Cluster

Extensions are not synced between ClearPass cluster members, and thus must be installed on each member separately.

Some Extensions can run in two modes: Periodic Sync Mode and Authorization Source Mode.

Periodic Sync Mode

If you are configuring the extension to poll external system periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

HTTP Authorization Source Mode

In this mode we configure an HTTP Auth source that results in a HTTPS call to external system during endpoint authorization. In this deployment model the extension must be installed on every cluster node that process authentications. Also in this scenario every cluster member’s extension must be set to the exact same IP address during installation time, as the HTTP Auth source configuration is propagated globally across all cluster members.

For example, if the extension IP range is 172.17.0.0/16, we would set the extension to 172.17.0.5 on every cluster member during installation of the extension.

While we normally want to avoid duplicate IP addresses in a network, this is not a concern with ClearPass extensions. Each ClearPass node communicates internally only with its own extension, and this traffic is not routed outside of ClearPass.

Subscriber nodes support the same ability as publishers to install an Extension from the Extension store.

Appendix C – endpoint sync schedule settings

The syncSchedule and similar scheduling parameters sets how often ClearPass executes certain actions like syncing or pushing endpoints. This setting is based on a slightly modified version of the CRON job scheduler found in Unix-like operating systems. It can be used to schedule jobs to run periodically at fixed times, dates or intervals.

A ‘cron’ is a job scheduler. Any scheduled task is called a ‘cron job’. The syntax for a cron job schedule is as follows:

In our use of the cron scheduler, we’ve dropped the use of the last instruction ≤command to execute> and use only the time/date functions, see below for a number of examples of scheduling a sync process.

• Schedule a sync to run at 2am daily:- 0 2 * * *

• Schedule a sync to run twice a day at 5am and 5pm:- 0 5,17 * * *

• Schedule a sync to run on every Sunday at 5pm:- 0 17 * * sun

• Schedule a sync to run every 30 minutes:- */30 * * * *

• Schedule a sync to run at 5pm on selected days:- 0 17 * * sun,fri

You can see from the above that the scheduling process is extremely flexible, alternatively https://crontab.guru/ is a great page for learning more about CRON scheduling.

Appendix D – Extension performance optimizations

Extensions are a critical part of ClearPass deployments today and with the increased dependency on extension interactions that involve periodic polling or real-time lookups, here are some of the best practice recommendations around optimizing overall performance when using extensions:

• If the extension is used to periodically poll external systems and populate endpoint repository, ensure that it is not installed in all the nodes in the cluster. Ideally these type of extensions should only be installed on the publisher node since only publisher node can add endpoint entries to the database. For redundancy, it can be installed on another additional node but it is recommended to stagger the polling interval so that both do not attempt to poll and update endpoint database at the same time.

  Example: 0 * * * *, This cron job runs at minute 0 of every hour (e.g., 00:00, 01:00, 02:00, etc.).

    30 * * * *, This cron job runs at minute 30 of every hour (e.g., 00:30, 01:30, 02:30, etc.).
  

• If the extension is used for looking up attributes from external systems in real time during authentication, it should be installed in all the nodes handling authentication. Note that the context server config is replicated from the publisher. When using extension for real time lookup, ensure that the extension has the same IP address in all the cluster nodes.

• If the extension is expected to do both real-time lookup and periodic polling, ensure that polling is enabled only on the publisher while the extension in subscribers can have the polling disabled by setting the “enableSyncAll” attribute to false.

     "enableSyncAll": false,
  

• Some 3rd party systems support fetching delta updates vs fetching all of the device information every polling cycle. The extensions that support fetching delta updates are: Workspace ONE Crowdstrike Falcon Microsoft Intune Mosyle SentinelOne Service Now

  For these extensions, the syncUpdatedOnly attribute should be set to true in extension config so that the number of DB updates in ClearPass is minimized

    "syncUpdatedOnly": true,
  

  For extensions that do not support syncUpdatedOnly, ensure that the sync interval is not aggressive. We recommend syncing at most twice a day and that too during off peak hours whenever a full sync is performed.

• Some 3rd party systems can be very noisy in terms of attribute updates. There could be certain attributes that keep changing every sync interval like “Free Memory in Bytes”, “Last Check in Time” etc. There is no value in updating endpoints when such trivial attributes change for the device. Hence it is recommended to use “ignoreEndpointDifferences” attribute in extension configuration to ignore change in attributes that you do not care about in terms of ClearPass policies.

  You can review the Audit Viewer in ClearPass under Monitoring > Audit Viewer to see what attributes are being updated for endpoints to check if there are unnecessary updates.

  Sample for JAMF extension:

    "ignoreEndpointDifferences": "Last Update, Report Date UTC, Last Contact Time UTC, Last Inventory Update UTC, Last Reported IP, IP Address",
  

  Default for Microsoft Intune extension:

    "ignoreEndpointDifferences": "Last Sync Date Time, Free Storage Space in Bytes",
  

• To further optimize the number of endpoints being updated in ClearPass, you can specify which attributes are being used in the ClearPass policies so that only changes to those attributes would trigger an update to the endpoint. This is done by listing out the specific attributes under endpointAttributes in extension configuration.

  Sample for JAMF extension:

    "endpointAttributes": "Group names, MDM Enabled, Managed, Remote Managed, Supervised, Serial Number",
  

• Setup extension to restart unless it was intentionally stopped. A restart policy can be defined in extension configuration to ensure that the extension starts up automatically after server reboots and such. Restart policy of “unless-stopped” would ensure the extension always starts up unless it was manually stopped.

  “restartPolicy”: “no” — The extension will not be automatically restarted after the server is restarted.

  “restartPolicy”: “always” — The extension will always be restarted after the server is restarted.

  “restartPolicy”: “unless-stopped” — The extension will be restarted unless it was stopped prior to the server restart, in which case it will maintain that state.

  “restartPolicy”: “on-failure:N” — If the extension fails to restart, the value for “N” specifies the number of times the extension should try to restart. If you do not provide a value for “N”, the default value will be “0”.

  The “restartPolicy” parameter is not present by default in extension configurations. When it is not present, if the system is restarted a default policy is applied to the extension to maintain the state it was in before the restart. If the “restartPolicy” parameter is added to the configuration but later removed, the extension will then revert to the default restart policy.

Appendix E – Using the Jamf Extension Information in a ClearPass Service

In this appendix, we’ll provide more detail on how to incorporate information from the Jamf Extension in an existing ClearPass service. We’ll add the Endpoint Database to an existing basic Wired 802.1X service that processes authentications from HPE ArubaOS switches. This service checks Active Directory to set roles, then uses those roles in an enforcement policy to send different RADIUS attributes to the switch. The configuration of your existing policies will likely differ, so please use this appendix as a general guide.

Service Authorization

The first step is to add Authorization to our service by checking the Authorization box on the Service tab. Checking this box makes the Authorization tab visible in the service definition.

Note: your existing services may already have this box checked.

Proceed to the Authorization tab and add the Endpoint Database.

We also added the [Time Source] [Local SQL DB] for evaluating dates and times.

Role Mapping Policy

Our Role Mapping Policy originally only contained the first two lines seen below.

We first created the role names in ClearPass by navigating to Configuration > Identity > Roles. We then added the subsequent lines to the role mapping policy to set roles based on the returned values from Jamf. Note this is an evaluate-all Role Mapping Policy, so all matching roles will be applied.

Appendix F – Using Webhooks for real-time event updates from Jamf to ClearPass

Jamf supports triggering Webhooks based on certain events which include changes in device groups and newly added devices in the inventory. This eliminates the dependency on endpoint sync schedule interval to get the correct state of managed endpoints with the use of real-time updates for any state changes in existing endpoints and updates for newly added endpoints in Jamf. These events can be leveraged by ClearPass when Jamf is configuted to send these events to Skyhook and update the endpoint attributes based on the attributes received from the Skyhook events.

Configuring Webhooks in Jamf

Under All Settings > Global Management click on Webhooks:

Click “+ New” button to configure a new Webhook:

Set the Display Name for the Webhook and enable it. The Webhook URL sample is provided below. The Skyhook tenant ID is suffixed in the URL to send the webhook events to the right skyhook tenant. The procedure to get a skyhook tenant registered for Jamf is discussed in the following steps. Set all other configuration settings as shown below in the example (make sure Content Type is set to JSON) and click on Save.

Register for a Skyhook Tenant ID

Skyhook Tenant ID’s can be registered in the skyhook self-service portal by accessing the following link https://clearpass.arubanetworks.com/webhooks/skyhook and instructions on using the skyhook self-service portal is available here: https://arubanetworking.hpe.com/techdocs/NAC/clearpass/integrations/clearpass-extension/skyhook-self-service-portal/

Kindly copy the skyhookTenant, dbAccessToken and the Webhook URL in a text file. This will be used for configuration of the extension in ClearPass Policy Manager as well as configuring the tenant details in Jamf.

Example: New Device Enrollment

Here is a sample configuration for New Device Enrollment on Jamf:

Here is a sample log from the Jamf Extension based on a new mobile device enrolled:

The newly enrolled device is then entered in the Endpoint DB and can be looked up based on the MAC address shown in the extension log.

Example: Smart Group Mobile Device Membership Change

Here is a sample configuration for Mobile Device Membership Change on Jamf:

Here is a sample log from the Jamf Extension based on a mobile device membership change:

5.2 - Jamf School

Introduction and Overview

Jamf School is a powerful, cost effective Mobile Device Management system for today’s modern digital classroom. With Jamf School all your Apple devices can be managed. Jamf School has easy to use tools for the IT Department, teachers and parents.

In combination with Apple’s iOS, Jamf School is the very best MDM choice for education. Inventory, deploy and secure every Mac, iPad and iPhone in your schools – and integrate them into existing IT with an ease that has never been possible until now.

This integration guide covers the deployment and configuration of ClearPass Policy Manager to interface with Jamf School. The integration leverages Jamf School APIs to obtain attributes associated with an endpoint. It provides an ability to pull all device details from a customer tenant into ClearPass endpoints database. The contextual data inserted into ClearPass can then be leveraged to drive granular access policy.

Pictorial View of the Integration

The diagram below shows a pictorial overview of the components and how they interact with each other.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

ClearPass Jamf School Extension Configuration

After installing the Extension, the default configuration will need to be updated. The configuration parameters are divided into two tables, one for Jamf Extension-specific configuration parameters and the other for Extension framework configuration parameters that are common across multiple vendor Extensions.

Table 1: Jamf School Extension-specific configuration parameters

Jamf School Configuration

Common extension attributes

Extension framework configuration parameters (common configuration)

Periodic Polling to Sync Endpoints

When leveraging the pull capabilities of the Extension to get the device attributes from Jamf School, use the attribute enableSyncAll and specify syncAllSchedule. These 2 attributes are leveraged for periodic poll of endpoints from Jamf School. The syncAllOnStart attribute can be leveraged as well to sync everything upon the start of the extension.

The JamfSchoolNetworkId,JamfSchoolApiKeys are collected from inside the Jamf School system. For the username, you will have to use the Network ID for your account, which can be found at Devices > Enroll Device(s). For the password, you will have to use the API Key.

A copy of the Jamf School Extension with the desired configuration is shown below, this has to be modified for your deployment. Include the JamfSchoolHost, JamfSchoolNetworkId and JamfSchoolApiKeys that will be specific to your environment.

Change or include any other values based on the description of each in the above table. Select Restart and click on Save Changes to restart the extension.

After the configuration and the restart of the extension, click on Show Logs.

The above log shows that the Extension has pulled the endpoint data from Jamf School. The above steps pull endpoint details at the time of starting the Extension and then regular updates are fetched at the interval specified by SyncAllSchedule. Please note the IP address of the Extension. This will be used in the next section where we leverage the Jamf School attributes during real-time AuthZ. A sample of endpoint attributes fetched are shown below.

Multiple use-cases exist for how the data that is returned from Jamf School can be used in the Policy enforcement. In the example below, we are performing multiple checks:

1. Check if the device is managed by Jamf School. If it is not, redirect it to the captive Portal. Create a helpdesk ticket for remediation.

2. If the iCloud Backup is not enabled, create a helpdesk ticket.

3. If the device is not supervised by Jamf School, put it in the Quarantine VLAN.

Different companies will have different enforcement profiles and policies. The key takeaway here is to leverage the attributes received from Jamf School to drive the policy engine into making different enforcement actions for the device as they authenticate on the network.

Using JamfSchool extension as HTTP AuthZ source for Real-time attribute lookups for Endpoints.

To add JamfSchool as a real-time AuthZ source:

Navigate to Configuration > Authentication > Sources and click Add.

Select Type = HTTP, then go to the Primary tab. Enter the JamfSchool extension IP as the HTTP address and click Next.

Configure the Filter Query, specifying the attributes you want to retrieve from JamfSchool.

These attributes can then be leveraged in your policies.

Appendix A – Troubleshooting and Support

Here we list some basic troubleshooting steps. If you need any help beyond this, please reach out to HPE Aruba Networking Support.

Check API Access Application Control restrictions

If you’ve previously hardened your ClearPass deployment with Application Access Controls, it’s possible that the Extension will not work. Reviewing the Extension Log might show something like the following after immediately starting the Extension. This likely indicates the ClearPass Application API’s are in place.

Example of Extension authorization failure due to Policy Manager Application Control:

[2020-03-16T15:42:21.083] [INFO] Intune - Server listening on port 80.

[2020-03-16T15:42:21.243] [DEBUG] Intune - Request “GET ‘https://172.17.0.1/api/server/version’” took 51.91ms.

[2020-03-16T15:42:21.245] [DEBUG] Intune - <!DOCTYPE html><html>

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

var locHref = window.location.protocol + “//” + window.location.hostname;

window.location.href = locHref;

}

</script>

To resolve this issue, add the IP address of the Extension to the list of nodes permitted to access the API by navigating to Administration > Server Manager > Server Configuration {choose your node} > Network

Checking on the Extension Service

The ClearPass Extensions are supported by a system service which must be running.

Restarting this service will affect all deployed and running extensions.

To check on the state of the Extension Service, or to restart the service, go to Administration > Server Manager > Server Configuration > [SERVER] > Service Control. By default this service is automatically started.

Extensions and web proxy / firewall whitelisting

If ClearPass Policy Manager has been configured with a proxy, it’s still possible that domain whitelists are required, the same for some datacenter firewall to allow the installation of Extensions. Some enterprise customers maintain a whitelist of domain that are allowed to transit the proxy/firewall. The underlying docker configuration process uses standard docker registry access to pull images (hosted in docker hub). In general, the following hosts are used:

This is all also geo dependent to some degree and based on various AWS services, so AWS redirects and geo location services will vary. Finally, this all runs via standard HTTPS (port 443).

Extension Logs/Enable Debugging

If you have a requirement to access and view the logs from the Extension, you can turn on different logging levels from the Extension GUI. Adjust the logLevel to ‘DEBUG’ and restart the extension as shown below.

Logs can then be viewed from the ‘Show Logs’.

Remember after changing the logging level, as with any extension configuration change the extension will need to be restarted for this change to take effect.

Accessing the extension logs using ‘Collect Logs’ system function

In addition to viewing the logs as shown above, logs can also be collected and examined via the Policy Manager Collect Logs system function (Administration > Server Manager > Server Configuration > [Select SERVER] > Collect Logs). This is extremely useful should you have a need to call for technical assistance.

If the support team needs to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. By default the “logLevel” is set to INFO, but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set as required. Any of the levels will display the information for the selected state and lower; if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the logs have been collected, downloaded and expanded, you can locate the extension logs in the following location in the folder structure PolicyManagerLogs > extension > your-extension-id as shown below. Note the file-name is the same as the running instance ID of the extension.

Monitoring extension statistics

There is a way to monitor extension’s critical resource statistics with the configurable parameter added as part of the extension’s configuration. To enable extension statistics set the “enableStats” parameter to true. Remember a restart of the extension is need to activate the change anytime the config is modified.

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

Since we are authorizing against an external system, it could be relevant to monitor the performance of these transactions as you setup and deploy. If you suspect there is a performance issue, ClearPass provides a way to monitor the authorization processing time. The graph below shows an example of this data, navigate to Monitoring > Live Monitor > System Monitor [click on ClearPass Tab, then select [Authorization]….

Appendix B – Considerations for Installing in a Cluster

Extensions are not synced between ClearPass cluster members, and thus must be installed on each member separately.

Some Extensions can run in two modes: Periodic Sync Mode and Authorization Source Mode.

Periodic Sync Mode

If you are configuring the extension to poll external system periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

HTTP Authorization Source Mode

In this mode we configure an HTTP Auth source that results in a HTTPS call to external system during endpoint authorization. In this deployment model the extension must be installed on every cluster node that process authentications. Also in this scenario every cluster member’s extension must be set to the exact same IP address during installation time, as the HTTP Auth source configuration is propagated globally across all cluster members.

For example, if the extension IP range is 172.17.0.0/16, we would set the extension to 172.17.0.5 on every cluster member during installation of the extension.

While we normally want to avoid duplicate IP addresses in a network, this is not a concern with ClearPass extensions. Each ClearPass node communicates internally only with its own extension, and this traffic is not routed outside of ClearPass.

Subscriber nodes support the same ability as publishers to install an Extension from the Extension store.

Appendix C – endpoint sync schedule settings

The syncSchedule and similar scheduling parameters sets how often ClearPass executes certain actions like syncing or pushing endpoints. This setting is based on a slightly modified version of the CRON job scheduler found in Unix-like operating systems. It can be used to schedule jobs to run periodically at fixed times, dates or intervals.

A ‘cron’ is a job scheduler. Any scheduled task is called a ‘cron job’. The syntax for a cron job schedule is as follows:

In our use of the cron scheduler, we’ve dropped the use of the last instruction ≤command to execute> and use only the time/date functions, see below for a number of examples of scheduling a sync process.

• Schedule a sync to run at 2am daily:- 0 2 * * *

• Schedule a sync to run twice a day at 5am and 5pm:- 0 5,17 * * *

• Schedule a sync to run on every Sunday at 5pm:- 0 17 * * sun

• Schedule a sync to run every 30 minutes:- */30 * * * *

• Schedule a sync to run at 5pm on selected days:- 0 17 * * sun,fri

You can see from the above that the scheduling process is extremely flexible, alternatively https://crontab.guru/ is a great page for learning more about CRON scheduling.

Appendix D – Extension performance optimizations

Extensions are a critical part of ClearPass deployments today and with the increased dependency on extension interactions that involve periodic polling or real-time lookups, here are some of the best practice recommendations around optimizing overall performance when using extensions:

• If the extension is used to periodically poll external systems and populate endpoint repository, ensure that it is not installed in all the nodes in the cluster. Ideally these type of extensions should only be installed on the publisher node since only publisher node can add endpoint entries to the database. For redundancy, it can be installed on another additional node but it is recommended to stagger the polling interval so that both do not attempt to poll and update endpoint database at the same time.

  Example: 0 * * * *, This cron job runs at minute 0 of every hour (e.g., 00:00, 01:00, 02:00, etc.).

    30 * * * *, This cron job runs at minute 30 of every hour (e.g., 00:30, 01:30, 02:30, etc.).
  

• If the extension is used for looking up attributes from external systems in real time during authentication, it should be installed in all the nodes handling authentication. Note that the context server config is replicated from the publisher. When using extension for real time lookup, ensure that the extension has the same IP address in all the cluster nodes.

• If the extension is expected to do both real-time lookup and periodic polling, ensure that polling is enabled only on the publisher while the extension in subscribers can have the polling disabled by setting the “enableSyncAll” attribute to false.

     "enableSyncAll": false,
  

• Some 3rd party systems support fetching delta updates vs fetching all of the device information every polling cycle. The extensions that support fetching delta updates are: Workspace ONE Crowdstrike Falcon Microsoft Intune Mosyle SentinelOne Service Now

  For these extensions, the syncUpdatedOnly attribute should be set to true in extension config so that the number of DB updates in ClearPass is minimized

    "syncUpdatedOnly": true,
  

  For extensions that do not support syncUpdatedOnly, ensure that the sync interval is not aggressive. We recommend syncing at most twice a day and that too during off peak hours whenever a full sync is performed.

• Some 3rd party systems can be very noisy in terms of attribute updates. There could be certain attributes that keep changing every sync interval like “Free Memory in Bytes”, “Last Check in Time” etc. There is no value in updating endpoints when such trivial attributes change for the device. Hence it is recommended to use “ignoreEndpointDifferences” attribute in extension configuration to ignore change in attributes that you do not care about in terms of ClearPass policies.

  You can review the Audit Viewer in ClearPass under Monitoring > Audit Viewer to see what attributes are being updated for endpoints to check if there are unnecessary updates.

  Sample for JAMF extension:

    "ignoreEndpointDifferences": "Last Update, Report Date UTC, Last Contact Time UTC, Last Inventory Update UTC, Last Reported IP, IP Address",
  

  Default for Microsoft Intune extension:

    "ignoreEndpointDifferences": "Last Sync Date Time, Free Storage Space in Bytes",
  

• To further optimize the number of endpoints being updated in ClearPass, you can specify which attributes are being used in the ClearPass policies so that only changes to those attributes would trigger an update to the endpoint. This is done by listing out the specific attributes under endpointAttributes in extension configuration.

  Sample for JAMF extension:

    "endpointAttributes": "Group names, MDM Enabled, Managed, Remote Managed, Supervised, Serial Number",
  

• Setup extension to restart unless it was intentionally stopped. A restart policy can be defined in extension configuration to ensure that the extension starts up automatically after server reboots and such. Restart policy of “unless-stopped” would ensure the extension always starts up unless it was manually stopped.

  “restartPolicy”: “no” — The extension will not be automatically restarted after the server is restarted.

  “restartPolicy”: “always” — The extension will always be restarted after the server is restarted.

  “restartPolicy”: “unless-stopped” — The extension will be restarted unless it was stopped prior to the server restart, in which case it will maintain that state.

  “restartPolicy”: “on-failure:N” — If the extension fails to restart, the value for “N” specifies the number of times the extension should try to restart. If you do not provide a value for “N”, the default value will be “0”.

  The “restartPolicy” parameter is not present by default in extension configurations. When it is not present, if the system is restarted a default policy is applied to the extension to maintain the state it was in before the restart. If the “restartPolicy” parameter is added to the configuration but later removed, the extension will then revert to the default restart policy.

5.3 - Meraki System Manager

Introduction

This TechNote covers how to deploy and configure the ClearPass Extension to interface with Meraki System Manager. In this TechNote we will cover the complete installation, configuration and integration between the Extension and ClearPass Policy Manager. The Extension effectively becomes an authorization source to service policies.

With Meraki System Manager hosted in the cloud and ClearPass sitting primarily on-prem, there are challenges in making these two applications communicate in real time on device posture status. Traditionally the apps would communicate using APIs where an application would request information which is usually followed by a response. Hence in order to get real-time information you must poll or request as often as possible which is not scalable. The answer or the solution is a webhook which does not wait for a request to send information but sends the data as soon as it is available.

Before we proceed with the flow, we need to understand the concept of webhooks and skyhook.

What is a webhook?

A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately.

What is skyhook?

Skyhook was developed to overcome the inability for Cloud based applications to send events [webhooks] directly into a ClearPass that was typically deployed on the Trust side of a corporate firewall. In short, it is a service that runs in the Cloud, deployed, developed and managed by Aruba. ClearPass nodes running onprem, use extensions to open a persistent connection into Skyhook to receive the events originally sent from a 3rd party cloud application specific for that customer/tenant. As an overview, Meraki System Manager running in the cloud will send a webhook upon an alert notification. This will communicate with Skyhook. The ClearPass extension configured and installed will maintain a persistent connection with Skyhook awaiting an event.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

Pictorial View of the Integration

The extension can be configured for two different ways of operation.

Periodic Sync Mode

In this mode ClearPass polls Meraki System Manager periodically and updates the ClearPass Endpoint database with attributes obtained from Meraki System Manager. These attributes can be utilized in ClearPass during endpoint Authorization. This mode has a simpler configuration demand, however, the data provided may not be completely up to date at authentication time.

Ingress Event Processing (IEE):

In this mode we configure an IEE source that results in real time alert notifications from Meraki System Manager. Information in this case is more up to date, but there is the higher overhead of an API call during endpoint authorization. A view of this process is below.

Register and Request for a Skyhook Tenant ID

Skyhook Tenant ID’s can be registered in the skyhook self-service portal by accessing the following link https://clearpass.arubanetworks.com/webhooks/skyhook and instructions on using the skyhook self-service portal is available here: https://arubanetworking.hpe.com/techdocs/NAC/clearpass/integrations/clearpass-extension/skyhook-self-service-portal/

Meraki System Manager Configuration

The ClearPass Meraki System Manager extension communicates with your Meraki System Manager tenant via REST API calls. By default, your Meraki System Manager tenant is not enabled to receive and respond to API calls, so you will need to create a Meraki System Manager API Key to enable API access. In this process an API key should be collected as it will be required to configure the ClearPass Meraki System Manager Extension.

Meraki System Manager API Tenant Configuration

Follow the below steps to configure and collect the data from your Meraki System Manager tenant.

After login, go to Your login name > My profile on the upper right nav-bar as shown below.

Then from under My profile options, scroll down to API Access and click “Generate new API key”.

At this time you will be shown the API key and you will need to copy it for later user in ClearPass, click “I have stored my new API Key” and then “Done”, as shown below.

Meraki System Manager Alert Webhook Configuration

Follow the below steps to configure and collect the data from your Meraki System Manager tenant.

After login, go to System Manager -> Alerts on the left nav-bar as shown below.

Then scroll down to Webhooks and click “Add an HTTP server”. Fill in the “Name” field to anything you prefer. The “URL” field will be “https://skyhook.clearpassbeta.com/api/skyhook/meraki-sm/put-yourskyhook-tenant-id-here” where “put-your-skyhook-tenant-id-here” will be replace with the skyhook tenant ID you received after enrollment. “Shared secret” is a password you specify that is optionally used within the extension to validate the authenticity of the webhook, this needs to be referenced later in the extension configuration. Then click “Save”.

In “Default recipients” add the Webhook alias you created earlier and then create/modify a “Security Alert” that you want to be notified on.

Meraki System Manager Extension Configuration

After installing the Extension, the default configuration will need to be updated.

Edit the three configuration value pairs from the previous steps with your saved values.

Below is an explanation of all of the configuration value pairs. The logLevel, verifySSLCerts and merakiHost should be left as their default settings unless advised by ClearPass TAC or your Aruba SE/Partner. Once you configure these parameters, you can start your extension. Any subsequent reconfiguration requires a restart of the extension.

Extension Configuration options

Additional Configuration Notes

If you only want the extension to sync device information to the endpoint database, set the endpointSyncSchedule attributes, and optionally the endpointSyncOnStart attribute.

At a minimum, you’ll need to set these attributes:

• merakiApiKey

• cppmUserName

• cppmPassword

The cppmUserName and cppmPassword attributes are set, the extension can configure endpoint profiling based on data from Meraki System Manager. Create this user in ClearPass, navigate to Administration > Users and Privileges > Admin Users. Click on Add. Set the Privilege Level to Network Administrator.

Configure ClearPass Policy Manager

Multiple methods exist for how ClearPass can utilize the returned data from Meraki System Manager, such as:

• Ensure that the endpoint is managed by Meraki System Manager. If not, perhaps restrict access for the device on the Corporate Network with a role that only allows the user to remediate and enroll the device to Meraki System Manager. This provides a controlled environment where all endpoints are managed.

• Check if the endpoint is meeting compliance requirements set by your company (i.e. Firewall enable, Anti-virus installed, etc)

• Take automated actions on notifications sent from Meraki System Manager.

As mentioned previously, the extension can be run in two modes.

Periodic Sync Mode: Using stored attributes

The Extension can sync data from Meraki System Manager periodically, write this data into the ClearPass EndpointDB, then use the EndpointDB as an authorization source. Also, as part of this sync configuration notifications can be processed for devices that are not meeting company compliance. Why this is useful is that if a device were to fall out of compliance an event can be triggered, and a new enforcement can be processed to handle the violation.

Be aware that this data will not be completely ‘real-time,’ but may be adequate for many use cases. Here’s an example of a ClearPass Role Mapping Policy that utilizes these Meraki System Manager Endpoint Attributes.

Ingress Event Processing: A Real-Time Notification

In this scenario we configure ClearPass Policy Manager to process event notifications. For a complete and more detailed overview of Ingress Event Processing please review the technote “CPPM_TechNote__Ingress_Event_Engine_V1.0.pdf”

Ingress Event Processing uses the Ingress Event Engine [IEE] that is built-in ClearPass Policy Manager. The IEE delivers an extra dimension to the capabilities on how ClearPass Policy Manager can interoperate with Devices and Users. IEE is where an inbound syslog can be the trigger for CPPM to take action on authenticated networks devices & users.

Configuring Ingress Event Processing

Let’s check the basics first….. we need to enable the Ingress Events processing engine. Enable this under Administration-> Server Manager > Server Configuration > [Your CPPM Node] > System as below.

Check if Ingress Daemons are Running

As a part of the Ingress framework, we have added two new daemons, check they are running, if they are ‘Stopped’, then start them using the controls as shown below.

Check on the Configured Inbound Ingress Listening Port

As shown above there are a couple of daemons, one of these, the logger service is responsible for listening on the TCP/UDP port defined below [default 514] and ingesting the syslog records on that port, configure the TCP/UDP port from the following location **Administration > Server Manager > Server Configuration > [Your CPPM Node] > Service Parameters [select Ingress logger]… set the TCP/UDP port number required.

Configure Ingress Events Dictionary

This is the actual file which takes the structured/unstructured syslog and turns it into fields/attributes that we can reference within a Namespace. This section of the configuration requires some knowledge of Groks, especially when adding a new Vendor. We supply multiple IEE dictionaries by default and will add more over time. We have provided dictionaries for Juniper, Palo-Alto, CheckPoint and InfoBlox. As you can see below the supplied dictionaries are disabled. Only enable the required dictionaries.

Here you will want to import two new IEE dictionary for Meraki System Manager. One dictionary is used for the polling notifications that provides rich device detail to where we can trigger action on an authenticated device. The other dictionary is used for real-time Alert notification via the Meraki Webhook. Currently the Alert notifications contain very limited information.

Add an Event Source

Next we need to define the event source, go to Configuration > Network > Events Sources > [Add your node].

Add an Enforcement Profile

We need to create a policy under Configuration > Enforcement > Policies that we will use to trigger an action for notification.

Example for Notification Profile

This example is created for email notification, but different notification types can be configured. This is to handle the minimal information provided in Alerts, in some circumstances admins may want some type of notification for device policy change state.

Add an Event Enforcement Policy

Next create an Event Enforcement Policy. Create this under Configuration -> Enforcement -> Policies [add] be sure to select as highlighted below of the Enforcement Type as Event.

Based upon the Meraki System Manager Event Dictionary you enabled, it will determine what is available here in the rules definition. Then expanding the namespace ‘Name’, we see all the fields that are configured in this Ingres Event Dictionary.

In this case we do a check to demonstrate the configuration for a device policy violation notification from the Extension polling. We set the policy to trigger a session re-auth if we see the words “security_policy_violating” in the violatingPolicy field. The other one is for a real-time Alert notification generated by the Webhook. We set the policy to trigger an email if we see the words “Clients are violating” in the alertType field.

Add an Event Service

Now that all of the parsing/enforcement is completed, add the Event Service. Create this under Configuration -> Services -> [add ‘Event-based Enforcement’].

CPPM Access Tracker Logs Examples

Below is an example of the logs that get posted in the CPPM Access Tracker when an ‘Event’ occurs. The below is filtering just on ‘Events’ in Access Tracker.

Appendix A – Troubleshooting and Support

Here we list some basic troubleshooting steps. If you need any help beyond this, please reach out to HPE Aruba Networking Support.

Check API Access Application Control restrictions

If you’ve previously hardened your ClearPass deployment with Application Access Controls, it’s possible that the Extension will not work. Reviewing the Extension Log might show something like the following after immediately starting the Extension. This likely indicates the ClearPass Application API’s are in place.

Example of Extension authorization failure due to Policy Manager Application Control:

[2020-03-16T15:42:21.083] [INFO] Intune - Server listening on port 80.

[2020-03-16T15:42:21.243] [DEBUG] Intune - Request “GET ‘https://172.17.0.1/api/server/version’” took 51.91ms.

[2020-03-16T15:42:21.245] [DEBUG] Intune - <!DOCTYPE html><html>

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

var locHref = window.location.protocol + “//” + window.location.hostname;

window.location.href = locHref;

}

</script>

To resolve this issue, add the IP address of the Extension to the list of nodes permitted to access the API by navigating to Administration > Server Manager > Server Configuration {choose your node} > Network

Checking on the Extension Service

The ClearPass Extensions are supported by a system service which must be running.

Restarting this service will affect all deployed and running extensions.

To check on the state of the Extension Service, or to restart the service, go to Administration > Server Manager > Server Configuration > [SERVER] > Service Control. By default this service is automatically started.

Extensions and web proxy / firewall whitelisting

If ClearPass Policy Manager has been configured with a proxy, it’s still possible that domain whitelists are required, the same for some datacenter firewall to allow the installation of Extensions. Some enterprise customers maintain a whitelist of domain that are allowed to transit the proxy/firewall. The underlying docker configuration process uses standard docker registry access to pull images (hosted in docker hub). In general, the following hosts are used:

This is all also geo dependent to some degree and based on various AWS services, so AWS redirects and geo location services will vary. Finally, this all runs via standard HTTPS (port 443).

Extension Logs/Enable Debugging

If you have a requirement to access and view the logs from the Extension, you can turn on different logging levels from the Extension GUI. Adjust the logLevel to ‘DEBUG’ and restart the extension as shown below.

Logs can then be viewed from the ‘Show Logs’.

Remember after changing the logging level, as with any extension configuration change the extension will need to be restarted for this change to take effect.

Accessing the extension logs using ‘Collect Logs’ system function

In addition to viewing the logs as shown above, logs can also be collected and examined via the Policy Manager Collect Logs system function (Administration > Server Manager > Server Configuration > [Select SERVER] > Collect Logs). This is extremely useful should you have a need to call for technical assistance.

If the support team needs to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. By default the “logLevel” is set to INFO, but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set as required. Any of the levels will display the information for the selected state and lower; if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the logs have been collected, downloaded and expanded, you can locate the extension logs in the following location in the folder structure PolicyManagerLogs > extension > your-extension-id as shown below. Note the file-name is the same as the running instance ID of the extension.

Monitoring extension statistics

There is a way to monitor extension’s critical resource statistics with the configurable parameter added as part of the extension’s configuration. To enable extension statistics set the “enableStats” parameter to true. Remember a restart of the extension is need to activate the change anytime the config is modified.

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

Since we are authorizing against an external system, it could be relevant to monitor the performance of these transactions as you setup and deploy. If you suspect there is a performance issue, ClearPass provides a way to monitor the authorization processing time. The graph below shows an example of this data, navigate to Monitoring > Live Monitor > System Monitor [click on ClearPass Tab, then select [Authorization]….

Appendix B – Considerations for Installing in a Cluster

Extensions are not synced between ClearPass cluster members, and thus must be installed on each member separately.

Some Extensions can run in two modes: Periodic Sync Mode and Authorization Source Mode.

Periodic Sync Mode

If you are configuring the extension to poll external system periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

HTTP Authorization Source Mode

In this mode we configure an HTTP Auth source that results in a HTTPS call to external system during endpoint authorization. In this deployment model the extension must be installed on every cluster node that process authentications. Also in this scenario every cluster member’s extension must be set to the exact same IP address during installation time, as the HTTP Auth source configuration is propagated globally across all cluster members.

For example, if the extension IP range is 172.17.0.0/16, we would set the extension to 172.17.0.5 on every cluster member during installation of the extension.

While we normally want to avoid duplicate IP addresses in a network, this is not a concern with ClearPass extensions. Each ClearPass node communicates internally only with its own extension, and this traffic is not routed outside of ClearPass.

Subscriber nodes support the same ability as publishers to install an Extension from the Extension store.

Appendix C – endpoint sync schedule settings

The syncSchedule and similar scheduling parameters sets how often ClearPass executes certain actions like syncing or pushing endpoints. This setting is based on a slightly modified version of the CRON job scheduler found in Unix-like operating systems. It can be used to schedule jobs to run periodically at fixed times, dates or intervals.

A ‘cron’ is a job scheduler. Any scheduled task is called a ‘cron job’. The syntax for a cron job schedule is as follows:

In our use of the cron scheduler, we’ve dropped the use of the last instruction ≤command to execute> and use only the time/date functions, see below for a number of examples of scheduling a sync process.

• Schedule a sync to run at 2am daily:- 0 2 * * *

• Schedule a sync to run twice a day at 5am and 5pm:- 0 5,17 * * *

• Schedule a sync to run on every Sunday at 5pm:- 0 17 * * sun

• Schedule a sync to run every 30 minutes:- */30 * * * *

• Schedule a sync to run at 5pm on selected days:- 0 17 * * sun,fri

You can see from the above that the scheduling process is extremely flexible, alternatively https://crontab.guru/ is a great page for learning more about CRON scheduling.

Appendix D – Extension performance optimizations

Extensions are a critical part of ClearPass deployments today and with the increased dependency on extension interactions that involve periodic polling or real-time lookups, here are some of the best practice recommendations around optimizing overall performance when using extensions:

• If the extension is used to periodically poll external systems and populate endpoint repository, ensure that it is not installed in all the nodes in the cluster. Ideally these type of extensions should only be installed on the publisher node since only publisher node can add endpoint entries to the database. For redundancy, it can be installed on another additional node but it is recommended to stagger the polling interval so that both do not attempt to poll and update endpoint database at the same time.

  Example: 0 * * * *, This cron job runs at minute 0 of every hour (e.g., 00:00, 01:00, 02:00, etc.).

    30 * * * *, This cron job runs at minute 30 of every hour (e.g., 00:30, 01:30, 02:30, etc.).
  

• If the extension is used for looking up attributes from external systems in real time during authentication, it should be installed in all the nodes handling authentication. Note that the context server config is replicated from the publisher. When using extension for real time lookup, ensure that the extension has the same IP address in all the cluster nodes.

• If the extension is expected to do both real-time lookup and periodic polling, ensure that polling is enabled only on the publisher while the extension in subscribers can have the polling disabled by setting the “enableSyncAll” attribute to false.

     "enableSyncAll": false,
  

• Some 3rd party systems support fetching delta updates vs fetching all of the device information every polling cycle. The extensions that support fetching delta updates are: Workspace ONE Crowdstrike Falcon Microsoft Intune Mosyle SentinelOne Service Now

  For these extensions, the syncUpdatedOnly attribute should be set to true in extension config so that the number of DB updates in ClearPass is minimized

    "syncUpdatedOnly": true,
  

  For extensions that do not support syncUpdatedOnly, ensure that the sync interval is not aggressive. We recommend syncing at most twice a day and that too during off peak hours whenever a full sync is performed.

• Some 3rd party systems can be very noisy in terms of attribute updates. There could be certain attributes that keep changing every sync interval like “Free Memory in Bytes”, “Last Check in Time” etc. There is no value in updating endpoints when such trivial attributes change for the device. Hence it is recommended to use “ignoreEndpointDifferences” attribute in extension configuration to ignore change in attributes that you do not care about in terms of ClearPass policies.

  You can review the Audit Viewer in ClearPass under Monitoring > Audit Viewer to see what attributes are being updated for endpoints to check if there are unnecessary updates.

  Sample for JAMF extension:

    "ignoreEndpointDifferences": "Last Update, Report Date UTC, Last Contact Time UTC, Last Inventory Update UTC, Last Reported IP, IP Address",
  

  Default for Microsoft Intune extension:

    "ignoreEndpointDifferences": "Last Sync Date Time, Free Storage Space in Bytes",
  

• To further optimize the number of endpoints being updated in ClearPass, you can specify which attributes are being used in the ClearPass policies so that only changes to those attributes would trigger an update to the endpoint. This is done by listing out the specific attributes under endpointAttributes in extension configuration.

  Sample for JAMF extension:

    "endpointAttributes": "Group names, MDM Enabled, Managed, Remote Managed, Supervised, Serial Number",
  

• Setup extension to restart unless it was intentionally stopped. A restart policy can be defined in extension configuration to ensure that the extension starts up automatically after server reboots and such. Restart policy of “unless-stopped” would ensure the extension always starts up unless it was manually stopped.

  “restartPolicy”: “no” — The extension will not be automatically restarted after the server is restarted.

  “restartPolicy”: “always” — The extension will always be restarted after the server is restarted.

  “restartPolicy”: “unless-stopped” — The extension will be restarted unless it was stopped prior to the server restart, in which case it will maintain that state.

  “restartPolicy”: “on-failure:N” — If the extension fails to restart, the value for “N” specifies the number of times the extension should try to restart. If you do not provide a value for “N”, the default value will be “0”.

  The “restartPolicy” parameter is not present by default in extension configurations. When it is not present, if the system is restarted a default policy is applied to the extension to maintain the state it was in before the restart. If the “restartPolicy” parameter is added to the configuration but later removed, the extension will then revert to the default restart policy.

Periodic Sync Mode

If you are configuring the extension to poll Meraki System Manager periodically and utilize the resulting ClearPass Endpoint database during endpoint Authorization, then you only need to install the extension on one cluster member, often the publisher.

You may wish to install the extension on a second cluster member as a backup, but remember that both extensions will individually be updating the endpoint database. You may want to stagger the updates between the two extensions, for example, Subscriber1 updates at the top of the hour and Subscriber2 updates at 30 minutes after the hour.

Also, in this mode there is no need to explicitly enter an IP address during installation. The defaults will suffice and ClearPass will select an IP in the range specified in the server configuration.

Ingress Event Processing

In this scenario we configure ClearPass Policy Manager to process event notifications. For a complete and more detailed overview of Ingress Event Processing and cluster consideration please review the technote “CPPM_TechNote_-_Ingress_Event_Engine_V1.0.pdf”

5.4 - Microsoft Intune

Version History

This integration is implemented through ClearPass Extensions which run independent of the ClearPass platform version. Hence extensions can be updated and released outside of ClearPass release cycles.

What’s new in ClearPass Intune Extension v6.4 ?

Support for HTTP caching for User and Device Group queries

In this release, support for HTTP caching is added for User and Device group queries to the Intune extension. ClearPass policies that use Intune extension as the authorization source for real time User and Device group queries can now be cached with a configurable TTL cache timeout. This avoids frequent HTTP real-time calls from the Intune extension to the Entra ID tenant for User and Device group queries improving the performace of the overall integration components.

The following configuration knobs are added to the extension which are hidden by default. Adding these knobs with the below settings on the extension configuration will enable the HTTP caching for User and Device group real time queries.

“httpCacheTtlInSeconds”: 30, - HTTP Cache TLL in seconds defines the cache timeout. E.g 30 seconds

“httpCacheMaxEntries”: 100, - HTTP Cache Max Entries should not exceed 100 for optimal performance.

Sample Configuration:

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“httpCacheTtlInSeconds”: 30,

“httpCacheMaxEntries”: 100,

“azureADEndpoint”: “login.microsoftonline.com”,

“graphEndpoint”: “graph.microsoft.com”,

“tenantId”: “xxxxxxxx”,

“clientId”: “xxxxxxxx”,

“clientSecret”: “xxxxxxxx”,

“syncPageSize”: 50,

“enableSyncAll”: true,

“syncAllSchedule”: “*/30 * * * *”,

“syncUpdatedOnly”: false,

“syncOnStart”: true,

“enableEndpointCache”: true,

“endpointCacheTimeSeconds”: 900,

“intuneAttributes”: null,

“enableUserGroups”: false,

“userGroupUpdateSchedule”: “*/5 * * * *”,

“bypassProxy”: false,

“enableStats”: true,

“statsUsername”: “whoever”,

“statsPassword”: “********”,

}

What’s new in ClearPass Intune Extension v6.3 ?

Support for Strong Mapping

With Intune extension version 6.3.3, we have made changes to align with Microsoft’s Strong Mapping requirements detailed below.

https://techcommunity.microsoft.com/t5/intune-customer-success/support-tip-implementing-strong-mapping-in-microsoft-intune/ba-p/4053376

https://support.microsoft.com/en-us/topic/kb5014754-certificate-based-authentication-changes-on-windows-domain-controllers-ad2c23b0-15d8-4340-a468-4d4f3b188f16

With the introduction of Strong Mapping feature the SAN URI field is now also used by Microsoft to insert a security identifier (SID) value for Microsoft Entra hybrid joined users/devices. This means that Intune managed clients in a Microsoft Entra hybrid joined environment when provisioned with a certificate using the Intune SCEP certificate profile will have SID tag in the SAN URI field of the certificate. This means that the Intune attribute used for real time lookups now comes in the SAN URI field of the certificate along with the Strong Mapping SID attribute as comma seperated strings in ClearPass. It is therfore important for us to be able to extract only the Intune Device ID attribute from this field to make API calls for real time lookups.

This release supports parsing of the Intune Device ID attribute from the comma seperated string that comes in the SAN URI field to make API calls for real time lookups on Intune. Therfore, all customers adopting the Strong Mapping feature are required to upgrade to this release of the Intune extension. Starting Jan 2025 the Strong Mapping adoption is expected to be enforced on the overall windows ecosystem after which the key distribution system (KDC) will check if certificates have the security identifier during certificate-based authentications.Upgrading to this extension release will therefore not be optional once Microsoft enforces Strong Mapping for Microsoft Entra hybrid joined users/devices.

The URI attribute “{{OnPremisesSecurityIdentifier}}” is required on the Intune SCEP certificate profile to add the Strong Mapping SID value in the SAN URI field once Strong Mapping is enabled for the Intune tenant by Microsoft.

New Recommendation around using alternate Intune ID to support Device / User Group Lookups

For customers using Intune extension as real-time AuthZ source to do user and device group lookups, we use the Intune Device ID from the SAN URI field of the certificate to fetch the Intune attributes and parse the User ID / AAD_Device_ID to then make another call to fetch either the user or device group information. This adds an additional API call for getting the User ID / AAD_Device_ID as part of Intune attributes (Using Intune Device ID) first and then using that information to do the user or device group lookup. However, if the AAD_Device_ID and the UserPrincipalName if already present in the SAN / CN field of certificate we can save an API call for better performance in high client density environments to directly parse them from the certificate and make the API call to fetch the user or device group lookup directly without having to make that extra API call to first fetch those attributes as Intune attributes (Using Intune Device ID) first then make the second call.

To address this we have added support for KEY:VALUE pair when more than one ID is included in the SAN URI field or when using AAD_Device_ID. AAD_Device_ID can fetch both Intune attributes and device group information. UserPrincipalName fetches the user group information and Intune Device ID only fetches the Intune attributes. Given below are the examples to setup Intune SCEP certificate profile to use KEY:VALUE pairs for different ID’s. Note that making changes in the below fields would require the configured Certificate Authority to re-sign / issue new certificates for the clients.

Supported KEY:VALUE pairs are as follows. The KEY names used are same as the variable names that Intune supports in the SCEP profile. Please refer the below link from Micrsoft for details.

https://learn.microsoft.com/en-us/mem/intune/protect/certificates-profile-scep

1. DeviceId:{{DeviceId}} - Used for Intune attributes lookup.
2. AAD_Device_ID:{{AAD_Device_ID}} - Used for both Intune attributes and Device group membership lookup.
3. UserPrincipalName:{{UserPrincipalName}} - Used for User group lookup only when user group lookup using extension is enabled.

The order of priority for querying Intune using these attributes during real-time AuthZ is DeviceId, AAD_Device_ID and finally the standalone value. Any attribute value in the SAN URI that does not have any one of the above KEYs before them is considered as a standalone value and is considered as DeviceId by default to maintain backward compatibility for environments that are already setup with DeviceId in the SAN URI field of the client certificates for real-time lookpus against Intune or environments that have Strong Mapping enabled. These recommendations as noted above are optional and environments that use only the DeviceId value (wthout the KEY:VALUE pair) in the SAN URI field is still supported for both Microsoft Entra hybrid joined users/devices and Microsoft Entra only joined users/devices.

For more information on how to use the extension in HTTP Authorization Mode please refer to the Configuring ClearPass Policy Manager as an HTTP authZ source section of this document.

What’s new in ClearPass Intune Extension v6 ?

Microsoft released the Compliance Retrieval service with the Intune June 2021 service release. This new service is intended to replace the Intune NAC service, and includes changes to improve the security, reliability, and privacy of the NAC service. For example, it uses lookup by Intune device ID only, which removes the dependency on internal identifiers, such as serial numbers, which are not consistently accessible. It also eliminates MAC address identifiers, which are problematic because devices can have multiple or randomized MAC addresses. The new service is also streamlined to return only enrollment and compliance data from Intune. Any other device data not related to access control is eliminated from this service.

Intune Extension v6 adheres to the main requirement to use certificate-based authentication (e.g. EAP-TLS) with the new service. In conjunction with this, it is required to include the Intune device ID in the subject alternative name (SAN) of your certificate profiles. Please refer to Appendix E for more details on SCEP certificate profile configuration.

As noted below, Intune Extension v5 made a major move to use Microsoft GraphAPI. However, we encountered an issue with GraphAPI when syncing with Intune to retrieve device attributes as it did not support pulling the Ethernet MAC address attribute (wired interface). We addressed this with a workaround that utilizes real-time lookup by Intune device ID to pull the Ethernet MAC address attribute and have it stored in the endpoint DB. Please refer to the section “Utilizing HTTP Authorization Mode to Retrieve Specific Device Attributes” for more details.

What’s new in ClearPass Intune Extension v5 ?

In this MAJOR update the integration changes fundamentally how it works. You MUST read the ‘change in behaviors’ below to understand how this might affect how you use this Extension. We feel this change is for the better, we’ve constantly had customers telling us that the authN event-driven approach was not how they liked or wanted this integration to work. Previously we had been restricted to using the “Intune NAC-API”, however this version uses the Microsoft GraphAPI, this open up a list of new features and some changes.

• Batch Ingest all Tenant endpoints like other UEM vendors

• Only sync updated endpoint context after previous sync

• Send CMD’s to Intune to ‘run’ against endpoints

• Lock Screen

• Wipe Device

• Shutdown Device

v5 - Change in Behavior

It is important to note that this Extension works in a different way to the previous Intune extensions, it does not query Intune on each and every authN {or reference cached data as in previous versions} thus it’s not an authZ source like before, though an authZ use-case exists it works differently from the previous version.

This integration works by ingesting all of the endpoint with a customer’s tenant, this is inline with how every other UEM integration fundamentally works. However, because of the API changes we can’t query based upon the authenticating mac-address, more on this later. With the v5 we have to use the EndpointDb as the authZ source, so depending on the sync schedule, this will determine the fresh ‘v’ stale view of the data.

There is an option to query real-time Intune, however there is an assumption that the endpoint is already managed by Intune and you’re only querying for current data. You could have an authZ rule such as Endpoint Source=Intune trigger a CSA profile for an update, and if Source != Intune trigger a different CSA profile. The reason behind this is that the query exposed in GraphAPI is based on the Azure DeviceID {AZID}, so for ClearPass to query for an endpoint update it needs the AZID, which it has from data already synced, the Extension uses the mac-address of the authenticating device, looks up the AZID in the ClearPass endpointDb before it can query Intune.

For this reason the previous process of using a real-time query based upon mac-address for found/not-found devices in Intune needs to be adjusted, perhaps validating an endpoint has an AZID attribute value.

What’s new in ClearPass Intune Extension v4

In v4, we added the capability to cache Intune attributes for a configurable time. This allows device attributes from Intune to be written to the Endpoint Repository of ClearPass. If a device authenticates within the cache period, ClearPass would not send requests to Intune Authorization source, rather use the attributes cached in the Endpoint Repository. This helps reduce the number of API calls to Intune.

What’s new in ClearPass Intune Extension v3

Enabling Intune NAC API to ingest endpoint ownership such as it can be used in Policy within ClearPass

What’s new in ClearPass Intune Extension v1

The first Intune extension for ingesting endpoint data, based upon a 1:1 API call due to limited ability in Intune to ingest ALL endpoint in a tenant.

Software Requirements

The minimum software version required for CPPM is 6.11.0 . At the time of writing, version 6.11.10 is available as the long supported release and 6.12.4 is available as the short supported release. CPPM runs on hardware appliances with pre-installed software or as a Virtual Machine under the following hypervisors. Hypervisors that run on a client computer such as VMware Player are not supported.

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

• Windows Server 2019 with Hyper‑V and Windows Server 2022 with Hyper‑V.

• KVM on CentOS Stream 8, CentOS Stream 9, Ubuntu 20.04 LTS, and Ubuntu 22.04 LTS.

ClearPass Installation and Deployment Guide

This document assumes your ClearPass environment is already configured and operational. If you require assistance with basic deployment, refer to the following deployment guide:

https://arubanetworking.hpe.com/techdocs/ClearPass/6.11/Installation-Guide/Default.htm

ClearPass Extensions

The integration between ClearPass Policy Manager and external systems is driven through a ClearPass capability known as Extensions, a sub-component of the ClearPass Exchange Integration framework. ClearPass Extensions are micro-services running on top of the base ClearPass platform. These micro-services enable HPE Aruba Networking to deliver new features outside of the main software release cycle and facilitate a faster time to market for specific features and integrations. Configuration and control of ClearPass Extensions is accomplished through the ClearPass Guest GUI, as covered later in this document.

Installing Extension

ClearPass Extensions are easy to install from the ClearPass Extensions Store. In a cluster, ClearPass Extensions can be installed on a subscriber independently of the publisher. Multiple copies of the same extension can be installed if needed as well.

Access to the extension store

Access the Extension Store to download and install ClearPass extensions. The Extension store utilizes the same HPE Passport account credentials used to validate support entitlement in the Software Updates Por- tal. This is configured under Administration > Agents and Software Updates > Software Updates as shown below. Ensure that valid HPE Passport credentials have been entered in these fields to enable Ex- tension download capabilities.

Installing the Extension from Store

Extensions are installed from the extension page in ClearPass Guest, as shown below. Access it from Guest > Administration > Extensions

From here, click on ‘Install Extension’, and the search box below appears.

Enter “Intune” and click on ‘Search’, see the example below.

Click on the extension name and then click “Install.”

In the “Install Extension” dialog box, set the IP address if necessary, as described in section “Extensions and IP address configuration support” below. Do not check the box to start the extension at this time. Click the “Install” button.

In this example, we’ve not entered an IP address for the extension to use, if there is intent to use the extension as an authorization source set this value and ensure its set the same on all nodes where the Extension is deployed.

The extension will download and appear in a “Stopped” state. Notice the options to Start, Delete, Reinstall, Show Logs, and view Configuration. Click on “Configuration” to view settings.

After the extension has been installed, proceed to configure the extension

A copy of the default Extension configuration is shown above, this will need to be modified for your deployment.

Extensions and web proxy support

Extensions support communications with 3^rd parties via a web proxy. This adds incremental proxy functionality. If a proxy is defined in ClearPass Policy Manager, then an extension will inherit that configuration. See later in the document on how to disable the proxy inherited configuration.

Extensions and IP address configuration support

ClearPass uses a non-externally routed IP address range to communicate with the Extension. The default is 172.17.0.0/16. You may configure a different range, if desired. This is especially useful when deploying extensions across nodes within a cluster where there is the requirement for a fixed consistent IP address for the extension across the cluster.

Changing the “Extensions Network Address” range is only necessary if either the ClearPass MGMT or DATA interface are using an IP address in the extension default range of 172.17.x.x/12, or if ClearPass needs to communicate with some external device in that range.

To Configure the base Extension IP subnet within Policy Manager navigate to Administration > Server Manager > Server Configuration [chose your node] Service Parameters [ClearPass system service].

Pictorial View of the Integration

The extension can be configured for two different modes of operation.

Periodic Sync Mode:

In this mode ClearPass polls Intune periodically and updates the ClearPass Endpoint database with attributes obtained from Intune. These attributes can be utilized in ClearPass during endpoint Authorization. This mode has a simpler configuration demand, however, the data provided may not be completely up to date at authentication time.

HTTP Authorization Source Mode:

In this mode we configure an HTTP Auth source that results in a real time API call to Intune during endpoint authorization. Information in this case is more up to date, but there is a higher overhead of an API call during endpoint authorization, remember we only query for already known/ingested endpoint context. A view of this process is below.

Configurations Steps

There are primarily 4 steps involved in getting this Integration configured.

1. Configuring and Collecting Information from Microsoft to Configure Intune extension

2. Installation and Configuration of the Intune Extension

3. Configuring ClearPass Intune Extension to sync endpoint data from Intune to the EndpointDb

4. Configuring ClearPass Policy Manager to use already ingest endpoint context from Intune or configure an Authorization source for real-time updates.

Collecting Information to Configure Intune extension

It is assumed you have Intune/Azure environment already setup and configured. The setup of these environments is beyond the scope of this TechNote.

In order to complete the integration, you need to collect multiple pieces of information from Intune and the Azure platform when configuring the ‘ClearPass App’ that are required to complete the extension configuration. The goal is to collect information to complete the highlighted attributes below in red:

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“azureADEndpoint”: “login.microsoftonline.com”,

“graphEndpoint”: “graph.microsoft.com”,

"tenantId": "xxxxxxxx",

"clientId": "xxxxxxxx",

"clientSecret": "********",

“syncPageSize”: 50,

“enableSyncAll”: true,

“syncAllSchedule”: “*/30 * * * *”,

“syncUpdatedOnly”: false,

“syncOnStart”: true,

“enableEndpointCache”: true,

“endpointCacheTimeSeconds”: 900,

“intuneAttributes”: null,

“enableUserGroups”: false,

“userGroupUpdateSchedule”: “*/5 * * * *”,

“bypassProxy”: false,

“enableStats”: true,

“statsUsername”: “whoever”,