Ruckus SCG™ 200 And VSZ H™Hotspot WISPr Reference Guide For SmartZone 3.4.1 Smart Zone (MR) Hotspot Portal Integration (SCG200/v SZ H) Scg200 341 Vszh34Hotspot Guide20161001
2016-10-17
User Manual: Ruckus SmartZone 3.4.1 (MR) Hotspot Portal Integration Reference Guide (SCG200/vSZ-H)
Open the PDF directly: View PDF 
.
Page Count: 52
| Download | |
| Open PDF In Browser | View PDF |
Ruckus Wireless
SmartCell Gateway 200 and Virtual
SmartZone High Scale
™
™
Hotspot WISPr Reference Guide for
SmartZone 3.4.1
Part Number 800-71364-001 Rev A
Published October 2016
www.ruckuswireless.com
Copyright Notice and Proprietary Information
Copyright 2016. Ruckus Wireless, 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 Ruckus Wireless, Inc.
(“Ruckus”), or as expressly provided by under license from Ruckus.
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. RUCKUS AND ITS 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. RUCKUS RESERVES THE RIGHT TO MAKE CHANGES OR
UPDATES TO THE MATERIAL AT ANY TIME.
Limitation of Liability
IN NO EVENT SHALL 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, ZoneFlex, FlexMaster, ZoneDirector, SmartMesh, Channelfly, Smartcell,
Dynamic PSK, and Simply Better Wireless are trademarks of Ruckus Wireless, Inc. in the United States and other
countries. All other product or company names may be trademarks of their respective owners.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
2
Contents
About This Guide
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Online Training Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1
Web Interface Configuration
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Controller Web Interface Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2
JSON Commands
User Online Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Request Authentication - Asynchronous Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Using Asynchronous API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Request Authentication - Synchronous Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Querying a User Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Terminating a User Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Disconnect Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3
JSON Responses
GetConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
JSON Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
JSON Response Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Example: Client unauthorized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Example: Client authorized. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Example: Success information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Example: Login succeeded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Example: Authentication pending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Example: Not found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Example: Login failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Example: Bad request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
3
Example: Version not supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Example: Command not supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Example: Category not supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Example: Wrong request password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Example: Internal server error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Example: RADIUS server error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Example: Encrypt for MAC address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Example: Decrypt for MAC address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A
WISPr Support for ZoneDirector Login
Customer Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Customer Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
B
Captive Portal Attributes
Redirection Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
C
The Smart Client
The Smart Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Example: Information on the redirection page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Example: Authentication Request (HTTP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Example: Authentication Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Example: Authentication Result (Login succeeded). . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Example: Authentication Result (Login failed) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Example: Logoff Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
D
User Defined Interface
NBI and UDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Index
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
4
About This Guide
This SmartCell Gateway™ (SCG) 200 and Virtual SmartZone High-Scale (vSZ-H)
Hotspot Portal Integration Reference Guide describes the SCG-200/vSZ-H (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.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
5
Document Conventions
Document Conventions
Table 1 and Table 2 list the text and notice conventions that are used throughout
this guide.
Table 1.
Text conventions
Convention
Description
monospace
Represents information as it [Device name]>
appears on screen
monospace bold
Represents information that [Device name]> set
you enter
ipaddr 10.0.0.12
default font bold
Keyboard keys, software
buttons, and field names
On the Start menu, click All
Programs.
italics
Screen or page names
Click Advanced Settings.
The Advanced Settings page
appears.
Table 2.
Example
Notice conventions
Notice Type
Description
NOTE
Information that describes important features or instructions
CAUTION!
Information that alerts you to potential loss of data or potential
damage to an application, system, or device
WARNING!
Information that alerts you to potential personal injury
Terminology
Table 3 lists the terms used in this guide.
Table 3.
Terms used in this guide
Terms
Description
AP
Access Point
CP
Captive Portal
NBI
Northbound Interface
RADIUS
Remote Access Dial In User Service
SCG
Smart Cell Gateway
SSL
Secure Socket Layer
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
6
Related Documentation
Table 3.
Terms used in this guide
Terms
Description
TCP
Transmission Control Protocol
UDI
User Define Interface
UE
User Equipment
UE-IP
User Equipment - IP Address
UE-MAC
User Equipment - MAC Address
Related Documentation
For a complete list of documents that accompany this release, refer to the Release
Notes.
Online Training Resources
To access a variety of online Ruckus Wireless training modules, including free
introductory courses to wireless networking essentials, site surveys, and Ruckus
Wireless products, visit the Ruckus Wireless Training Portal at:
https://training.ruckuswireless.com.
Documentation Feedback
Ruckus Wireless is interested in improving its documentation and welcomes your
comments and suggestions. You can email your comments to Ruckus Wireless at:
docs@ruckuswireless.com
When contacting us, please include the following information:
• Document title
• Document part number (on the cover page)
• Page number (if appropriate)
For example:
• SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1
• Part number: 800-71364-001
• Page 88
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
7
Web Interface Configuration
1
In this chapter:
• Overview
• Request Format
• Controller Web Interface Configuration
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
8
Web Interface Configuration
Overview
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 its role in the hotspot portal as seen
in Figure 1.
• 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 (user name 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 (user name and password).
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
9
Web Interface Configuration
Overview
Figure 1. Hotspot portal components
This reference guide describes the controller RESTful-like/JSON interfaces for
external web portal servers.
NOTE: Refer to About This Guide chapter for conventions used in this guide.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
10
Web Interface Configuration
Request Format
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://{scg_management_ip}:9080/portalintf
HTTPS Request
https://{scg_management_ip}:9443/portalintf
NOTE: The above URI is a fixed value and cannot be modified.
NOTE: You can download the log for northbound portal interface from the controller
web interface by navigating to Administration > Diagnostics > Application Logs
& Status, as all other applications.
Table 4 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 4.
Portal details
Port
Layer 4 Source
Number Protocol
Destination
Configurable from Purpose
Web Interface?
9080
HTTP
Any
Controller
No
Northbound Portal Interface
for Hotspot
9443
HTTPS
Any
Controller
No
Northbound Portal 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 portal
interface.
The northbound portal interface request password can be configured in the
controller web interface by navigating to Configuration > SCG System > General
System Settings > Northbound Portal Interface. See Figure 2.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
11
Web Interface Configuration
Controller Web Interface Configuration
The password in Figure 2 is a token to ensure that a portal has the permission to
get the services from the northbound portal 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.
Figure 2. Setting the password
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
12
JSON Commands
2
In this chapter:
• User Online Control
• Request Authentication - Asynchronous Login
• Request Authentication - Synchronous Login
• Querying a User Status
• Terminating a User Session
• Disconnect Command
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
13
JSON Commands
User Online Control
User Online Control
The northbound portal interface supports the following JSON commands:
• Login
• Login Async
• Status
• Logout
• Disconnect
These commands are used for user authentication, user status query, and terminating user sessions. For each command (JSON POST), both the UE-IP and UEMAC 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 Table 10 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
GetConfig section.
NOTE: Northbound Interface (NBI) expects to receive encrypted UE-IP and UEMAC 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 RADIUS 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).
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
14
JSON Commands
Request Authentication - Asynchronous Login
NOTE: To use asynchronous APIs refer to Using Asynchronous API
The following is an example of the asynchronous login request:
{
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”
}
Table 5 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 RADIUS server. The hotspot portal does not
provide an interface for manipulating user account information.
Table 5.
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.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
15
JSON Commands
Request Authentication - Synchronous Login
Table 5.
Controller responses to authentication (asynchronous login) requests
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 App 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 synchronous login command, the external Web portal must wait for
the authentication process to complete, which is usually processed by the RADIUS
server. This could result in a delayed response if the controller is unable to get a
response from the RADIUS 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”,
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
16
JSON Commands
Request Authentication - Synchronous Login
UE-Proxy: “0”,
UE-Username: “test”,
UE-Password: “test”
}
Table 6 lists the controller responses to the synchronous login command.
Table 6.
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 RADIUS
reply message is returned.
• 400, Internal server error: Response when an
controller internal error occurs.
• 401, Radius server error: Response when a
RADIUS 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.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
17
JSON Commands
Querying a User Status
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”
}
Table 7 lists the controller responses to these user status query commands.
Table 7.
Controller responses to user status query
Response Type
Possible Responses
If there is a pending
• 201, Login succeeded.
authentication process • 202, Authentication pending: Authentication is in
for this client
progress, portal server needs to check the result later.
If there is no pending • 100, Client unauthorized.
authentication process or
for this client
• 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 RADIUS reply
message is returned
• 400, Internal server error: Response when an controller
internal error occurs.
• 401, Radius server error: Response when a RADIUS
connection error occurs or the connection request times
out.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
18
JSON Commands
Terminating a User Session
Table 7.
Controller responses to user status query
Response Type
Possible Responses
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”,
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
19
JSON Commands
Disconnect Command
UE-MAC: “ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157”
}
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”
}
Table 8 lists the controller response.
Table 8.
Controller responses 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.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
20
JSON Commands
Disconnect Command
Table 8.
Controller responses to a disconnect command
Response Type
Possible Responses
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.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
21
JSON Responses
3
In this chapter:
• GetConfig
• JSON Responses
• JSON Response Examples
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
22
JSON Responses
GetConfig
GetConfig
The northbound interface supports the following JSON commands in request
category - GetConfig:
1 Control Blade IP List
2 Cluster Blade IP List
3 Management Blade IP List
4 User Interface IP List
5 Encrypt
6 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 first four commands are used for obtaining the different blade IP lists. The
northbound portal interface simply responds with the control, cluster, management
blade or user defined IP list of the controller. The following is an example of the
GetConfig command:
{
Vendor: “ruckus”,
RequestPassword: “myPassword”,
APIVersion: “1.0”,
RequestCategory: “GetConfig”,
RequestType: “ControlBladeIPList”,
The following is an example of the success response:
{
Vendor:“ruckus”,
ReplyMessage:”OK",
ResponseCode:200,
APIVersion:"1.0"
ControlBladeIPList:[“172.17.18.149”, “172.17.18.159”,
“172.17.18.169”]
}
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
23
JSON Responses
GetConfig
Control Blade IP address list can be replaced by Cluster Blade IP List, Management
Blade IP List or User Interface IP List, depending on context of the GetConfig
command.
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:
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
24
JSON Responses
JSON Responses
{
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
JSON Responses
Table 9 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)
• GC: Get Config (Control Blade IP, Cluster Blade IP, Management Blade IP, User
Interface IP, Encrypt and Decrypt)
NOTE: Refer to JSON Commands for commands related to the responses
mentioned above.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
25
JSON Responses
JSON Response Examples
Table 9.
JSON response definitions
Category
Code Definition
Used In
UA
Informational
Success
Client Error
Server Error
SQ
TU
•
•
100
Client unauthorized
101
Client authorized
200
OK
201
Login succeeded
202
Authentication pending
•
•
300
Not found
•
•
301
Login failed
•
•
302
Bad request
•
303
Version not supported
304
Command not supported
305
Category not supported
306
•
EI
GC
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Wrong request password
•
•
•
•
•
400
Internal server error
•
•
•
•
•
401
Radius server error
•
•
JSON Response Examples
This section provides the following examples of JSON responses defined in Table 9.
• Example: Client unauthorized
• Example: Client authorized
• Example: Success information
• Example: Login succeeded
• Example: Authentication pending
• Example: Not found
• Example: Login failed
• Example: Bad request
• Example: Version not supported
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
26
JSON Responses
JSON Response Examples
• Example: Command not supported
• Example: Category not supported
• Example: Wrong request password
• Example: Internal server error
• Example: RADIUS server error
• Example: Encrypt for MAC address
• Example: Decrypt for MAC address
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
27
JSON Responses
JSON Response Examples
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",
}
Example: Success information
{
Vendor: "Ruckus",
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
28
JSON Responses
JSON Response Examples
Version: "1.0",
ResponseCode: "200",
ReplyMessage: "OK"
UE-IP: "ENC12bc24c4777703327f2e0aabbf6b9f9e",
UE-MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157",
SmartClientMode: "none",
SmartClientInfo: "",
GuestUser: "0",
}
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
29
JSON Responses
JSON Response Examples
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",
}
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
30
JSON Responses
JSON Response Examples
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",
}
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
31
JSON Responses
JSON Response Examples
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",
}
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
32
JSON Responses
JSON Response Examples
Example: Internal server error
{
Vendor: "ruckus",
APIVersion: "1.0",
ResponseCode: "400",
ReplyMessage: "Internal server error",
}
Example: RADIUS server error
{
Vendor: "ruckus",
APIVersion: "1.0",
ResponseCode: "401",
ReplyMessage: "Radius server error",
}
Example: Encrypt for MAC address
{
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"
}
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
33
JSON Responses
JSON Response Examples
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"
}
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
34
WISPr Support for ZoneDirector
Login
A
In this appendix:
• Customer Login
• Customer Logout
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
35
Customer Login
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 the controller's captive portal redirection
NOTE: See Captive Portal Attributes for details.
.
• Login: The login request path in the external portal to the controller should be
changed:
From:
https://{sip-server-ip-address}:9998/login
To:
https://{sip-server-ip-address}:9998/SubscriberPortal/hotspotlogin
NOTE: The login request also supports HTTP with port number 9997.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
36
Customer Logout
NOTE: This login request should include the customer’s login credentials such as
the user name 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
The logout request path in the external portal to the controller should be changed:
From:
https://{sip-server-ip-address}:9998/logout
To:
https://{sip-server-ip-address}:9998/SubscriberPortal/
hotspotlogout?uip=10.20.30.40
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
37
Captive Portal Attributes
B
In this appendix:
• Redirection Attributes
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
38
Redirection Attributes
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 GetConfig section.
NOTE: Apple CNA only works for HTTP redirect. If does not work if the external
portal is in HTTPS.
Redirection Attributes
Table 10 lists these parameters provided by controller's captive portal redirection.
NOTE: See WISPr Support for ZoneDirector Login 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.
loc
AP location.
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.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
39
Redirection Attributes
Table 10. Redirection attributes
Attributes
Description
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.”
• “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 the WLAN.
wlanName
SSIDs configured WLAN Name
zoneId
In case of a 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 Zone name is configured using the WLANs. The
zone name is used for Kumo. The value is encrypted
based on a special key.
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
40
The Smart Client
C
In this appendix:
• The Smart Client
SmartCell Gateway 200 and vSZ-H Hotspot WISPr Reference Guide for SmartZone 3.4.1, 800-71364-001 Rev A
41
The Smart Client
The Smart Client
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:
< head>
< meta http-equiv="content-type" content="text/html; charset=UTF-8">
< /head>
< body>