Configuring a Custom-Hosted Splash Page to Work with the Meraki Cloud
Most of Cisco Meraki's customers who need a captive portal (UAM) authentication system on their wireless networks use the customizable splash pages that are hosted by Meraki's cloud and configured in the Meraki dashboard.
However, some network administrators may prefer to host a captive portal page on their own servers, a feature we refer to as EXCAP. This document describes how to get started plus describes the interface between the captive portal server and the Meraki cloud controller in both click-through and sign-on cases.
Note: This feature is for advanced users and will require the ability to parse HTTP GET parameters in order to build a grant or login URL. Knowledge of HTML alone is not sufficient; you will also be required to have server-side scripting enabled.
For an explanation of data flow and necessary network configurations to allow communication with the cloud, please refer to our whitepaper on the subject.
Meraki Support cannot provide any assistance in debugging scripts if issues occur.
Configuration
This section outlines the configuration in the Meraki dashboard necessary to direct new users to your web server hosting a custom splash page.
Configure Access Control
- In the dashboard, navigate to Wireless > Configure > Access control.
- Select the SSID you want to configure from the SSID drop-down.
- Under Security, choose Open (no encryption), or Pre-shared key (PSK).
- Under Splash page, choose Click-through or Sign-on with and choose one of the options from the drop-down menu.
- Under the Advanced splash settings subsection, set Walled garden to Enabled and enter the public IP address of your web server. The address specified needs to be the public-facing IP address of the web server hosting the splash page, not the local LAN IP; the actual web page request comes from the dashboard, not the local devices.
- Click Save.
Enabling a Custom-Hosted Splash page on the Meraki Cloud
- In the dashboard, navigate to Wireless > Configure > Splash page.
- Select the SSID you want to configure from the SSID drop-down.
- Under Custom splash URL, select the radio button Or provide a URL where users will be redirected:
- Enter the URL of your custom splash page (e.g. http://yourwebsite.com/yourscript.php).
- Click Save changes.
PHP Scripting – Explanation and Theory
This section describes the process by which a user goes through a splash page, including how PHP can be used to provide a custom experience.
Click-through based splash page
- When a client connects to your network, a web browser is opened with an HTTP-based request (ie. http://google.com).
- Assuming you have successfully completed the configuration on the Meraki cloud in the steps above the Meraki access points (AP) in your network will intercept this request and redirect the user through the Meraki cloud to the custom URL you specified. The user should be directed to a URL similar to the following string:
http://yourwebsite.com/clickthrough....xx:xx:xx:xx:xx
Assuming you have correctly added the web server's IP to the walled garden, the user will be viewing the splash page. Note the extra parameters appended to the URL. It is critical that your web server detects and makes use of these parameters, as they indicate how to grant access. You might choose to store these parameters in a session or otherwise save them for later use.
Note: If your browser enters an infinite redirect loop, check your walled garden settings and ensure your web server's IP has been added to the walled garden.
- At this point, you can interact with the user however you wish. You might require them to agree to your terms of service, complete a form, or watch an advertisement. It is important to note that the user can fetch any web content within your walled garden.
- Once you are prepared to grant access to the user, you must forward certain parameters you can gather from the URL in step 2 above. Specifically, you must forward the user to the following URL:
GET['base_grant_url'] + "?continue_url=" + GET['user_continue_url']
Where the following parameters are extracted from the user’s original query or specified by you:
- base_grant_url = https://n##.network-auth.com/splash/grant
- user_continue_url = http://google.com
In order for the ?continue_url parameter to function, the "Where should users go after the splash page" option in the dashboard must be set to "The URL they were trying to fetch."
Depending on the device type, this option is available in the following locations:
- MR - Wireless > Configure > Splash page > Splash behavior
- MX - Security & SD-WAN > Configure > Splash page > Splash behavior
In the case of the example above the assembled URL would be:
https://n##.network-auth.com/splash/...p://google.com
Note: Your URL may be different than the above example. It is dynamic and you should therefore never hard-code the grant URL.
- The Meraki cloud grants access on the AP and redirects the user to continue to the URL (ie. http://www.google.com).
- Advanced: Network operators can optionally specify the length of the session they are granting. To do so include an extra GET parameter with name "duration."
For example:
GET['base_grant_url'] + "?continue_url=" + GET['user_continue_url'] + "&duration=3600" (to grant access for one hour).
Please ensure the Splash frequency option configured in the dashboard matches the duration provided in the GET request. If there is a mismatch, the lower time value will be used.
For additional info, please reference our example Click-through Splash page code. The script is in its simplest form, but it's a working script and can be readily uploaded to your host for testing or use.
Sign-on based splash page
- When a client connects to your network a web browser is opened with an HTTP-based request (ie. http://google.com).
- Assuming you have successfully completed the configuration on the Meraki cloud in the steps above the Meraki access points (AP) in your network will intercept this request and redirect the user through the cloud to the custom URL you specified. The user should be directed to a URL similar to the following string:
http://yourwebsite.com/clickthrough?continue_url=http%3A%2F%2Fgoogle.com...
- Assuming you have correctly added the web server's IP address to your walled garden (step I-5), the user will be viewing your splash page (Note the extra parameters appended to the URL). It's critical that your web server detects and makes use of these parameters as they indicate how to grant access. You might choose to store these parameters in a session or otherwise save them for later use.
Note: If your browser enters an infinite redirect loop, check your walled garden settings and ensure your web server's IP was added to the walled garden.
- At this point, you can interact with the user however you wish. You might require them to agree to your terms of service, complete a form, or watch an advertisement. It is important to note that the user can fetch any web content within your walled garden.
- In order to collect logon credentials, you will need to create an HTML based form that collects and then submits these to the login URL. In its simplest form this could look similar to the code below:
<html> <head> <title>Internet Access Login</title> </head> <body> <h2>Internet Access Login</h2> <form method=POST action="<? urldecode(GET['login_url']) ?>"> <input type="hidden" name="success_url" value="<? urldecode(GET['continue_url']) ?>" /> Username: <input type ="text" name="username" /> Password: <input type ="text" name="password" /> <input type="submit" value="Login" /> </form> </body> </html>
In the above example the code inside <? ?> is executed via the server-side. The login_url parameter is an opaque string used by the Meraki cloud for authentication and security. It is subject to change and should not be hard-coded.
- The user will be prompted (per your custom-hosted page) to enter their credentials and then submit the form to the Meraki cloud.
- The Meraki cloud will then send a RADIUS access-request message to the configured RADIUS server which will then receive an Access-accept message (assuming the account is valid and grants access to the AP as appropriate).
- In a successful sign-on, the Meraki cloud redirects the user to the provided success URL. On failure, the user is instead redirected to the original captive portal URL. If the RADIUS server responds with an error the user will be presented with the error contained in the "error_message" parameter.
Forcing a User Back to the Splash Page
If a device should be forced back through the splash, simply clear that device's splash authorization. The AP will then send the client through the splash page the next time it initiates an HTTP flow.