First Published: October 10, 2019

This document describes how to configure Enterprise Captive Portal.

Overview

Cisco Digital Network Architecture (DNA) Spaces allows customers to have their own portals to onboard end users who connect to Wi-Fi. This is achieved by bridging Cisco DNA Spaces Captive Portal Runtime (also referred to as runtime or captive portal container), with the customers' own onboarding portal (enterprise portal). Runtime abstracts the nuances of the Captive Portal behavior across browsers and OS versions. Customers' onboarding portal is expected to implement the workflow required to onboard a user.

When users connect to the SSID at the location, the controller redirects them to Cisco DNA Spaces runtime. Runtime resolves the rule configured for the SSID or the location and loads the enterprise portal in an iframe, which is of the same size as that of CNA (Captive Network Assistant)/browser. At the time of loading, the following parameters are passed to the enterprise portal:

  • client_mac: MAC address of the end user's device.

  • client_ip: IP address of the end user’s device.

  • client_id: Unique identifier, which Cisco DNA Spaces uses to identify the device; also known as device subscriber ID.

  • location_id: ID of the location node in the Cisco DNA Spaces location hierarchy.

Apart from the above fields, runtime also passes all the location metadata information defined in the location hierarchy as key value pairs. A sample URL is shown below: 

https://example.com/splash?client_mac=00:00:00:00:00:00&client_ip=10.10.0.1&client_id=device-ert123ert123&location_id=10000101&state=California&country=US

When the user flow is completed in enterprise portal, the portal container expects the enterprise portal to send a message as shown below to initiate internet provisioning. 

window.parent.postMessage({start_provisioning : true, landing_page : <land-ing_page_url>}, '*');

The above message triggers the internet provisioning process in the captive portal container. After the internet provisioning is completed, users are directed to the landing_page provided in the above message. If the landing page URL is not specified, runtime falls back to the enterprise portal home page. If the controller fails to provision internet or if the runtime gets an error response, the home page is reloaded with all the default parameters in the URL along with another parameter p_status, which have value set to false. As expected, p_status is true in case of successful internet provisioning case.

Sample Flow

  1. When users connect to the SSID at a location, the network controller redirects them to the Cisco DNA Spaces Captive Portal URL, which is configured in the network controller. To get the Cisco DNA Spaces Captive Portal URL and to configure the same in the controller, see Cisco DNA Spaces Configuration Guide.

  2. When the captive portal loads, the iframe is loaded with the configured enterprise portal URL, with parameters client_id,client_ip, client_mac, location_id,, and all the available location metadata. For the initial loading, the parameter p_status is false as internet is not yet provisioned.

  3. After the user-flow is completed in the enterprise portal, the portal sends a message to the parent iframe container, and the parent sends a request to the controller to provision internet for the users.

  4. When the callback is received from the controller, the iframe is loaded with the landing page (or home page if the landing page is not provided) with default parameters (those parameters present in the home page loading). p_status is true or false based on the internet provisioning status.

Support for Analytics

The platform has support for analytics and enterprise portals can send logs as messages to the captive portal container. Currently, menu clicks and page load events can be tracked as shown below: 

window.parent.postMessage({log_action: { type : “CLICK”, sub_type : “Menu” url : <clicked_url>, item : <menu_name>}}), '*'); 
 
window.parent.postMessage({log_action:  { type : “LOAD”, sub_type : “Screen”, url : <page_url>}}), '*');

Note

  • Even though any web page, which allows embedding in an iframe, can be used with Cisco DNA Spaces Enterprise Captive Portal, we recommend the enterprise portal to load all assets (scripts, stylesheets, images and deep links, and so on) from the same domain or restrict them to very few domains. This is considering the number of domains and IPs, which need to be added to ACLs in controller for the enterprise portal to load before internet is available to the users.

  • The landing page are not loaded for Android devices if the portal is loaded in Captive Network Assistant, as the same is shut down when the internet is successfully provisioned.

  • Currently, there is no support to configure the enterprise captive portal through dashboard. To configure one, send the enterprise captive portal home page URL to Cisco DNA Spaces Support Team (cisco-dnaspaces-support@external.cisco.com.

Support for Data Exchange

Support is available for data exchange between Enterprise Captive Portal and Cisco DNA Spaces by posting a message to the parent window from the Enterprise Captive Portal.

Saving Data to Cisco DNA Spaces Database

window.parent.postMessage({action: 'set_device_property',
 key : 'device_last_visit_date', value : '2019-Sep-01'}, '*');

Optionally, you can check the incoming message from the parent window to capture the result of the Set operation performed with the preceding posted message. 

function incomingMessageHandler(event) {
var data = event.data;
}
window.addEventListener("message", incomingMessageHandler);

The data received in the case of the preceding operation is as follows:

{ status: "success”, id: "device-az6cebmfk9Jic1oKaSz2", action:
 "set_device_property, key : 'device_last_visit_date', value : '2019-Sep-01'}

The status is either success or failure. In the case of a failure, reason is sent in the response object.

The id corresponds to the device ID against which the Save operation is performed. This ID remains the same for a device irrespective of the captive portal. The action, key, and value are the same as you passed in the Save operation. This helps you to identify which Save operation has failed and which one has succeeded, in the case of multiple Save operations performed concurrently.

Retrieve Data from Cisco DNA Spaces Database

Similarly, you can get the value saved against a key using the following messaging:

window.parent.postMessage({ action: 'get_device_property', key: 'device_last_visit_date'}, '*');

The data retrieve API sends back a message to Enterprise Captive Portal, which is similar to the response described earlier for the Save operation. Likewise, the Retrieve operation also sends the data in the message handler function. In this case incomingMessageHandler. Following is the message that the Enterprise Captive Portal receives in the handler (data) for the preceding Get action. 

status: "success, action: "get_device_property, key: “device_last_visit_date", value: "'2019-Sep-01"}

The status can be success or failure, and the action and key are the same as used in the posted message. You will receive the data saved against the key in the value.

Support for Creation of User Entity

Support is available for creation of user entity for Enterprise Captive Portals. This is done in the same way that is used for existing data exchange by posting a message to the parent window from the Enterprise Captive Portal.

Using a User ID

window.parent.postMessage({ action: ”create_user”, key: ”userId”, value:”<enterprise_id>” }, '*');
Using a Mobile Number
window.parent.postMessage({ action: 'create_user', key: "mobilenumber", value: '+19876543211' }, '*');

Using an E-mail ID

window.parent.postMessage({ action: 'create_user', key: "email", value: 'username@domain.com' }, '*');

Optionally, Enterprise Captive Portal can subscribe for messages from the parent window to capture the result of the user entity creation operation performed. 

function incomingMessageHandler(event) {
var data = event.data;
}
window.addEventListener("message", incomingMessageHandler);

The data received in case of the create user entity is as follows: 

{status:“success”,
        id:“user-ba5dfanej8Kjd2pLbTz1”, action:"create_user”,
        key:“userId/email/mobilenumber”, value:'<provided_value>'}

The status will be success or failure. In case of failure, data will have reason which explains the reason for failure. The id corresponds to the user entity unique ID in the Cisco DNA Spaces database. The action, key and value are the same that was passed in the Create User operation.

Landing Page Parameters

When the breakout happens in the landing page, the URL is appended with the following parameters (considering that they are not already present) :

  • client_mac: MAC address of the end user's device.

  • client_ip: IP address of the end user’s device.

  • client_id: Unique identifier (device subscriber ID) which Cisco DNA Spaces uses to identify the device.

  • location_id: ID of the location node in Cisco DNA Spaces location hierarchy.

  • p_status: A flag which is set to false by default. It is set to true when the end user’s device is provisioned with internet.

Apart from the above fields, runtime also passes all the location metadata information defined in the location hierarchy as key value pairs. A sample URL for when users are provisioned with the internet is as follows:

https://example.com/splash?client_mac=00:00:00:00:00:00&client_ip=10.10.0.1&client_id=device-ert123ert123&p_status=true &location_id=10000101&state=California&country=US

Additional Enhancements

  • Support to send notifications to an API endpoint using Trigger API.

  • Support to tag the Captive Portal Users based on their actions.