Service Now CMDB

  38 minute read  

Introduction and Overview

The ServiceNow v3 extension is a full featured extension enabling the pushing of ClearPass endpoints to ServiceNow CMDB as well as the pulling of devices from ServiceNow into ClearPass. This extension requires a ServiceNow application to be installed for custom APIs and data mapping. This Integration guide covers how to deploy and configure the ClearPass extension to interface with ServiceNow Configuration Management Database. In this guide we will cover the complete installation, configuration and integration between the extension and ClearPass Policy Manager.

Extension Version Updates

ServiceNow Extension Version	ClearPass App on ServiceNow Store Version	ServiceNow Release Certification	Date	Notes
2.1.1	2.0.1	Tokyo	May 2023	Updated Endpoint Sync Filtering Mechanisms (refer to details in subsection under Configuration)
3.1.3	2.2.0	Tokyo Utah Vancouver	Oct 2023	New Endpoint Sync Filtering Mechanisms (refer to details in subsection under Configuration)
3.2.9	2.2.1	Tokyo Utah Vancouver Washington Xanadu Yokohama Zurich	Sep 2025	Updated to push additional attributes from insight DB to Service Now

What’s new in Service Now Extension v3.2.9

Until now the extension could push 3 attributes CPPM-Device-Category, CPPM-Device-Family, and CPPM-Device-Name from ClearPass insight database to Service Now CMDB. With v3.2.9, the extension is now able to push additional attributes from insight db to CMDB. Care has been taken to ensure backwards compatibility with existing deployments using endpoint push workflow.

Sample of insight attributes made available in v3.2.9:

mac	11ab33ae55d6
ip	192.168.0.10
ipv6	null
user	bruce
domain	tmelab
roles	{"Domain Computers",Faculty,"Front Desk","Intune Compliant",[Employee],"[User Authenticated]"}
spt	QUARANTINE
aruba_user_role	quarantine
aruba_user_vlan	100
device_category	SmartDevice
device_family	Apple
device_name	Apple iPhone
is_conflict	false
other_category	Unknown
other_family	Unknown
other_name	Unknown
is_online	false
updated_at	2024-10-09T14:07:13+05:30

What’s new in Service Now Extension v3.2.2

Starting with ServiceNow extension version 3.2.2, communication with Service Now is able to use OAuth. Version 3.1.3 and earlier only supported basic auth. Adding support for OAuth gives us additional security with the integration in terms of password exposure.

With OAuth support, there are two additional fields in the extension configuration namely ClientId and ClientSecret.

“serviceNowUser”: “”,

“serviceNowPassword”: “********”,

“clientId”: “********”,

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

The ClientId and ClientSecret fields are set to work in conjunction with the existing serviceNowUser and serviceNowPassword fields. ServiceNow does not support only clientID and clientSecret based authentication, the username and password fields are still mandatory while the clientID and clientSecret fields to support OAuth are optional. However, it is recommended to enable OAuth by configuring the clientID and clientSecret fields from ServiceNow > System OAuth > Application Registries

Note: It is recommended to first update the ClearPass App on ServiceNow Store to version 2.2.0 and then update the ServiceNow Extension on ClearPass to version 3.2.2.

Pictorial View of the Integration

Use Cases

ClearPass Policy Manager integrates with ServiceNow in multiple ways:

• Use Case 1: Bulk import of all devices information from ServiceNow CMDB to ClearPass Policy Manager leveraging flexible polling definition based on cron based scheduling.

• Use Case 2: Push individual endpoint attributes and insight attributes from ClearPass Policy Manager and map them in ServiceNow as and when they authenticate

• Use Case 3: Push individual endpoint attributes and insight attributes from ClearPass Policy Manager and map them in ServiceNow based on a queueing mechanism. This is similar to the previous use case but adds batching to help with performance.

• Use Case 4: Bulk export of all endpoints (including endpoint attributes and insight attributes) from ClearPass Policy Manager to ServiceNow.

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

The above use cases are covered as part of this integration and are documented in this integration guide.

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].

ServiceNow Configuration Requirements

Before the ClearPass application can be installed in ServiceNow, the following configuration changes are required.

1. The plugin “Configuration Management For Scoped Apps (CMDB)” (com.snc.cmdb.scoped) must be enabled.

2. The CI Identifier rule for MAC Address only lookups must be enabled. CI Identifiers > Hardware Rule > Network Adapter [cmdb_ci_network_adapter] (mac_address) and enable the mac_address only rule.

3. You must add “ClearPass” to the discovery source choice list. Navigate to Choice Lists and add a “ClearPass” record.

Configuring ClearPass Extension and ClearPass Policy Manager

Depending upon the use case and the workflows being implemented, there are different configuration items that must be setup. Here we are going to list out each possilbe workflow and the configuration needed for each both on the extension and on Policy Manager.

ServiceNow Extension Configuration Parameter

These are the SNOW Configuration Parameters within the extension

Configuration Parameter	Description	Example/Values
logLevel	Logging level for troubleshooting	"INFO"
verifySSLCerts	Should SSL certificates be validated when communicating with Service Now.	true or false
serviceNowUri	The host and port (if other than 443) of your ServiceNow instance.	ven00000.service-now.com
serviceNowUser	The user name you would like the extension to use for accessing ServiceNow.
serviceNowPassword	The password of the user for accessing ServiceNow.
clientId	ClientID from OAuth Client in ServiceNow System OAuth > Application registries.
clientSecret	ClientSecret from OAuth Client in ServiceNow System OAuth > Application registries.
serviceNowOperationalStatus	Ability to filter endpoints based on Operational Status	Refer to Endpoint Sync Filtering Mechanisms section after table
serviceNowInstallStatus	Ability to filter endpoints based on Install Status	Refer to Endpoint Sync Filtering Mechanisms section after table
serviceNowSysClassAllow	Ability to filter endpoints based on Allowlist of cmdb_ci tables	Refer to Endpoint Sync Filtering Mechanisms section after table
serviceNowSysClassDeny	Ability to filter endpoints based on Denylist of cmdb_ci tables	Refer to Endpoint Sync Filtering Mechanisms section after table
macAddressSeparator	The MAC Address separator used in ServiceNow. The default value is a hyphen "-". ClearPass stores MAC Addresses with no separator, so if no seperator is specified MAC Addresses will be sent to ServiceNow as they are seen in ClearPass, something that could result in duplicates.	-
enableEndpointCache	Enable or disable the endpoint caching process. When enabled endpoints when looked up using the MAC Address lookup APIs will cache the ServiceNow results in the endpoint database. Information will only be refreshed by this process after the Cache Time is elapsed.	true or false
endpointCacheTimeSeconds	The time in seconds for endpoint lookup API to use cached endpoint data from ServiceNow.	300
enableQueue	Enable or disable the endpoint processing queue for pushing endpoints to ServiceNow. When enabled, you can add MAC Addresses to the processing queue using the queue related API endpoints.	true or false
queueSchedule	The schedule used for the queue processor. This is a CRON based schedule.	*/30 * * * * *
queueRequireIdentity	Should identity information be required to send data to ServiceNow. If set to true, a mac address processed by the queue processor will only be sent to ServiceNow if the mac address is found in the identity endpoint database.	true or false
queueRequireInsight	Should insights information be required to send data to ServiceNow. If set to true, a mac address processed by the queue processor will only be sent to ServiceNow if the mac address is found in the insight endpoint database.	true or false
queueRetryCount	The queue retry count is the number of times a mac address will be looked up to attempt to get information to send to ServiceNow. This queue will take effect if there is not information in ClearPass for the MAC Address or if one of the queues require rules comes into play.	3
cmdbDiscoverySourceName	The CMDB Discovery source that is used when sending data to the CMDB. This must be added to Service Now. Add a choice list option for cmdb_ci -> discovery_source named "ClearPass"	“ClearPass”
cmdbDefaultTarget	The default table target mapping if no mappings can be found in the cmdbTargetMap configuration.	cmdb_ci_netgear
cmdbTargetMap	This map describes how CMDB table mappings are identified. For example, a CPPM endpoint, profiled as a "Computer", will map to the CMDB cmdb_ci_computer table. This base matching is done using the device category, optional device family mappings can also be used to further refine the mapping. A default set of mappings is provided.	[ { "deviceCategory": "Computer", "target": "cmdb_ci_computer" }, { "deviceCategory": "Server", "target": "cmdb_ci_server", "deviceFamilies": [{ "deviceFamily": "win", "target": "cmdb_ci_win_server" }, { "deviceFamily": "unix", "target": "cmdb_ci_unix_server" }, { "deviceFamily": "vmware", "target": "cmdb_ci_vm_vmware" }] }, { "deviceCategory": ["SmartDevice", "Network Camera", "Access Points"], "target": "cmdb_ci_netgear" }, { "deviceCategory": "Printer", "target": "cmdb_ci_printer" }, { "deviceCategory": "Switch", "target": "cmdb_ci_switch" } ]
cmdbAttributeMap	This is a list of endpoint or insight attributes to send to ServiceNow and what fields they should be mapped to in the CMDB. Each entry is a key/value pair. The key is the CPPM attribute name, the value is the ServiceNow CMDB table column name. Only unreferenced columns from ServiceNow can be used here. The names in the list should match up to endpoint attributes. When a matching attribute is found it will be pushed to ServiceNow. When available, the insights information of Device Category, Device Family and Device Name are available using the names CPPM-Device-Category, CPPM-Device-Family, and CPPM-Device-Name or by using the actual attribute name in insight database (starting with v3.2.9). Only unreferenced fields in cmdb tables can be used to push raw values.	{ "Description": "short_description" }
enableSyncAll	Enable or disable pulling all endpoints from ServiceNow.	true or false
syncAllSchedule	The ServiceNow pull schedule. This is a CRON based schedule.	0 3 * * *
syncPageSize	The number of ServiceNow cmdb items to pull with each request. You can adjust this based on the number of cmdb items you have, the performance of your ClearPass system, and the performance of your network.	100
syncUpdatedOnly	True or false to only pull cmdb_ci records that have been updated since the last update.	true or false
syncAllOnStart	Sync all endpoints from ServiceNow when the extension starts or restarts	true or false
enableEndpointPush	Enable or disable pushing all identity endpoints from ClearPass to ServiceNow.	true or false
endpointPushSchedule	The endpoint push schedule. This is a CRON based schedule.	0 3 * * *
endpointPushPageSize	The number of ClearPass endpoints to pull with each request. You may want to adjust this based on the number of endpoint attributes your endpoints contain.	100
endpointPushRequireInsight	Should insight information be required to send an endpoint to ServiceNow.	true or false
asyncOperationLimit	The number of asynchronous operations to run at one time. This controls how many individual internal workers are running at any given time for any one process. For example, if this is set to 10, and the queue processor and pull processors are running at the same time, this setting will limit each process to processing at most 10 items at a time, so in the mentions situation there would be 20 works pushing and pulling information. You can adjust this value based on your ClearPass load. The lower the value the longer it will take for items to be processed.	3
bypassProxy	Bypasses the configured system proxy	true or false
enableStats	Option to enable extension statistics	true or false
statsUsername	Create a username to access the extension statistics page	Give any username you want to use
statsPassword	Create a password to access the extension statistics page	Give any password you want to use

Enter the ServiceNow tenant details such as serviceNowUri, serviceNowUser, serviceNowPassword into the extension configuration. Depending upon the use case, adjust the other configuration switches as necessary, pay attention to attributes related to push/pull queues and schedules.

In the next section we discuss the configuration values and how to use them and where to collect the configuration items that are required.

Use Case 1: Bulk Endpoint Sync from CMDB to ClearPass

The custom API built in the ClearPass Integration App is designed to work in conjunction with the ServiceNow Extension to pull a set of attributes from devices in ServiceNow CMDB and map them into the ClearPass Endpoints DB.

These are the extension configuration parameters that impact endpoint sync from Service Now CMDB:

Configuration Parameter	Description	Example/Values
enableSyncAll	Enable or disable pulling all endpoints from ServiceNow.	true or false
syncAllSchedule	The ServiceNow pull schedule. This is a CRON based schedule.	0 3 * * *
syncPageSize	The number of ServiceNow cmdb items to pull with each request. You can adjust this based on the number of cmdb items you have, the performance of your ClearPass system, and the performance of your network.	100
syncUpdatedOnly	True or false to only pull cmdb_ci records that have been updated since the last update.	true or false
syncAllOnStart	Sync all endpoints from ServiceNow when the extension starts or restarts	true or false
serviceNowOperationalStatus	Ability to filter endpoints based on Operational Status	Refer to Endpoint Sync Filtering Mechanisms section after table
serviceNowInstallStatus	Ability to filter endpoints based on Install Status	Refer to Endpoint Sync Filtering Mechanisms section after table
serviceNowSysClassAllow	Ability to filter endpoints based on Allowlist of cmdb_ci tables	Refer to Endpoint Sync Filtering Mechanisms section after table
serviceNowSysClassDeny	Ability to filter endpoints based on Denylist of cmdb_ci tables	Refer to Endpoint Sync Filtering Mechanisms section after table

Utilize enableSyncAll, enabling this will turn on the ingest polling, ensure that in conjunction with syncAllSchedule (cron based scheduling) ingest works, all data is written to endpoint, if the endpoint does not previously exist, its created and the endpoint attributes are added. Ensure the scheduling engine works, test to ensure it can be scheduled as expected, E.g. one-hour repeat runs, daily repeat etc. also to be tested in this use case.

Utilize the syncPageSize to ensure we adjust the size of the returned body, start with 100 records and try perhaps 20.

Utilize the syncUpdatedOnly to only have the ingest process pull updated delta changes, for this you’ll need to make changes to endpoints in the CMDB tenant and check only those records with changed records/attributes are retrieved, (based upon the last update).

When pulling a MAC address (or multiple MAC addresses) for an endpoint, it is based on network adapter configuration item “cmdb_ci_network_adapter”. A default filter based on Operational Status is applied in which only MAC addresses with “Operational Status = Operational” are pulled in. This continues to be the default mode of operation.

The ServiceNow Extension v2.1.1 expanded to two filters that can be applied, and there is also more flexibility in how these filters are applied. The two filters that can be applied are based on Operational Status and Install Status as seen in the default configuration:

“serviceNowOperationalStatus”: “1”,

“serviceNowInstallStatus”: “”,

A value of “1” for Operational Status is equivalent to Operational. An empty value for Install Status means this filter is not applied.

Another option is to apply filter based on Install Status only rather than Operational Status. In this case, the configuration is changed to the following:

“serviceNowOperationalStatus”: “”,

“serviceNowInstallStatus”: “1”,

Here a value of “1” for Install Status is equivalent to Installed. An empty value for Operational Status means this filter is not applied.

For reference, the following tables list the possible values for Operational Status and Install Status.

Operational Status

Selection	Value
Operational	1
Non-Operational	2
Repair in Progress	3
DR Standby	4
Ready	5
Retired	6

Install Status

Selection	Value
Installed	1
On Order	2
In Maintenance	3
Pending Install	4
Pending Repair	5
In Stock	6
Retired	7
Stolen	8
Absent	100

For the case where no filter needs to be applied and all MAC addresses are to be pulled in, the configuration is changed to the following with empty values:

“serviceNowOperationalStatus”: “”,

“serviceNowInstallStatus”: “”,

The ServiceNow Extension v3.1.3 expands even further with two new filters that can be applied. In order to optimize the syncing of large databases, now either an Allowlist or Denylist can be configured to filter which “cmdb_ci” tables will be included or excluded during the endpoint sync process.

By default, the configuration starts with empty values for both the Allowlist and Denylist:

“serviceNowSysClassAllow”: “”,

“serviceNowSysClassDeny”: “”,

Here is an example of an Allowlist that can be applied to only include “cmdb_ci” tables that contain MAC addresses (the end customer to determine the “cmdb_ci” tables to be included pertaining to their environment):

“serviceNowSysClassAllow”: “cmdb_ci_computer_list,cmdb_ci_printer_list,cmdb_ci_ip_phone_list,cmdb_ci_ups_list”,

Here is an example of a Denylist that can be applied to exclude “cmdb_ci” tables that do not contain MAC addresses (the end customer to determine the “cmdb_ci” tables to be excluded pertaining to their environment):

“serviceNowSysClassDeny”: “dscy_route_next_hop,cmdb_ci_ups_alarm”,

Use Case 2: Push endpoint to CMDB after authentication

This triggers a MAC Address’s information to be pushed to ServiceNow using the Identity and Insights information in ClearPass.

Only the identity attributes mapped in the cmdbAttributeMap configuration are sent to ServiceNow. If available, the insights data of device_category, device_family, and device_name are internally mapped to the properties CPPM-Device-Category, CPPM-Device-Family, and CPPM-Device-Name and sent to ServiceNow. Starting with extension v3.2.9, there are other insight attributes also available as listed in the section “What’s new in Service Now Extension v3.2.9”

A context server action can be used to push an endpoint from ClearPass to ServiceNow CMDB database. To trigger the push, enable the attribute “enableEndpointPush”: true in extension configuration. Any attribute from endpoint repository and a set of attributes from insight db can be pushed to cmdb. cmdbTargetMap and cmdbAttributeMap defines to which tables and fields the attributes are pushed to and should be configured appropriately.

“endpointPushRequireInsight”: true should be enabled if you wish to push insight attributes for the endpoint to CMDB.

Steps to configure this context server based endpoint push:

1. Define Endpoint Context Server

2. Add Context Server Action

3. Create an Enforcement Profile to trigger the action

So first configure a basic Context-Server pointing to the Extension IP-Address, pay specific attention to the Server Base URl of http://Extension_IP_address .

Note that it is not https, after this configure the individual context server action as shown below. in our working example 172.17.0.7 is the IP-address of the Service Now extension, your IP will likely differ.

The next step involves using the Context Server Action in the Enforcement Profile as below. The Enforcement Profile to push an endpoint to ServiceNow is shown below:

Use Case 3: Push endpoints from ClearPass to ServiceNow via push-queue

Using push queue helps to batch the pushes from ClearPass to ServiceNow. Enable cmdbAttributeMap to add additional endpoint context to be sent to SNOW. When available, extension sends Device Category, Device Family and Device Name, but cmdbAttributeMap allows you to send additional endpoint attributes. Perhaps you want to send MDM or some EDR attributes. List them in the array like this [ “Owner Email”, “OS Version” ], ensure they are mapped however via the SNOW Identification and Reconciliation engine (I&R) and that the proper mappings are made in the Aruba SNOW Application.

Enable enableQueue to start using the queuing mechanism, then utilize the queueSchedule to validate scheduling and repetitive scheduling functions. When queueRequireIdentity is enabled, only mac addresses present in Endpoint DB are sent to CMDB. Enable queueRequireInsight to ensure endpoint exists in InsightDb and to send attributes from InsightDB.

Steps to configure this context server based endpoint push using queuing mechanism:

1. Define Endpoint Context Server

2. Add Context Server Action

3. Create an Enforcement Profile to trigger the action

So first configure a basic Context-Server pointing to the Extension IP-Address, pay specific attention to the Server Base URl of http://Extension_IP_address .

Note that it is not https, after this configure the individual context server action as shown below. in our working example 172.17.0.7 is the IP-address of the Service Now extension, your IP will likely differ.

The next step involves using the Context Server Action in the Enforcement Profile as below. The Enforcement Profile to push an endpoint to ServiceNow is shown below:

Use Case 4: Sync endpoint database from ClearPass into ServiceNow

Utilize enableEndpointPush to sync all of the CPPM endpoints into ServiceNow CMDB with the frequency of the sync based on endpointPushSchedule. Optionally, configure endpointPushPageSize for endpoint being pushed into ServiceNow.

In our example below we’ve set the schedule to run every 2-hours, sync all endpoint when the extension starts/restarts and cache the results for 30 minutes. Adjust these config items as necessary for your environment.

“enableEndpointPush”: true,

**“enableEndpointPushSchedule”: * /2 * * ,

“endpointPushPageSize”: 100,

“endpointPushRequireInsight”: false

Refer to Appendix C for more details about configuring the cron based scheduling for enableEndpointPushSchedule

Use Case 5: Perform real time authorization lookup against Service Now CMDB

Service Now CMDB can be added as an auth source in ClearPass to perform a real time authorization call. The attributes fetched as part of this real time lookup can be used within the service policies. Making a get request to the extension with a MAC Address in the URL will return the details for the CMDB device in ServiceNow. If enableEndpointCache is true, the data may be cached for the duration of endpointCacheTimeMinutes.

The attribute “Found In SNOW” should always be returned by the API and will be true or false.

From ServiceNow, the cmdb_ci parent table as well as the asset, location, owned_by, cpu_manufacturer, assigned_to, company and department information will be returned and prefixed with the cmdb_ci reference field name followed by the column name (e.g. asset.display_name is the data from joined cmdb_ci.asset).

Steps to add CMDB as authorization source:

Navigate to Configuration > Authentication > Sources to create a new auth source of the type HTTP

Once the auth source has been created, it can be added to the service and referenced in policy conditions.

Additional context server action options

Service Now extension supports these additional context server action options to trigger raw API calls to Service Now. The payload must be specified as part of context server action in json format. There is no validation for these context server actions and data is sent as is. These can be useful if you want to push some attributes that are not part of endpoint db or insight db but is part of the computed attributes of the authentication request.

URL	Description	Example Data
POST /push	This process triggers a device send to ServiceNow using the data specified in the request body. The request body should be a JSON object containing at least a MAC Address. This process does not use internal endpoint lookup information and only sends the information supplied. The properties mac, ip, device_category, device_family, device_name are internally mapped to the properties CPPM-Device-Category, CPPM-Device-Family, and CPPM-Device-Name when being sent to ServiceNow. The other properties included in the object should match to the attributeMAP configuration.	{ "mac": "000f7c0d5cd0", " ip": "", "device_category": "Network Camera", " device_family": "", "device_name": "", "Owner": "user@hpe.com", "OS Version": "Unknown", ... }
POST /identifyreconcile	This endpoint will send the body to the ServiceNow identifyreconcile API. This simply relays the information posted to it, giving the user full control over what the I&R engine does. More information can be found here, https://docs.servicenow.com/bundle/paris-application-development/page/integrate/inbound-rest/concept/c_IdentifyReconcileAPI.html	{ "items": [ { "className": "cmdb_ci_computer", "internal_id":"comp", "values": { "mac_address": "01-01-01-01-01-01", "name": "Computer 2", "os": "Windows", "os_version": "10", "short_description": "Test Device" }, "lookup": [ { "className": "cmdb_ci_network_adapter", "values": { "mac_address": "01-01-01-01-01-01", "install_status": 1 } } ] } ] }
POST /queue	Adds the specified MAC Address to the processing queue to be sent to ServiceNow. This queue process runs based on the queueSchedule and will look up the endpoint’s identity and insight information. Only the identity attributes mapped in the attributesToSend configuration are sent to ServiceNow. If available, the insights data of device_category, device_family, and device_name are internally mapped to the properties CPPM-Device-Category, CPPM-Device-Family, and CPPM-Device-Name and sent to ServiceNow. This setting uses the queueRequireIdentity and queueRequireInsight options to determine if certain sets of information are required for sending to ServiceNow. If either of these options is set to true, the corresponding set of data must be available in ClearPass for the data to be sent to ServiceNow.	{ "mac": "000f7c0d5cd0" }
GET /resetPullLastUpdate	Resets the last updated date saved by the ServiceNow pull process when the serviceNowPullUpdatedOnly configuration option is true.

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 data from ServiceNow

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

{ "source": "SNOW", "network.skip_sync": "0", "network.operational_status": "1", "network.sys_updated_on": "2019-04-06 00:17:51", "network.first_discovered": "2019-04-03 23:45:17", "network.sys_created_on": "2019-04-03 23:45:17", "network.dhcp_enabled": "0", "network.install_status": "1", "network.name": "NetworkAdapter@10.2.100.218", "network.subcategory": "Network", "network.virtual": "0", "network.last_discovered": "2019-04-06 00:17:51", "network.can_print": "0", "network.sys_class_name": "cmdb_ci_network_adapter", "network.sys_id": "b00ea29adb207f4061840bb6f496194a", "network.netmask": "255.255.255.0", "network.mac_address": "00-0f-7c-0d-5c-d0", "network.monitor": "0", "network.ip_address": "10.2.100.218", "network.cost_cc": "USD", "network.unverified": "0", "network.category": "Hardware", "network.fault_count": "0", "cmdb_ci.can_switch": "0", "cmdb_ci.skip_sync": "0", "cmdb_ci.operational_status": "1", "cmdb_ci.device_type": "Network Camera", "cmdb_ci.sys_updated_on": "2019-04-06 00:17:51", "cmdb_ci.discovery_source": "ClearPass", "cmdb_ci.first_discovered": "2019-04-03 23:45:17", "cmdb_ci.sys_created_on": "2019-04-03 23:45:17", "cmdb_ci.can_partitionvlans": "0", "cmdb_ci.hardware_status": "installed", "cmdb_ci.install_status": "1", "cmdb_ci.subcategory": "Network", "cmdb_ci.last_discovered": "2019-04-06 00:17:51", "cmdb_ci.can_print": "0", "cmdb_ci.sys_class_name": "cmdb_ci_netgear", "cmdb_ci.can_hub": "0", "cmdb_ci.cpu_count": "1", "cmdb_ci.sys_id": "fc0ea25adb207f4061840bb6f4961923", "cmdb_ci.mac_address": "00-0f-7c-0d-5c-d0", "cmdb_ci.can_route": "0", "cmdb_ci.monitor": "0", "cmdb_ci.ip_address": "10.2.100.218", "cmdb_ci.cost_cc": "USD", "cmdb_ci.unverified": "0", "asset.skip_sync": "0", "asset.residual": "0", "asset.sys_updated_on": "2019-04-03 23:45:17", "asset.sys_created_on": "2019-04-03 23:45:17", "asset.depreciated_amount": "0", "asset.pre_allocated": "0", "asset.display_name": "Unknown", "asset.install_status": "1", "asset.sys_class_name": "alm_hardware", "asset.sys_id": "f40ea25adb207f4061840bb6f4961924", "asset.resale_price": "0", "asset.cost": "0", "asset.quantity": "1", "asset.active_to": "0", "asset.salvage_value": "0", "cmdb_ci.category": "Hardware", "cmdb_ci.fault_count": "0", "SNOW Last Update": "2019-04-06T00:18:57.201Z", "Found In SNOW": true }