Ruckus SmartZone 100 And Virtual Essentials Hotspot WISPr Reference Guide Smart Zone 3.6 (SZ100/v SZ E) SZ100VSZE 36 Rev A 20171110

SmartZone 3.6 Hotspot WISPr Reference Guide (SZ100/vSZ-E) SZ100VSZE-36-HotspotWisprGuide-RevA-20171110

2017-11-17

User Manual: Ruckus SmartZone 3.6 Hotspot WISPr Reference Guide (SZ100/vSZ-E)

Open the PDF directly: View PDF PDF.
Page Count: 40

Supporting SmartZone 3.6
REFERENCE GUIDE
Ruckus SmartZone 100 and
Virtual SmartZone Essentials
Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A
Publication Date: November 2017
Copyright Notice and Proprietary Information
Copyright 2017 Brocade Communications Systems, Inc. All rights reserved.
No part of this documentation may be used, reproduced, transmitted, or translated, in any form or by any means, electronic, mechanical,
manual, optical, or otherwise, without prior written permission of or as expressly provided by under license from Brocade.
Destination Control Statement
Technical data contained in this publication may be subject to the export control laws of the United States of America. Disclosure to
nationals of other countries contrary to United States law is prohibited. It is the reader’s responsibility to determine the applicable regulations
and to comply with them.
Disclaimer
THIS DOCUMENTATION AND ALL INFORMATION CONTAINED HEREIN (“MATERIAL”) IS PROVIDED FOR GENERAL INFORMATION
PURPOSES ONLY. BROCADE and RUCKUS WIRELESS, INC. AND THEIR LICENSORS MAKE NO WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, WITH REGARD TO THE MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, OR THAT THE MATERIAL IS ERROR-FREE,
ACCURATE OR RELIABLE. BROCADE and RUCKUS RESERVE THE RIGHT TO MAKE CHANGES OR UPDATES TO THE MATERIAL AT
ANY TIME.
Limitation of Liability
IN NO EVENT SHALL BROCADE or RUCKUS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL
DAMAGES, OR DAMAGES FOR LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY YOU OR ANY THIRD PARTY, WHETHER
IN AN ACTION IN CONTRACT OR TORT, ARISING FROM YOUR ACCESS TO, OR USE OF, THE MATERIAL.
Trademarks
Ruckus Wireless, Ruckus, the bark logo, BeamFlex, ChannelFly, Dynamic PSK, FlexMaster, Simply Better Wireless, SmartCell, SmartMesh,
SmartZone, Unleashed, ZoneDirector and ZoneFlex are trademarks of Ruckus Wireless, Inc. in the United States and in other countries.
Brocade, the B-wing symbol, MyBrocade, and ICX are trademarks of Brocade Communications Systems, Inc. in the United States and in
other countries. Other trademarks may belong to third parties.
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
2 Part Number: 800-71571-001 Rev A
Contents
Preface..........................................................................................................................................................................................................5
Document Conventions..........................................................................................................................................................................5
Notes, Cautions, and Warnings.......................................................................................................................................................5
Command Syntax Conventions..............................................................................................................................................................5
Document Feedback..............................................................................................................................................................................6
Ruckus Product Documentation Resources........................................................................................................................................... 6
Online Training Resources...................................................................................................................................................................... 6
Contacting Ruckus Customer Services and Support..............................................................................................................................7
What Support Do I Need?...............................................................................................................................................................7
Open a Case...................................................................................................................................................................................7
Self-Service Resources................................................................................................................................................................... 7
About This Guide.......................................................................................................................................................................................... 9
Overview................................................................................................................................................................................................ 9
Terminology............................................................................................................................................................................................9
Web Interface Configuration Overview......................................................................................................................................................... 11
Overview.............................................................................................................................................................................................. 11
Request Format................................................................................................................................................................................... 12
Controller Web Interface Configuration................................................................................................................................................. 13
JSON Commands - User Online Control..................................................................................................................................................... 15
Overview.............................................................................................................................................................................................. 15
Request Authentication - Asynchronous Login..................................................................................................................................... 15
Using Asynchronous API......................................................................................................................................................................16
Request Authentication - Synchronous Login.......................................................................................................................................16
Querying a User Status........................................................................................................................................................................ 17
Terminating a User Session.................................................................................................................................................................. 18
Disconnect Command......................................................................................................................................................................... 19
Querying Enrichment Information......................................................................................................................................................... 19
JSON Responses........................................................................................................................................................................................21
JSON Responses - GetConfig .............................................................................................................................................................21
JSON Responses Definitions................................................................................................................................................................22
JSON Response Examples.................................................................................................................................................................. 22
WISPr Support for ZoneDirector Login........................................................................................................................................................ 25
WISPr Support for ZoneDirector Login Overview.................................................................................................................................. 25
Customer Login................................................................................................................................................................................... 25
Customer Logout................................................................................................................................................................................. 26
Captive Portal Attributes..............................................................................................................................................................................27
Captive Portal Attributes Overview....................................................................................................................................................... 27
Redirection Attributes...........................................................................................................................................................................27
The Smart Client......................................................................................................................................................................................... 29
The Smart Client Overview................................................................................................................................................................... 29
Example: Information on the redirection page................................................................................................................................31
Example: Authentication Request (HTTP)...................................................................................................................................... 31
Example: Authentication Reply......................................................................................................................................................31
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 3
Example: Authentication Result (Login succeeded)....................................................................................................................... 32
Example: Authentication Result (Login failed).................................................................................................................................32
Example: Logoff Reply.................................................................................................................................................................. 32
User Defined Interface................................................................................................................................................................................. 33
User Defined Interface Overview...........................................................................................................................................................33
NBI and UDI.........................................................................................................................................................................................33
WISPr Portal Details.................................................................................................................................................................................... 37
WISPr Portal Details Overview..............................................................................................................................................................37
Certificate Warning...................................................................................................................................................................................... 39
Certificate Warning Overview................................................................................................................................................................39
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
4 Part Number: 800-71571-001 Rev A
Preface
Document Conventions.............................................................................................................................................5
Command Syntax Conventions................................................................................................................................. 5
Document Feedback.................................................................................................................................................6
Ruckus Product Documentation Resources.............................................................................................................. 6
Online Training Resources......................................................................................................................................... 6
Contacting Ruckus Customer Services and Support................................................................................................. 7
Document Conventions
The following tables list the text and notice conventions that are used throughout this guide.
TABLE 1 Text conventions
Convention Description Example
monospace Identifies command syntax
examples. device(config)# interface ethernet 1/1/6
bold User interface (UI) components such
as screen or page names, keyboard
keys, software buttons, and field
names
On the Start menu, click All Programs.
italics
Publication titles Refer to the
Ruckus Small Cell Release Notes
for more information
Notes, Cautions, and Warnings
Notes, cautions, and warning statements may be used in this document. They are listed in the order of increasing severity of potential
hazards.
NOTE
A NOTE provides a tip, guidance, or advice, emphasizes important information, or provides a reference to related information.
CAUTION
A CAUTION statement alerts you to situations that can be potentially hazardous to you or cause damage to hardware, firmware,
software, or data.
DANGER
A DANGER statement indicates conditions or situations that can be potentially lethal or extremely hazardous to you. Safety labels
are also attached directly to products to warn of these conditions or situations.
Command Syntax Conventions
Bold and italic text identify command syntax components. Delimiters and operators define groupings of parameters and their logical
relationships.
Convention Description
bold text Identifies command names, keywords, and command options.
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 5
Convention Description
italic
text Identifies a variable.
[ ] Syntax components displayed within square brackets are optional.
Default responses to system prompts are enclosed in square brackets.
{ x | y | z }A choice of required parameters is enclosed in curly brackets separated by vertical bars. You must select
one of the options.
x | yA vertical bar separates mutually exclusive elements.
< > Nonprinting characters, for example, passwords, are enclosed in angle brackets.
... Repeat the previous element, for example,
member
[
member
...].
\ Indicates a “soft” line break in command examples. If a backslash separates two lines of a command input,
enter the entire command at the prompt without the backslash.
Document Feedback
Ruckus is interested in improving its documentation and welcomes your comments and suggestions.
You can email your comments to Ruckus at: docs@ruckuswireless.com
When contacting us, please include the following information:
Document title and release number
Document part number (on the cover page)
Page number (if appropriate)
For example:
Ruckus Small Cell Alarms Guide SC Release 1.3
Part number: 800-71306-001
Page 88
Ruckus Product Documentation Resources
Visit the Ruckus website to locate related documentation for your product and additional Ruckus resources.
Release Notes and other user documentation are available at https://support.ruckuswireless.com/documents. You can locate
documentation by product or perform a text search. Access to Release Notes requires an active support contract and Ruckus Support
Portal user account. Other technical documentation content is available without logging into the Ruckus Support Portal.
White papers, data sheets, and other product documentation are available at https://www.ruckuswireless.com.
Online Training Resources
To access a variety of online Ruckus training modules, including free introductory courses to wireless networking essentials, site surveys,
and Ruckus products, visit the Ruckus Training Portal at https://training.ruckuswireless.com.
Preface
Document Feedback
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
6 Part Number: 800-71571-001 Rev A
Contacting Ruckus Customer Services and Support
The Customer Services and Support (CSS) organization is available to provide assistance to customers with active warranties on their
Ruckus Networks products, and customers and partners with active support contracts.
For product support information and details on contacting the Support Team, go directly to the Support Portal using https://
support.ruckuswireless.com, or go to https://www.ruckuswireless.com and select Support.
What Support Do I Need?
Technical issues are usually described in terms of priority (or severity). To determine if you need to call and open a case or access the self-
service resources use the following criteria:
Priority 1 (P1)—Critical. Network or service is down and business is impacted. No known workaround. Go to the Open a Case
section.
Priority 2 (P2)—High. Network or service is impacted, but not down. Business impact may be high. Workaround may be available.
Go to the Open a Case section.
Priority 3 (P3)—Medium. Network or service is moderately impacted, but most business remains functional. Go to the Self-Service
Resources section.
Priority 4 (P4)—Low. Request for information, product documentation, or product enhancements. Go to the Self-Service
Resources section.
Open a Case
When your entire network is down (P1), or severely impacted (P2), call the appropriate telephone number listed below to get help:
Continental United States: 1-855-782-5871
Canada: 1-855-782-5871
Europe, Middle East, Africa, and Asia Pacific, toll-free numbers are available at https://support.ruckuswireless.com/contact-us and
Live Chat is also available.
Self-Service Resources
The Support Portal at https://support.ruckuswireless.com/contact-us offers a number of tools to help you to research and resolve problems
with your Ruckus products, including:
Technical Documentation—https://support.ruckuswireless.com/documents
Community Forums—https://forums.ruckuswireless.com/ruckuswireless/categories
Knowledge Base Articles—https://support.ruckuswireless.com/answers
Software Downloads and Release Notes—https://support.ruckuswireless.com/software
Security Bulletins—https://support.ruckuswireless.com/security
Using these resources will help you to resolve some issues, and will provide TAC with additional data from your troubleshooting analysis if
you still require assistance through a support case or RMA. If you still require help, open and manage your case at https://
support.ruckuswireless.com/case_management
Preface
Contacting Ruckus Customer Services and Support
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 7
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
8 Part Number: 800-71571-001 Rev A
About This Guide
Overview................................................................................................................................................................... 9
• Terminology...............................................................................................................................................................9
Overview
This SmartZone (SZ) 100 and Virtual SmartZone Essentials (vSZ-E) Hotspot WISPr Reference Guide describes the SZ-100/vSZ-E
(collectively referred to as “the controller” throughout this guide) RESTful-like/JSON interfaces for external web portal servers.
This guide is written for service operators and system administrators who are responsible for managing, configuring, and troubleshooting
Ruckus Wireless devices. Consequently, it assumes a basic working knowledge of local area networks, wireless networking, and wireless
devices.
NOTE
If release notes are shipped with your product and the information there differs from the information in this guide, follow the
instructions in the release notes.
Most user guides and release notes are available in Adobe Acrobat Reader Portable Document Format (PDF) or HTML on the Ruckus
Wireless Support Web site at https://support.ruckuswireless.com/contact-us.
Terminology
The table lists the terms used in this guide.
TABLE 2 Terms used in this guide
Terminology Description
AP Access Point
CP Captive Portal
MSP Managed Service Provider
NBI Northbound Interface
SCG Smart Cell Gateway
SSL Secure Socket Layer
TCP Transmission Control Protocol
UDI User Define Interface
UE User Equipment
UE-IP User Equipment - IP Address
UE-MAC User Equipment - MAC Address
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 9
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
10 Part Number: 800-71571-001 Rev A
Web Interface Configuration Overview
Overview................................................................................................................................................................. 11
Request Format...................................................................................................................................................... 12
Controller Web Interface Configuration.................................................................................................................... 13
Overview
The controller provides Wi-Fi hotspot services in conjunction with external web portal servers. In most cases, an external web portal server
provides the landing web pages with Wi-Fi hotspot usage instructions, terms and conditions, etc., while the end user submits his login ID
and password directly to the AP for authentication. There are, however, some cases when an external web portal server requires total
control of a user session by requesting authentication on the user’s behalf as well as terminating user sessions. JSON interface defined in
this reference guide provides a standard way for an external web portal server to communicate with the controller for this kind of usage.
The following are the hotspot components and their roles in the hotspot portal as seen in the figure below.
Northbound: Listens on the control and management interface. It is responsible for handling requests from external subscriber
portal and authenticates with the AAA server.
Captive portal: Listens on the control interface or UDI. It is responsible for providing a wall garden for web-proxy UE. It blocks UEs,
which uses user agents that are listed in the configured black-list and mainly handles high scalable redirecting UEs to the external
subscriber portal.
External subscriber portal: Is a Web service. The user sends his/her login credentials (username and password) through this portal.
The authentication is performed through the northbound by user input credential. The external subscriber portal can reach the
northbound depending on the type of interface it can reach such as control interface, management interface or both.
AAA server: Is responsible for authenticating the UE through the UE’s login credentials (username and password).
NOTE
Refer to appendix WISPr Portal Details Overview on page 37 for IPv4 and IPv6 protocol support for GRE tunnels.
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 11
FIGURE 1 Hotspot portal components
This reference guide describes the controller RESTful-like/JSON interfaces for external web portal servers.
Request Format
As defined in JSON commands, each request issued from an external web portal server is in JSON format.
NBI is only accessible via the management, control and user defined interfaces. The following are the request formats.
HTTP Request
http://{sz_management_ip}:9080/portalintf
HTTPS Request
https://{sz_management_ip}:9443/portalintf
NOTE
The above URI is a fixed value and cannot be modified.
Web Interface Configuration Overview
Request Format
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
12 Part Number: 800-71571-001 Rev A
NOTE
You can download the log for northbound portal interface from the controller web interface by navigating to Diagnostics >
Application Logs as all other applications.
The table lists the ports that must be opened on the network firewall to ensure that the controller and NBI can communicate with each other
successfully.
TABLE 3 Portal Details
Port Number Layer 4 Protocol Source Destination Configurable from Web
Interface?
Purpose
9080 HTTP Any Controller No Northbound Interface
for Hotspot
9443 HTTPS Any Controller No Northbound Interface
for Hotspot
Controller Web Interface Configuration
Each JSON request must be accompanied by a request password that is preconfigured on the controller, as well as on the external web
portal server.
This helps ensure that only authorized web portal servers can access the northbound interface.
The northbound interface request password can be configured in the controller web interface by navigating to System > General Settings >
Northbound Interface. See the figure below.
NOTE
The password in the figures is a token to ensure that the interface has the permission to get the services from the northbound
interface. It must be included in all JSON request as
RequestPassword
sent to NBI.
A web portal server must use the POST command to issue JSON requests. The controller will not accept a request with the GET request
command.
Web Interface Configuration Overview
Controller Web Interface Configuration
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 13
FIGURE 2 Enable Northbound Interface
Web Interface Configuration Overview
Controller Web Interface Configuration
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
14 Part Number: 800-71571-001 Rev A
JSON Commands - User Online Control
Overview................................................................................................................................................................. 15
Request Authentication - Asynchronous Login........................................................................................................ 15
Using Asynchronous API......................................................................................................................................... 16
Request Authentication - Synchronous Login.......................................................................................................... 16
Querying a User Status............................................................................................................................................17
Terminating a User Session..................................................................................................................................... 18
Disconnect Command.............................................................................................................................................19
Querying Enrichment Information.............................................................................................................................19
Overview
The northbound portal interface supports the following JSON commands:
• Login
Login Async
• Logout
• Status
• Disconnect
Enrichment Info
These commands are used for user authentication, user status query, terminating user sessions and verifying that the enrichment
information has the same content. For each command (JSON POST), both the UE-IP and UE-MAC may be included. Where both are
present, the UE-MAC will be preferred.
The NBI decrypts the strings and returns the decrypted version within the response message. This is because the Captive Portal (CP)
encrypts the IP and MAC address parameters in each redirection (See the table for the full list of these parameters) to the subscriber portal.
The controller decrypts the UE-IP and UE-MAC address before returning the response, by using the Encrypt and Decrypt API described in
JSON Responses - GetConfig on page 21 section.
NOTE
Northbound Interface (NBI) expects to receive encrypted UE-IP and UE-MAC address (For example,
ENC12bc24c4777703327f2e0aabbf6b9f9e) when the request category is UserOnlineControl. In the GetConfig request category
you do not need to encrypt UE-IP and UE-MAC address (For example: 172.21.134.87)
Request Authentication - Asynchronous Login
In the hotspot (WISPr) WLAN use case, an unauthorized user is redirected to an external web portal server by the controller.
Using the asynchronous login command (RequestType=LoginAsync), the external web portal server sends a request to the controller to
authenticate the user using the authentication server. The external Web portal server receives the response - 202 Authentication pending,
while the controller performs the authentication in the background. It is the responsibility of the Web portal to poll the controller and fetch
the authentication result. This action is performed using the status command (RequestType=Status).
The following is an example of an asynchronous login request:
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 15
{ Vendor: “ruckus” RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “UserOnlineControl”, RequestType:
“LoginAsync”, UE-IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, UE-MAC:
“ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157”, UE-Proxy: “0”, UE-Username: “test”, UE-Password: “test” }
The table lists the controller responses to these authentication requests.
NOTE
The user account test (UE username) mentioned in the above example, is created as an external user in the authentication server.
The hotspot portal does not provide an interface for manipulating user account information.
TABLE 4 Controller responses to authentication (asynchronous login) requests
Response Type Possible Responses
Normal response 101, Client authorized: Response if the user is already authorized.
202, Authentication pending: Authentication is in progress, portal
server needs to check the result later.
Service error 300, Not found: Response if the lookup fails with given UE-MAC
or UE-IP address.
400, Internal server error: Response when the controller internal
error occurs.
General error 302, Bad request: Response if the JSON request is not well-
formed.
303, Version not supported: Response if there is a version
mismatch.
304, Command not supported: Response if the request type is
not supported.
305, Category not supported: Response if the request category
not supported.
306, Wrong request password: Response if the request
password is mismatched.
Using Asynchronous API
When using the asynchronous API (RequestType = LoginAsync), NBI will always return a response as
pending authentication
.
The client must send a status request (each X seconds/milliseconds) to check for the authentication result. This is useful when using a
smart device. The application in a smart device can query the login status periodically. It stores the user credentials in the background
thereby reducing the user driven actions.
Request Authentication - Synchronous Login
The controller also provides a synchronous login blocking command (RequestType=Login).
In a synchronous login command, the external Web portal must wait for the authentication process to complete, which is usually processed
by the authentication server. This could result in a delayed response if the controller is unable to get a response from the authentication
server.
The following is an example of this command.
{ Vendor: “ruckus” RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “UserOnlineControl”, RequestType: “Login”, UE-
IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, UE-MAC: “ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157”, UE-
Proxy: “0”, UE-Username: “test”, UE-Password: “test” }
JSON Commands - User Online Control
Using Asynchronous API
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
16 Part Number: 800-71571-001 Rev A
The table lists the controller responses to the synchronous login command.
TABLE 5 Controller responses to a synchronous login command
Response Type Possible Responses
Normal response 101, Client authorized: Response if the user is already authorized.
201, Login succeeded: Response if the login is accepted.
Service error 300, Not found: Response if the lookup fails with given UE-MAC
or UE-IP address.
301, Login failed: It will be replaced if the authentication reply
message is returned.
400, Internal server error: Response when an controller internal
error occurs.
401, Authentication server error: Response when an
authentication connection error occurs or the connection request
times out.
General error 302, Bad request: Response if the JSON request is not well-
formed.
303, Version not supported: Response if there is a version
mismatch.
304, Command not supported: Response if the request type is
not supported.
305, Category not supported: Response if the request category
not supported.
306, Wrong request password: Response if the request
password is mismatched.
NOTE
If an authentication process has a result (not pending), the controller responds to it only once. For example, if the controller replies
301, Login failed to the web portal server, and the web portal server sends the same query, the response will be 100,
unauthorized. If the controller replies 201, Login succeeded, and the web portal server queries again, the response will be 101,
Authorized.
Querying a User Status
After the authentication request is issued, the external web portal server can query the user's authentication status.
The following is an example of the user status query command:
{
Vendor: “ruckus”
RequestPassword: “myPassword”,
APIVersion: “1.0”,
RequestCategory: “UserOnlineControl”,
RequestType: “Status”,
UE-IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”,
UE-MAC: “ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157”
}
The table lists the controller responses to these user status query commands.
TABLE 6 Controller responses to user status query
Response Type Possible Responses
If there is a pending authentication process for this client 201, Login succeeded.
JSON Commands - User Online Control
Querying a User Status
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 17
TABLE 6 Controller responses to user status query (continued)
Response Type Possible Responses
202, Authentication pending: Authentication is in progress, portal
server needs to check the result later.
If there is no pending authentication process for this client 100, Client unauthorized.
or
101, Client authorized.
Service error 300, Not found: Response if the lookup fails with given UE- MAC
or UE-IP address.
301, Login failed: It will be replaced if the authentication reply
message is returned
400, Internal server error: Response when an controller internal
error occurs.
401, Authentication server error: Response when a authentication
connection error occurs or the connection request times out.
General error 302, Bad request: Response if the JSON request is not well-
formed.
303, Version not supported: Response if there is a version
mismatch.
304, Command not supported: Response if the request type is
not supported.
305, Category not supported: Response if the request category
not supported.
306, Wrong request password: Response if the request
password is mismatched.
NOTE
If an authentication process has a result (not pending), the controller responds to it only once. For example, if the controller replies
301, Login failed to the web portal server, and the web portal server sends the same query, the response will be 100,
unauthorized. If the controller replies 201, Login succeeded, and the web portal server queries again, the response will be 101,
Authorized.
Terminating a User Session
After a user session is authorized, the external web portal server can terminate the user session by sending a JSON request to the
controller. In this case, the Web portal changes the status of the client from authenticated, to unauthenticated, forcing the user to login
again.
When un-authenticating a user, existing TCP sessions are not terminated and the UE is not disassociated from the AP. It only changes the
status of the UE from authorized to unauthorized. The following is an example of terminating a user session command:
{ Vendor: “ruckus” RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “UserOnlineControl”, RequestType: “Logout”,
UE-IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, UE-MAC: “ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157” }
JSON Commands - User Online Control
Terminating a User Session
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
18 Part Number: 800-71571-001 Rev A
Disconnect Command
The controller also provides a command for terminating user TCP (Transmission Control Protocol) connections from the AP (Access Point).
In other words, the disconnect command (RequestType=Disconnect) changes the status of the UE from authorized to unauthorized and
also disassociates the UE from the AP.
{ Vendor: “ruckus” RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “UserOnlineControl”, RequestType:
“Disconnect”, UE-IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, UE-MAC:
“ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157” }
The table lists the controller response.
TABLE 7 Controller response to a disconnect command
Response Type Possible Responses
Normal response 200, OK
100, Client unauthorized: Response if the user is already
unauthorized
Service Error 300, Not found: Response if the lookup fails with given UE- MAC
or the UE-IP address.
400, Internal server error: Response when an controller internal
error occurs.
General error 302, Bad request: Response if the JSON request is not well-
formed.
303, Version not supported: Response if there is a version
mismatch.
304, Command not supported: Response if the request type is
not supported.
305, Category not supported: Response if the request category
not supported.
306, Wrong request password: Response if the request
password is mismatched.
Querying Enrichment Information
The northbound interface provides the JSON command Enrichment Info for verifying that the enrichment information has the same content
as HTML header
enrichment info
sent from the AP.
This allows the captive portal to obtain the enriched parameters in an SSL (Secure Sockets Layer) scenario or in other cases wherein the
AP enrichment info is not available.
NOTE
The EnrichmentInfo command is only applicable for UEs connected to Ruckus APs and not for third party APs.
The following is an example of an
EnrichmentInfo
request:
{ Vendor: “ruckus” RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “UserOnlineControl”, RequestType:
“EnrichmentInfo”, UE-IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, }
JSON Commands - User Online Control
Querying Enrichment Information
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 19
The table lists the responses for enrichment information.
TABLE 8 Query enrichment
Response Type Possible Responses
Normal response 102, Enrichment Information.
Service error 300, Not found: Response if the lookup fails with given UE- MAC
or UE-IP address.
400, Internal server error: Response when an controller internal
error occurs.
General error 302, Bad request: Response if the JSON request is not well-
formed.
303, Version not supported: Response if there is a version
mismatch.
304, Command not supported: Response if the request type is
not supported.
305, Category not supported: Response if the request category
not supported.
306, Wrong request password: Response if the request
password is mismatched.
JSON Commands - User Online Control
Querying Enrichment Information
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
20 Part Number: 800-71571-001 Rev A
JSON Responses
JSON Responses - GetConfig ................................................................................................................................21
JSON Responses Definitions...................................................................................................................................22
JSON Response Examples..................................................................................................................................... 22
JSON Responses - GetConfig
The northbound interface supports the following JSON commands in the request category - GetConfig:
• Encrypt
• Decrypt
NOTE
It is recommended for new users to implement and use the new APIs - Encrypt and Decrypt. Existing users can continue using
the legacy APIs - EncryptIP and DecryptIP provided; you have not made any changes to it during implementation on your portal
server.
The following is an example of an Encrypt IP address command, which returns an encrypted IP address for direct access to the subscriber
portal. By default the encryption is enabled. To disable the encryption, use the CLI command:
ruckus(config)# [no] encrypt-mac-ip
NOTE
Refer to the CLI examples given below for enabling and disabling the IP and MAC address encryption.
{ Vendor: “ruckus”, RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “GetConfig”, RequestType: “Encrypt”, Data:
“172.21.134.87” }
The following is an example of the success response:
{ Vendor: “ruckus”, ReplyMessage:”OK", ResponseCode:200, APIVersion:”1.0” Data: “ENC1234bfdbe5y5hbfdgh45y54ryt5y5th5” }
Another example is the decrypt command, which returns a decrypted value of IP address.
{ Vendor: "ruckus", RequestPassword: "myPassword", APIVersion: "1.0", RequestCategory: "GetConfig", RequestType: "Decrypt", Data:
"ENC1234bfdbe5y5hbfdgh45y54ryt5y5th5" }
The success response:
{ Vendor:"ruckus", ReplyMessage:"OK", ResponseCode:200, APIVersion:"1.0" Data: "172.21.134.87" }
The following are examples of using the CLI command for enabling and disabling the IP address and MAC address encryptions.
Enabling the IP address and MAC address encryption:
# show running-config encrypt-mac-ip
Disabling the IP address and MAC address encryption:
# config (config)# no encrypt-mac-ip Do you want to continue to disable (or input 'no' to cancel)? [yes/no] yes Successful operation
Confirming that the IP address and MAC address encryption is disabled:
(config)# do show running-config encrypt-mac-ip Encryption MAC and IP: Disabled
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 21
JSON Responses Definitions
The table lists the definitions of JSON responses from the northbound portal interface.
The following are the expansions for the abbreviations mentioned in the Used In column.
UA: User Authenticate (includes LoginSync and LoginAsync)
SQ: Status Query
TU: Terminating User (Logout and Disconnect)
EI: Enrichment Info
GC: Get Config (Encrypt and Decrypt)
NOTE
Refer to Overview on page 15 for commands related to the responses mentioned above.
TABLE 9 JSON response definitions
Category Code Definition Used In
UA SQ TU EI GC
Informational 100 Client unauthorized
101 Client authorized
102 Enrichment Info
Success 200 OK
201 Login succeeded
202 Authentication pending
Client Error 300 Not found
301 Login failed
302 Bad request
303 Version not supported
304 Command not supported
305 Category not supported
306 Wrong request password
Server Error 400 Internal server error
401 Authentication server error
JSON Response Examples
This section provides the following examples of JSON responses defined in the Table (JSON Response Definitions)
Example: Client unauthorized
{ Vendor:"Ruckus", APIVersion:"1.0", ResponseCode:100, ReplyMessage:"Client unauthorized", UE-IP:"ENC323e79bf1bbd5ac4", UE-
MAC:"ENCf6b7f49da92a45f8978c35966b95eeafc6451102af391592", AP-MAC:"00:11:22:AA:BB:CC", SSID:" hotspot-01",
SmartClientInfo:"", GuestUser:"0", SmartClientMode:"none" }
Example: Client authorized
{ Vendor: "Ruckus", APIVersion: "1.0", ResponseCode: "101", ReplyMessage: "Client authorized", UE-IP:
"ENC12bc24c4777703327f2e0aabbf6b9f9e", UE-MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157", UE-
Username: "user001", AP-MAC: "04:4f:aa:32:25:f0", SSID: "hotspot-01" SmartClientMode: "none", SmartClientInfo: "", GuestUser: "0", }
JSON Responses
JSON Responses Definitions
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
22 Part Number: 800-71571-001 Rev A
Example: Enrichment information
{ Vendor: "Ruckus", APIVersion: "1.0", ResponseCode: "102", ReplyMessage: "Enrichment Information", UE-IP:
"ENC12bc24c4777703327f2e0aabbf6b9f9e", UE-MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157", AP-
MAC: "04:4f:aa:32:25:f0", SSID: "hotspot-01", WLAN-ID: "1", Location: "a location", VLAN-ID: 1 }
Example: Success information
{ Vendor: "Ruckus", Version: "1.0", ResponseCode: "200", ReplyMessage: "OK" UE-IP: "ENC12bc24c4777703327f2e0aabbf6b9f9e", UE-
MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157", SmartClientMode: "none", SmartClientInfo: "", GuestUser:
"0", }
Example: Login succeeded
{ Vendor: "Ruckus", APIVersion: "1.0", ResponseCode: "201", ReplyMessage: "Login succeeded", UE-IP:
"ENC12bc24c4777703327f2e0aabbf6b9f9e", UE-MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157", UE-
Username: "user001", AP-MAC: "04:4f:aa:32:25:f0", SSID: "hotspot-01", SmartClientMode: "none", SmartClientInfo: "", GuestUser: "0",
UE-Proxy: "0" }
Example: Authentication pending
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "202", ReplyMessage: "Authentication pending", UE-IP:
"ENC12bc24c4777703327f2e0aabbf6b9f9e", UE-MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157", UE-
Username: "user001", AP-MAC: "04:4f:aa:32:25:f0", SSID: "hotspot-01", SmartClientMode: "none", SmartClientInfo: "", GuestUser: "0", }
Example: Not found
{ Vendor: "Ruckus", APIVersion: "1.0", ResponseCode: "300", ReplyMessage: "Not found", }
Example: Login failed
{ Vendor: "Ruckus", APIVersion: "1.0", ResponseCode: "301", ReplyMessage: "Login failed", UE-IP:
"ENC12bc24c4777703327f2e0aabbf6b9f9e", UE-MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157", AP-
MAC: "04:4f:aa:32:25:f0", SSID: "hotspot-01", SmartClientMode: "none", SmartClientInfo: "", GuestUser: "0", }
Example: Bad request
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "302", ReplyMessage: "Bad request", }
Example: Version not supported
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "303", ReplyMessage: "Version not supported" }
Example: Command not supported
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "304", ReplyMessage: "Command not supported", }
Example: Category not supported
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "305", ReplyMessage: "Category not supported", }
Example: Wrong request password
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "306", ReplyMessage: "Wrong request password", }
Example: Internal server error
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "400", ReplyMessage: "Internal server error", }
Example: Authentication server error
{ Vendor: "ruckus", APIVersion: "1.0", ResponseCode: "401", ReplyMessage: "Authentication server error", }
Example: Encrypt for MAC address
JSON Responses
JSON Response Examples
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 23
{ Vendor: “ruckus”, RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “GetConfig”, RequestType: “Encrypt”, Data:
“04:4f:aa:32:25:f0” } The success response: { Vendor: “ruckus”, ReplyMessage:”OK", ResponseCode:200, APIVersion:”1.0”, Data:
"ENC4782689566f8eac8aa30e276aa907f332d0bf93f9f60a7d8" }
Example: Decrypt for MAC address
{ Vendor: "ruckus", RequestPassword: “myPassword”, APIVersion: "1.0", RequestCategory: "GetConfig", RequestType: "Decrypt", Data:
"ENC4782689566f8eac8aa30e276aa907f332d0bf93f9f60a7d8" } The success response: { Vendor:"ruckus", ReplyMessage:"OK",
ResponseCode:200, APIVersion:"1.0" Data: "04:4f:aa:32:25:f0" }
JSON Responses
JSON Response Examples
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
24 Part Number: 800-71571-001 Rev A
WISPr Support for ZoneDirector Login
WISPr Support for ZoneDirector Login Overview..................................................................................................... 25
Customer Login.......................................................................................................................................................25
Customer Logout.................................................................................................................................................... 26
WISPr Support for ZoneDirector Login Overview
The WISPr hotspot portal logon API supports existing customer’s external logon page (working with Zone Director (ZD)). Customers, who
already have a ZD deployment and have implemented their own external logon page for hotspot WLAN, can use ZD's API (provided by
Ruckus) for UE authentication. The controller provides the same API as that of ZD for customers to use their existing logon page.
NOTE
This new API is provided since controller's official portal integration using JSON requests does not support ZD login API. Ruckus
Wireless recommends that the customer works with the JSON API as documented in this guide - Hotspot Portal Integration
Interface.
Customer Login
Customers who already have ZD deployment with their own external portal must change their login/logout URLs to match the new
supported API.
The external portal sends the login/logout request to the controller. The requests should include the parameters provided by controller's
captive portal redirection
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 25
NOTE
See Captive Portal Attributes Overview on page 27 for details.
Login - The login request path in the external portal to the controller should be changed:
From:
https://sip:9998/login
To:
https://sip:9998/SubscriberPortal/hotspotlogin
NOTE
The login request also supports HTTP with port number 9997.
NOTE
This login request should include the customer's login credentials such as the username and password
parameters. It is expected that the customer's portal also sends the following parameters from Captive
Portal's redirection -
url - the original URL which the user tried to browse
proxy - if the UE browser is set to Web proxy
uip - UE IP address
client_mac - UE MAC IP address
Customer Logout
This section describes customer logout.
The logout request path in the external portal to the controller should be changed:
From:
https://sip:9998/logout
To:
https://sip:9998/SubscriberPortal/hotspotlogout?uip=10.20.30.40
WISPr Support for ZoneDirector Login
Customer Logout
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
26 Part Number: 800-71571-001 Rev A
Captive Portal Attributes
Captive Portal Attributes Overview...........................................................................................................................27
Redirection Attributes.............................................................................................................................................. 27
Captive Portal Attributes Overview
The UE-IP and UE-MAC address parameters are decrypted at the beginning of each user online control request. This is because the
Captive Portal (CP) encrypts the IP and MAC address parameters in each redirection to the subscriber portal. The controller decrypts the
UE-IP and UE-MAC address before returning the response, by using the Encrypt and Decrypt API described in the JSON Responses on
page 21 chapter.
NOTE
Apple CNA only works for HTTP redirect. It does not work if the external portal is in HTTPS.
Redirection Attributes
The table lists these parameters provided by controller's captive portal redirection.
NOTE
See WISPr Support for ZoneDirector Login on page 25 for login and logout details.
TABLE 10 Redirection attributes
Attributes Description
client_mac Encrypted UE Mac address.
NOTE
The format of the MAC Address is defined in the Hotspot (WISPr) Portal configuration.
dn The domain name.
lid AP application identifier. For example: isocc=us, cc=1,ac=408,network=ACMEWISP_Newark_Airport
loc AP location name. For example: ACMEWISP,Gate_14_Terminal_C_of_Newark_Airport
mac AP Mac address.
proxy The UE browser if it is set to the Web proxy.
reason Reason for redirecting the WLAN. The value could either be:
Un-Auth-Captive – Regular unauthenticated UE redirected to Login Portal
or
Un-Auth-SSL-Captive – In case of HTTPS, Captive Portal is performing a “double redirect”. Adding this
value to identify this flow.
nbilp The IP of SCG/SZ’s Northbound Interface.
sip The value could either be the:
FQDN of the uploaded SCG/SZ Web UI certificate if the uploaded certificate’s common name is FQDN.
Concatenation of the SCG/SZ cluster name with the common name value after the wild card, if the
uploaded certificate’s common name is not FQDN (meaning if it includes wild card). For example, if the
common name is “*.ruckuswireless.com” and the cluster name is “Cluster_Node1”, then the sip will be
“cluster_node1.ruckuswireless.com.”
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 27
TABLE 10 Redirection attributes (continued)
Attributes Description
“scg.ruckuswireless.com”, which is the FQDN of the self-signed certificate which SCG/SZ is packaged with,
if the certificate was not uploaded at all.
ssid The broadcasted SSID name.
startUrl The URL as per the Hotspot configuration, which is to be redirected after successful login.
uip Encrypted UE IP address.
url Original URL which the customer tries browsing.
vlan VLAN which the customer is set to.
wlan WLAN ID of the UE's associated to the WLAN.
wlanName SSIDs configured WLAN name.
zoneId In case of third party AP, this attribute will be included instead of WLAN and will include the zone ID where the SSID is
configured in the controller.
zoneName AP zone name of the UE's associated with the WLAN. The WLANs configured Zone name. This name is used for
Kumo. The value is encrypted based on a special key.
Captive Portal Attributes
Redirection Attributes
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
28 Part Number: 800-71571-001 Rev A
The Smart Client
The Smart Client Overview...................................................................................................................................... 29
The Smart Client Overview
The Smart Client is a software solution which resides on the user’s access device that facilitates the user’s connection to Public Access
Networks, whether via a browser, signaling protocol or other proprietary method of access.
The XML is embedded in the HTML source code as a comment block as the following:
<html>
< head>
< meta http-equiv="content-type" content="text/html; charset=UTF-8">
< /head>
< body></body>
<!--<?xml version="1.0" encoding="utf-8"?>
{{{ The Embedded XML }}}
-->
</html>
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 29
FIGURE 3 Smart Client Example
Extract the embedded XML as the following.
<?xml version="1.0" encoding="utf-8"?>
<WISPAccessGatewayParam xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance"xsi:noNamespaceSchemaLocation=
"http://www.acmewisp.com/WISPAccessGatewayParam.xsd">
<Redirect>
<AccessProcedure>1.0</AccessProcedure>
<AccessLocation></AccessLocation>
<LocationName></LocationName>
<LoginURL>https://scg.ruckuswireless.com:9998/
SubscriberPortal/WisprLogin?nbiIP=172.17.18.173&client_mac
=ENCd67be23390a743c6095b6635a31e93c19e2487fa83931d98&sip
=scg.ruckuswireless.com&wlan=1&reason=Un-Auth-Captive&proxy
=0&wlanName=RADIUS_TEST&ssid=RADIUS_TEST&mac
=8c:0c:90:2b:8b:90&dn=scg.ruckuswireless.com&uip
=ENCec4cc1fd0c146d5348cd4f1ba20ef459&zoneName
=%5BB%40453f2dba_1439953901413&url=http%3A%2F%2Fwww.google.com%2F
</LoginURL><AbortLoginURL>
https://scg.ruckuswireless.com:9998/SubscriberPortal/
AbortWisprLogin?nbiIP=172.17.18.173&client_mac
=ENCd67be23390a743c6095b6635a31e93c19e2487fa83931d98&sip
=scg.ruckuswireless.com&wlan=1&reason=Un-Auth-Captive&proxy
The Smart Client
The Smart Client Overview
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
30 Part Number: 800-71571-001 Rev A
=0&wlanName=RADIUS_TEST&ssid=RADIUS_TEST&mac=8c:0c:90:2b:8b:90&dn
=scg.ruckuswireless.com&uip=ENCec4cc1fd0c146d5348cd4f1ba20ef459&zoneName
=%5BB%40453f2dba_1439953901413&url=http%3A%2F%2Fwww.google.com%2F
</AbortLoginURL>
<MessageType>100</MessageType>
<ResponseCode>0</ResponseCode>
</Redirect>
Example: Information on the redirection page
<?xml version="1.0" encoding="utf-8"?>
<WISPAccessGatewayParam xmlns:xsi
="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation
="http://www.acmewisp.com/WISPAccessGatewayParam.xsd">
<Redirect>
<AccessProcedure>1.0</AccessProcedure>
<AccessLocation></AccessLocation>
<LocationName></LocationName>
<LoginURL>https://sip:9998/SubscriberPortal/WisprLogin?nbiIP=<nbiIP>
{& ... other Redirection attributes in Table 11}</LoginURL>
<AbortLoginURL>
https://sip:9998/SubscriberPortal/AbortWisprLogin?nbiIP=<nbiIP>
</AbortLoginURL>
<MessageType>100</MessageType>
<ResponseCode>0</ResponseCode>
</Redirect>
</WISPAccessGatewayParam>
NOTE
To do authentication. An HTTP POST request must be sent to the <LoginURL> with the `UserName` and `Password` fields.
NOTE
The content type of request must be "application/x-www-form-urlencoded".
Example: Authentication Request (HTTP)
POST /SubscriberPortal/WisprLogin?nbiIP=<nbiIP>
HTTP/1.1
Host: sip:9998
Content-Type: application/x-www-form-urlencoded
UserName=<UserName>&Password=<Password>
Example: Authentication Reply
<?xml version="1.0" encoding="UTF-8"?>
<WISPAccessGatewayParam xmlns:
xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation
="http://www.acmewisp.com/WISPAccessGatewayParam.xsd">
<AuthenticationReply>
<MessageType>120</MessageType>
<ResponseCode>201</ResponseCode>
<ReplyMessage>Authentication pending</ReplyMessage>
<LoginResultsURL>
https://sip:9998/SubscriberPortal/WisprStatus?nbiIP=<nbiIP>
</LoginResultsURL>
</AuthenticationReply>
</WISPAccessGatewayParam>
The Smart Client
The Smart Client Overview
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 31
Example: Authentication Result (Login succeeded)
<?xml version="1.0"encoding="UTF-8"?>
<WISPAccessGatewayParam xmlns:
xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation
="http://www.acmewisp.com/WISPAccessGatewayParam.xsd">
<AuthenticationPollReply>
<MessageType>140</MessageType>
<ResponseCode>50</ResponseCode>
<ReplyMessage>Login succeeded</ReplyMessage>
<LogoffURL>
https://sip:9998/SubscriberPortal/WisprLogout?nbiIP=<nbiIP>
&UserName=<UserName>&Password=<Password></LogoffURL>
</AuthenticationPollReply>
</WISPAccessGatewayParam>
Example: Authentication Result (Login failed)
<?xml version="1.0" encoding="UTF-8"?>
<WISPAccessGatewayParam xmlns:
xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation
="http://www.acmewisp.com/WISPAccessGatewayParam.xsd">
<AuthenticationPollReply>
<MessageType>140</MessageType>
<ResponseCode>100</ResponseCode>
<ReplyMessage>Login failed</ReplyMessage>
</AuthenticationPollReply>
</WISPAccessGatewayParam>
Example: Logoff Reply
<?xml version="1.0" encoding="UTF-8"?>
<WISPAccessGatewayParam xmlns:
xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation
="http://www.acmewisp.com/WISPAccessGatewayParam.xsd">
<LogoffReply>
<MessageType>130</MessageType>
<ResponseCode>150</ResponseCode>
</LogoffReply>
</WISPAccessGatewayParam>
The Smart Client
The Smart Client Overview
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
32 Part Number: 800-71571-001 Rev A
User Defined Interface
User Defined Interface Overview..............................................................................................................................33
NBI and UDI............................................................................................................................................................ 33
User Defined Interface Overview
AP uses the control interface to communicate with the controller regarding its configuration.
NBI and UDI
To have a logical separation of UE traffic from the AP control traffic, the administrator can create an UDI (User Defined Interface).
In case the UDI (using control interface, physical interface and hotspot service as shown in the figure) is configured, the AP uses it to DNAT
unauthorized UE requests to the controller's captive portal (otherwise the AP uses the control interface).
NOTE
UDI option is not available for vSZ-E.
The controller's captive portal redirects the UE to the configured portal login page URL. When the UE triggers this portal URL request, the
AP will let it go through (it will not DNAT to the controller's captive portal), as it is configured as ACL in the AP, direct to the external portal
server.
The external portal communicates with the controller's NBI for status/login/logout requests. The interfaces external portal can communicate
are the interfaces NBI listens to. NBI is bound by default to the controller's control and management interfaces.
In addition, the administrator can configure UDI interface, which NBI will bind as well. This UDI for NBI can be the same UDI which AP
DNAT to the controller's captive portal, or others using control or management physical interfaces and whatever service (hotspot/not
specified) as in the figure below. To define UDI on the controller’s web interface, navigate to System > Cluster > Select an existing Control
Plane > Click on Configure > User Defined Interfaces. Enter the following details. Click on Add to add and on OK to save the configuration
details.
Name of the UDI
Physical Interface
• Service
IP Address
Subnet Mask
• Gateway
• VLAN
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 33
FIGURE 4 Configuring UDI
The figure below describes the request flows per interface.
User Defined Interface
NBI and UDI
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
34 Part Number: 800-71571-001 Rev A
FIGURE 5 Request flows per interface
User Defined Interface
NBI and UDI
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 35
User Defined Interface
NBI and UDI
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
36 Part Number: 800-71571-001 Rev A
WISPr Portal Details
WISPr Portal Details Overview................................................................................................................................. 37
WISPr Portal Details Overview
The following are the WISPr portal details for GRE tunnels.
Non GRE Tunnel
The below table lists the WISPr details for non GRE tunnel.
TABLE 11 Non GRE tunnel
Non GRE Tunnel IPv4 IPv6
Non WISPr Client IPv4 Supported Supported
IPv6 Supported Supported
TABLE 12 Non GRE tunnel and internal portal
Non GRE Tunnel IPv4 IPv6
WISPr Client IPv4 Supported Supported
IPv6 Not supported Not supported
TABLE 13 Non GRE tunnel and external portal
Non GRE Tunnel IPv4 IPv6
WISPr Client IPv4 Supported Supported (This portal is IPv4)
IPv6 Not supported Not supported
Ruckus GRE Tunnel
The below table lists the WISPr details for Ruckus GRE tunnel.
TABLE 14 Non GRE tunnel
Non GRE Tunnel IPv4 IPv6
Non WISPr Client IPv4 Supported Not supported
IPv6 Not supported Not supported
TABLE 15 Non GRE tunnel and internal portal
Non GRE Tunnel IPv4 IPv6
WISPr Client IPv4 Supported Not supported
IPv6 Not supported Not supported
TABLE 16 Non GRE tunnel and external portal
Non GRE Tunnel IPv4 IPv6
WISPr Client IPv4 Supported Not supported
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 37
TABLE 16 Non GRE tunnel and external portal (continued)
Non GRE Tunnel IPv4 IPv6
IPv6 Not supported Not supported
WISPr Portal Details
WISPr Portal Details Overview
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
38 Part Number: 800-71571-001 Rev A
Certificate Warning
Certificate Warning Overview................................................................................................................................... 39
Certificate Warning Overview
Certificate warning when end users are redirecting with HTTPS request.
When a CA-signed certificate is imported to SZ certificate store and applied to Hotspot (WISPr), SZ captive portal and internal portal page
use the imported certificate. However, if an end user enters a HTTPS URL through the browser manually, one certificate warning message is
still expected to be seen in the UE browser.
SZ captive portal need to complete the SSL handshake before sending 302 redirect response to UE. Since the FQDN(common name) in
the certificate is impossible to match the URL that UE tries to visit, the browser will display a certificate warning.
To avoid certificate warning messages, major operating systems already have built in mechanisms to detect captive network and sending
HTTP requests (not HTTPS), so that users can be redirected to a portal page automatically without any certificate error.
Apple iOS CNA (captive network assistant) sends HTTP requests to some static URLs to detect captive portal.
Android devices detected it by sending HTTP requests to http://clients3.google.com/generate_204.
Window 7 sends HTTP requests to http://www.msftncsi.com/ncsi.txt to detect captive portal.
NOTE
URL may vary based on different software releases.
In either case, user devices pop up a window and redirect users to the portal page with HTTP requests instead of HTTPs requests. No
certificate warning will be shown if the UE is redirected automatically by the operating system.
Ruckus SmartZone 100 and Virtual SmartZone Essentials Hotspot WISPr Reference Guide
Part Number: 800-71571-001 Rev A 39
Copyright © 2006-2017. Ruckus Wireless, Inc.
350 West Java Dr. Sunnyvale, CA 94089. USA
www.ruckuswireless.com

Navigation menu