Jamf Pro

  32 minute read  

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.

JAMF4 (Attribute names as seen in v4 and older versions)	JAMF5 (Attribute names in v5 version)	Change Type
JAMF Activation Lock Enabled	JAMF Activation Lock Enabled	Unchanged
JAMF Asset Tag	JAMF Asset Tag	Unchanged
JAMF Block Level Encryption Capable	JAMF Block Level Encryption Capable	Unchanged
JAMF Data Protection	JAMF Data Protected	Renamed
JAMF Department	JAMF Department	Unchanged
JAMF Device Ownership Level	JAMF Device Ownership Type	Renamed
-	JAMF Declarative Device Management Enabled	New attribute
JAMF File Level Encryption Capable	JAMF File Level Encryption Capable	Unchanged
JAMF Group Names	JAMF Group Names	Unchanged
JAMF Hardware Encryption	JAMF Hardware Encryption	Unchanged
JAMF ID	JAMF ID	Unchanged
JAMF IMEI	JAMF IMEI	Unchanged
JAMF Initial Entry Date UTC	JAMF Initial Entry Date	Renamed
JAMF IP Address	JAMF IP Address	Unchanged
JAMF Jailbreak Detected	JAMF Jailbreak Detected	Unchanged
JAMF Last Contact Time UTC	JAMF Last Contact Time	Renamed
JAMF Last Inventory Update UTC	JAMF Last Inventory Update UTC	Unchanged
JAMF Last Reported IP	JAMF Last Reported IP	Unchanged
JAMF Last Update	JAMF Last Update	Unchanged
JAMF Lost Mode Enabled	JAMF Lost Mode Enforced	Renamed
JAMF Make	JAMF Make	Unchanged
JAMF Managed	JAMF Managed	Unchanged
JAMF Model	JAMF Model	Unchanged
JAMF Model Display	-	Missing
JAMF Model Identifier	JAMF Model Identifier	Unchanged
JAMF Model Number	JAMF Model Number	Unchanged
JAMF Name	JAMF Name	Unchanged
JAMF OS Name	JAMF OS Name	Unchanged
JAMF OS Version	JAMF OS Version	Unchanged
JAMF Passcode Compliant	JAMF Passcode Compliant	Unchanged
JAMF Passcode Present	JAMF Passcode Present	Unchanged
JAMF Phone Number	-	Missing
JAMF Platform	JAMF Platform	Unchanged
JAMF Remote Managed	JAMF Remote Managed	Unchanged
JAMF Report Date UTC	JAMF Report Date	Renamed
JAMF Room	JAMF Room	Unchanged
JAMF Serial Number	JAMF Serial Number	Unchanged
JAMF Supervised	JAMF Supervised	Unchanged
JAMF System Found	JAMF System Found	Unchanged
JAMF Type	JAMF Type	Unchanged
JAMF UDID	JAMF UDID	Unchanged
JAMF User Approved Enrollment	JAMF User Approved MDM	Renamed
JAMF Version	JAMF Version	Unchanged
-	JAMF Management ID	New attribute
-	JAMF Last Enrolled Date	New attribute
-	JAMF Department ID	New attribute
-	JAMF Tethered	New attribute

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

Attribute	Description	Values/Examples
jamfHost	This is the sub-domain of the Jamf API URL. This will be the URL used by ClearPass to communicate with Jamf.	instance.jamfcloud.com
jamfUserName	The Jamf username used to interface with Jamf and create Extension Attributes. Ensure this username has sufficient privileges in which to create Extension Attributes.	admin
jamfPassword	The password for the aforementioned Jamf username.	[password]
additional-attributeMapping	This array allows for more information to be retrieved from Jamf.	See Appendix A
macExtensionAttributeName	The name of the Extension Attribute used. In this example, it is the "cppm-alma-addresses" Extension Attribute.	cppm-alma-addresses
createMacExtensionAttribute	Specifies whether to run or create the extension attribute automatically.	true or false
skyhookTenant	The Skyhook tenant ID received in the registration email. Required when using Webhooks for real-time event updates from Jamf to ClearPass.	See Appendix F
dbAccessToken	The access token for Skyhook received in the registration email. Required when using Webhooks for real-time event updates from Jamf to ClearPass.	See Appendix F
smartGroupTrig-gerDisconnect	Tied to Webhooks events, after adding or updating devices. In the case it triggers a Webhook that matches SmartGroupMobileDeviceMembership-Change or SmartGroupComputerMembership-Change, the devices with corresponding MAC address in the configured Smart Group are sent a disconnect.	Smart Group name. For example, "OutofCompliance" is name of Smart Group for devices where Jailbreak Detected is a condition.

Common extension attributes

Extension framework configuration parameters (common configuration)

Attribute	Description	Default Values
logLevel	Logging level for troubleshooting	“INFO”
verifySSLCerts	Should SSL certificates be validated when communicating with external context sources	true
enableEndpointCache	Cache endpoint attributes to optimize authorization queries, avoid repeated DB queries and reduce API calls to external context sources	true
endpointCacheTimeSeconds	The duration in seconds to cache the endpoint attributes	300
syncUpdatedOnly	If this option is set to true, only the endpoints updated after the previous sync would be fetched from the context source. Note that this option only works for the third-party context sources that have APIs to support this functionality. If this option is set to false, all endpoints are fetched at every sync interval.	true
syncAllOnStart	If this option is set to true, when the extension starts, the system will attempt to sync all endpoints in the external context source to ClearPass. Note that if you have a large number device context to be fetched, it would take a long time for the initial sync to complete. When used along with syncUpdatedOnly, the subsequent syncs should be faster.	true
enableSyncAll	Enable periodic sync of all endpoints	true
syncAllSchedule	The schedule for when the Sync All Endpoints process should run. Note: This uses CRON type scheduling.	0 2 * * 6
enableStats	Enable display of extension statistics	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
bypassProxy	Bypass the web proxy configured on ClearPass Policy Manager	false

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:

general.	id	network_adapter_type	Other
mac_address	id	name	network_adapter_type
last_reported_ip	serial_number	udid	jamf_version
platform	barcode_1	barcode_2	asset_tag
remote_management	managed	management_username	management_password_sha256
supervised	mdm_capable	mdm_capable_users	mdm_capable_user
management_status	enrollment_via_dep	user_approved_enrollment	user_approved_mdm
report_data	report_data_epoch	report_data	last_contact_time
initial_entry_date_epoch	initial_entry_date	last_enrolled_date_utc	last_enrolled_date_epoch
initial_entry_date_utc	last_cloud_backup_date_epoch	distribution_point	sus
site	id	name	notebook server
itunes_store_account_is_active

location.	username	realname	real_name
email_address	position	phone	phone_number
department	building	room

purchasing.	is_purchased	is_leased	po_number
vendor	applecareid	purchase_price	purchasing_account
po_date	po_date_epoch	warranty	warranty_expires
warranty_expires_epoch	lease_expires	lease_expires_epoch	os_applecare_id
lease_expires_utc	life_expactancy	attachments	purchasing_contact
os_maintenance_expires

peripherals.	size

hardware.	make	model	model_identifier
os_name	os_version	os_build	master_password_set
active_directory_status	service_pack	processor_type	processor_architecture
processor_speed	processor_speed_mhz	number_processors	number_cores
total_ram	total_ram_mb	boot_rom	bus_speed
bus_speed_mhz	battery_capacity	cache_size	cache_size_kb
available_ram_slots	optical_drive	nic_speed	smc_version
ble_capable	sip_status	gatekeeper_status	xprotect_version
institutional_recovery_key	disk_encryption_configuration	filevault2_users	user
storage	device	disk	model
revision	serial_number	size	drive_capacity_mb
connection_type	smart_status	partitions	partition
name	size	type	partition_capacity_mb
percentage_full	filevault_status	filevault_percent	filevault2_status
filevault2_percent	boot_drive_available_mb	lvUUID	lvUUID
pvUUID	mapped_printers	printer	name
uri	type

certificates.	certificate	common_name	identity
expires_utc	expires_epoch	name

security	activation_lock	secure_boot_level	external_boot_level

software.	unix_executables	licensed_software	installed_by_casper
installed_by_installer_swu	cached_by_casper	available_software_updates	available_updates
running_services	applications	size	application
name	path	version	fonts
plugins

extension_attributes.	extension_attribute	id	name
type	multi_value	value

groups_accounts.	computer_group_memberships	local_accounts	user_inventories
disable_automatic_login	user	username	password_history_depth
password_min_length	password_max_age	password_min_complex_characters	password_require_alphanumeric

iphones.	size

configuration_profiles.	size	configuration_profile	id
name	uuid	is_removable
filevault2_percent	boot_drive_available_mb	lvUUID	lvUUID
pvUUID	mapped_printers	printer	name
uri	type

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: