Teem LobbyConnect

  15 minute read  

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

1. Guest account creation upon Visitor Check In

2. Guest account deletion upon Visitor Check Out

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.

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 Wifi requirements.

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?

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

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

• VMware vSphere Hypervisor (ESXi) 7.0 U3c and 8.0

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

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

ClearPass Installation and Deployment Guide

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

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

ClearPass Extensions

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

Installing Extension

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

Access to the extension store

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

Installing the Extension from Store

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

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

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

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

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

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

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

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

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

Extensions and web proxy support

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

Extensions and IP address configuration support

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

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

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

Pictorial View of the Integration

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

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

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/

Step II: Configuring Teem LobbyConnect for ClearPass Integration

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.

You would require the following details on Teem for the config

1. Skyhook Webhook Posting URL

2. Teem Secret

3. ClearPass Expiration Time: Account expiration time for the guest checked in

4. SMS Gateway configured on ClearPass (optional)

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

  

  
  
  

• Once activated Click on Settings and use the details collected above
  
  

  

  
  
  

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.

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

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