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

Return to the regular view of this page.

Visitor Management / Webhook Processing

ClearPass integrates with a wide range of Visitor Management solutions for automated guest workflows. Combining ClearPass Guest Management along with these solutions can enhance the user experience by providing seamless visitor solution that automates visitor’s Wi-Fi requirements.

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

1: Envoy

2: SinePro

3: Teem LobbyConnect

4: Skyhook Generic Processor

1 - Envoy

Envoy Visitors is a visitor management platform for a modern front desk which helps streamline visitor Sign-in. When visitors arrive, Envoy makes it easy for them to Sign-in, presents them with relevant forms where they can provide their information, sign documents (NDAs) and optionally notifies the person they are visiting of their arrival using an Email or SMS.

Envoy

This guide covers the setup, configuration, and monitoring of the ClearPass extension for Envoy and the configuration of webhook in Envoy for the Integration with HPE Aruba Networking ClearPass. This guide walks through the v2 of this integration. We will also cover the migration steps from v1 to v2.

INFO

The Envoy v2 integration requires Envoy Enterprise edition.

ClearPass is an industry leading Guest Management solution that delivers secure, automated guest access workflows. It’s very useful for an enterprise to combine these two applications to get a seamless visitor management system that automates visitor’s Wi-Fi requirements.

This Extension serves two primary use-cases

Creates a guest account upon Visitor Sign In
Disables a guest account upon Visitor Sign Out

With Envoy hosted in the cloud and ClearPass sitting primarily on-prem, there are challenges in making these two applications communicate in real time so that a visitor receives guest Wi-Fi credentials from ClearPass as soon as he registers using Envoy Visitors application. 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 have to 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’s 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 AWS. ClearPass nodes running on-prem, 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, Envoy running in the cloud will send a webhook upon a Visitor Sign in or a Sign out event. This will communicate with skyhook. The ClearPass extension configured and installed will maintain a persistent connection with skyhook awaiting an event (Sign in/ Sign out).

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.

Configuration Steps

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

Register and request for a Skyhook tenant
Configuration of Envoy for Integration
Installation and Configuration of the Envoy Extension using GUI in ClearPass 6.7.X

It is assumed you have SMTP and SMS configured to allow ClearPass Guest to send visitor account details to the Visitor/Guest.

Step I: Register and Request for a Skyhook Tenant ID

Skyhook Tenant ID’s can be registered in the skyhook self-service portal by accessing the following link https://clearpass.arubanetworks.com/webhooks/skyhook and instructions on using the skyhook self-service portal is available here: https://arubanetworking.hpe.com/techdocs/NAC/clearpass/integrations/clearpass-extension/skyhook-self-service-portal/

Kindly copy the skyhookTenant and the dbAccessToken in a text file. This will be used for configuration of the extension in ClearPass as well as configuring the tenant details on the Envoy plugin.

Step II: Configuring Envoy for ClearPass Integration

INFO

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

Below are the configuration steps to follow.

Select the Location you wish to integrate with ClearPass as highlighted below**.** Navigate to Integrations and “Install” the ClearPass plugin.

Once the plugin is installed, click on Configure and follow the steps.

For the first step, copy the Envoy Plugin Install Token. This will be used for the extension configuration in ClearPass to perform health checks.

For the next step, we need to use the skyhookTenant obtained in Step I from the email in Figure 8. Copy this value in the CLEARPASS TENANTNAME section as shown below.

Ensure that the default URL in the section SKYHOOK API HOST matches with https://skyhook.clearpassbeta.com/api/skyhook/envoy. Do not edit the field if it does or unless instructed by TAC.

Select the SMS Gateway that will be used to send the credentials to a visitor. We should use ClearPass SMS Gateway as an option here.

INFO

Configuration of ClearPass SMS Gateway and it’s template is beyond the scope of this guide.

The other option is to use the Envoy SMS gateway (using Twilio). The SMS gateway used here uses the SMS template shown in the screenshot. This can be modified as per requirements. For this setup, we are going to use the ClearPass SMS Gateway.

The last step shows the Status Report of the health checks performed by ClearPass extension.

ClearPass extension sends a health check every 5 minutes using the Envoy Plugin Install token for the given tenant. The statistics associated with this health check are shown here. This will only happen after the installation of the Envoy extension which is covered under the section Step III: Envoy Extension Installation and Configuration. Click on Complete Setup

Step III: Envoy Extension Installation and Configuration

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

The default configuration used for extension is below

{

“skyhookTenant”: “0f4cxxxx-xxxx-xxxx-xxxx-2e04897691a8”,

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

“envoyInstallToken”: “********”,

“countryIsoCode”: “US”,

“phoneNumberField”: “Your Phone Number”,

“cppmDefaultExpiryHrs”: 8,

“cppmGuestRoleName”: “[Guest]”,

“cppmGuestRoleId”: 2,

“cppmGuestSmsReceipt”: true,

“cppmGuestEmailReceipt”: true,

“cppmGuestAccessCode”: false,

“dbLogging”: false,

“logLevel”: “INFO”

}

A copy of the Envoy Extension with the desired configuration is shown below, this will need to be modified for your deployment. Include the skyhookTenant, dbAccessToken and envoyInstallToken that will be specific to your environment. Change any other default values if necessary. Select ‘Restart’ and click on Save Changes to restart the extension.

GUI review and setting the Extension configuration

The table below explains each option with the values and examples required for configuration.

Extension configuration options

Configuration attribute	Description	Example/Values
skyhookTenant	The Skyhook tenant ID received in the registration email.	c7xxxxx8-b2b6-4125-9741-cxxxxxxxx38a6
dbAccessToken	The access token for Skyhook received in the registration email.	Long Random string like 7INXYr1YUixxxxxv...
envoyInstallToken	The install token from Envoy used for Health Checks to ensure a valid communication channel exists.	f2343xxx-xxxx-xxxx-xxxx-2abd3e415a12
CountryIsoCode	The country code to use for phone number formatitting when the number is not specified in the international format.	US, IN
phoneNumberField	The sign-in field from Envoy to use for the visitor phone number.	“Your Phone Number”
cppmDefaultExpiryHrs	The default number of hours for an account to be active.	8
cppmGuestRoleName	The role name to be used in ClearPass Guest when creating the account. This value should match with the cppmGuestRoleId	[Contractor], [Guest], [Employee], Custom Role
cppmGuestRoleId	This value sets the role id to use when creating guest accounts	1 - [Contractor], 2 - [Guest], 3 - [Employee], 4 - Custom Role
cppmGuestSmsReceipt	Sets the value of auto_send_sms for ClearPass to send the Guest credentials receipt via SMS	true/false
cppmGuestEmailReceipt	Sets the value of auto_send_smtp for ClearPass to send the Guest credentials receipt via SMTP	true/false
cppmGuestAccessCode	Enables creation of random codes as Guest Username. If not used the defaul email field is used as username.	true/false
dbLogging	Enables advanced logging of skyhook db connection	true/false
logLevel	Logging level for troubleshooting	"DEBUG", "INFO", "WARN", "ERROR"

INFO

Set cppmGuestSmsReceipt value to false if leveraging the Envoy SMS Gateway. This would trigger an SMS using Envoy’s SMS Gateway which leverages Twilio in the backend.

After the configuration and the restart of the extension, click on Show Logs. You should see the following.

The above log states that the extension is now ready to process the events for Envoy.

You can change the logLevel to DEBUG under configuration for detailed logs. These are very useful for troubleshooting and should be included before raising a support case if necessary.

The configuration of Envoy Sign-in form is beyond the scope of this guide however there are a couple of interesting features introduced in Envoy v2 extension which requires us to go through this in brief. These features are not available in v1.

An Envoy Sign-in flow can be configured by selecting the location of your choice and then navigating to Visitors > Settings > Sign-in flow. Click on Sign-in fields.

The v2 extension now allows you to use any custom field as a Phone number field. This gives you the flexibility to change the name of the field displayed on the form. It can now be changed for example to “Mobile Number” or “Cellphone Number” or any other custom label. In v1 this was hardcoded and cannot be changed.

This field is then mapped to visitor_phone field in ClearPass Guest using the extension configuration parameter phoneNumberField as described in the “Extension configuration options” in Figure 19. It allows an administrator to effectively rename this field in Envoy and map the value to visitor_phone field in ClearPass Guest which is then used by ClearPass to SMS the credentials.

Envoy v2 extension can also consume information from other custom fields defined in the form. One can also add a custom field in the Sign-in form the input to which will be captured under the Guest account details within ClearPass. For instance, the custom field “Favourite Drink” is added to this form as shown in the figure. This can be added by clicking “Add a New Field” which is highlighted.

This is captured under Guest account details within ClearPass. Go to Guest > Manage Accounts, select a registered account and click on Show Details.

To add further, you can also use this field for the reports within Insight.

Migration Steps from Envoy v1 to Envoy v2

Envoy v1 was available as a ClearPass extension prior to writing this guide. Customers who already have v1 installed are recommended to move to v2 for performance enhancements. The v2 version of the Extension also provides an additional flexibility in defining custom fields as shown in Figure 22.

Following are the migration steps.

Request for a new SkyHook Tenant ID for Envoy v2 integration. The steps for the same are specified in the section “Step I: Register and Request for a Skyhook Tenant ID”.
Stop the Envoy v1 extension installed on your ClearPass server. Navigate to ClearPass Guest and go to Administration > Extensions. Click on the Envoy Extension to Stop it as shown below.

Install the new Envoy plugin for ClearPass Integration. Use the steps in the section “Step II: Configuring Envoy for ClearPass Integration”.
Follow the section “Step III: Envoy Extension Installation and Configuration” to install the new Envoy v2 extension.
Test the functionality for few days to ensure it works. If yes, the old extension can be deleted. If no, it can be restarted to ensure no service interruption. Contact support for any further assistance with troubleshooting.

Testing/Demo

Now that the components are all configured and ready to use, let’s walk through the experience from the visitor and administrator perspective. In order to do so, the first step for a visitor is to sign in using the Envoy Visitors app running on an iPad at a reception in the customer setup.

Configuring an iPad to assist customers with registration at front desk is beyond the scope of this document. Essentially, one needs to download the Envoy Visitors app from the appstore and register the device to your Envoy account.

Detailed steps are available here https://dashboard.envoy.com/devices/ipads/new

Visitor walks up to a tablet used for registration. Every company can personalize the branding by using their logos for the registration pages and email. A simple registration Sign-in page configured for our demo is shown below.

Visitor taps to sign in.

A first-time visitor is asked to fill the form completely with his details as shown below. The visitor is also asked to select the Sponsor, the person he is visiting. The sponsor is notified via an email/SMS of the visitor’s arrival. We have used basic forms here for demo. These forms are customizable and can be created as per customer requirements.

The next steps will ask the visitor to click a picture if configured and then make them digitally sign the required forms like NDA etc. There are several options available for the Sign-in flow on Envoy.
Once done, you will see a welcome message. This could be a message, image or a video based on the configuration on Envoy. The customization options are a part of the Sign-in flow. This finishes the registration from a visitor perspective.
Visitor should receive an email as well as an SMS with his credentials to login to guest Wi-Fi. Following is the snapshot of the email. Notice the account expiry time is set to 8 hours by default.

You can change the Receipt Template (Guest Manager Receipt) under Configuration > Receipts > Templates.

After the visit, user can Sign out at the registration desk using the same tablet. Type the first 3 letter of the name used during Sign in and select the user.

Now let’s see what happens in the backend from an administrator perspective.

The new account has been created upon registration. Note the Expiration time, this should match with the Envoy extension configuration setting for cppmDefaultExpiryHrs. By default, it is set to 8 hours. Another thing to note is the Role which is set to [Guest]. This depends on the extension configuration settings for cppmGuestRoleName and cppmGuestRoleId. This could also be set to a custom Role value if required. The configuration for the same is beyond the scope of this guide.

If you enable DEBUG and Click on Show Logs under Extension, you should see the following details as a part of the Sign in event.

[2018-10-24T08:10:46.907] [INFO] envoy - [Sign In] The following guest signed in: clearpass.test@gmail.com

[2018-10-24T08:10:46.908] [DEBUG] envoy - Sending health check to https://app.envoy.com/platform/clearpass-staging/sign-in-callback?_juuid=8d089232-c25c-4b57-9aa3-xxxxxxxxxxx

[2018-10-24T08:10:46.908] [DEBUG] envoy - {“status”:“sign-in”,“visitor”:“Test User”,“username”:“clearpass.test@gmail.com”,“password”:30922,“tenant”:“3d72456d-fbd1-49cd-aa08- xxxxxxxxxxx “,“extId”:“313deebb-3807-45ee-ace8-f4e908fc83cb”}

[2018-10-24T08:10:47.373] [DEBUG] envoy - handleEnvoyHealthCheck Response: [202] payload: “ACCEPTED”

[2018-10-24T08:10:47.373] [INFO] envoy - Successfully called Envoy healthcheck

[2018-10-24T08:10:47.373] [DEBUG] envoy - Successfully sent healthcheck update to Envoy.

[2018-10-24T08:10:47.649] [DEBUG] envoy - Successfully deleted transaciton from realtime db.

Upon Sign out, the visitor account will be disabled. This can be validated under Manage Accounts in ClearPass Guest

The user’s Wi-Fi session should also get disconnected automatically upon Sign out. This depends on the policy configured for the Guest SSID. This configuration is beyond the scope of this document.
You would see a similar Sign out event in the DEBUG logs.

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.

2 - SinePro

Sine Pro is an easy to use cloud-based visitor management platform. When visitors arrive, Sine makes it easy for them to Check-In and Check-Out, presents them with relevant forms where they can provide their information, sign documents (NDAs) and it optionally notifies the person they are visiting of their arrival.

Introduction

This guide covers the setup, configuration, and monitoring of the ClearPass extension for Sine Pro and the configuration of a webhook in Sine Pro for the Integration.

This Extension serves two primary use-cases

Guest account creation upon Visitor Check In
Guest account deletion upon Visitor Check Out

With Sine hosted in the cloud and ClearPass sitting primarily on-prem, there are challenges in making these two applications communicate in real time so that a visitor gets guest WiFi credentials from ClearPass as soon as he registers using Sine application. 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 have to 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’s available.

Before we proceed with the flow, we need to understand the concept of webhooks and skyhook.

What is a webhook?

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 AWS. ClearPass nodes running on-prem, 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, Sine Pro running in the cloud will send a webhook upon a Visitor check-in (signin_after) or a check-out (signout_after) event. This will communicate with Skyhook. The ClearPass extension configured and installed will maintain a persistent connection with Skyhook awaiting an event (Check In/ Check Out).

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 diagram below shows a pictorial overview of the components and how they interact with each other.

Pictorial view of ClearPass Policy Manager integration with Sine Pro

Configuration Steps

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

Register and request for a Skyhook tenant
Configuration of Sine Pro for Integration
Installation and Configuration of the Sine Pro extension using GUI in ClearPass 6.7.X

It is assumed you have SMTP and SMS configured to allow ClearPass Guest to send visitor account details to the Visitor/Guest.

Step I: Register and Request for a Skyhook Tenant ID

Step II: Configuring Sine Pro for ClearPass Integration

INFO

Setup and Configuration of Sine Pro is beyond the scope of this guide. Here we specify the steps necessary to configure the integration.

The “Email Required” field must be enabled in Sine Pro. This can be accessed from Passes > Check-In Requirements under Settings for individual sites. This email field is mapped to the Guest account username created in ClearPass.

Below are the configuration steps to follow:

Click on Sites. Select a Site and go to Settings. Navigate to Integrations and add (+) a WebHook.

The screen capture above covers the configuration required in the Sine Pro environment. Following are the values required for the configuration.

URL: This is the Skyhook Posting URL. The SkyHook Tenant is obtained from the sample email as shown in previous step. Replace the <SKYHOOK TENANT> below to create the URL.

https://skyhook.clearpassbeta.com/api/skyhook/sine**/<SKYHOOK TENANT>**

API Key: This is a shared key for communication between ClearPass and Sine.

INFO

We recommend using a GUID value or a large random value as the key. You can generate a GUID value here: https://www.guidgenerator.com/ OR a random value here: https://www.random.org/bytes/

External ID: This can be left blank as it is not used currently. It will automatically pick the default value.
Visitor Types: You could choose these based on your requirement however, in current versions of ClearPass all Visitor Types will be mapped to a Guest role on ClearPass by default.
Events: “signin_after” is a mandatory event that has to be selected. It is strongly recommended to select both the events “signin_after” and “signout_after” to complete the guest sign in workflow.
Status: Ensure the status is enabled.

Step III: Sine Pro Extension Installation and Configuration

The default configuration used for extension is below

{

“skyhookTenant”: “27f80f8aaaea8974d9c7ca43e69xxxxb5xxxx85910”,

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

“sineApiKey”: “********”,

“cppmDefaultExpiryHrs”: 8,

“cppmGuestRoleName”: “[Guest]”,

“cppmGuestRoleId”: 2,

“cppmGuestSmsReceipt”: true,

“cppmGuestEmailReceipt”: true,

“dbLogging”: false,

“logLevel”: “INFO”

}

A copy of the Sine Pro Extension with the desired configuration is shown below, this will need to be modified for your deployment. Include the skyhookTenant, dbAccessToken and sineApiKey that will be specific to your environment. Change any other default values if necessary. Select ‘Restart’ and click on Save Changes to restart the extension.

The table on the next page explains each option with the values and examples required for configuration.

Extension Configuration options

Configuration attribute	Description	Example/Values
skyhookTenant	The Skyhook tenant ID received in the registration email.	27f80f8aaaea8974d9c7ca43e69xxxxb5xxxx85910
dbAccessToken	The access token for Skyhook received in the registration email.	Long Random string like 7INXYr1YUixxxxxv...
sineApiKey	The API key configured in the sine integrations configuration.	4a348197-cc57-4cf7-a339-5a4c3f76b2b0
cppmDefaultExpiryHrs	The default number of hours for an account to be active.	8
cppmGuestRoleName	The role name to be used in ClearPass Guest when creating the account. This value should match with the cppmGuestRoleId	[Guest], [Contractor], [Employee], Custom Role
cppmGuestRoleId	This value sets the role id to use when creating guest accounts	1 - [Guest], 2 - [Contractor], 3 - [Employee], 4 - Custom Role
cppmGuestSmsReceipt	Sets the value of auto_send_sms for ClearPass to send the Guest credentials receipt via SMS	true/false
cppmGuestEmailReceipt	Sets the value of auto_send_smtp for ClearPass to send the Guest credentials receipt via SMTP	true/false
dbLogging	Enables advanced logging of skyhook db connection	true/false
logLevel	Logging level for troubleshooting	"DEBUG", "INFO", "WARN", "ERROR"

After the configuration and the restart of the extension, click on Show Logs. You should see the following.

The above log shows the License Agreement and also states that the extension is now ready to process events for Sine Pro.

You can change the logLevel to DEBUG under configuration for detailed logs. These are very useful for troubleshooting and should be included before raising a support case if necessary.

Migration Steps from Sine Pro v1 to Sine Pro v2

Sine Pro v1 was available as a ClearPass extension prior to writing this guide. Customers who already have v1 installed are recommended to move to v2 for performance enhancements.

INFO

Note the Sine Pro v1 is denoted as version 0.3 in ClearPass Extension UI.

Following are the migration steps.

Request for a new SkyHook Tenant ID for Sine Pro v2 integration. The steps for the same are specified in the section “Step I: Register and Request for a Skyhook Tenant ID”.
Disable the WebHook created for v1 Integration. Do not delete this. The idea is to keep the v1 integration in a disabled state so that we can move back to v1, if the v2 migration fails.

You can also rename this to WebHook-v1 or WebHook-OLD to avoid confusion.

The next step is to create another WebHook for v2 integration. Follow the steps in the section “Step II: Configuring Sine Pro for ClearPass Integration”.
Stop the Sine Pro v0.3 extension installed on your ClearPass server. Navigate to ClearPass Guest and go to Administration > Extensions. Click on the Sine Extension to Stop it as shown below.

Follow the section “Step III: Sine Pro Extension Installation and Configuration” to install the new Sine Pro v2 extension.
Test the functionality for few days to ensure it works. If yes, the old extension and the WebHook can be deleted. If no, they can be re-enabled to ensure no service interruption. Contact HPE Aruba Networking support for any further assistance with troubleshooting.

Testing/Demo

Now that the components are all configured and ready to use, let’s walk through the experience from the user and administrator perspective. In order to do so, the first step for a visitor is to register using the Sine Pro app running on an iPad at a reception in the customer setup.

Configuring an iPad or any other device to assist customers with registration at front desk is beyond the scope of this document. Essentially, you download the SinePoint Pro app from the appstore and use the registered account to login with this device to your Sine Pro tenant. Detailed steps are available on Sine’s website here

https://www.sine.co/sinepointsetup/

Visitor walks up to a tablet used for Registration. Every company can have a different skin for the Registration page. A simple Registration Check-In page configured for our demo is shown below.

Visitor clicks Check-In.

A first-time visitor is asked to fill all the forms with his details as shown below. A site location in Sine is recognized using the Google Maps. This will default the country code to that region. For example, 0414 will automatically be converted to +61414 for sites in Australia. Visitors from outside the region can manually enter the country code when checking-in.

We have used basic forms here for demo. These forms are customizable and can be created as per customer requirements. As you can see below, the email field should be available in the Check-In form. This field is mapped to the username of the Guest account created in ClearPass.

The next steps will ask the visitor to click a picture if configured and then make them digitally sign the required forms like NDA etc.
As a final step, the application asks the visitor to select the host. A notification about the visitor’s arrival will be sent to this host via SMS, email and/or push notification, as configured within Sine Pro.
Once done, you will see a successful check-In. This finishes the registration from the user perspective.

User should receive an email as well as an SMS with his credentials. Following is the snapshot of the email. Notice the account expiry time is set to 8 hours by default.

You can change the Receipt Template (Guest Manager Receipt) under Configuration > Receipts > Templates.

After the visit, user can Check Out at the registration desk using the same Tablet. Type you email, mobile or you can also scan the QR code to check-out. Click Next.

Now let’s see what happens in the backend from an administrator perspective.

The new account has been created upon registration. Note the Expiration time, this should match with the Sine Pro extension configuration setting for cppmDefaultExpiryHrs. By default, it is set to 8 hours. Another thing to note is the Role which is set to [Guest]. This depends on the extension configuration settings for cppmGuestRoleName and cppmGuestRoleId. This could also be set to a custom Role value if required. The configuration for the same is beyond the scope of this guide.

If you enable DEBUG and Click on Show Logs under Extension, you should see the following details as a part of the Check In event.

[2018-08-14T15:08:18.168] [DEBUG] sine - New event received (43ef9b54-e4b1-4f56-b8c0-690db430e96a).

[2018-08-14T15:08:18.178] [DEBUG] sine - The Sine API Key is a match. Processing message…

[2018-08-14T15:08:18.178] [DEBUG] sine - [Sign In] Looking up guest “peter@webworks.com” in CPPM.

Attmepting to call https://172.17.0.1/api/guest/username/peter@webworks.com with token of Bearer aabbcc13d3a5bfab48e3890d3937046f1aaabbcc

[2018-08-14T15:08:18.482] [DEBUG] sine - [Sign In] Creating guest “peter@webworks.com” in CPPM.

Attmepting to call https://172.17.0.1/api/guest with token of Bearer 0df7cf13d3a5bfab48e3890d3937046f1a35659d

[2018-08-14T15:08:19.136] [INFO] sine - [Sign In] The following guest signed in: Peter Parker (peter@webworks.com)

[2018-08-14T15:08:19.136] [DEBUG] sine - Removing event from skyhook (43ef9b54-e4b1-4f56-b8c0-690db430e96a)…

[2018-08-14T15:08:19.405] [DEBUG] sine - Event removed (43ef9b54-e4b1-4f56-b8c0-690db430e96a).

Upon Check Out, the User account will be disabled, see this under Manage Accounts in ClearPass Guest

The user’s WiFi session should also get disconnected automatically upon Check Out. This depends on the Policy configured for the Guest SSID. This configuration is beyond the scope of this document.
You would see a similar Check Out event in the DEBUG logs.

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

LobbyConnect(LCx) is a visitor management module of Teem’s cloud-based platform. When visitors arrive, LCx presents them with relevant forms where they can provide their information, sign documents (NDAs) and it optionally notifies the person they are visiting of their arrival.

Introduction

This TechNote covers the setup, configuration, and monitoring of the ClearPass extension for Teem LobbyConnect and the configuration of the ClearPass plugin in Teem.

This Extension serves two primary use-cases

Guest account creation upon Visitor Check In
Guest account deletion upon Visitor Check Out

With LCx hosted in the cloud and ClearPass sitting primarily on-prem, there are challenges in making these two applications communicate in real time so that a visitor gets guest WiFi credentials from ClearPass as soon as he registers on Teem’s LCx application. 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 have to 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’s available.

Before we proceed with the flow, we need to understand the concept of webhooks and skyhook.

What is a webhook?

What is skyhook?

As an overview, Teem LCx running in the cloud will send a webhook upon a Visitor CheckIn or a CheckOut event. This will communicate with Skyhook. The ClearPass extension configured and installed will maintain a persistent connection with Skyhook awaiting an event (Check In/ Check Out).

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 diagram below shows a pictorial overview of the components and how they interact with each other.

Pictorial view of ClearPass Policy Manager integration with Teem LobbyConnect

Configuration Steps

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

Step I: Register and request for a Skyhook tenant.

Step II: Configuration of Teem LobbyConnect for Integration.

Step III: Configuration of the Teem Extension.

Its assumed you have SMTP and SMS configured to allow ClearPass Guest to send account data to the Visitor/Guest.

Step I: Register and Request for a Skyhook Tenant ID

Step II: Configuring Teem LobbyConnect for ClearPass Integration

INFO

For the ClearPass Plugin to be available under 3rd Party Apps on Teem, please contact your Teem Account Manager. This is currently enabled upon request.

Below we cover the configuration required in the Teem environment. To aid the configuration of the extension it helps to collect a number of items from the email received above.

INFO

Setup and Configuration of Teem LobbyConnect is beyond the scope of this guide. Here we specify the steps necessary to configure ClearPass Plugin within the Teem LobbyConnect application.

You would require the following details on Teem for the config

Skyhook Webhook Posting URL
Teem Secret
ClearPass Expiration Time: Account expiration time for the guest checked in
SMS Gateway configured on ClearPass (optional)
SMTP server configured on ClearPass (optional)

Below are the configuration steps to follow:

Login to Teem using your credentials on www.teem.com
Click on Manage > Apps & Integration > 3rd Party Apps. Search for ClearPass by Aruba and click on Activate. You should see the following.

ClearPass Plugin within the Teem App

INFO

Ensure you select the correct Aruba plugin. Teem already integrates with Aruba Beacons and Sensors. Ensure you activate the ClearPass Plugin under User Management.

Once activated Click on Settings and use the details collected above

ClearPass Plugin Configuration Settings

ClearPass URL: The format of this URL would be similar to https://skyhook.clearpassbeta.com/api/skyhook/teem/<skyhook tenant>

Example: https://skyhook.clearpassbeta.com/api/skyhook/teem/3f5913f5-b4b0-4e38-8d53-b7425baabbcc

Secret: A shared secret that needs to be configured later in the ClearPass extension and must match what is configured here.

ClearPass Expiration Time: Directly controls the period of time the Visitor account can remain active in ClearPass Guest based upon the account creation time.

Send ClearPass SMS: Setting it to yes invokes ClearPass to send credentials for Guest login via SMS with the SMS Gateway configured on ClearPass.

Send ClearPass Email: Setting it to yes invokes ClearPass to send credentials for Guest login via Email with the SMTP Server configured on ClearPass.

Step III: Teem Extension Configuration

The default configuration used for extension is below

{

"logLevel": "INFO",

"verifySSLCerts": true,

"teemSecret": "",

"randomPasswordLength": 6,

"skyhookTenant": "",

"dbAccessToken": ""

}

Extension Configuration options

Configuration attribute	Description	Example/Values
logLevel	The logging level the extensions should use.	"DEBUG", "INFO", "WARN", "ERROR"
verifySSLCerts	Should the extension validate SSL certificates.	true/false
teemSecret	The secret configured previously in LCx ClearPass plugin.	SecretValueHere
randomPasswordLength	The length of the random password to generate for new Guest/Visitor accounts.	6
skyhookTenant	The Skyhook tenant ID.	965abd48-zzzz-aaaa-8164-xxxxxxxxxx
dbAccessToken	The access token for Skyhook.	LongRandomAccessTokenString

Configure the teemSecret, skyhookTenant and dbAccessToken and restart the extension.

A copy of the default Teem LobbyConnect Extension is shown above, this will need to be modified for your deployment. Include the teemSecret, skyhookTenant and dbAccessToken that will be specific to your environment. This needs to be requested per customer which is explained later in the document.

Select ‘Restart’ and click on Save Changes to restart the extension. Following the restart, click on Show Logs. You should see the following:

You can change the logLevel to DEBUG for detailed logs and troubleshooting or include the same before raising a TAC case if necessary.

Testing/Demo

Now that the components are all configured and ready to use, let’s walk through the experience from the user and administrator perspective. In order to do so, the first step for a visitor is to register using the LobbyConnect app running on an iPad or other smartdevice in the customer setup.

Configuring an iPad or any other device to assist customers with registration at front desk is beyond the scope of this document. Essentially, you download the LobbyConnect app from the appstore and use the activation code to register this device with your TEEM LobbyConnect tenant. Add a device for the Location in Teem using the Activation Code. Detailed steps are available here:

https://teem.com/support/eventboard-room-scheduling/how-to-add-move-or-delete-eventboard-devices#subarticleNum2

I. Visitor walks up to a tablet used for Registration

II. Visitor enters his details as shown below. It is important to enter the cell phone number with the country code, e.g. in the US prefix a ‘+1’ before your cell number, for India it is ‘+91’ and so on.

III. The next screen will ask for the details of the host or sponsor. A notification about the visitor’s arrival will be sent to this host via an email or SMS as configured within LobbyConnect.

IV. You may or may not be asked to take a picture. This depends on the setup used in Teem. This finishes the registration from the user perspective.

V. User should receive an email as well as an SMS with his credentials. Following is the snapshot of the email.

INFO

You can change the Receipt Template (Guest Manager Receipt) under Configuration > Receipts > Templates.

VI. After the visit, user can Check Out at the registration desk using the same Tablet. Type and Select your name. Click Next.

Now let’s see what happens in the backend from an administrator perspective.

I. Login to ClearPass Guest and go to Manage Accounts under Guest.

The new account has been created upon registration. Note the Expiration time, this should match with the setting configured in the ClearPass Plugin in Teem. In this example, it is set to 4 hours.

II. If you enable DEBUG and Click on Show Logs under Extension, you should see the following details as a part of the Check In event.

[2018-03-07T11:54:55.651] [DEBUG] teem - Event Details:

[2018-03-07T11:54:55.651] [DEBUG] teem - {

"auto_send_sms": true,

"last_name": "Bhatt",

"enabled": true,

"sponsor_name": null,

"first_name": "Arpit",

"sponsor_email": null,

"visitor_company": "Aruba",

"create_time": "2018-03-07T06:24:54.770198+00:00",

"dynamic_expire_time": 240,

"visitor_phone": "1911911911",

"auto_send_email": true,

"role_name": null,

"email": "arpit.bhatt@hpe.com",

"expire_timezone": "Asia/Kolkata"

}

[2018-03-07T11:54:55.651] [DEBUG] teem - {

"X-EventBoard-Event": "lobbyconnect-checkin-clearpass",

"X-EventBoard-ID": "afd0f9f9-db49-5f8a-8b91-71b4b4498faa",

"X-EventBoard-Signature": "9395711f8fe96319c36372093f80206f"

}

III. A similar log entry cab seen in the Teem app as well. Go to Manage > Apps & Integrations > 3rd Party Apps. Click on Settings and then select the Logs tab as shown below

IV. Upon Check Out, the User account will have been disabled, see this under Manage Accounts in ClearPass Guest.

V. The user’s WiFi session should also get disconnected automatically upon Check Out. This depends on the Policy configured for the Guest SSID. This configuration is beyond the scope of this document.

VI. You would see a Check Out event in the DEBUG logs.

Appendix A – Additional Diagnostics & Support

Extension logs and debugging

If there is a need to access the logs from inside the extension, turn on log collection from the API Explorer. Referencing the configuration previously used, adjust the "logLevel" to "DEBUG". In the new 6.7 GUI change the config and restart the extension as shown below. Logs can then be viewed from the ‘Show Logs’.

Alternatively, the config can be changed from the API Explorer. Remember after changing the logging level, the extension will need to be restarted for this change to take effect.

Here are a few examples of ’normal’ logs under DEBUG

[2018-03-07T12:46:05.538] [DEBUG] teem - Using CPPM API Url: https://172.17.0.1/api

[2018-03-07T12:46:05.538] [INFO] teem - Connecting to skyhook database...

[2018-03-07T12:46:05.538] [DEBUG] teem - Enabling skyhook advanced logging.

[2018-03-07T12:46:05.542] [DEBUG] teem - p:0: Browser went online.

[2018-03-07T12:46:05.547] [DEBUG] teem - p:0: Authenticating using credential: YYYYYYYYYYYYYYYYYYYYYYYYYYYY.eyJleHAiOjE1NTAwODAwMzEsInYiOjAsImQiOnsidWlkIjoiYzUwN2U2NGQtZjBhMS00NjQ3LWI0YjMtYWNlODQwNjA1YTM0IiwiZW1haWwiOiJ3aWxsLnNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-FudCI6ImEwYjdkZjQ2LTcxZWEtNDE1O11111111111111111111111111111111111-iOjE1MTg1NDQwMzF9.ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ

[2018-03-07T12:46:05.551] [DEBUG] teem - p:0: Listen called for /teem/XXXXXXXX-71ea-YYYY-YYYY-ZZZZZZZZZZZZZ default

[2018-03-07T12:46:05.554] [DEBUG] teem - p:0: Making a connection attempt

[2018-03-07T12:46:05.554] [DEBUG] teem - c:0:0: Connection created

[2018-03-07T12:46:05.556] [DEBUG] teem - c:0:0:0 Websocket connecting to wss://aruba-skyhook.firebaseio.com/.ws?v=5

[2018-03-07T12:46:06.684] [DEBUG] teem - c:0:0:0 Websocket connected.

[2018-03-07T12:46:06.692] [DEBUG] teem - c:0:0: Realtime connection established.

[2018-03-07T12:46:06.692] [DEBUG] teem - p:0: connection ready

[2018-03-07T12:46:06.693] [DEBUG] teem - p:0: reportStats {"c":{"sdk.js.2-4-2":1}}

[2018-03-07T12:46:06.693] [DEBUG] teem - p:0: {"r":1,"a":"s","b":{"c":{"sdk.js.2-4-2":1}}}

[2018-03-07T12:46:06.695] [DEBUG] teem - p:0: {"r":2,"a":"auth","b":{"cred":"YYYYYYYYYYYYYYYYYYYYYYYYYYYY.eyJleHAiOjE1NTAwODAwMzEsInYiOjAsImQiOnsidWlkIjoiYzUwN2U2NGQtZjBhMS00NjQ3LWI0YjMtYWNlODQwNjA1YTM0IiwiZW1haWwiOiJ3aWxsLnNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-FudCI6ImEwYjdkZjQ2LTcxZWEtNDE1O11111111111111111111111111111111111-iOjE1MTg1NDQwMzF9.ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ"}}

[2018-03-07T12:46:06.696] [DEBUG] teem - p:0: Listen on /teem/a0b7df46-71ea-4159-afd5-231001ab5922 for default

[2018-03-07T12:46:06.696] [DEBUG] teem - p:0: {"r":3,"a":"q","b":{"p":"/teem/ XXXXXXXX-71ea-YYYY-YYYY-ZZZZZZZZZZZZZ ","h":""}}

[2018-03-07T12:46:06.959] [DEBUG] teem - p:0: from server: {"r":1,"b":{"s":"ok","d":""}}

[2018-03-07T12:46:06.960] [DEBUG] teem - c:0:0: Primary connection is healthy.

[2018-03-07T12:46:06.960] [DEBUG] teem - p:0: from server: {"r":2,"b":{"s":"ok","d":{"auth":{"email":"will.smith@teem.com","tenant":" XXXXXXXX-71ea-YYYY-YYYY-ZZZZZZZZZZZZZ ","token":{"email":"w.s@t.com","tenant":" XXXXXXXX-71ea-YYYY-YYYY-ZZZZZZZZZZZZZ ","exp":1550080031,"app":"teem","iat":1518544031,"sub":"c507e64d-f0a1-4647-b4b3-ace840605a34","aud":"aruba-skyhook","auth_time":1518544031,"iss":"https://securetoken.google.com/aruba-skyhook"},"uid":"abc123abc123-XxXx-YyYy-ZzZz-abc123abc123","app":"teem"},"expires":1550080031}}}

[2018-03-07T12:46:06.962] [INFO] teem - Logged in to skyhook. Waiting for events...

[2018-03-07T12:46:06.962] [DEBUG] teem - p:0: from server: {"r":3,"b":{"s":"ok","d":{}}}

[2018-03-07T12:46:06.962] [DEBUG] teem - p:0: listen response {"s":"ok","d":{}}

Errors observed during configuration

Configuration error

[2018-03-07T11:41:29.940] [ERROR] teem - Error: Received message that failed hash validation, Skipping.

at processEvent (/src/app.js:292:38)

at /src/app.js:364:9

at /src/node_modules/firebase/lib/firebase-node.js:203:375

at ec (/src/node_modules/firebase/lib/firebase-node.js:52:165)

at ac (/src/node_modules/firebase/lib/firebase-node.js:31:216)

at bc (/src/node_modules/firebase/lib/firebase-node.js:30:1259)

at Ji.h.Ib (/src/node_modules/firebase/lib/firebase-node.js:220:287)

at Rh.h.Jd (/src/node_modules/firebase/lib/firebase-node.js:186:251)

at Fh.Jd (/src/node_modules/firebase/lib/firebase-node.js:176:364)

at wh.Jg (/src/node_modules/firebase/lib/firebase-node.js:174:280)

Issue: Unable to process the message as it fails hash validation. The configuration template used for extensions is sensitive. Ensure there are no human errors. Leading space in the Shared Secret used was the issue.\

Resolution: Have a coffee and avoid human errors

Accessing extension logs within ClearPass ‘Collect Logs’

In addition to the logging of messages that be examined in the extension as shown above, it’s possible to configure the extension to log messages so that they can be collected and examined via the Policy Manager ‘Collect Logs’ system function. This is extremely useful for Aruba TAC.

If there is a requirement for HPE Networking Aruba TAC to investigate a system issue, one of the items they regularly ask for is the system logs to aid with their diagnostic investigation. The ClearPass extension can write its logs such that they are available and can be collected with all other system diagnostics information when the ‘Collect Logs’ function is run. Remember that by default, the logLevel is set to INFO but TRACE, DEBUG, INFO, WARN, ERROR, FATAL can also be set. Any of the levels will display the information for the selected state and lower. For example, if INFO is selected, it will show messages for INFO, WARN, ERROR, FATAL.

After the Logs have been collected and exported from the system, expand the GZ file and locate the extension logs in the following location ‘PolicyManagerLogs->extension’ as shown below.

Extension logs location in 'Collect Logs' diagnostic GZ file

4 - Skyhook Generic Processor

Skyhook Generic Processor provides a simple method for customers to push data from a cloud app to an on-prem ClearPass using a webhook style interface.

Introduction and Overview

This TechNote covers how to deploy and configure the ClearPass ‘Skyhook Generic Processor’ Extension that provides a simple method for customers to push data from a cloud app to an on-prem ClearPass using a webhook style interface. For example, a use-case workflow may require a cloud enabled app to create Guest accounts, Devices or Endpoints within the ClearPass Guest framework.

You may think of it as optimizing several existing manual actions within an existing Help/Service Desk workflow that authorizes Guest accounts, Devices or Endpoints and then the operator has to access the ClearPass Guest Portal to manually create the Guest account, Device or Endpoint. Using this Extension, the workflow can now be simplified by automatically triggering the creation of a Guest account, Device or Endpoint by sending data in a webhook directly from the cloud app. This eliminates the requirement to login to the ClearPass Guest Portal to manually create the account, device or endpoint.

A real world example for this may be taking the input from a Cloud-based Ticketing system workflow and automatically creating the Guest account right from the cloud app, eliminating the second manual step for the Help/Service Desk to login and create the account within ClearPass – for example, ServiceNow or any other cloud app that can send data in a webhook.

The idea here is that this Integration opens up the possibilities of creativity to link cloud-apps with ClearPass as any attributes that are part of the (Guest, Device and Endpoint) REST API can be leveraged.

With apps hosted in the cloud and ClearPass sitting primarily on-prem, there are challenges in making these two applications communicate in real time so the desired output from the cloud app triggers an action and response within ClearPass. Traditionally the apps would communicate using APIs where an application would request information which is usually followed by a response. In order to get real-time information, the app would have to continuously poll or request the data, however that would not be a scalable solution. The solution for this is to use a webhook as it does not wait for a request to send information but rather sends the data as soon as it’s available.

Before we proceed with the flow, we need to understand the concepts of webhooks and Skyhook.

What is a webhook?

What is Skyhook?

Skyhook was developed to overcome the inability for cloud-based applications to send events [webhooks] directly into a ClearPass system that is typically deployed on the trust side of a corporate firewall. In short, it is a service that runs in the Cloud, developed and managed by HPE Aruba Networking. ClearPass nodes running on-prem, 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.

The cloud-based app will send a webhook to trigger a Guest, Device or Endpoint event and it will be consumed by Skyhook. The installed ClearPass ‘Skyhook Generic Processor’ Extension will maintain a persistent connection with Skyhook and process the cloud apps events in real-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.

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 the Skyhook Generic Processor Integration

Configuration Steps

The following steps are required to get this integration working:

Register and request a Skyhook Tenant ID
Install and configure the Skyhook Generic Processor Extension

INFO

Ensure you have SMTP and SMS configured to allow ClearPass Guest to send visitor account details to the Visitor/Guest.

Step 1: Register and Request for a Skyhook Tenant ID

Copy the skyhookTenant and the dbAccessToken to a text file. This will be used for configuration of the extension in ClearPass.

Skyhook Generic Processor Extension Configuration

The ClearPass Skyhook Generic Processor Extension communicates with your Skyhook tenant via REST API calls. The extension establishes and maintains a persistent connection to Skyhook where it continuously ingests data received into Skyhook from your cloud-enabled application. The extension configuration and supported data types are shown below.

For your convenience, a copy of the default Extension configuration.

Default Configuration

{

"logLevel": "INFO",

"verifySSLCerts": true,

"dbAccessToken": "********",

"skyhookTenant": "",

"useHeaderPreSharedKey": false,

"headerPreSharedKeyName": "X-Skyhook-PSK",

"headerPreSharedKeyValue": "",

"guestRandomPasswordLength": 5,

"guestDefaultRoleId": 2,

"guestSendRegistrationSms": false,

"guestSendRegistrationEmail": false,

"guestDefaultAccountExpireHrs": 2,

"deviceDefaultRoleId": 2,

"deviceDefaultAccountExpireHrs": 2,

"enableStats": false

}

ClearPass Skyhook Generic Processor Extension Configuration

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

At a minimum, the “dbAccessToken” and “skyhookTenant” need to be changed with values received in your registration email.

Below is an explanation of all of the configuration value pairs. The logLevel and verifySSLCerts should be left as their default settings unless advised by ClearPass TAC or your SE/Partner. Once you configure these parameters, you can start your extension. Any subsequent reconfiguration requires a restart of the extension.

Table 1: Skyhook Processor Extension-specific configuration parameters

Attribute	Description	Values/Examples
dbAccessToken	The Skyhook access token.	Null
skyhookTenant	The Skyhook tenant id.	Null
useHeaderPreSharedKey	When processing events, should a header pre-shared key be required and validated. When true, the headerPreSharedKeyName and headerPreSharedKeyValue must be populated or all requests will fail validation.	true/false
headerPreSharedKeyName	The header pre-shared key name. This is the name of an HTTP header sent with the request that contains the pre-shared key value. Default value is "X-Skyhook-PSK".	"X-Skyhook-PSK"
headerPreSharedKeyValue	The pre-shared validation key.	******************
guestRandomPasswordLength	When no password is sent with a new guest account, what should the default password length be?	5
guestDefaultRoleId	The Role ID to be used for new guest accounts.	2 (Guest)
guestSendRegistrationSms	Should SMS messages be sent for new guest registrations?	true/false
guestSendRegistrationEmail	Should email messages be sent for new guest registrations?	true/false
guestDefaultAccountExpireHrs	The default expire duration of new guest accounts. This can be overridden by including an expire_time value.	2 hours
deviceDefaultRoleId	The Role ID to be used for new device accounts.	2 (Guest)
deviceDefaultAccountExpireHrs	The default expire duration of new device accounts. This can be overridden by including an expire_time value.	2 hours

Supported Skyhook Datatypes

For each data type there are 3 possible actions, "update", "replace", or "delete".

INFO

For all actions guests require a username field, devices require a mac field and endpoints require a specific structure including mac_address and status.

Action Details

Action	Description
update	Creates the object if it doesn’t exist, otherwise updates the existing object information.
replace	Creates the object if it doesn’t exist, otherwise replaces the existing object.
delete	Deletes the specified matching item.

Data Types

Guests

Type	Sample Data	Details
Guests	{ "action": "update", "guest": { "username": "Guest.User@hpe.com", "email": "Guest.User@hpe.com", "expire_time": 1596240000, "enabled": true, "visitor_company": "", "visitor_name": "", "visitor_phone": "" } }	curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{tenantId}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-Skyhook-PSK: {PSK Value}' \ --data-raw '{ "action": "update", "guest": { "username": "Guest.User@hpe.com", "email": "Guest.User@hpe.com", "expire_time": 1596240000, "enabled": true, "visitor_company": "", "visitor_name": "", "visitor_phone": "" } }'

Type

Sample Data

Details

Guests

{
  "action": "update",
  "guest": {
    "username": "Guest.User@hpe.com",
    "email": "Guest.User@hpe.com",
    "expire_time": 1596240000,
    "enabled": true,
    "visitor_company": "",
    "visitor_name": "",
    "visitor_phone": ""
  }
}

curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{tenantId}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Skyhook-PSK: {PSK Value}' \
--data-raw '{
  "action": "update",
  "guest": {
    "username": "Guest.User@hpe.com",
    "email": "Guest.User@hpe.com",
    "expire_time": 1596240000,
    "enabled": true,
    "visitor_company": "",
    "visitor_name": "",
    "visitor_phone": ""
  }
}'

INFO

Any attributes that are part of the Guest REST API can be included in the “guest” object detail..

Devices

Type	Sample Data	Details
Devices	{ "action": "update", "device": { "mac": "01-02-03-04-05-06", "email": "Guest.User@hpe.com", "expire_time": 158708348, "enabled": true, "visitor_company": "", "visitor_name": "", "visitor_phone": "" } }	curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{tenantId}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-Skyhook-PSK: {PSK Value}' \ --data-raw '{ "action": "update", "device": { "mac": "01-02-03-04-05-06", "email": "Guest.User@hpe.com", "expire_time": 158708348, "enabled": true, "visitor_company": "", "visitor_name": "", "visitor_phone": "" } }'

Type

Sample Data

Details

Devices

{
  "action": "update",
  "device": {
    "mac": "01-02-03-04-05-06",
    "email": "Guest.User@hpe.com",
    "expire_time": 158708348,
    "enabled": true,
    "visitor_company": "",
    "visitor_name": "",
    "visitor_phone": ""
  }
}

curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{tenantId}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Skyhook-PSK: {PSK Value}' \
--data-raw '{
  "action": "update",
  "device": {
    "mac": "01-02-03-04-05-06",
    "email": "Guest.User@hpe.com",
    "expire_time": 158708348,
    "enabled": true,
    "visitor_company": "",
    "visitor_name": "",
    "visitor_phone": ""
  }
}'

INFO

Any attributes that are part of the Device REST API can be included in the “device” object detail.

Endpoints

Type	Sample Data	Details
Endpoints	{ "action": "update", "endpoint": { "mac_address": "01-02-03-04-05-06", "status": "Known or Unknown", "attributes": { "Source": "", "My Custom Attribute": "Attribute Value" } } }	curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{tenantId}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-Skyhook-PSK: {PSK Value}' \ --data-raw '{ "action": "update", "endpoint": { "mac_address": "01-02-03-04-05-06", "status": "Known or Unknown", "attributes": { "Source": "", "My Custom Attribute": "Attribute Value" } } }'

Type

Sample Data

Details

Endpoints

{
  "action": "update",
  "endpoint": {
    "mac_address": "01-02-03-04-05-06",
    "status": "Known or Unknown",
    "attributes": {
      "Source": "",
      "My Custom Attribute": "Attribute Value"
    }
  }
}

curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{tenantId}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Skyhook-PSK: {PSK Value}' \
--data-raw '{
  "action": "update",
  "endpoint": {
    "mac_address": "01-02-03-04-05-06",
    "status": "Known or Unknown",
    "attributes": {
      "Source": "",
      "My Custom Attribute": "Attribute Value"
    }
  }
}'

INFO

Any attributes that are part of the Endpoint REST API can be included in the “endpoint” and “attribute” object details.

How to test the Integration using cURL

This Tech Note was written to illustrate how a Generic cloud-based application could create or manipulate Guest accounts, Devices or Endpoints. Most apps would provide the capability to send or POST data in a webhook json payload and within this guide we use cURL to send the data.

The following example uses a widely deployed command line tool found in many operating systems call cURL. More details on the cURL client can be found on the following website http://curl.haxx.se/

The following three use-cases will demonstrate how you can update, replace or delete Guest accounts, Devices and Endpoints.

Creating a Guest Account

For your convenience, copy the following text to paste into your terminal or into Git Bash terminal in Windows.

curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{Insert-your-tenantId}' \ --header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Skyhook-PSK: {PSK Value}' \

--data-raw '{

"action": "update",

"guest": {

"username": "guest.user@hpe.com",

"email": "guest.user@hpe.com",

"expire_time": 1596240000,

"enabled": true,

"visitor_company": "HPE Aruba Networking",

"visitor_name": "Guest User",

"visitor_phone": "5556789"

}

INFO

Try changing the “action” value pair from “update” to either “replace” or “delete” and verify the results in ClearPass

Verifying the Cloud-based Applications creation of Guest Accounts

To examine the result of the webhook sent by your cloud-app, go to ClearPass Guest and navigate to ‘Guest’ ** ‘Manage Accounts’ and you will see the account was created. Verify by clicking on “Show Details” as shown below.

Creating a MAC Device

For your convenience, copy the following text to paste into your terminal or into Git Bash terminal in Windows.

curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{Insert-your-tenantId}' \ --header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Skyhook-PSK: {}' \

--data-raw '{

"action": "update",

"device": {

"mac": "F4-2E-7F-C6-56-0C",

"sponsor_name": "admin",

"expire_time": 0,

"enabled": true,

"visitor_company": "HPE Aruba Networking",

"visitor_name": "AP515 - CSE Lab"

}

INFO

Try changing the “action” value pair from “update” to either “replace” or “delete” and verify the results in ClearPass

Verifying the Cloud-based Applications creation of a MAC Device

To examine the result of the webhook sent by your cloud-app, go to ClearPass Guest and navigate to ‘Devices’ ** ‘Manage Devices’ and you will see that it was created. Verify by clicking on “Show Details” as shown below.

Creating an Endpoint

For your convenience, copy the following text to paste into your terminal or into Git Bash terminal in Windows.

curl --location --request POST 'https://skyhook.clearpassbeta.com/api/skyhook/processor/{Insert-your-tenantId}' \ --header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Skyhook-PSK: {}' \

--data-raw '{

"action": "update",

"endpoint": {

"mac_address": "01-02-03-04-05-06",

"status": "Known",

"attributes": {

"Source": "Scotts-Cloud-App-Testing",

"My Custom Attribute":"MyCustomAttributeValue"

}

INFO

Try changing the “action” value pair from “update” to either “replace” or “delete” and verify the results in ClearPass

Verifying the Cloud-based Applications creation of an Endpoint

To examine the result of the webhook sent by your cloud-app, go to ClearPass Policy Manager and navigate to ‘Configuration’ ** ‘Identity’ ** ‘Endpoints’ and you will see that it was created – you can find it quickly with the MAC Address Filter. Verify by clicking on the “MAC Address” to see the general Endpoint status and ‘Attributes’ as shown below.

Appendix A – Troubleshooting and Support

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

Check API Access Application Control restrictions

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.