VMware Workspace ONE (Airwatch)

Categories:

• Class-1

  34 minute read  

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.

1. Device enrollment

2. Device unenrolled/ Enterprise wipe

3. Device compromised/ Status changed

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

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

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

2. 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”: “********”,

“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”: “********"

}

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

Software Requirements

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

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

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

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

ClearPass Installation and Deployment Guide

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

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

ClearPass Extensions

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

Installing Extension

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

Access to the extension store

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

Installing the Extension from Store

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

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

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

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

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

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

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

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

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

Extensions and web proxy support

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

Extensions and IP address configuration support

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

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

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

Configuration Steps

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

1. Register and request for a Skyhook tenant

2. Configuration of VMware Workspace ONE for Integration

3. Installation and Configuration of the Workspace ONE extension using the GUI in ClearPass.

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

Below are the configuration steps to follow.

Getting API Credentials

Login to the Workspace ONE UEM tenant, using your administrator 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.

1. Select “Override” as the Current Setting.

2. Set “Enable API Access” to “Enabled**”**.

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

4. Ensure you Save your changes.

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.

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.

Step III: 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”: “********”,

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

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.

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.

Appendix A – Troubleshooting and Support

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

Check API Access Application Control restrictions

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

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

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

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

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

<head>

<title>

Error 403 (Forbidden)

</title>

<script language=“javascript”>

function reloadPage() {

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

window.location.href = locHref;

}

</script>

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

Checking on the Extension Service

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

Restarting this service will affect all deployed and running extensions.

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

Extensions and web proxy / firewall whitelisting

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

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

Extension Logs/Enable Debugging

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

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

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

Accessing the extension logs using ‘Collect Logs’ system function

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

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

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

Monitoring extension statistics

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

To navigate to statistics page, click Show Details.

This will show statistics similar to the following:

Monitoring authorization performance

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

Appendix B – Considerations for Installing in a Cluster

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

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

Periodic Sync Mode

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

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

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

HTTP Authorization Source Mode

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

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

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

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

Appendix C – endpoint sync schedule settings

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

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

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

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

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

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

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

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

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

Appendix D – Extension performance optimizations

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

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

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

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

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

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

     "enableSyncAll": false,
  

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

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

    "syncUpdatedOnly": true,
  

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

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

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

  Sample for JAMF extension:

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

  Default for Microsoft Intune extension:

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

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

  Sample for JAMF extension:

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

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

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

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

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

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

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

Appendix E – Sample 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"