This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Unified Endpoint Management

ClearPass integrates with a wide range for UEM / MDM solutions authorize devices as part of HPE Aruba Networking Zero Trust framework

A detailed list of third party interoperability can be found here: https://www.arubanetworks.com/support-services/clearpass-interoperability/

1: Jamf Pro

2: Jamf School

3: Meraki System Manager

4: Microsoft Intune

4.1: ClearPass Onboard Enrollment using Microsoft Intune SCEP Extension

5: VMware Workspace ONE (Airwatch)

6: Ivanti MDM (formerly MobileIron)

7: Mosyle

8: SOTI MobiControl

1 - Jamf Pro

This integration guide covers how to deploy and configure the ClearPass Extension to interface with Jamf Pro Apple Management MDM.

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.

INFO

To avoid service disruption, switch to the Jamf Pro API by setting enableV2Api to true ahead of the Jamf Classic API deprecation.

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.

Enforcement based on date-time based jamf attribute

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.

INFO

Internet access is required for ClearPass Policy Manager to install the ClearPass Extensions from the Extension Store. Starting with ClearPass 6.12, extensions can be can be installed offline as well. Offline ClearPass Extension images are available on HPE networking support portal.

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.

INFO

Here we are using Intune as an example. The installation steps are the same for all the extensions. For your deployment, please search for the appropriate extension like Jamf, Mosyle, Crowdstrike, etc.

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

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.

INFO

Note that the Policy Manger web proxy configuration is ONLY read by the extension at installation time. If the web proxy configuration is changed in Policy Manager, then the extension must be re-installed so the new settings are re-read and bonded to the extension.

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

INFO

The subnet defined here for the extension framework must fall within the following subnet range 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 as defined by RFC1918. For best results, set the network address range to a subnet that does not exist in your enterprise, and restart the extension service for this change to take effect.

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

Defining the base IP SUBNET and LOCALHOST for the Extensions Framework

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

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.

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.

INFO

Pay special attention to the values in the extension configuration. Where a configuration attribute is a Boolean value {true/false}, it must not be enclosed with literals..

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.

Role Mapping Policy using Jamf 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>

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

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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:

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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,
```

WARNING

Having the extension installed on all the cluster nodes with enableSyncAll set to true would cause each cluster node to independently poll the external system and update endpoint repository. This could impact the performance of ClearPass. Hence it is strongly recommended to enable endpoint sync only on the extension installed on the publisher and on another cluster node for redundancy.

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:

2 - Jamf School

This integration guide covers the deployment and configuration of ClearPass Policy Manager to interface with Jamf School formerely ZuluDesk.

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.

Pictorial view of ClearPass Policy Manager integration with Jamf School

Software Requirements

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

Installing Extension

INFO

Access to the extension store

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.

INFO

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

Extensions and web proxy support

INFO

Extensions and IP address configuration support

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

INFO

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

ClearPass Jamf School Extension Configuration

Table 1: Jamf School Extension-specific configuration parameters

Jamf School Configuration

Attribute	Description	Values/Examples
JamfSchoolHost	This will be the URL used by ClearPass to communicate with Jamf School API endpoints.	account.jamfcloud.com
JamfSchoolNetworkId	The network ID for your Jamf School Instance. See, https://developer.jamf.com/developer-guide/docs/jamf-school for more details.	30174556
JamfSchoolApiV2Key	The ApiV2key is mandatory and used to access the Jamf School API for periodic sync with JamfSchool. See, https://developer.jamf.com/developer-guide/docs/jamf-school for more details.	secret-Value
JamfSchoolApiV1Key	The ApiV1key is optional if only periodic sync is configured. However to support Real-time AuthZ against JamfSchool this API key is needed.	secret-Value
ignoreEndpointDifferences	List of endpoint fields that should be ignored during comparison/syncing.	lastCheckin, lastCheckin.date, modified, etc
removeEndpointAttributes	List of attributes that should be removed from endpoints during sync.	availableCapacity, batteryLevel, etc

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

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.

GUI review and setting the Extension configuration

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:

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.
If the iCloud Backup is not enabled, create a helpdesk ticket.
If the device is not supervised by Jamf School, put it in the Quarantine VLAN.

Example of an Enforcement Policy utilizing attributes returned from Jamf School

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.

INFO

When using the JamfSchool extension as an HTTP AuthZ source for real-time attribute lookups of endpoints, you must configure the JamfSchoolApiV1Key. This key enables real-time queries to Jamf School during authorization. If real-time lookups are not required, the JamfSchoolApiV1Key can be omitted. In such cases, configuring only the JamfSchoolApiV2Key is sufficient for periodic polling and endpoint synchronization.

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.

Attributes to be fetch during real-time AuthZ

These attributes can then be leveraged in your policies.

Leveraging attributes in Enforcement 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

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>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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.

Extensions and web proxy / firewall whitelisting

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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

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

Monitoring extension statistics

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

HTTP Authorization Source Mode

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.

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

Appendix C – endpoint sync schedule settings

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

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

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,
```

WARNING

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.

3 - Meraki System Manager

Meraki Systems Manager is a cloud-based endpoint management solution designed to simplify the administration of devices across diverse environments. It supports multiple platforms, making it ideal for organizations with mobile-centric operations. It enables quick provisioning, monitoring, and securing of devices across distributed sites.

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

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

Installing Extension

INFO

Access to the extension store

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.

INFO

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

Extensions and web proxy support

INFO

Extensions and IP address configuration support

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

INFO

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

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

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.

Meraki System Manager My Profile Menu

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.

Generating a Meraki System Manager API Key

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

Configuration attribute	Description	Example/Values
logLevel	Logging level for troubleshooting	"DEBUG", "INFO", "WARN", "ERROR"
verifySSLCerts	Specifies whether SSL certificates should be validated when making requests	true or false
merakiHost	URL for API calls to Meraki	api.meraki.com
merakiApiKey	The API Key from Meraki System Manager configuration	—
endpointSyncSchedule	The CRON schedule used for the sync process	10 3 * * *
endpointSyncOnStart	Specifies whether to run the endpoint sync immediately when the extension starts	true or false
enableSyslogEvents	Enables the processing of syslog events from Meraki System Manager alerts	true or false
syslogServers	Host: IP of the extension gateway; Port: syslog port (usually 514); useTCP: true or false	—
enableSkyhook	Enables or disables the endpoint sync scheduler	true or false
skyhookTenant	The Tenant ID for Skyhook from registration	965abd48-zzzz-aaaa-8164-xxxxxxxxxx
dbAccessToken	The access token for Skyhook (sent from Skyhook registration)	—
sharedSecret	The Meraki System Manager Webhook Secret from alert settings	—
cppmUserName	A ClearPass username used for device profiling	—
cppmPassword	Password for the above ClearPass user	—
bypassProxy	Enable extension to bypass web proxy	true or false

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.

Role Mapping Policy using Meraki System Manager 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.

INFO

Note when enabling this feature, a warning message is displayed as shown below which highlights and warns of the potential consequences. Be aware that is can generate a significant CPU load on the node. Careful consideration needs to be used and we specifically do not want CPPM to be receiving a constant stream of syslog messages that it has to then process. CPPM should only be receiving syslog messages by exception that it has to process and take action on, if you send a constant stream of syslog then the overhead will likely cause the node to become CPU bound and the potential failure/timeout of the primary function, the Authentication of Users/Computers.

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.

Adding an Enforcement Profile

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.

Building the Event Rules from the Ingress 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.

Defining the event rule trigger and the Enforcement Profile to call

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

Then set the Service Rule conditions that will trigger the service.

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

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>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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.

Extensions and web proxy / firewall whitelisting

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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

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

Monitoring extension statistics

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

HTTP Authorization Source Mode

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.

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

Appendix C – endpoint sync schedule settings

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

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

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,
```

WARNING

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.

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”

4 - Microsoft Intune

This integration guide covers the setup, configuration, and monitoring of the Microsoft Intune ClearPass Extension within ClearPass Policy Manager.

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.

Client Certificate with Strong Mapping attribute in SAN Field

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.

Attribute variable for security identifier on Intune SCEP profile

New Recommendation around using alternate Intune ID to support Device / User Group Lookups

INFO

The following are only recommendations and not mandatory settings. They also only apply to environments that need device or user group lookups using Intune extension. With ClearPass release 6.12 Device group lookups against Entra ID is also supported natively along with 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

DeviceId:{{DeviceId}} - Used for Intune attributes lookup.
AAD_Device_ID:{{AAD_Device_ID}} - Used for both Intune attributes and Device group membership lookup.
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.

Intune attributes in ‘Key:Value’ format in the certificate SAN URI

Intune SCEP certificate Profile configuration

INFO

Supported special characters in the KEY variable names are “_” and “-”. KEYS can be set in any case as required but it is strongly recommended to use the same variable names that Intune supports in the SCEP profile. Supported variables can be found in the following Microsoft Intune documentation https://learn.microsoft.com/en-us/intune/intune-service/protect/certificates-profile-scep#create-a-scep-certificate-profile

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.

INFO

The following are recent changes done by Google that impact Android devices in Intune: (1) Removal of serial number, IMEI, and MEID on personally-owned work profile devices [running Android 12] and (2) Removal of Wi-Fi MAC address on newly-enrolled device administrator and personally-owned work profile devices [running Android 9 and above]. For more information, see the Android Day Zero Support with Microsoft Endpoint Manager blog post.

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.

INFO

As/If you move to this v5 you must carefully consider the adjustments that may be need in your work flow and configuration and how you use the Intune data ingested into the endpointDb repo.

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

INFO

Intune v2 was never released publicly

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

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

Installing Extension

INFO

Access to the extension store

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.

INFO

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

Extensions and web proxy support

INFO

Extensions and IP address configuration support

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

INFO

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

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.

Configuring and Collecting Information from Microsoft to Configure Intune extension
Installation and Configuration of the Intune Extension
Configuring ClearPass Intune Extension to sync endpoint data from Intune to the EndpointDb
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

INFO

Below we cover the process of adding a ‘ClearPass App’ into Azure as an application and enabling the necessary application level permissions. Think of this as the gateway between ClearPass and Microsoft Intune.

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”,

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

}

Login to https://portal.azure.com. Log in using your Intune Tenant Admin account. We assume here you have already identified and configured at least one of your Intune accounts with Administrator rights.

Once logged in, open “Azure Active Directory” and select “App Registrations”. In “App Registrations”, click on “New registration” menu. Provide a name to identify this application, something like “ClearPass Intune Integration”. Use all the default values when defining the new application, click on ‘Register’.

After clicking on Register, in the next screen for the application previously created, record the clientId and the tenantdID as highlighted below. Collect these string as they will be required later to complete the Extension configuration.

Next the permissions must be configured for the new application. To the left on the navigation tree, click on ‘API permissions’ followed by ‘Add a Permission’

Next, click on ‘Microsoft Graph > Application permission’, add the permissions listed below. Next click on ‘Intune > Application permission’ add the permissions listed below.

TIP

Check Appendix F for details about permissions required for the application. We have a detailed breakdown of permissions needed for each use case. Only enable the appropriate permissions as required by your setup.

At this stage all of the permission should be added, but show as ‘Not granted for…..’ Click on ‘Grant admin consent for XXX’

Confirm on the request for granting consent for the requested permissions.

Ensure you see a successful confirmation of this process, as the below two screen images indicate.

One final step in this section, create a secret. From the navigation pane on the left side, click on ‘Certificates & secrets’, then under ‘Client secret’ add a ‘New client secret’, provide a descriptive description, choose the expiration and be sure to make a note of the expiration date. Depending on your sensitivity to password rotation and corporate policy, this is ultimately your decision. You can configure a new password at any time, change its duration accordingly as long as you match this to the secret configured in the Extension.

Before you leave this screen record the client-secret shown below as this is also required to complete the configuration of the Intune extension.

Configuring ClearPass Intune Extension to sync endpoint data

It’s 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 a “real-time” authZ to Intune. Not all configuration settings need to be set but some are mandatory. We have divided the parameters into two tables, one for Intune Extension-specific configuration parameters and the other for extension framework configuration parameters that are common across multiple vendor Extensions.

Table 1: Intune Extension-specific configuration parameters

Attribute

Description

Values/Examples

tenantId

Azure Tenant ID for the instance, as previously recorded.

XXXXXXXXX-b3e5-12ab-34cd-ZZZZZZZZZZZ

clientId

The API Client ID configured for the Intune instance, as previously recorded.

123abcde-45fg-67hi-jk89-1234567890a

clientSecret

The Client Secret that corresponds to the clientId, as previously recorded.

XyzYZ123456-aabbccddeeff123-abcfgh12=

syncPageSize

The page size used when puling data from Graph.

intuneAttributes

{See below for a more detailed explanation of this field}

This setting allows the user to restrict the requested attributes from Intune.

The setting requires an array of strings, each string being an attribute to include.

Example:

["complianceState", "deviceEnrollmentType", "jailBroken"]

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

Mandatory fields are; tenantId, clientId, clientSecret obtained earlier.

Configuration of syncSchedule 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. syncOnStart determines if when the extension is started or restarted should it immediately run the sync process, or wait until the syncSchedule job is run.

The two values of enableEndpointCache and cacheTimeInSeconds are specifically used in conjunction with the extension is used as an Authorization source to retrieve real-time data for a known endpoint. If using the Extension in combination as discussed later with a HTTP authZ source which needs to do lookup based on Intune Device ID as following:

GET /device/info/id/:intuneId

Then these switches will ensure that if the extension is asked to refresh data, it will check the cacheTimeInSeconds to decide if the data current held is fresh or stale.

intuneAttributes is used to filter the returned data back from Intune, this can be used if there are large amounts of tenants or you just want to reduce the number of attributes returned and updated. This setting allows the user to restrict the requested attributes from Intune.

The setting requires an array of strings, each string being an attribute to include.

Example:

["complianceState", "deviceEnrollmentType", "jailBroken"]

When blank, which is the default value when the extension is initailly installed, it will say null, all attributes from Intune will be returned and added to the endpoint database. If you populate a filter the following fields will always be included, ‘id’, ‘wiFiMacAddress’, ‘deviceName’, ‘model’, ‘osVersion’, ‘operatingSystem’.

The following values are valid optional attributes:

id, userId, deviceName, managedDeviceOwnerType enrolledDateTime, lastSyncDateTime, operatingSystem, complianceState, jailBroken, managementAgent, osVersion, easActivated, easDeviceId, easActivationDateTime, azureADRegistered, deviceEnrollmentType, activationLockBypassCode, emailAddress, azureADDeviceId, deviceRegistrationState, deviceCategoryDisplayName, isSupervised, exchangeLastSuccessfulSyncDateTime, exchangeAccessState, exchangeAccessStateReason, remoteAssistanceSessionUrl, remoteAssistanceSessionErrorDetails, isEncrypted, userPrincipalName, model, manufacturer, imei, complianceGracePeriodExpirationDateTime, serialNumber, phoneNumber, androidSecurityPatchLevel, userDisplayName, configurationManagerClientEnabledFeatures, wiFiMacAddress, deviceHealthAttestationState, subscriberCarrier, meid, totalStorageSpaceInBytes, freeStorageSpaceInBytes, managedDeviceName, partnerReportedThreatState

INFO

Note: If something is incorrect or a field that Intune doesn’t like to limit, it will cause errors. If this happens check or remove the configured values. A sample of this error is, “Parsing OData Select and Expand failed: Could not find a property named ‘XXXXX’ on type ‘microsoft.graph.managedDevice’.”

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

An example of an Intune 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 Intune tenant, you should see something similar to the below.

INFO

IP address assigned to the extension is “172.17.0.4”. This will be used when configuring Intune as an HTTP Authorization source within ClearPass Policy Manager. It’s likely the IP address of your Extension will differ.

Configuring ClearPass Policy Manager as an HTTP authZ source

Endpoint Sync Mode

After configuring the syncSchedule and starting the Extension, data should immediately start to appear in the EndpointDb, especially if syncOnStart is set as true, you can see this by filtering data as shown below.

Filter=Attribute equals Source contains Intune

After the initial sync is complete, it’s a simple process of utilizing the data in the EndpointDb inside Role-Mapping/Enforcement-Policy.

HTTP Authorization Mode

To complete the configuration to use the Extension as a ‘real-time’ authorization source, configure an HTTP authorization source within ClearPass. With Intune as an authorization source to the extension, ClearPass can receive the latest data from the Intune platform for previously ingested endpoints, presented under the authZ source. This is more real-time but consideration needs to be made relative to the number of API calls that would be made.

Click on Next. This will advance to the Primary Tab provide the connection details.

The Base URL IP address is what can be seen in figures above.

Set the Base URL as HTTP://IP_of_the_Extension/device/info/id/ and pay special attention to HTTP not HTTPS, and also the addition of “id/” in the path which is required in v6 of Extension.

It’s mandated that a Login Username/Password is entered, but it’s not used, so this can be set to 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 Intune extension asking for context about the endpoint. The query is indexed off the Intune Device ID in the certificate of the authenticating endpoint. The Device ID can be referenced in the subject alternative name in the certificate (see Appendix E for more details).For completeness, the Filter Query is provided here, copy one of the options carefully corresponding to how the certificate is configured.

%{Certificate:Subject-AltName-URI}

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. You can choose whatever attributes you want to be exposed under authZ based upon what you list here. A complete list is available in Appendix A, the first fields in BOLD listed in Appendix A translate to the fields you can enter when configuring the query results, a short example is below.

Once the HTTP authorization source is defined you can use the returned attributes in your policy processing. As an example lets view the returned attributes from the above from an authentication request in access-tracker.

Below can be see the result of a real-time query from Intune based upon the attributes configured in the above authZ source, this data has been returned and is available to the policy at authentication time.

Similarly, For fetching User group information as AuthZ attributes using the Intune extension the Base URL of the authentication source should be set as HTTP://IP_of_the_Extension//realtimeUserGroup/ and the filter query is indexed of the UserPrincipalName from the SAN field of the certificate. For the Device group information the Base URL of the authentication source should be set as HTTP://IP_of_the_Extension/realtimeDeviceGroup/ and the filter is indexed of the AAD_Device_ID from the SAN field of the certificate.

Fetching user group membership:

Fetching device group membership:

Utilizing HTTP Authorization Mode to Retrieve Specific Attributes

The HTTP authorization mode can be leveraged as a general method for retrieving specific attributes from Intune. This comes in handy when we need to overcome a limitation with GraphAPI when syncing with Intune to retrieve device attributes. One such limitation of GraphAPI is it does not support retrieving the Ethernet MAC address attribute (wired interface). In order to address this, we can add Ethernet MAC Address to the HTTP authorization source query and returned attribute as shown below:

INFO

It is important that “enableEndpointCache” is set to true in the Extension configuration.

This method utilizes real-time lookup by Intune device ID to pull the Ethernet MAC attribute and have it stored in the endpoint DB as shown below:

In the next section we cover options on how to use the results of the returned attributes from Intune in Role-Mapping or in an Enforcement-Policy.

Using data from Intune in a ClearPass Enforcement Policy

Multiple use-cases exist for how the data that is returned from Intune can be used in your policy enforcement. In the example below, we are performing multiple checks:

Check the device is a Corporately issued and managed device. If true then update the Palo Alto and Checkpoint corporate firewall with context about this device.
Check that the device is managed by Intune and that it’s compliant. In addition to allowing access for these devices, we’re also updating the endpoint with the authentication Date & Time so we can track the device’s access to the network.
If the device is not in compliance then we will apply a Quarantine role.
If the device is running an OS that is not 13.6 [assume iOS] then we flag it as an old-OS.
If the device is running an OS that begins with 13.6 [assume iOS] then we flag it as an approved-OS.
If the device is running Android OS then we attach a label of Android.
If the device is running Android OS then we attach a label of Apple.

The policy used in the screenshot above is just a reference. Different companies will have different enforcement profiles and policies. The key take away here is that it showcases the use of authorization attributes received from Intune to drive the policy engine into taking different enforcement actions for the device as they authenticate on the network. It is recommended to use these policies within Role-Mapping. Enforcement policies usually will not use an “Evaluate all” rules evaluation algorithm.

Sending updates and triggering actions on Azure enrolled Devices

Starting with the v5 Extension we’ve enabled some new capabilities in respect of how we can interact with the Intune managed devices. The framework adopted for v5 allows ClearPass Policy Manager to update endpoint attributes in Intune and trigger actions against managed devices.

Review this link to see a list of the possible actions; https://docs.microsoft.com/en-us/graph/api/resources/intune-devices-manageddevice?view=graph-rest-1.0

This list shows all of the supported actions that can be envoked against an Intune managed device, at this stage based upon request from customer’s we’ve implmented a small subnet of actions to gauge the need from our customers, if there are other actions required, please contact us.

Trigger a device-sync
Trigger a device endpoint update {very limited capabilities}
Trigger a device shutdown
Trigger a device wipe
Trigger a device remote lock

From the list of commands above in the link it can be seen that via a Context Server Actions {CSA}, any actions in theory can be sent via the Extension to Intune. Below are some examples of building out the CSA’s for the action’s supported.

Before configuring the CSA, you must configure a basic Context-Server pointing to the Extension IP-Address, pay specific attention to theServer Base URl of http://Extension_IP_address . Note that it is not https, after this configure the individual CSA’s shown below. in our working example 172.17.0.4 is the IP-address of the Intune extension, your IP will likely differ.

Next create the Context-Server-Actions.

Creating the remoteLock Action CSA

Depending on the action, there are several steps to check/configure.

Firstly, ensure the required permission in Azure have been configured. The permission to run the actions is additional to the base permission required to ingest the endpoint data. For example; reviewing the remoteLock actions from the link supplied above shows that a specific GraphAPI permissions is required.

TIP

So be sure to add the permissions as necessary as per the above;

It likely after adding the new permission you’ll see a warning messages like below;

Ensure that you “Grant admin consent for XXXXX”, for the permission that was just added.

Once this above step is complete, you’ll see a message indicating success and the permission grant will change as shown below.

Following the configuration of the Context-Server and the configuration in Azure, configure the CSA in ClearPass.

Configure the CSA, chose the Context-Server previously configured {172.17.0.4 in our example}, configure as a POST, set Authentication Method equal to None and set the URL as /device/remoteLock/%{Connection:Client-Mac-Address-Hyphen}

Then the CSA needs to be added to a Enforcement Profile, configure it as the below as a post_authentication session-notification, then this can be added to an existing enforcment-policy rule.

When this is run succesfully in the Extension the following logs can be seen;

[2020-09-01T21:06:36.809] [INFO] Intune - [/device/remoteLock/:mac] request received from ::ffff:172.17.0.1.

[2020-09-01T21:06:37.023] [DEBUG] Intune - Request “GET ‘/endpoint’” took 213 ms.

[2020-09-01T21:06:38.091] [DEBUG] Intune - Request “POST ‘/deviceManagement/managedDevices/94ee89b5-55b0-4635-9f74-1f732dac8497/remoteLock’” took 1.067 Seconds.

[2020-09-01T21:06:38.091] [INFO] Intune - The action “remoteLock” was sent to Intune for device 94ee89b5-55b0-4635-9f74-1f732dac8497.

INFO

Based on customer feedback, if the NAD device deployed is not sending the framed IP address in the accounting packets, the “Post_Authentication Type” based enforcement profile does not get triggered/applied for the endpoint. A workaround for this to remove the dependency on the framed IP address in accounting is to use “HTTP Type” based enforcement profile instead to trigger the post authentication.

Creating the deviceShutdown Action {requires Supervised Mode on endpoint}

Configure the CSA as a POST, set Authentication Method equal to None and set the URL as /device/shutDown/%{Connection:Client-Mac-Address-Hyphen}, this CSA can then be attached to a enforcement-profile, which can then ultimatly be added to a service-policy to be triggered under certain matching conditions.

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

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>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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.

Extensions and web proxy / firewall whitelisting

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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

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

Monitoring extension statistics

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

HTTP Authorization Source Mode

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.

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

Appendix C – endpoint sync schedule settings

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

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

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,
```

WARNING

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 – List of all available Intune Attributes

“Source”:“Intune”,

“Intune Last Updated”:“2020-08-24 22:51:00”,

“Intune ID”:“04bbcce0-07bb-4c88-a3bb-c88a123abcb0c”,

“Intune User ID”:“abaf94ff-b6b3-1a2b-5e6f-19581de12345”,

“Intune Device Name”:“Danny’s iPhone”,

“Intune Managed Device Owner Type”:“personal”,

“Intune Enrolled Date Time”:“2019-02-06T21:33:29.6217769Z”,

“Intune Last Sync Date Time”:“2019-07-20T21:38:23.0716346Z”,

“Intune Operating System”:“iOS”,

“Intune Compliance State”:“noncompliant”,

“Intune Jail Broken”:“False”,

“Intune Management Agent”:“mdm”,

“Intune OS Version”:“12.3.1”,

“Intune Eas Activated”:true,

“Intune Eas Device ID”:“12345445XXX0B396FFF642NOG3C”,

“Intune Eas Activation Date Time”:“2019-02-06T21:34:08.5872874Z”,

“Intune Azure AD Registered”:true,

“Intune Device Enrollment Type”:“userEnrollment”,

“Intune Azure AD Device Id”:“7a80afd3-aabb-1234-9acf-83f987654321”,

“Intune Device Registration State”:“registered”,

“Intune Device Category Display Name”:"",

“Intune Is Supervised”:false,

“Intune Exchange Last Successful Sync Date Time”:“0001-01-01T00:00:00Z”,

“Intune Exchange Access State”:“none”,

“Intune Exchange Access State Reason”:“none”,

“Intune Remote Assistance Session Url”:"",

“Intune Remote Assistance Session Error Details”:"",

“Intune Is Encrypted":true,

“Intune User Principal Name”:“dannyjump@clearpassyeahbaby.onmicrosoft.com”,

“Intune Model”:“iPhone X”,

“Intune Manufacturer”:“Apple”,

“Intune IMEI”:“351234567890154321”,

“Intune Compliance Grace Period Expiration Date Time”:“2020-05-10T11:15:10.1451Z”,

“Intune Serial Number”:“G6TWXXYXYZXYZXYZ”,

“Intune Phone Number”:"+*******9748”,

“Intune User Display Name”:“Danny Jump”,

“Intune Wi Fi MAC Address”:“a056f38cc6be”,

“Intune Subscriber Carrier”:“AT&T”,

“Intune MEID”:"",

“Intune Total Storage Space in Bytes":251419164672,

“Intune Free Storage Space in Bytes":211984318464,

“Intune Managed Device Name”:“dannyjump_IPhone_2/6/2019_9:33 PM”,

“Intune Partner Reported Threat State”:“unknown”

Appendix F – SCEP Certificate Configuration Profile

This appendix provides an example of how to create a SCEP certificate configuration profile for a specific device type, such as Windows, in Intune. Configuration profiles for other device types are done in a similar fashion. For reference, Microsoft provides the following useful guides:

Create and assign SCEP certificate profiles in Intune

https://docs.microsoft.com/en-us/mem/intune/protect/certificates-profile-scep

Configure and use PKCS certificates with Intune

https://docs.microsoft.com/en-us/mem/intune/protect/certificates-pfx-configure

Windows Device Configuration Profile

The first step is to create a “Trusted certificate” configuration profile for Windows devices with the following properties:

Upload certificate file from your own implemented CA (e.g. AD CS).

The next step is to create a “SCEP certificate” configuration profile for Windows devices with the following properties:

The configurations settings for this profile are as follows:

It is important to reference the Device ID in the Subject alternative name.

The Root certificate refers back to the “Trusted certificate” profile done in the first step.

When the endpoint authenticates with ClearPass, the Access Tracker details can be inspected to ensure that the Device ID is present in the SAN URI attribute of the certificate as shown below:

If a real-time query is being implemented via HTTP authorization source, make sure to reference the Subject alternative name URI attribute in the filter query as shown in Figure 27.

Appendix G – Permissions needed for the Entra ID Application

The complete list of permissions required by the Entra Application for Intune integration is listed below:

GroupMember.Read.All

Directory.Read.All

User.Read.All

Device.Read.All

DeviceManagementManagedDevices.ReadWrite.All (Post Auth)

DeviceManagementManagedDevices.PrivilegedOperations.All (Post Auth)

DeviceManagementManagedDevices.Read.All

INFO

Note that depending upon your use case and workflows, you might only need a subset of these permissions. The table listed below breaks down the permissions required by different use cases. Please enable only the ones required in your setup.

Use Case	Usage	Permission	URL
Fetch Intune user group membership	config.enableUserGroups GET '/groupsByMac/:mac' GET '/groupsByUserId/:userId'	GroupMember.Read.All	https://learn.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0&tabs=http
Real time call to fetch Intune user group membership	GET '/realtimeGroupsByUserId/:userId' GET '/realtimeGroupsByMac/:mac' GET '/realtimeUserGroup/:macOrSanUri'	Directory.Read.All	https://learn.microsoft.com/en-us/graph/api/user-list-memberof?view=graph-rest-1.0&tabs=http
Real time call to fetch Intune user transitive group membership	GET '/realtimeTransitiveGroupsByUserId/:userIdOrSanUri'	User.Read.All	https://learn.microsoft.com/en-us/graph/api/user-list-transitivememberof?view=graph-rest-1.0&tabs=http
Real time call to fetch Intune user group membership	GET /realtimeGroupsById/:id	Device.Read.All	https://learn.microsoft.com/en-us/graph/api/device-list-memberof?view=graph-rest-1.0&tabs=http
Real time call to fetch Intune device group membership	GET '/realtimeDeviceGroup/:sanUri' GET '/realtimeGroupsByDeviceId/:deviceId'	Device.Read.All	https://learn.microsoft.com/en-us/graph/api/device-list-memberof?view=graph-rest-1.0&tabs=http
Real time call to fetch Intune device transitive group membership	GET '/realtimeTransitiveGroupsById/:id'	Device.Read.All	https://learn.microsoft.com/en-us/graph/api/device-list-transitivememberof?view=graph-rest-1.0&tabs=http
Real time call to fetch Intune device transitive group membership	GET '/realtimeTransitiveGroupsByDeviceId/:deviceId' GET '/realtimeTransitiveDeviceGroup/:sanUri'	Device.Read.All	https://learn.microsoft.com/en-us/graph/api/device-list-transitivememberof?view=graph-rest-1.0&tabs=http
Trigger action from ClearPass to Intune	POST '/device/sync/:macOrSanUri' POST '/device/shutDown/:macOrSanUri' POST '/device/wipe/:macOrSanUri' POST '/device/remoteLock/:macOrSanUri'	DeviceManagementManagedDevices.ReadWrite.All DeviceManagementManagedDevices.PrivilegedOperations.All	https://learn.microsoft.com/en-us/graph/api/intune-devices-manageddevice-get?view=graph-rest-1.0&tabs=http
Trigger action from ClearPass to Intune	POST '/device/update/:macOrSanUri'	DeviceManagementManagedDevices.ReadWrite.All	https://learn.microsoft.com/en-us/graph/api/intune-devices-manageddevice-update?view=graph-rest-1.0&tabs=http
Fetch information about a specific device from Intune	GET '/realtimeTransitiveDeviceGroup/:sanUri' GET '/realtimeDeviceGroup/:sanUri' GET '/device/info/:mac' GET '/device/info/id/:managedDeviceIdOrSanUri'	DeviceManagementManagedDevices.Read.All	https://learn.microsoft.com/en-us/graph/api/intune-devices-manageddevice-get?view=graph-rest-1.0&tabs=http
Fetch information about a specific device from Intune using Entra Device ID	GET '/device/info/:mac' GET '/device/info/id/:managedDeviceIdOrSanUri'	DeviceManagementManagedDevices.Read.All	https://learn.microsoft.com/en-us/graph/api/intune-devices-manageddevice-list?view=graph-rest-1.0
Fetch list of devices periodically	config.enableSyncAll GET '/realtimeManagedDevices'	DeviceManagementManagedDevices.Read.All	https://learn.microsoft.com/en-us/graph/api/intune-devices-manageddevice-list?view=graph-rest-1.0
Fetch list of devices periodically	GET '/realtimeDevices'	Device.Read.All	https://learn.microsoft.com/en-us/graph/api/device-list?view=graph-rest-1.0&tabs=http

4.1 - ClearPass Onboard Enrollment using Microsoft Intune SCEP Extension

Introduction

The Intune-SCEP Extension for Onboard Enrollment enables seamless certificate provisioning for devices managed by Microsoft Intune by integrating ClearPass Onboard as the SCEP server and certificate authority (CA). In this deployment model, Microsoft Intune validates certificate enrollment requests from managed endpoints, while ClearPass Onboard issues and manages the certificates used for secure authentication to enterprise resources.

This integration allows organizations to automate certificate enrollment for Intune-managed devices and leverage certificate-based authentication for services such as Wi-Fi, VPN, and network access control. By combining Microsoft Intune’s device management capabilities with ClearPass Onboard’s PKI and certificate lifecycle management, organizations can deliver a scalable and secure onboarding experience across supported device platforms.

This document provides the configuration and deployment steps required to install the Intune-SCEP Extension, integrate it with Microsoft Entra ID and Microsoft Intune, configure ClearPass Onboard for external SCEP validation, and verify successful certificate enrollment and operation.

Pictorial View of the Integration

Deployment Workflow

The deployment of the Intune-SCEP Extension for Onboard enrollment consists of the following high-level steps:

Create and register an application in Microsoft Entra ID with the required API permissions.
Install and configure the Intune-SCEP Extension in ClearPass Guest.
Configure the ClearPass Onboard Certificate Authority (CA) for SCEP enrollment and external validation.
Create Microsoft Intune device profiles for the target operating systems.
Create Wi-Fi Profile to connect to the network using the obtained certificate through SCEP.
Verify successful integration and certificate enrollment in both ClearPass and Intune.

Creating and Registering an application in Microsoft Entra ID

Once logged in, open “Entra ID” and select “App Registrations”. In “App Registrations”, click on “New registration” menu. Provide a name to identify this application, something like “ClearPass Intune Integration”. Use all the default values when defining the new application, click on ‘Register’.

After clicking on Register, in the next screen for the application previously created, record the clientId and the tenantdID as highlighted below. Record these values, as they will be required later to complete the Extension configuration.

Next the permissions must be configured for the new application. To the left on the navigation tree, click on ‘API permissions’ followed by ‘Add a Permission’

Next, click on ‘Microsoft Graph > Application permission’, add the permissions listed below. Next click on ‘Intune > Application permission’ and ‘Delegated permission’ as required and add the permissions listed below.

API permissions for the registered application

At this stage, all permissions should be added but will appear as"Not granted for…" until admin consent is granted. Click on ‘Grant admin consent for XXX’

Confirm on the request for granting consent for the requested permissions.

Ensure you see a successful confirmation of this process, as the below two screen images indicate.

Before you leave this screen, Record the client-secret shown below as this is also required to complete the configuration of the Intune extension.

Installing and Configuring Intune-SCEP extension for Onboard Enrollment

In ClearPass Guest, navigate to Administration > Extensions and click Install Extension. The list of available extensions is displayed, along with a Search field.
Type Intune SCEP in the search text box field and click Search.
Select the Intune SCEP extension from the results to see the install option.

Extension Installation
Click Install. The installation form displays the extension details and the available startup and network configuration options.
Leave the IP Address field blank to allow ClearPass to automatically assign an available IPv4 address based on the extension network configuration unless you have a designated IP address scope for extensions.
Click Install to complete the installation.

Verify that the extension appears in the Manage Extensions list.

In the Manage Extensions view, select the extension and click Configuration. The Extension Configuration form is displayed.
From the Microsoft Entra ID portal, open the application created earlier for this integration and obtain the values for azureApplicationId (client ID), azureApplicationKey (client secret), and tenantId and use them in the extension configuration form.
Click Save Changes to apply the configuration. You can choose to start the extension now or later once the Intune and ClearPass Onboard configurations are done.

Extension Configuration

Configure the Certificate Authority for External SCEP Validation

After installing and configuring the extension, configure the certificate authority (CA) to use external SCEP validation.

In ClearPass Guest, navigate to Onboard > Certificate Authorities, Create a new certificate authority as required or select Local Certificate Authority, and click Edit.

Configure CA for External SCEP validation
In the Certificate Authority Settings form, enable the SCEP Server option. Additional SCEP configuration settings are displayed.
From the SCEP Validation drop-down list, select External Validator. Choose the Intune SCEP extension installed earlier as the External SCEP Validator.
Save the configuration to apply the changes and enable external SCEP validation through the extension.

Configure CA for External SCEP validation

Creating Microsoft Intune device profiles for the target operating systems.

Create two profiles for each platform — a trusted certificate profile and a SCEP certificate profile.

Log in to Intune using your credentials and then go to Devices > Manage Devices > Configuration.

Creating device profiles
Click Create New Policy, and then select the appropriate operating system in the Platform drop-down list.

Creating device profiles

Creating Trusted Certificate Profiles

Select the target platform from the Platform drop-down list. Here, Andriod enterprise is used as an example.
From the Profile type drop-down list, select the appropriate Trusted certificate profile for the selected platform and enrollment scenario.

Creating Trusted certificate profiles
Click Create.

Creating Trusted certificate profiles
For each trusted certificate, enter a Name and Description in the Basics area.
For each trusted certificate, to complete the Certificate file field within the Configuration settings area, browse to the signing CA / Intermediate CA and add it to the trusted certificate profile.
To export the CA certificate to be imported to device profiles in Intune, navigate to ClearPass Onboard > Certificate Authorities > and select Certificate Authority > Trust Chain.

Exporting ClearPass Onboard Trust Chain
Select Download Bundle option to advance to the next page.

Exporting ClearPass Onboard Trust Chain
Export the certificate in .crt format.

Exporting ClearPass Onboard Trust Chain

Repeat these steps for each platform. Examples for each platform are given below.

Andriod Trusted Certificate

iOS Trusted Certificate

macOS Trusted Certificate

Windows Trusted Certificate

Creating SCEP Certificate Profiles

Select the target platform from the Platform drop-down list. Here, Andriod enterprise is used as an example.
From the Profile type drop-down list, select the SCEP certificate profile for the selected platform and enrollment scenario.
Click Create.
For each SCEP certificate, enter a Name and Description.
For each SCEP certificate, complete the Certificate type, Subject name format, and Subject alternative name fields in the Configuration settings area.

Repeat these steps for each platform type. Sample SCEP certificate profile configurations for supported platforms are shown below.

Android SCEP Certificate Profile

iOS SCEP Certificate Profile

macOS SCEP Certificate Profile

Windows SCEP Certificate Profile

Creating Wi-Fi profile to connect to the network using the certificate obtained through ClearPass Onboard

Finally, create a Wi-Fi profile that uses the client certificate obtained through SCEP enrollment to connect to the network. The sample configuration shows how to configure a Wi-Fi profile for Windows devices.

For Certificate server names, either leave the field blank or specify the server name configured for EAP-TLS authentication. Select the trusted root certificate profile that was created earlier and associate the SCEP certificate profile used to provision client certificates.

INFO

This is a sample Wi‑Fi profile configuration. Similar profiles can also be created for other connection types, such as wired, VPN, or other certificate-based access methods, depending on organizational requirements. The specific profile settings and deployment options may vary depending on the use case and platform.

Verify successful integration and certificate enrollment in both ClearPass and Intune

After completing the preceding configuration steps, validate the deployment by enrolling a device into Intune.

You can validate the deployment by enrolling a device into Intune. During enrollment, Intune applies the configured device and certificate policies, which trigger the device to submit a certificate request to ClearPass Onboard using SCEP. The ClearPass Onboard CA forwards the validation request to the Intune-SCEP Extension, which verifies the device and enrollment information against Intune. Upon successful validation, the CA issues the certificate, enabling the device for certificate-based authentication or other access workflows.

In ClearPass Guest, navigate to Administration > Support > Application Log. If the deployment is successful, the following information is displayed.

In ClearPass Guest, navigate to Administration > Extensions, select the extension, and click Show Logs. The extension logs are displayed. If the extension log level is set to Debug, the logs include validation request and successful validation entries similar to the following examples.

In the Intune admin console navigate to the appropriate SCEP certificate profile. It should display the deployment status as either “Succeeded” or “Failed.”

Intune Profile Deployment Status

5 - VMware Workspace ONE (Airwatch)

Workspace ONE, formerly known as VMware Airwatch is the unified digital Workspace platform that simplifies and secures app access and IT management for the modern workforce.

Introduction and Overview

With the extension-based integration we receive information associated with the endpoints in real time rather than relying on a poll interval like how we used to integrate with Vmware Workspace ONE earlier using Endpoint Context Servers. Hence, upon device enrollment/unenrollment, Workspace ONE triggers a webhook which will be consumed by a ClearPass service running in the cloud. The extension installed within ClearPass for this integration maintains a persistent connection with this service and immediately writes the updated information in the ClearPass endpoint repository. This integration is an enhancement that leverages an extension. The events for which the real time updates can be sent via webhook are configurable in Workspace ONE. Following are a list of the events we support today.

Device enrollment
Device unenrolled/ Enterprise wipe
Device compromised/ Status changed
Device Delete

To summarize, the endpoint repository continues to be used as an Authorization source, but the information is updated in real time hence allowing an administrator to create more accurate policies. Without integration with the extension, ClearPass would only get the latest information based on the polling interval. The default value of this polling interval is 60 minutes. It could be set to a lower value {under guidance from HPE Aruba Networking} depending on the number of endpoints to be fetched and varies based on the environments.

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. Updates are done with backwards compatibility in mind and any breaking changes would be called out in this tech note. Extensions are validated against the latest instance of Workspace ONE and unless explicitly noted here, should be compatible with all supported Workspace ONE releases.

What’s new in Workspace ONE v6.6 Extension? – Important Changes

Workspace ONE release v6.6.0 adds support for OAuth 2.0 in addition to the previous API key based approach. Workspace ONE extension now supports using OAuth 2.0 client credentials for API authentication.

Three additional extension configuration attributes have been added to support OAuth: clientId, clientSecret and tokenEndpoint. Details about configuring OAuth credentials both on Workspace ONE and ClearPass extension is documented under the respective configuration sections below.

INFO

Note that the airWatchApiKey and OAuth credentials are both supported. If both user credentials (airWatchUser and Password) and OAuth credentials are given, OAuth credentials would be used.

What’s new in Workspace ONE v6 Extension? – Important Changes

Workspace ONE release v6.2.0 supports an additional knob in the extension configuration called “airWatchExtensiveSearch” which if set to true makes use of the /extensivesearch API replacing the default /search API call during the periodic polls. When set to false the default /search API is used for the periodic polls.

Some environments require both wired and wireless mac addresses in the ClearPass endpoint repository for endpoints which use both the NICs and tend to switch from wireless to wired and vice-versa. The expectation is that both the interfaces are authenticated before allowing access to the network. In such cases it is necessary that both the interface mac addresses are available in the ClearPass endpoint repository to be able to check for the attributes when evaluating policies for the endpoint to allow the right access.

Addition of this configuration knob solves this problem however one should be mindful that setting “airWatchExtensiveSearch” to true fetches limited number of attributes to work from for an endpoint and can be a limitation for few environments though the attributes which are missed by enabling this configuration knob are not very widely used. This is currently a limitation on Workspace ONE API’s and once /search is worked upon or any new API is introduced to add both the mac addresses with the most complete information returned as attributes then we will implement it on our side which will eliminate the need to choose from enabling or disabling airWatchExtensiveSearch.

A copy of attributes fetched when “airWatchExtensiveSearch” is set to true and a copy of attributes fetched when “airWatchExtensiveSearch” is set to false is given in Appendix D.

INFO

Extension upgrade from the ClearPass Guest UI retains the configuration for minor version upgrades. However, it does not incorporate any new configuration fields added to the new version. Therefore, new fields like “airWatchExtensiveSearch”: true, will need to be added manually in the config.

With the release of Workspace ONE v6.1.0 we now support authenticated webhooks hitting ClearPass from a customer’s tenant. This eliminates the risk of any unauthorized webhook event being processed by ClearPass. Workspace ONE now supports sending authenticated webhook events by introducing a username and password field in the event notification section. This means that every webhook event sent by Workspace ONE is hashed using these configured credentials and ClearPass would be able to decrypt the webhook events when it has the same credentials configured in the extension as shown below.

Any webhook event which does not include the authentication header from Workspace ONE will not be processed by ClearPass if the extension is configured with a username and password. ClearPass would also not process any events from Workspace One when there is a mismatch in the configured username and password on Workspace ONE and ClearPass extension.

The following are the two config knobs that needs to be added in the extension (not available in the default config setting) to support authenticated webhook events from Workspace ONE.

“skyhookAuthorizationUsername”:

“skyhookAuthorizationPassword”:

Sample extension configuration with the new skyhook credential attributes:

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“skyhookTenant”: “”,

“skyhookAuthorizationUsername”: “”,

“skyhookAuthorizationPassword”: “********”,

“dbAccessToken”: “********”,

“airWatchHost”: “”,

“airWatchUser”: “”,

“airWatchPassword”: “********”,

“airWatchApiKey”: “********”,

“clientId”: “abacxxxxxxxxxxxxxxxxxxxxx”,

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

“tokenEndpoint”: “https://na.uemauth.workspaceone.com/connect/token",

“airWatchExtensiveSearch”: false,

“enrollmentRetries”: 3,

“enrollmentWaitTimer”: 5,

“toggleEndpointStatus”: false,

“enableOutOfComplianceDisconnect”: false,

“enableOutOfComplianceReconnect”: false,

“enableCompromisedDisconnect”: false,

“enableCompromisedReconnect”: false,

“enableEndpointCache”: false,

“endpointCacheTimeSeconds”: 300,

“syncAllOnStart”: false,

“enableSyncAll”: false,

“syncAllSchedule”: “*/15 * * * *”,

“syncUpdatedOnly”: true,

“syncPageSize”: 50,

“includeSecurityInfo”: false,

“attributePrefix”: “”,

“bypassProxy”: false,

“enableStats”: false,

“statsUsername”: “”,

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

“skyhookAuthorizationUsername”: “testuser”,

“skyhookAuthorizationPassword”: “********"

}

Adding username password for authenticated webhook event notification in Workspace ONE

To address “Android 12 Day Zero Support with Microsoft Endpoint Manager“ like hurdles and be prepared for client vendors restricting MDMs from reading the MAC address from the clients and any upcoming compliance requirements to use certificate-based authentication and expose endpoint information only based on some MDM specific attributes unlike MAC address and serial numbers, we have also added the support to able to query endpoint information from Workspace ONE using the Device UDID attribute.

This is achieved by adding a real time HTTP AuthZ source which reads the Device UDID attribute from the certificate passed during the EAP-TLS authentication and fetches the endpoint attributes from Workspace ONE in real time. For endpoints which don’t reveal their MAC addresses the extension would not be able to sync those endpoints as they wouldn’t have a valid MAC address to add in the endpoint repository. Hence, using certificate-based authentication with Device UDID as the certificate CN name is the workaround for devices which does reveal their MAC addresses.

With the real time HTTP AuthZ source added to the ClearPass service addresses this caveat and we can fetch the attributes from Workspace ONE to be able to evaluate them in the ClearPass enforcement policies and Role Mappings. We will see some more details and sample configuration later in this document.

Pictorial View of the Integration

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

Pictorial view of ClearPass Policy Manager integration with VMware Workspace ONE

Software Requirements

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

Installing Extension

INFO

Access to the extension store

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.

INFO

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

Extensions and web proxy support

INFO

Extensions and IP address configuration support

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

INFO

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

Configuration Steps

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

Register and request for a Skyhook tenant
Configuration of VMware Workspace ONE for Integration
Installation and Configuration of the Workspace ONE extension using the GUI in ClearPass.

Register for a Skyhook Tenant ID

Kindly copy the skyhookTenant, dbAccessToken and the Target 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 on Workspace ONE UEM.

Configuring Workspace ONE for ClearPass Integration

INFO

Setup and configuration of Workspace ONE UEM is beyond the scope of this guide. Here we specify the steps necessary to configure the integration.

Below are the configuration steps to follow.

Getting API Credentials

Create a new administrator account for this integration.

Navigate to Accounts > Administrator > List View > Add > Add Admin.

Specify the mandatory fields below and create a user. It is not recommended to use the default admin account for this integration for security reasons.

When creating this user, one can specify the role associated with the user. Use “Device Manager” role or any custom role that gives device information access via the REST API.

The credentials of the account created can be used as “airwatchUser” and “airwatchPassword” in the ClearPass extension configuration.

Getting REST API key

Go to “Groups & Settings” > All Settings.

Navigate to System > Advanced > API > REST API.

To add a new API service.

Select “Override” as the Current Setting.
Set “Enable API Access” to “Enabled**”**.
Click on +ADD box to add a new service account. This should generate the API Key.
1. Set the Service name to something that can be identified later like “ClearPass Extension**”**.
2. Set the Account Type to “Admin**”**.
3. Copy the API Key. This will be used as “airwatchApiKey” for the ClearPass extension configuration.
Ensure you Save your changes.

Configuring OAuth 2.0

Extension version 6.6.0 introduces support for OAuth 2.0 for API authentication. First we need to create an admin role that provides read access to the API client.

On Workspace ONE, navigate to Accounts > Administrators > Admin Roles > Add Role

Enable “read” access to the following:

API > REST Device Management > Compliance Device Management > Device Details Device Management > Devices List View Groups

Next, to create OAuth 2.0 credentials, navigate to Groups&Settings > Configurations > OAuth Client Management > Add and register a new OAuth client referencing the Role that was created previously

Upon saving the this, the OAuth Client ID and secret would be displayed. Store them somewhere safe since the credentials cannot be viewed again later.

These credentials now can be used within the extension configuration as described in the extension configuration section.

Also make a note of the base URL for UEM token service for each environment as shown below. This is also required in the extension configuration.

Configuring Event Notifications

Go to “Groups & Settings” > All Settings.

Navigate to System > Advanced > API > Event Notifications.

Click on + ADD RULE to add the events that the ClearPass skyhook needs to be notified for.

The Event Notification window helps to specify the Target Name and the Target URL. The Target URL contains the skyhook tenant that was granted to you at the time of the request in “Step I: Register and Request for a Skyhook Tenant ID**”**. The email received should consist of the Target URL to be used.

The Username and Password field could be left blank. However, for secure and authenticated webhook events from Workspace ONE to ClearPass a username and password should be configured at both ends (ClearPass and Workspace ONE). Username and password at both sides should be same so that events hashed using the username and password on Workspace ONE can be decrypted by the ClearPass extension.

Select the Format as JSON.

INFO

The attempt to “TEST CONNECTION” will be unsuccessful in this scenario.

Finally, scroll down under the “Events” section and specify the events for which we require a real time update from Workspace ONE.

Currently ClearPass has added support for the following events.

Device Enrollment
Device Unenrolled Enterprise Wipe
Device Wipe
Device Compromised Status Change
Device Compliance Status Change
Device Delete
Device Attribute Change - Ownership

These are essentially the events which are leveraged within ClearPass Policy Manager to define policies and hence requires a real time update for accurate policy enforcement.

Once the required events are Enabled, Save the changes.

Workspace ONE Extension Configuration

The default configuration used for the extension is below

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“skyhookTenant”: “”,

“skyhookAuthorizationUsername”: “”,

“skyhookAuthorizationPassword”: “********”,

“dbAccessToken”: “********”,

“airWatchHost”: “”,

“airWatchUser”: “”,

“airWatchPassword”: “********”,

“airWatchApiKey”: “********”,

“clientId”: “abacxxxxxxxxxxxxxxxxxxxxx”,

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

“tokenEndpoint”: “https://na.uemauth.workspaceone.com/connect/token",

“airWatchExtensiveSearch”: false,

“enrollmentRetries”: 3,

“enrollmentWaitTimer”: 5,

“toggleEndpointStatus”: false,

“enableOutOfComplianceDisconnect”: false,

“enableOutOfComplianceReconnect”: false,

“enableCompromisedDisconnect”: false,

“enableCompromisedReconnect”: false,

“enableEndpointCache”: false,

“endpointCacheTimeSeconds”: 300,

“syncAllOnStart”: false,

“enableSyncAll”: false,

“syncAllSchedule”: “*/15 * * * *”,

“syncUpdatedOnly”: true,

“syncPageSize”: 50,

“includeSecurityInfo”: false,

“attributePrefix”: “”,

“bypassProxy”: false,

“enableStats”: false,

“statsUsername”: “”,

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

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

Workspace ONE specific extension configuration attributes

Configuration attribute	Description	Default Values
includeSecurityInfo	Not supported as of 6.0.2. Planned for later releases.	NA
skyhookTenant	The Skyhook tenant ID received in the registration email.	Null
dbAccessToken	The access token for Skyhook received in the registration email.	Null
airWatchHost	The URL/FQDN for Workspace ONE instance	Null
airWatchUser	The Workspace ONE account username who has access to the device information using the APIs.	Null
airWatchPassword	The Workspace ONE account password for the user who has access to the device information using the APIs.	Null
airWatchApiKey	Allows access to Workspace ONE REST APIs.	Null
clientId	OAuth Client ID	Null
clientSecret	OAuth Client Secret	Null
tokenEndpoint	Value of this field is derived from the UEM token service base URL as {base-url}/connect/token	Null
airWatchExtensiveSearch	Fetches both wired and wireless mac address of an endpoint if set to true	false
enrollmentRetries	During the enrollment process, if there is no MAC Address found, retry X number of times to wait for a MAC Address.	3
enrollmentWaitTimer	The delay between retries when attempting to get a MAC Address.	5
toggleEndpointStatus	When a device is unenrolled, if set to true, the endpoints status will be set to "Unknown".	false
enableOutOfComplianceDisconnect	When true and “Compliance Status Changed” event is received with state “non-compliant” active session disconnect is issued to the endpoint if exists in ClearPass	false
enableOutOfComplianceReconnect	When true and “Compliance Status Changed” event is received with state “Complaint” active session disconnect is issued to the endpoint if exists in ClearPass	false
attributePrefix	Add prefix to endpoint attributes to be able to identify attributes synced from two parallel extension instances.	Null
enableCompromisedDisconnect	When true and “Compromised Status Changed” event is received with state “false” active session disconnect is issued to the endpoint if exists in ClearPass	false
enableCompromisedReconnect	When true and “Compromised Status Changed” event is received with state “true” active session disconnect is issued to the endpoint if exists in ClearPass	false

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

A copy of the VMware Workspace ONE Extension with the desired configuration is shown below, this has to be modified for your deployment. Include the skyhookTenant, dbAccessToken, airwatchHost, airwatchApiKey, airwatchUser, airwatchPassword 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 states that the extension has established a successful connection to skyhook and ready to ingest events from Workspace ONE in real time.

Sample Events

In this section we look at some sample events. The logs have been enabled in DEBUG mode for details.

Device Registration

As soon as a device enrolls with Workspace ONE, it triggers a webhook which is consumed by ClearPass using extensions. In this scenario the Event Type triggered is ‘Enrollment Complete’.

Once the extension gets the device ID using webhook, it will trigger an API call into Workspace ONE to get all details associated with the device since the webhook triggered does not send all the details. These details are then copied into the endpoint database in ClearPass.

[2022-08-08T10:10:39.355] [INFO] WorkspaceONE - New event received -N8ww1-fB5v8oNlvVKKP.

[2022-08-08T10:10:39.381] [DEBUG] WorkspaceONE - Event Details: {“body”:{“EventId”:170,"EventType”:“Enrollment Complete”,“DeviceId”:37971,“DeviceFriendlyName”:“Android_BND-AL10_866676030046304”,“EnrollmentEmailAddress”:“bikki.gupta@nacsecurity.com”,“EnrollmentUserName”:“bikki”,“EventTime”:“2022-08-08T10:11:22.7859476Z”,“EnrollmentStatus”:“Enrolled”,“CompromisedStatus”:””,“CompromisedTimeStamp”:“2022-08-08T10:11:24.5384903Z”,“ComplianceStatus”:“PendingComplianceCheck”,“PhoneNumber”:"",“Udid”:“6780aead7ae0df2c298c6dd8da3a9dc3796894d59f”,“SerialNumber”:“P2L4C17B14003317”,“MACAddress”:“1044008DB104”,“DeviceIMEI”:“866676030046304”,“EnrollmentUserId”:84707,“AssetNumber”:“6780aead7ae0df2c298c6dd8da3a9dc3796894d59f”,“Platform”:“Android”,“OperatingSystem”:“9.0.0”,“Ownership”:“EmployeeOwned”,“SIMMCC”:"",“CurrentMCC”:"",“OrganizationGroupName”:“HPE Aruba Networking”,“DeviceUUID”:“90b60c2b-5e1b-4646-b5fc-6c27a8d03469”,“EnrollmentUserUUID”:“7d9222d6-0fa1-44e6-b205-8d9415f111a6”}

Compliance Status Change

This event is triggered immediately after a device is enrolled and performs its first compliance check. It is also triggered if Workspace One detects a change in the compliance status of the device. Again, the webhook sends us the Device ID which is used by the extension to trigger an API call on Workspace ONE and get more information about the device. Once the device lookup is completed, the extension writes the attributes into the ClearPass endpoint repository.

[2022-08-08T10:16:23.912] [INFO] WorkspaceONE - New event received -N8wxL7kBfy8abbqcy0F.

[2022-08-08T10:16:23.940] [DEBUG] WorkspaceONE - Event Details: {“body”:{“EventId”:184,“EventType”:“Compliance Status Changed”,“DeviceId”:37971,“DeviceFriendlyName”:“Android_BND-AL10_866676030046304”,“EnrollmentEmailAddress”:“bikki.gupta@nacsecurity.com”,“EnrollmentUserName”:“bikki”,“EventTime”:“2022-08-08T10:17:08.4541214Z”,“EnrollmentStatus”:“Enrolled”,“CompromisedStatus”:"",“CompromisedTimeStamp”:“2022-08-08T10:17:08.9987884Z”,“ComplianceStatus”:“NonCompliant”,“PhoneNumber”:"",“Udid”:“6780aead7ae0df2c298c6dd8da3a9dc3796894d59f”,“SerialNumber”:“P2L4C17B14003317”,“MACAddress”:“1044008DB104”,“DeviceIMEI”:“866676030046304”,“EnrollmentUserId”:84707,“AssetNumber”:“6780aead7ae0df2c298c6dd8da3a9dc3796894d59f”,“Platform”:“Android”,“OperatingSystem”:“9.0.0”,“Ownership”:“EmployeeOwned”,“SIMMCC”:"",“CurrentMCC”:"",“OrganizationGroupName”:“HPE Aruba Networking”,“DeviceUUID”:“90b60c2b-5e1b-4646-b5fc-6c27a8d03469”,“EnrollmentUserUUID”:“7d9222d6-0fa1-44e6-b205-8d9415f111a6”}

Once the compliance check on the device is finished, the endpoint table on ClearPass gets updated with the device information as shown below

MDM Unenroll

Once the Device Management profile is deleted from the managed endpoint, it would trigger a webhook for the event type captured below.

[2022-08-08T10:46:19.457] [INFO] WorkspaceONE - New event received -N8x3BW3pJCnSFA2VfAV.

[2022-08-08T10:46:19.483] [DEBUG] WorkspaceONE - Event Details: {“body”:{“EventId”:39,"EventType":“Break MDM Confirmed”,“DeviceId”:37971,“DeviceFriendlyName”:“Android_BND-AL10_866676030046304”,“EnrollmentEmailAddress”:"",“EnrollmentUserName”:"",“EventTime”:“2022-08-08T10:47:05.8870115Z”,“EnrollmentStatus”:“Unenrolled”,“CompromisedStatus”:"",“CompromisedTimeStamp”:“2022-08-08T10:47:06.7020299Z”,“ComplianceStatus”:“NotAvailable”,“PhoneNumber”:"",“Udid”:“6780aead7ae0df2c298c6dd8da3a9dc3796894d59f”,“SerialNumber”:“P2L4C17B14003317”,“MACAddress”:“1044008DB104”,“DeviceIMEI”:“866676030046304”,“EnrollmentUserId”:0,“AssetNumber”:“6780aead7ae0df2c298c6dd8da3a9dc3796894d59f”,“Platform”:“Android”,“OperatingSystem”:“9.0.0”,“Ownership”:“EmployeeOwned”,“SIMMCC”:"",“CurrentMCC”:"",“OrganizationGroupName”:“HPE Aruba Networking”,“DeviceUUID”:“90b60c2b-5e1b-4646-b5fc-6c27a8d03469”,“EnrollmentUserUUID”:""}

This results in change of the attribute ‘MDM Enabled’ to ‘false’. ‘Let’s look at the attributes changed for the endpoint in the endpoint database.

The above attributes can be used in the ClearPass Policy Manager to ensure devices with “MDM Enabled = false” are either quarantined, or forced into a captive portal role or denied access.

Device Deletion

In this scenario, a device that was added previously by polling was deleted from Workspace ONE. This triggered a “Delete Device Requested” event.

[2022-08-08T10:39:54.674] [INFO] WorkspaceONE - New event received -N8x1iZIl4iM6fukq4PM.

[2022-08-08T10:39:54.702] [DEBUG] WorkspaceONE - Event Details: {“body”:{“EventId”:662,“EventType”:“Delete Device Requested”,“DeviceId”:37899,“DeviceFriendlyName”:“BGHOME”,“EnrollmentEmailAddress”:“bikki.gupta@nacsecurity.com”,“EnrollmentUserName”:“bikki”,“EventTime”:“2022-08-08T10:40:39.2698451Z”,“EnrollmentStatus”:“Unknown”,“CompromisedStatus”:null,“CompromisedTimeStamp”:“0001-01-01T00:00:00”,“ComplianceStatus”:null,“PhoneNumber”:null,“Udid”:“8D667CAA15ACCD48B785A104031DE3A0”,“SerialNumber”:“M4N0CX12R927169”,“MACAddress”:null,“DeviceIMEI”:null,“EnrollmentUserId”:0,“AssetNumber”:"",“Platform”:null,“OperatingSystem”:null,“Ownership”:null,“SIMMCC”:null,“CurrentMCC”:null,“OrganizationGroupName”:null,“DeviceUUID”:"",“EnrollmentUserUUID”:""},“headers”:{“x-aw-event-version”:“1”,“X-Clearpass-SourceIp”:“44.231.1.105”}}

This again results in change of the attribute “MDM Enabled” to false. Starting with V2 of the WorskspaceOne Extension a device deletion will also toggle the Known/Unknown status of the endpoint, the allows for ClearPass housekeeping to remove devices from the EndpointDb. This is an optional configuration switch.

Toggle Known to Unknown on delete action

A sample Enforcement Policy that can be used is shown here for reference. This may completely vary based upon the requirements of the customer.

Real Time Authorization Lookup

As discussed in the “What’s new in Workspace ONE v6 Extension” section of the document we can leverage the HTTP AuthZ source to fetch endpoint attributes from Workspace ONE using the extension in real time. Due to restrictions on the client side where the MAC address is not exposed to the MDM and the extension is not able to sync these endpoints to the endpoint repository, this is an alternate way to fetch the endpoint attributes which are used in the enforcement policy to assign the right roles as per the MDM assigned attributes to the endpoints.

However, this method is not just limited to one use case. As discussed earlier if there are any compliance requirements from MDM in the future to use certificate-based authentication and expose endpoint information only based on some MDM specific attributes (unlike MAC address and serial numbers) then we can also use this method to fetch attributes from Workspace ONE using the Device UDID attribute. This attribute can be injected in the CN field of the certificate using the certificate request templates in Workspace ONE. The extension supports querying endpoints to Workspace ONE using either MAC address or the Device UDID attribute.

Step I: Certificate template configuration

Configuring the Workspace ONE certificate template to use Device UDID in CN name field of the certificate when requesting certificate to the SCEP server.

Go to Group & Settings > All Settings > Enterprise Integration > Certificate Authorities and click Add.

Choose the applicable Authority type and fill in rest of all the mandatory fields and click Save. In this example we have used ClearPass Onboard CA as the SCEP server so the selection for Authority Type in this case is “Generic SCEP. For details on Certificate Authorities and Request templates refer ‘Certificate Authority Integrations’ in VMware Workspace ONE UEM Product Documentation.

https://docs.vmware.com/en/VMware-Workspace-ONE-UEM/services/Certificate_Authority_Integrations/GUID-Certificate_Authority_Integrations_intro.html

Next, go to Group & Settings > All Settings > Enterprise Integration > Certificate Authorities> Request Templates and click Add.

Set the Certificate Authority from the drop down created in the last step. Set the Subject Name to be CN={DeviceUid} as shown below and fill in the rest of the mandatory fields and click on Save.

Step II: Enabling SCEP server in ClearPass Onboard CA.

INFO

This step is optional and is required only if ClearPass is used as a SCEP server for enrolling clients

For enabling SCEP server on the Onboard CA Login to the Onboard module from ClearPass Login Page. Go to Onboard > Certificate Authority > Create a new certificate Authority or edit an existing one if you would like to use an existing Certificate Authority.

Under the SCEP Server select the “Enable access to the SCEP server” check box. Type a SCEP Secret and click on Save Changes.

The shown SCEP URL will need to be entered in the ‘SCEP URL’ field and SCEP Secret in the ‘Static Challenge’ field with challenge type set to Static while adding the Certificate Authority in Workspace ONE if ClearPass Onboard CA is used as the SCEP server.

For more details on Onboard CA Authorities and enabling SCEP refer the ClearPass documentation.

https://arubanetworking.hpe.com/techdocs/ClearPass/6.10/Guest/Content/Onboard/SettingUpCertificateAuthority.htm

Step III: Adding HTTP AuthZ source in ClearPass

Go to Configuration > Authentication > Sources and Click Add.

Give a name to the Auth source, Select ‘HTTP’ from Type dropdown and click Next.

This will advance to the Primary Tab which requires connection details. Here an internal POST is made to the extension. The extension then calls Workspace ONE APIs to fetch the attributes associated with the endpoint.

The Base URL is http://<Extension IP>/. The extension IP can be seen by going to the Guest module under Administration > Aruba Integrations > Extensions.

Enter the Workspace ONE extension IP address in the Base URL field and click Next.

Under the attributes tab, Click on Add more Filters.

Enter the Filter Name and Filter Query as shown in the below figure. We had earlier configured the Workspace ONE certificate request template to use Device UDID in the CN field of the certificate. This query will read the Device UDID attribute from CN field whenever a client presents the EAP-TLS certificate during authentication.

You can choose to add the attributes to be used for AuthZ as needed. Here we have used the WorkspaceONE Compliance, Enrollment Status and Compromised attributes to be fetched as our AuthZ attributes.

Save and Click Next. You will now see a summary page of the configured AuthZ source, Click on Save.

Add this AuthZ source in the service where Workspace ONE managed endpoints authenticate using EAP-TLS method.

INFO

This will make real time API queries for every endpoint authenticating on this service. It is not necessary to use the same service for endpoints which the extension has synced to the endpoint repository and for endpoints which could not be synced due limitations discussed around endpoints not exposing mac address e.g android devices. The way to segregate which clients need a real time lookup for AuthZ and which do not will vary for different deployments.

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

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>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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.

Extensions and web proxy / firewall whitelisting

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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

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

Monitoring extension statistics

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

HTTP Authorization Source Mode

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.

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

Appendix C – endpoint sync schedule settings

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

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

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,
```

WARNING

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 attributes from VMware Worskspace One

When airWatchExtensiveSearch is set to true:

"Source"	"WorkspaceONE",
"WorkspaceONE UDID"	"8D667CAA15ACCD48B785A104031DE3A0",
"WorkspaceONE UUID"	"ea6019a9-f592-41f9-8340-24c796fd02a6",
"WorkspaceONE Owner"	"bikki",
"WorkspaceONE Device ID"	"40848",
"WorkspaceONE Compliance"	"NotAvailable",
"WorkspaceONE Compromised"	"false",
"WorkspaceONE Last Update"	"2023-04-27 14
"WorkspaceONE MDM Enabled"	"true",
"WorkspaceONE Last Check In"	"2023-04-27 14
"WorkspaceONE Serial Number"	"M4N0CX12R927169",
"WorkspaceONE MDM Identifier"	"8D667CAA15ACCD48B785A104031DE3A0",
"WorkspaceONE Enrollment Status"	"Enrolled",
"WorkspaceONE Device Friendly Name"	"B07D64852C5D-BG",
"WorkspaceONE Enrollment User Name"	"bikki"

When airWatchExtensiveSearch is set to false:

"Source"	"WorkspaceONE",
"WorkspaceONE UDID"	"8D667CAA15ACCD48B785A104031DE3A0",
"WorkspaceONE UUID"	"ea6019a9-f592-41f9-8340-24c796fd02a6",
"WorkspaceONE Model"	"VivoBook_ASUSLaptop X571GT_F571GT",
"WorkspaceONE Owner"	"bikki",
"WorkspaceONE Group ID"	"9835",
"WorkspaceONE Platform"	"WinRT",
"WorkspaceONE Device ID"	"40848",
"WorkspaceONE Ownership"	"Undefined",
"WorkspaceONE Compliance"	"Compliant",
"WorkspaceONE Group Name"	"HPE Aruba Networking",
"WorkspaceONE Is Roaming"	"false",
"WorkspaceONE Compromised"	"true",
"WorkspaceONE Last Update"	"2023-04-27 14
"WorkspaceONE MAC Address"	"Bxxxxx5D",
"WorkspaceONE MDM Enabled"	"true",
"WorkspaceONE Last Check In"	"2023-04-27 14
"WorkspaceONE Serial Number"	"M4N0CX12R927169",
"WorkspaceONE MDM Identifier"	"8D667CAA15ACCD48B785A104031DE3A0",
"WorkspaceONE Operating System"	"10.0.22621",
"WorkspaceONE Enrollment Status"	"Enrolled",
"WorkspaceONE Is Network Tethered"	"false",
"WorkspaceONE Device Friendly Name"	"B07D64852C5D-BG",
"WorkspaceONE Enrollment User Name"	"bikki",
"WorkspaceONE Is Device DND Enabled"	"false",
"WorkspaceONE Is Cloud Backup Enabled"	"false",
"WorkspaceONE Enrollment Email Address"	bikki.gupta@hpe.com,
"WorkspaceONE Is Device Locator Enabled"	"false",
"WorkspaceONE Is Activation Lock Enabled"	"false",
"WorkspaceONE System Integrity Protection Enabled"	"false"

6 - Ivanti MDM (formerly MobileIron)

This Technote covers the setup, configuration, and monitoring of the ClearPass extension for Ivanti MDM formerly known as MobileIron. The technote also covers Common Platform Services (CPS) and Event Notification framework.

Introduction

MobileIron Cloud is now branded as Ivanti Neurons for MDM and MobileIron Core is branded as Ivanti Endpoint Manager Mobile. ClearPass uses a single extension for both cloud and core platforms and hence the extension is named Ivanti MDM (formerly MobileIron On-Prem & Cloud).

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 v4 Extension? – Important Changes

Version 4.0 is the new publicly available version, and it will have the following additional functionality:

Ivanti MDM extension v4 supports lookup based on Device Identifier or Device GUID, 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.
Ivanti MDM extension v4 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 Device Identifier or Device GUID in the subject alternative name (SAN) of your certificate profiles. Please refer to Onboard Certificate Enrollment for more details on SCEP certificate profile configuration.
Ivanti MDM extension v4 is built on a revamped underlying Extension framework which aims to standardize common configuration parameters across multiple extensions.
Extension v4 also has updates to branding from MobileIron to IvantiMDM. The default endpoint attribute prefix will also be “IvantiMDM” starting with extension v4. Existing deployments moving from v1 to v4, please follow the guidance given under attributePrefix extension configuration if you wish to continue using MobileIron as attribute prefix.

What’s new in v1 Extension? – Important Changes

Version 1.0 of the extension provides two key features.

Added support for MobileIron Cloud. MobileIron Cloud has not been previously supported, this extension adds support for Cloud version R50 and above.
Support for Common Platform Services Event Notifications. This provides for a near-real-time notification feed as discussed below, to allow ClearPass to maintain an up-to-date view of the managed devices, without the need to constantly poll. This is supported in MobileIron Cloud starting in R50 and in MobileIron Core starting in 9.5.

Note that ClearPass has supported MobileIron Core for several years, our support for this does not change. This Extension however can complement an existing MobileIron Core deployment or it can possibly replace it if the version of Core in 9.5 or greater and thus supports the Common Platform Services.

API Product	MI API’s supported	Native ClearPass Polling	Native ClearPass Polling + Extension CPS API [Hybrid deployment]	MobileIron Extension CPS API
Pre-Core 9.5	V1	Yes	Yes*	No
Core 9.5 +	V1 + CPS	Yes	Yes	Yes
Cloud R50 +	CPS	No	No	Yes

API

Product

MI API’s supported

Native ClearPass Polling

Native ClearPass Polling + Extension CPS API [Hybrid deployment]

MobileIron Extension CPS API

Pre-Core 9.5

Yes

Yes*

Core 9.5 +

V1 + CPS

Yes

Cloud R50 +

CPS

Yes

INFO

For the Pre-Core 9.5 in Hybrid mode, only the Native ClearPass Polling API V1 are supported, the CPS API’s are not available in the pre 9.5 Core so adding the Extension to add real-time updates is not supported.

As discussed, the Extension has the ability to ingest endpoint attributes (Core 9.5+ & Cloud R50+) and to receive a near real-time [typically circ. 5 seconds] feed of changes within the customer’s MobileIron tenant. There are five use-cases where ClearPass receives a real-time event notification.

A New Device Added
A Device Retired/Deleted
A Device changes state to “out of Compliance”
A Device changes state to “in Compliance”
A Device is Wiped

When one of the above events occurs, MobileIron places an event notification in a messages queue, all ClearPass nodes that are subscribed for that event, would then receive that message, afterwards, that message is purged from the system.

If no active ClearPass nodes are available to consume the message, the message is published to the messaging server, the message would be retained in the system for a maximum duration of 3 hours before it either gets consumed by a re-connecting ClearPass node or gets deleted out of the system.

In comparison, the legacy approach [still available] is to poll the tenant every hour and ingest all of the endpoint data, then update the delta changes into the EndpointDB. The obvious issue with the legacy approach is that if a device goes out of compliance, ClearPass won’t know of the state change until the next poll. Similarly, if a new device is added, typically the access-policy is that when a SmartDevice accesses the network, ClearPass checks to ensure it’s a known managed device. In the legacy approach access would be denied until the next poll had completed. Utilizing the full polling capabilities in conjunction with the event notifications allows a near real-time local view of all of the managed Endpoints.

Below, we cover installation and configuration of the extension, configuration within MobileIron, and finally ClearPass configuration. Additionally, we document a solution which allows a device to be ‘tagged’ as in or out of compliance. This creates an event notification and allows for testing of the end-to-end workflow.

Software Requirements

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

Installing Extension

INFO

Access to the extension store

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.

INFO

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

Extensions and web proxy support

INFO

Extensions and IP address configuration support

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

INFO

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

After the extension has been installed, proceed to configure Ivanti MDM and ClearPass.

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

Configuring the Ivanti MDM 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 a “real-time” authorization to Ivanti MDM. As shown on the previous page there are several parameters required to configure this version. Not all switch settings need to be set but some are mandatory. We have divided the parameters into two tables, one for Ivanti MDM Extension-specific configuration parameters and the other for Extension framework configuration parameters that are common across multiple vendor Extensions.

Ivanti MDM specific extension configuration attributes

Attribute	Description	Values/Examples
ivantiMDMUrl	URL to access the cloud / core Ivanti MDM instance	https://XXXXX.mobileiron.com
ivantiMDMUserName	Username used to make API calls against Ivanti MDM	cppm-api@XXXX.com
ivantiMDMPassword	Password corresponding to the API username	XXXXXXXXXXX
syncPageSize	The page size used when puling data from Ivanti MDM	50
enableMqtt	This setting enables processing of MQTT messages from Ivanti MDM	true
mqttUrl	URL from which Ivanti MDM would send MQTT updates (Common Platform Services Notification)	ssl://queue-XXXXX.mobileiron.com:8883
mqttUserName	Username which has Common Platform Services Notification enabled	cppm-api@XXXX.com
mqttPassword	Password corresponding to mqttUserName	XXXXXXXXXXX
toggleEndpointStatus	If a device is Wiped or Retired, toggle the endpoint status from "Known" to "Unknown"	true

Mandatory fields are: ivantiMDMUrl, ivantiMDMUserName, ivantiMDMPassword

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

INFO

There are changes in syntax for the sync parameters in Ivanti MDM Extension v4 due to updates in the underlying extension framework.

Configuration of syncAllSchedule is covered in more detail in Appendix C 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 values of enableEndpointCache and endpointCacheTimeSeconds are specifically used in conjunction with the extension is used as an Authorization source to retrieve real-time data for a known endpoint. If using the Extension in combination as discussed later with a HTTP authorization source which needs to do lookup based on Ivanti MDM Device ID / GUID as following:

GET /?identifier=:identifier
GET /?identifier=:deviceGuid&identifierType=GUID

Then these switches will ensure that if the extension is asked to refresh data, it will check the endpointCacheTimeSeconds to decide if the data current held is fresh or stale.

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

An example of an Ivanti MDM 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.

The configuration item “attributePrefix” controls the prefix that is added to the endpoint attributes fetched from Ivanti MDM and subsequently used in policy conditions. If you already have MobileIron v1 and is looking to update to latest version of the extension, you can configure attributePrefix as “MobileIron” so that extension will continue to use the same prefix as before. If this is a new deployment or if you wish to switch to new attribute prefix, you can leave the attributePrefix empty as shown below so that ClearPass will use “Ivanti MDM” as prefix for endpoint attribute names.

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

Ivanti MDM Configuration – Common Platform Services [CPS]

Below we cover the configuration required in the Ivanti MDM environment. To aid the configuration of the extension it helps to collect several items from the Ivanti MDM tenant. Within the configuration, there are two username/password combinations required. They are covered below.

Account Creation

Ivanti MDM-Tenant-Credentials: The first pair [ivantiMDMUserName/ivantiMDMPassword] is used by the extension to communicate with the Ivanti MDM instance for calling API’s that allow the extension to retrieve all the endpoint data that is then populated into the ClearPass EndpointDB. For the Ivanti MDM-
Tenant-Credentials, it is suggested that an account be created in Ivanti MDM dedicated for this function. These credentials can be an Administrator account, but it’s recommended that a new account with the “Device Registration” role be used. To create the account. Users -> +Add

Then select the API User and enter username and password to create the user.

Once the user account has been created, select it to view details and ensure the user has ‘Device Registration’ role assigned.

Ivanti MDM-MQTT-Credentials: The second pair [mqttUserName/mqttPassword] is used by the extension to communicate with the Ivanti MDM Common Platform Services. This service sends the real-time-notifications. It is possible to use the same account as above or a separate account. If using the same account, ensure that the Common Platform Services role has been added to the user account. In the Roles tab, click on Actions -> Assign Roles

Next add the role to the user. Note, to add the role Common Platform Services scroll down as highlighted below to locate the role. Select the role, and Next.

Click Done to complete adding the role

Enabling CPS framework

Following the creation of the accounts If the near-real-time event notification is to be used, then there are additional configuration steps required. To configure and enable the CPS Event Notifications follow the below steps. Navigate to the Admin > System > Common Platform Services Notification. Click on Common Platform Services Notification toggle button and enable the service.

If the CPS role has not been added to an existing user, then create a new CPS user and assign CPS role to this new user.

Manually triggering an event

Here are specific instructions showing an example of how use custom attributes and compliance policy to force devices in and out of non-compliant state: This section allows for the creation of an event to test the end-to-end workflow of the system.

A good use case would be to toggle a value of a custom attribute (say, nacCompliant) for devices which have moved out of compliance from true to false and then, use the attribute to take actions on the device. There are multiple ways to force compliance actions on the device to render it non-compliant. Please refer the below steps:

1: Create a compliance action policy: Navigate to Policies on the admin portal menu bar and click on Add

2: Add policy rule/definition to determine the criteria for a device going non-compliant: Click on “Custom Policy” option to create a custom compliance action policy.

Choose a custom policy rule: Enter a policy name and create a criteria query to specify policy rule, E.g. If the device ownership is ‘User Owned’ or the device OS is type ‘Android’ mark it as non-compliant and click Next.

3: Distribute the policy to all devices and click Done

4: Perform state changes on the device to match the criteria, this would mark the device non-compliant, in which case, device_not_compliant events would be triggered e.g., Changing device ownership to ‘User Owned’ and initiate force check-in and device sync.

Change an endpoint attribute to trigger an event notification – part1

Some sample policy rules affecting large enclosure of devices at once might not be recommended.

OS is iOS
Last check-in is 10 hrs. ago
Ownership Type is ‘User Owned’

5: To bring the device back to compliance, either perform reverse device state changes or delete the compliance action policy and initiate force-sync on devices.

ClearPass Policy Manager Configuration

The final part is the configuration on ClearPass Policy Manager. Depending on how you use the integration will ultimately define how you configure the interaction between Ivanti MDM and the ClearPass Extension and Policy Manager.

If you plan on using the extension to interface with Ivanti MDM, then configure the extension and its associated polling. Following this, configuring ClearPass Policy Manager configuration is no different in how you would authenticate and authorize any other device, it’s really about how you use the endpoint database attributes in your authorization policy checks.

If you plan on using the extension to complement the existing Ivanti MDM Endpoint Context Server polling, then overall this is a hybrid deployment. Using the built-in polling to ingest the endpoint details once per day in addition to using the extension to ‘trickle-feed’ changes into the endpoint-database as they happen. This hybrid deployment can remove the need for the lengthy polling; however, we still recommend a poll be run once per day.

When mac randomization is enabled, MAC address based lookups cannot be done against endpoint database. Android OS also stopped sharing MAC Address with MDM solutions like Ivanti MDM. Hence there is a need to fetch device attributes based on a unique identifier other than MAC Address. Ivanti MDM extension v4 has the ability to lookup device information based on either Device Identifier or Device GUID. This is a real time lookup by using the unique device identifier embedded within device certificate. Within the certificate, the identifier can be embedded either as CN or as one of the Subject Alt Name fields like Subject-AltName-URI.

Regardless of which deployment you configure, as noted above the power of the integration is how you use the endpoint data base attributes. Here are a few simple examples.

To add, a little more clarity, if a device is retired from within Ivanti MDM then the endpoint status flag is set accordingly. Within your enforcement policy you need to add a rule {#1} as shown above, where, when the status of the endpoint is set as RETIRED, the enforcement action would be to Deny Access. This can be adjusted to fit your own needs, as an example if you detected a device trying to access the network which has been deleted/retired from the system, you may want to have a workflow that drops the device into a captive portal role which directs the user to contact the helpdesk for assistance.

HTTP Authorization Mode

To complete the configuration to use the Extension as a ‘real-time’ authorization source, configure an HTTP authorization source within ClearPass. With Ivanti MDM as an authorization source to the extension, ClearPass can receive the latest data from the Ivanti MDM platform for devices based on Device Identifier or Device GUID. This is more real-time but consideration needs to be made relative to the number of API calls that would be made.

Click on Next. This will advance to the Primary Tab provide the connection details.

INFO

The Base URL IP address is the IP address of Ivanti MDM extension.

Set the Base URL as http://ip_of_the_extension/ and pay special attention to HTTP not HTTPS, and also the addition of “/” in the path. It is mandated that a Login Username/Password is entered, but it is not used, so this can be set to 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 Ivanti MDM extension asking for context about the endpoint. The query is indexed off either the Device Identifier or the GUID in the certificate of the authenticating endpoint. For completeness, the Filter Queries are provided here. Depending upon the type of lookup you want to do, select the appropriate filter and copy it carefully.

Device Identifier lookup	%{Certificate:Subject-CN}
Device GUID lookup	%{Certificate:Subject-CN}?identifierType=GUID

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. You can choose whatever attributes you want to be exposed under authorization based upon what you list here. A complete list is available in Appendix A, the first fields in BOLD listed in Appendix A translate to the fields you can enter when configuring the query results, a short example is below.

INFO

If you have configured a custom value for “attributePrefix” in extension configuration, replace “Ivanti MDM” with the custom string in the Name and Alias Name fields shown above.

Once the HTTP authorization source is defined you can use the returned attributes in your policy processing. As an example, lets view the returned attributes from the above from an authentication request in access-tracker.

Below can be see the result of a real-time query from Ivanti MDM based upon the attributes configured in the authorization source above, this data has been returned and is available to the policy at authentication time.

Onboard Certificate Enrollment

Managed devices should also be configured to authenticate securely to the network. EAP-TLS is considered the most secure authentication method available due to mutual authentication using digital certificates. Ivanti MDM configuration profiles help setup fully automated enrollment workflows. ClearPass Onboard CA can be used as certificate issuing authority with provisioning done using Simple Certificate Enrollment Protocol (SCEP). The steps below show how to setup SCEP enrollment against Onboard CA. Note that Onboard CA can be setup either as root or intermediate.

First, we need to enable SCEP enrollment for ClearPass Onboard CA. Navigate to ClearPass Onboard > Certificate Authorities > Click on the CA you want to enable SCEP for > Edit > Check the box to enable SCEP server as shown below.

Select SCEP secret as validation method and add a SCEP shared secret.

After saving the changes, click on the CA again > Trust Chain > Download Bundle to download as a .pem file. We will be uploading this certificate to the SCEP profile in Ivanti MDM later.

On Ivanti MDM, navigate to Configurations and add a new profile:

Search for certificate and select “Identity Certificate” profile:

Configure SCEP profile as shown below:

Once the SCEP profile is setup, you can create a WiFi profile to use the client certificate for EAP-TLS authentication

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

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>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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.

Extensions and web proxy / firewall whitelisting

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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

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

Monitoring extension statistics

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

HTTP Authorization Source Mode

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.

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

Appendix C – endpoint sync schedule settings

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

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

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,
```

WARNING

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 – List of all available Ivanti MDM Attributes

Ivanti MDM OS: OSX

Ivanti MDM UDID: DD1A8DDE-DDD2-5041-AC94-6655A6459D98

Ivanti MDM Model: MacBookAir6,2

Ivanti MDM Status: ACTIVE

Ivanti MDM Blocked: true

Ivanti MDM User ID: matt@bbqlabs.net

Ivanti MDM Compliant: false

Ivanti MDM Ownership: Unknown

Ivanti MDM User UUID: 8d1f27a2-6341-48be-97fc-8ff85fa5ef21

Ivanti MDM OS Version: 10.13.5

Ivanti MDM Compromised: false

Ivanti MDM Device GUID: cb806490-360f-4b1b-abc6-13a07aa3c1b2

Ivanti MDM Last Update: 2022-11-02 09:47:58

Ivanti MDM MAC Address: 5c:f9:38:98:7d:2c

Ivanti MDM MDM Enabled: true

Ivanti MDM Quarantined: true

Ivanti MDM Manufacturer: Apple Inc.

Ivanti MDM Last Check In: 2022-10-14 14:59:26

Ivanti MDM Serial Number: C02LM1HMF6T6

Ivanti MDM MDM Identifier: DD1A8DDE-DDD2-5041-AC94-6655A6459D98

Ivanti MDM Registration Date: 2022-10-13 21:39:22

7 - Mosyle

Mosyle provides the most flexible and best-in-class mobile device management (MDM) solution for Apple deployments of any size, complexity and industry. Mosyle solutions simplifies initial setup, provisioning and management of your iPad and iPhone devices, Mac computers and Apple TV.

Introduction and Overview

Mosyle provides two different solutions: Manager and Business. Starting from v2 of the Extension, we’ve added support for Mosyle Business which complements our initial support for Mosyle Manager.

Mosyle Manager was designed exclusively for K-12 schools and districts to incorporate education-focused features and hierarchy, with areas for students, class periods and course information. It also integrates directly with Apple School Manager. In addition, Mosyle Manager will offer Classroom Management capabilities, so teachers can manage student-device interactions within the classroom.

Mosyle Business, on the other hand, was built for enterprise and higher education institutions, and it will have a different hierarchy, as well as integrate with both Apple Business Manager and Apple School Manager. It allows companies to experience the most secure and compliant experience when automating and managing Apple devices to their end-users to be more productive at work.

This integration guide covers the deployment and configuration of ClearPass Policy Manager to interface with Mosyle.

It provides the ability to pull all device details from a customer tenant into ClearPass endpoints database. The contextual data inserted into Policy Manager can then be leveraged to drive granular access policy.

Pictorial View of the Integration

The diagrams below show pictorial overview of the components and how they interact with each other.

The primary workflow in the integration has ClearPass periodically syncing devices from Mosyle to its endpoint database.

There is also an advanced use case where a context server based dynamic lookup can be used to fetch the updated attributes for a device from Mosyle if the entry in endpoint repository is not up to date.

Dynamic lookup for updated endpoint attributes

Software Requirements

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

Installing Extension

INFO

Access to the extension store

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.

INFO

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

Extensions and web proxy support

INFO

Extensions and IP address configuration support

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

INFO

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

Mosyle Extension Configuration

The default configuration used for Extension is below

{

“logLevel”: “INFO”,

“verifySSLCerts”: true,

“mosyleHost”: “”,

“mosyleEmail”: “”,

“mosylePassword”: “********”,

“accessToken”: “********”,

“isMosyleBusiness”: false,

“osTypes”: [

“ios”,

“mac”,

“tvos”

“dataColumns”: [

“deviceudid”,

“wifi_mac_address”,

“ethernet_mac_address”,

“os”,

“device_name”,

“device_model”,

“device_type”,

“model_name”,

“osversion”,

“status”,

“is_supervised”,

“is_deleted”,

“date_checkin”,

“date_info”

“enableEndpointCache”: true,

“endpointCacheTimeSeconds”: 300,

“syncUpdatedOnly”: true,

“syncAllOnStart”: true,

“enableSyncAll”: true,

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

“enableStats”: true,

“statsUsername”: “”,

“statsPassword”: ""

}

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

Mosyle specific extension configuration attributes

Configuration	Description	Example/Values
mosyleHost	Mosyle Host URL. ClearPass automatically chooses between Mosyle Manager and Business URLs depending upon the value of “ isMosyleBusiness” attribute. This field is now optional and can be used to override the default URLs used by ClearPass.	managerapi.mosyle.com businessapi.mosyle.com
mosyleEmail	Email of administrative user in Mosyle Business	Administrator username {added in V3 of the extension}
mosylePassword	Password associated with Mosyle email account	Administrator password {added in V3 of the extension}
accessToken	Token to access Mosyle API	000000
isMosyleBusiness	Determines if the Extension is communicating with Mosyle Manager or Mosyle Business and uses the appropriate host URL	true or false {added in V2 of the extension}
dataColumns	Specify what information to be synced from Mosyle system. For all, enter “*”	device_name, device_model
osTypes	Specify OS types to be fetched from Mosyle system.	ios, mac, tvos

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

INFO

Starting in V2 of the Extension, support for Mosyle Business was added. This additional support added one new switch in the Extension configuration, isMosyleBusiness, which is a boolean true or false option and very self-explanatory, finally one other very important configuration option, see below.

The selection of whether you are using the Extension to communicate with Mosyle Manager or Mosyle Business will also automatically set the value for attribute mosyleHost. You can also override this value if the URL has changed.

Configuration Deployment Mode	Value for mosyleHost
Mosyle Manager	managerapi.mosyle.com
Mosyle Business	businessapi.mosyle.com

INFO

The V3 extension added additional configuration attributes like syncUpdatedOnly and enableEndpointCache. With syncUpdatedOnly, only the endpoints updated since the last sync are fetched from Mosyle. With enableEndpointCache, authorization queries use the cached endpoint attributes, thus reducing database / API queries and optimizing policy evaluation performance.

V3 extension also added two configuration attributes mosyleEmail and mosylePassword which are used with Mosyle Business for API authentication in addition to the accessToken.

When leveraging the sync capabilities of the Extension to get the device attributes from Mosyle, enable syncAllSchedule. This attribute is leveraged for periodic sync of endpoints from Mosyle.

INFO

When used in conjunction with “syncUpdatedOnly”, you can now configure the sync interval to be more aggressive than the default of once a week. For example, to have the “updated” endpoints sync every 30 minutes, you can use the following cron syntax.

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

The syncAllOnStart attribute can be leveraged as well to sync all devices upon the start or re-start of the extension. Note that first time sync of all the devices could take a long time to complete and can be resource intensive.

A copy of the Mosyle Extension with the desired configuration is shown below, this has to be modified for your deployment. Include accessToken, dataColumns, osTypes, mosyleEmail and mosylePassword 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 synced the endpoint data from Mosyle. The above steps sync 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 Mosyle attributes during enforcement. A sample of endpoint attributes fetched are shown below.

Multiple use-cases exist for how the data that is returned from Mosyle can be used in the Policy enforcement. In the example below, we are performing multiple checks:

Check if the device’s status is valid. If it is not, redirect it to the captive Portal. Create a helpdesk ticket for remediation.
If the device is deleted in Mosyle, create a helpdesk ticket.
If the device is not supervised by Mosyle, put it in the Quarantine VLAN.
Check when the device last checked-in with Mosyle. If the device has not checked in for certain number of days, flag it and redirect it to the Captive Portal.

Example of an Enforcement Policy utilizing attributes returned from Mosyle

Different companies will have different enforcement profiles and policies. The key takeaway here is to leverage the attributes received from Mosyle to drive the policy engine into making different enforcement actions for the device as they authenticate on the network.

Mosyle Real Time Authorization

We can also add the Mosyle extension as an Endpoint Context Server to fetch latest device information if it is not already present in endpoint repository. This is useful when the context has changed in Mosyle and we want to ensure that ClearPass fetches the latest state for authorization.

If using EAP-TLS authentication where client certificates contain the DeviceUDID attribute, we can use a device ID based context server action. The old method of pulling context information from Mosyle using the client MAC Address is still available. EAP-TLS with device ID is the preferred way to fetch device information dynamically. However, for organization that have not yet completed the process of deploying EAP-TLS, client MAC Address based workflow can still be used.

First step is to add Mosyle extension as an Endpoint Context Server as shown below.

Depending upon whether we want to use device ID or calling station ID based lookup, we can define the required Context Server Action under Administration > Dictionaries > Context Server Actions.

Example Context Server Action – Device ID based lookup

Set the HTTP Method to GET. There is no additional configuration required in Header, Content and Attributes tab.

Example Context Server Action based on client mac address

Set the HTTP Method to GET. There is no additional configuration required in Header, Content and Attributes tab.

Mosyle configuration

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

Available Data Fields

There is a wide range of available information from the Mosyle system. By default, we only pull a subset of the fields, but you can add or change them using the dataColumns configuration value. If you wish to include all fields simply add an asterisk ("*") to the dataColumns list.

If the “is_deleted” field is true we will set the ClearPass Endpoint status to “Unknown”. For all other endpoints the status will be “Known”.

All fields added to endpoints are prefixed with “Mosyle “, for example, “Mosyle is_deleted”.

Below are the available data fields:

deviceudid, total_disk, os, serial_number, device_name, device_model, battery, osversion, date_info, carrier, roaming_enabled, isroaming, imei, meid, available_disk, wifi_mac_address, bluetooth_mac_address, is_supervised, date_app_info, date_last_beat, date_last_push, status, isActivationLockEnabled, isDeviceLocatorServiceEnabled, isDoNotDisturbInEffect, isCloudBackupEnabled, IsNetworkTethered, needosupdate, productkeyupdate, device_type, lostmode_status, is_muted, date_muted, activation_bypass, date_media_info, tags, is_deleted, iTunesStoreAccountHash, iTunesStoreAccountIsActive, date_profiles_info, ethernet_mac_address, model_name, LastCloudBackupDate, SystemIntegrityProtectionEnabled, BuildVersion, LocalHostName, HostName, OSUpdateSettings, ActiveManagedUsers, CurrentConsoleManagedUser, date_printers, AutoSetupAdminAccounts, appleTVid, asset_tag, ManagementStatus, OSUpdateStatus, AvailableOSUpdates, appleTVid, enrollment_type, userid, date_checkin

Bold fields are required and are always returned.

API Token Creation

To obtain the accessToken, if you are using Mosyle Manager, the API Integration is available for only Mosyle Manager Premium accounts. You can access the API Integration by going to My School > API Integration.

API requests require Admin User Credentials for authorization. You can create an Admin user specifically for the API integration under My School > Administrators and limit the user’s permissions to only API access.

If you are using Mosyle Business, there is a self-service option within the UI. Navigate from the GUI to ‘Organization’, then click on ‘API Integration’ as shown below.

Creating an access-token in Mosyle Manager

then ‘Add new token’ on the top right-hand-side. Input an appropriate name, perhaps ‘clearpass’.

Creating an access-token in Mosyle Business, part2

The token will be created {example below}, record this as it will be shown only once and will be need in the extension configuration under accessToken.

INFO

With the latest update to Mosyle Business, an admin username and password is required along with the Access Token to make API calls. “Require User Credentials” is enabled by default for all new API integrations and cannot be disabled.

There is a wide range of available information from the Mosyle system. By default, we only ingest a subset of the fields, but you can add or change them using the dataColumns configuration value. If you wish to include all fields simply add an asterisk (”*”) to the dataColumns list.

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

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>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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.

Extensions and web proxy / firewall whitelisting

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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

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

Monitoring extension statistics

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

HTTP Authorization Source Mode

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.

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

Appendix C – endpoint sync schedule settings

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

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

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,
```

WARNING

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.

8 - SOTI MobiControl

SOTI MobiControl is the Enterprise Mobility Management (EMM) solution that gives you visibility and control over where your business-critical mobile devices are, what they’re doing, how they’re performing and what security or compliance risks they’re facing.

Deploy apps to smartphones. Enroll and provision new tablets in the field. Track the location of rugged devices. Identify and neutralize security risks to the IoT endpoints. Protect critical data stored on mobile devices. Minimize device downtime so field workers stay productive.

This technote covers how to deploy and configure the ClearPass Extension to interface with SOTI MobiControl MDM.

In this technote we will cover the installation and configuration of the extension for integration between MobiControl and ClearPass Policy Manager. The Extension effectively becomes an authorization source to service policies by utilizing the endpoint context synchronized from SOTI MobiControl.

This extension provides the ability to capture all of the mac-address’s on an endpoint and create corresponding entries in the ClearPass endpoint ensuing that if the devices uses a wires/wireless/dongle to authenticate, ClearPass will have the mac-address of the endpoint such that it can validate it.

Finally, in the extension we expose the ability to add any SOTI MobiControl endpoint attribute required to make your policy complete, add the endpoint attribute and the ClearPass Extension will capture that context and add it automatically to the ClearPass Policy Manager Endpoint DB so it can be used in role-mapping or in an Enforcement Policy.

Pictorial View of the Integration

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

In this mode ClearPass polls SOTI MobiControl periodically and updates the ClearPass Endpoint database with attributes obtained from SOTI MobiControl. 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.

Software Requirements

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

Installing Extension

INFO

Access to the extension store

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.

INFO

All currently available extensions are listed in the page: https://www.arubanetworks.com/techdocs/NAC/clearpass/integrations/clearpass-extension/extensions-list/

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

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.

INFO

Password and sensitive configuration items are obfuscated when presented in both the Extension GUI or in the Explorer configuration.

WARNING

The configuration attributes are case sensitive. It is recommended to refer the default configuration sample while editing your configuration.

Extensions and web proxy support

INFO

Extensions and IP address configuration support

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

INFO

Never set the DATA or MGMT IP address to use an address that matches the Extension Network

INFO

Note that changing the extension base IP address will require the extension service to be restarted.

ClearPass SOTI MobiControl Integration Extension Configuration

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

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

SOTI MobiControl specific extension attributes

Configuration attribute	Description	Example/Values
sotiHostName	This hostname of the SOTI MobiControl. This will be the URL used by ClearPass to communicate with SOTI MobiControl
sotiClientId	The API Client ID from SOTI MobiControl
sotiClientSecret	The API Client Secret from SOTI MobiControl
sotiUserName	The username of the SOTI MobiControl admin account
sotiPassword	The password for the SOTI MobiControl admin account

SOTI MobiControl Configuration

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

Adding an API Client

To add an API client, you must have administrative access to the Windows server where MobiControl is hosted. If you are a MobiControl cloud customer, please contact SOTI MobiControl support to add an API client. Please refer to https://www.soti.net/mc/help/v15.5/en/adminutility/tools/restapi.html for additional information.

Configure ClearPass Policy Manager

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

Periodic Sync Mode: Using stored attributes

The Extension will sync data from SOTI MobiControl based upon a configurable schedule, write this data into the ClearPass EndpointDB, this data is then used in policy as an authorization source.

INFO

Be aware that this data is not ‘real-time’ and the update frequency would depend on the sync schedule configured in the extension

Here’s an example of a ClearPass Role Mapping Policy that utilizes these SOTI MobiControl Endpoint attributes.

Role Mapping Policy using SOTI Endpoint Attributes

Using the SOTI MobiControl Integration Extension information in a ClearPass Service

Here we will provide more detail on how to incorporate information from the SOTI MobiControl Integration Extension in an existing ClearPass service. We’ll add the Endpoint Database to an existing basic Wired 802.1X service that processes authentications from 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 SOTI MobiControl. Note this is an evaluate-all Role Mapping Policy, so all matching roles will be applied.

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

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>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

INFO

For this reason its good practice to fix the IP address of the extension at installation time such that it doesn’t change over time and break the application controls.

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.

Extensions and web proxy / firewall whitelisting

INFO

extensions.clearpassbeta.com
registry-1.docker.io
index.docker.io
auth.docker.io
production.cloudflare.docker.com

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

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

Monitoring extension statistics

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

HTTP Authorization Source Mode

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.

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

Appendix C – endpoint sync schedule settings

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

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

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,
```

WARNING

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 – List of returned SOTI MobiControl endpoint attributes

{

“$type”: “DeviceIos”,

“ActivationLockBypassCode”: null,

“ActivationLockBypassStatus”: “NotApplicable”,

“AgentVersion”: null,

“Memory”: {

“$type”: “Memory”,

“AvailableExternalStorage”: null,

“AvailableMemory”: null,

“AvailableSDCardStorage”: null,

“AvailableStorage”: null,

“TotalExternalStorage”: null,

“TotalMemory”: null,

“TotalSDCardStorage”: null,

“TotalStorage”: null

“BatteryStatus”: null,

“BluetoothMACAddress”: null,

“BuildVersion”: null,

“CarrierSettingsVersion”: null,

“CellularCarrier”: null,

“CellularTechnology”: “None”,

“CurrentMCC”: null,

“CurrentMNC”: null,

“DataRoamingEnabled”: false,

“DeviceTerms”: {

“$type”: “DeviceTerms”,

“Status”: 3,

“StatusTime”: “2020-07-27T08:22:20.09Z”,

“StatusVersion”: “1”,

“RuleId”: 9,

“RuleName”: “sample”,

“StatusEnum”: “Accepted”

“DeviceUserInfo”: null,

“MultiUserDeviceInfo”: null,

“ExchangeBlocked”: false,

“ExchangeStatus”: “Accepted”,

“FirmwareVersion”: null,

“HardwareEncryptionCaps”: 0,

“HardwareEncryption”: “None”,

“ICCID”: null,

“IMEI_MEID_ESN”: null,

“InRoaming”: null,

“Ipv6”: null,

“IsActivationLockEnabled”: null,

“IsAgentCompatible”: true,

“IsAgentless”: true,

“IsDeviceLocatorServiceEnabled”: null,

“IsDoNotDisturbInEffect”: null,

“IsEncrypted”: false,

“IsEnrolled”: true,

“IsITunesStoreAccountActive”: null,

“IsMDMLostModeEnabled”: null,

“IsOSSecure”: true,

“IsPersonalHotspotEnabled”: null,

“IsSupervised”: null,

“ItunesIdHash”: null,

“LastCheckInTime”: null,

“LastAgentConnectTime”: null,

“LastAgentDisconnectTime”: null,

“LastLoggedOnUser”: null,

“LastStatusUpdate”: “2020-07-27T08:22:43.967Z”,

“ManufacturerSerialNumber”: null,

“ModelNumber”: null,

“ModemFirmwareVersion”: null,

“NetworkConnectionType”: “Unknown”,

“PasscodeEnabled”: false,

“PasscodeStatus”: “Unknown”,

“PersonalizedName”: null,

“PhoneNumber”: null,

“ProductName”: null,

“SIMCarrierNetwork”: null,

“SubscriberMCC”: null,

“SubscriberMNC”: null,

“SubscriberNumber”: null,

“UserIdHash”: null,

“VoiceRoamingEnabled”: false,

“ManagementProfileUpdateTime”: “2020-07-27T08:22:26.06Z”,

“ManagementProfileSigningCertificateExpiry”: “2039-07-15T00:00:00Z”,

“MDMClientCertificateHash”: “BB4D692033D2E33BC7FFE72D9370693B3B98CC51”,

“Kind”: “Ios”,

“ComplianceStatus”: true,

“ComplianceItems”: [

{

“$type”: “ComplianceItem”,

“ComplianceType”: “IsSecured”,

“ComplianceValue”: true

{

“$type”: “ComplianceItem”,

“ComplianceType”: “IsDeviceAdmin”,

“ComplianceValue”: null

{

“$type”: “ComplianceItem”,

“ComplianceType”: “NotWiped”,

“ComplianceValue”: true

{

“$type”: “ComplianceItem”,

“ComplianceType”: “IsEnabled”,

“ComplianceValue”: true

{

“$type”: “ComplianceItem”,

“ComplianceType”: “IsEnrolled”,

“ComplianceValue”: true

}

“DeviceId”: “00008030-001449C23CA3802E”,

“DeviceName”: “00008030-001449C23CA3802E”,

“EnrollmentTime”: “2020-07-27T08:22:20.073Z”,

“Family”: “Apple”,

“HostName”: null,

“IsAgentOnline”: false,

“CustomAttributes”: [],

“MACAddress”: null,

“WifiMAC”: null,

“Manufacturer”: null,

“Mode”: “Active”,

“Model”: null,

“OSVersion”: null,

“Path”: “\\Theja”,

“Platform”: “iOS”,

“ServerName”: null

}