How to Integrate Envoy with ClearPass?

MVP Expert
MVP Expert


  • Please ensure your ClearPass deployment is running 6.6 or newer as ClearPass Extensions were made available as part of the 6.6 release
  • CPPM will require outbound access to the internet using HTTPS (TCP port 443).
  • SMS as well SMTP gateway should be configured.

Before deploying any ClearPass Extensions, we have to decide which node within ClearPass cluster is most appropriate to host the extension. In a single node ClearPass deployment where there is only a publisher the choice is pretty simple. In multi-node clusters, the extension can be hosted on either the publisher or any of the subscriber nodes. If the extension is hosted on a subscriber node and API access to the publisher is required, this will be internally proxied by the Extensions framework. Extensions can create some additional load on the chosen ClearPass node, consideration should be given to the node which has comparatively less load.


Envoy is a customizable iPad app focused improving the visitor sign in and registration process for enterprise offices, schools and other venues.

It collects the visitor information, execute NDA's, snap photos of the visitor registering and take care of notifying the employee their guest has arrived.

Envoy ClearPass [CPPM] registration leverages users to have hassle free internet access after registration.



In order to manage your ClearPass Extensions, an API Client needs to be created with an Operator profile and should be granted to appropriate API privileges within ClearPass. as shown below:

  • Please navigate to ClearPass Guest >> Administration >> API Services >> API Clients and hit “Create API clients” as shown below:

  • After which you can specify client ID which need to be unique string, Operator profile which applies role-based access control to authorized API client as well as Grant type which can be username and password or Client Credentials.

  • After creating the API client you can generate an access token which would be used by the API Extensions in the upcoming steps.
  • You can access API extensions by clicking “API Explorer > Extensions” to the top right by navigating to Administration à API Services à API Clients or by navigating to following URL: https://<CPPM-IP/Hostname>/api-docs/Extension-v1
  • Enter the Access token generated in the above step near the Authorization header dialogue box which will look like: “Bearer -valid-access-token”
  • Once we have the access token in place, we will make a quick API call to verify that all the privileges have been successfully setup in the API Client definition.
  • On the API Explorer page select the Instance group of APIs and click on the GET method.

  • Towards the bottom of the GET instance method you will find a “Try it now!” button please click it which should yield result in a 200 response code and output should be similar to what you see below:

  • In order to install Envoy + ClearPass Extension you need to have the store ID which is not publically published as of now. If you don’t have it please get in touch with your Aruba representative to fetch it.
  • Once we have the store ID we can install the extension by navigating to the API Explorer page select the Instance group of APIs and click on POST method.
  • Scrolling down the documentation you can see that this method is used to create a new local instance of an Extensions. Please enter the store ID in the body parameter specified and hit Try it Out.

  • Clicking on is button should result in a 201 Response code and an output as shown below:

  • Extension would be being prepared for download in the background, please make a note of the instance id has been allocated to this installation.
  • This id can now be used to manage the local installed instance of the Extension, including checking the status of the extension, updating its configuration, displaying its logs etc.
  • Now that the download and install of the Extension has been initiated, next we need to check if that the install completed successfully.
  • Please hit on GET /extension/instance/{id} in the API explorer specify the ID which you have fetched from the previous step in the ‘id’ header and hit Try it Out. This should yield result in 200 response code with status as “Created” as shown below:

Next we need to configure the extension for which we need few information from Envoy and Skyhook.

Configuration of Skyhook API Key

The Skyhook web service is used as a data broker between cloud initiated events and locally deployed ClearPass Extension. In order to access the events associated with your deployment, an API key is required and needs to be configured as part of ClearPass Extension. We can request for Skyhook API key here:

Configuration on Envoy:

  • Please login to Envoy dashboard. First we need to fetch the API key that need to be configured as part of ClearPass Extension.
  • Please browse to Settings >> Account >> Advanced we can find listing for API key. Please save this API key.

  • Next we need to configure the Envoy to communicate with Skyhook.
  • Browse to Settings >> Integrations and scroll down to ‘Roll Your Own’ and click on the Install button for Webhooks Integration.
  • From the Webhooks configuration page, the Skyhook URL received from the Skyhook API request in Step 3 needs to be pasted in the *Your Webhook URL* dialogue box. It will look as follows:{tenant}
  • Similarly please configure ClearPass Integration from settings Integration:

  • Click on Configure on ClearPass Integration and make a note of the Install token and mention the tenant ID which was specified when requesting for Skyhook API.


Configuring Envoy Extension on ClearPass

  • In the API Explorer Screen please click on InstanceConfig and hit GET /extension/instance/{id}/config
  • Please provide the Envoy + CPPM Extension ID which we had fetched earlier during installation of extension in the header which has “id” and click “Try it Out”

  • Clicking on it will provide default configuration with response code 200 as shown below



"skyhookTenant": "customer",

"dbAccessToken": "7INXYr1YUixxxxxvSawdABPTmeEC3xxxxxxxgjFmMzIwY2U1NGJlIxxxxxxxWwiOiJjY",

"envoyApiKey": "27f80f8aaaea8974d9c7ca43e69xxxxb5xxxx85910",

"cppmPublisher": "",

"cppmAccessToken": "3dd3019aaea8974d9c7ca43e69xxxxb5xxxxx8d3",

"countryIsoCode": 'US',

"cppmDefaultExpiryHrs": 8,

"cppmGuestRoleName": "[Guest]",

"cppmGuestRoleId": 2,

"cppmGuestSmsReceipt": true,

"cppmGuestEmailReceipt": true,

"debug": false,

"dbLogging": false


A brief description of each attribute is provided below:

  • skyhookTenant - the allocated organization identifer received from your Skyhook API request (Step 3)
  • dbAccessToken - the API key received from your Skyhook API request
  • envoyApiKey - the API key recovered from the Envoy Dashboard (Step 4)
  • cppmPublisher - (Optional) IP Address of ClearPass Publisher if the target ClearPass is not the same as the one hosting the Extension
  • envoyInstallToken- Token fetched when creating ClearPass Integration on Envoy.
  • cppmAccessToken - (Optional) The OAuth2 access token associated with the ClearPass Publisher above
  • countryIsoCode - The two alpha character ISO country code to default the recevied phone numbers from Envoy, if the number does not include the international country code eg. 4082274500 will become +14082274500
  • cppmDefaultExpiryHrs - defines the numbers of hours before an Envoy sponsored guest account expires
  • cppmGuestRoleName - default name for Guest role in the ClearPass deployment
  • cppmGuestRoleId - default id for Guest role in the ClearPass deployment
  • cppmGuestSmsReceipt - auto send sms guest receipt
  • cppmGuestEmailReceipt - auto send email guest receipt
  • debug - enable debug log generation
  • dbLogging - enable Skyhook debugging


  • Please copy the default output and modify it with the fields which was fetched form Envoy and Skyhook.
  • After the values are modified please hit “Put” on the InstanceConfig and specify the ID along with the modified configurations in the Body section and hit “Try it Out”.

  • Clicking on Try it Out button should result in a 204 No Content Response to indicate the request to update the configuration was successful.
  • Now that the default or current configuration has been updated, these changes will not take effect until the Extension is restarted.
  • Please hit on ‘InstanceRestart’ and hit “Post”, specify the ID and and click "Try it Out".
  • It should result in a 204 No Content Response, showing the service has restarted successfully.
  • We can check the status of the Extension, by browsing to Instance GET /extension/instance/{id} specifying the ID and hitting Try it Out.
  • You should see the state as running as shown below:



Now we could try registering a user on Envoy iPad app and that should subsequently create a user on ClearPass Guest which could be verified from ClearPass Guest >> Guest >> Manage Accounts.

This user credentials can be used by Guest to login to guest network.

We should see following entry in application log when a user is created.





Version history
Revision #:
4 of 4
Last update:
‎03-08-2017 01:22 AM
Updated by:
Labels (1)

The Envoy integration has many problems with it. I've spent, collectively, 40+ hours working with engineers on this. It's far from being a reliable production solution.

Search Airheads
Showing results for 
Search instead for 
Did you mean: