Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale And 300 Hotspot WISPr Reference Guide Smart Zone 3.6 (SZ300/SCG200/v SZ H) SCG200SZ300VSZH 36 Rev A 20171110
SmartZone 3.6 Hotspot WISPr Reference Guide (SZ300/SCG200/vSZ-H) SCG200SZ300VSZH-36-HotspotWisprGuide-RevA-20171110
2017-11-17
User Manual: Ruckus SmartZone 3.6 Hotspot WISPr Reference Guide (SZ300/SCG200/vSZ-H)
Open the PDF directly: View PDF .
Page Count: 40
Download | ![]() |
Open PDF In Browser | View PDF |
REFERENCE GUIDE Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Supporting SmartZone 3.6 Part Number: 800-71572-001 Rev A Publication Date: October 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. 2 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-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 Enrichment Information......................................................................................................................................................... 17 Terminating a User Session.................................................................................................................................................................. 18 Disconnect Command......................................................................................................................................................................... 18 JSON Responses........................................................................................................................................................................................19 JSON Responses - GetConfig..............................................................................................................................................................19 JSON Responses Definitions................................................................................................................................................................20 JSON Response Examples.................................................................................................................................................................. 20 WISPr Support for ZoneDirector Login........................................................................................................................................................ 23 WISPr Support for ZoneDirector Login Overview.................................................................................................................................. 23 Captive Portal Attributes..............................................................................................................................................................................25 Captive Portal Attributes Overview....................................................................................................................................................... 25 The Smart Client......................................................................................................................................................................................... 27 The Smart Client Overview................................................................................................................................................................... 27 Example: Information on the redirection pageExample: Authentication Request (HTTP).................................................................27 Example: Authentication Reply......................................................................................................................................................29 Example: Authentication Result (Login succeeded)....................................................................................................................... 30 Example: Authentication Result (Login failed).................................................................................................................................30 Example: Logoff Reply.................................................................................................................................................................. 30 User Defined Interface - NBI and UDI.......................................................................................................................................................... 31 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 3 User Defined Interface - NBI and UDI Overview.................................................................................................................................... 31 Northbound Portal Interface Support...........................................................................................................................................................35 Northbound Portal Interface Support Overview.................................................................................................................................... 35 WISPr Portal Details.................................................................................................................................................................................... 37 WISPr Portal Details Overview.............................................................................................................................................................. 37 Certificate Warning...................................................................................................................................................................................... 39 Certificate Warning Overview................................................................................................................................................................39 4 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-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 monospace Example Identifies command syntax examples. 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 device(config)# interface ethernet 1/1/6 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 SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 5 Preface Document Feedback 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|y A 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. 6 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A Preface Contacting Ruckus Customer Services and Support 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 selfservice 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 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 7 8 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A About This Guide • • Overview................................................................................................................................................................... 9 Terminology...............................................................................................................................................................9 Overview This Hotspot WISPr Reference Guide describes the SmartCell Gateway™ (SCG) 200, Virtual SmartZone™ High-Scale (vSZ-H) and SmartZone™ (SZ) 300 (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 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 SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 9 10 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-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 • 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 SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 11 Web Interface Configuration Overview Request Format FIGURE 1 Hotspot portal components This reference guide describes the controller RESTful-like/JSON interfaces for external web portal servers. NOTE Refer to Overview on page 9 chapter for conventions used in this guide. 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. 12 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A Web Interface Configuration Overview Controller Web Interface Configuration 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 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 System > General System Settings > Northbound Interface. The password in the figure 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 NOTE Refer to Northbound Portal Interface Support Overview on page 35 for details on MSP support. Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 13 14 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-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 Enrichment Information.............................................................................................................................17 Terminating a User Session..................................................................................................................................... 18 Disconnect Command.............................................................................................................................................18 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 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). NOTE To use asynchronous APIs refer to Using Asynchronous API on page 16 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 15 JSON Commands - User Online Control 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” } The table lists the controller responses to these authentication requests. NOTE The user account test (UE username) mentioned in the above example, has been 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 Normal response Service error General error Possible Responses • 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. • 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. • 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 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”, UEIP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, UE-MAC: “ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157”, UEProxy: “0”, UE-Username: “test”, UE-Password: “test” } The table lists the controller responses to the synchronous login command. TABLE 5 Controller responses to a synchronous login command Response Type Normal response 16 Possible Responses • 101, Client authorized: Response if the user is already authorized. • 201, Login succeeded: Response if the login is accepted. Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A JSON Commands - User Online Control Querying Enrichment Information TABLE 5 Controller responses to a synchronous login command (continued) Response Type Possible Responses 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. • General error • 401, Authentication server error : Response when an authentication connection error occurs or the connection request times out. • 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 Enrichment Information The Northbound Portal Interface provides the JSON command EnrichmentInfo 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 3rd party APs. The following is an example of the EnrichmentInfo request: { Vendor: “ruckus” RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “UserOnlineControl”, RequestType: “EnrichmentInfo”, UE-IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, } The table lists the responses for enrichment information. TABLE 6 Query enrichment Response Type Normal response Service error General error Possible Responses • 102, Enrichment Information. • 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. • 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. Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 17 JSON Commands - User Online Control Terminating a User Session 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 the terminating a user session command: { Vendor: “ruckus” RequestPassword: “myPassword”, APIVersion: “1.0”, RequestCategory: “UserOnlineControl”, RequestType: “Logout”, UE-IP: “ENC12bc24c4777703327f2e0aabbf6b9f9e”, 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” } The table lists the controller response. TABLE 7 Controller responses to a disconnect command Response Type Normal response Service Error General error 18 Possible Responses • 200, OK • 100, Client unauthorized: Response if the user is already unauthorized • 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. • 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. Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A JSON Responses • • • JSON Responses - GetConfig.................................................................................................................................19 JSON Responses Definitions...................................................................................................................................20 JSON Response Examples..................................................................................................................................... 20 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 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 SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 19 JSON Responses JSON Responses Definitions 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 Information • GC: Get Config (Encrypt and Decrypt) TABLE 8 JSON response definitions Category Code Definition Used In UA Informational Success Client Error Server Error SQ TU • • 100 Client unauthorized 101 Client authorized 102 Enrichment Info 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 306 • EI GC • • • • • • • • • • • • • • • • • • • • • Category not supported • • • • • Wrong request password • • • • • 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", UEMAC:"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", UEUsername: "user001", AP-MAC: "04:4f:aa:32:25:f0", SSID: "hotspot-01" SmartClientMode: "none", SmartClientInfo: "", GuestUser: "0", } Example: Enrichment information 20 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A JSON Responses JSON Response Examples { Vendor: "Ruckus", APIVersion: "1.0", ResponseCode: "102", ReplyMessage: "Enrichment Information", UE-IP: "ENC12bc24c4777703327f2e0aabbf6b9f9e", UE-MAC: "ENCCDD319C6A476FA7127DF1FB80A63CD30ADC5E47C3DBE2157", APMAC: "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", UEMAC: "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", UEUsername: "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", UEUsername: "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", APMAC: "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 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 21 JSON Responses JSON Response Examples { 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" } 22 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A WISPr Support for ZoneDirector Login • WISPr Support for ZoneDirector Login Overview..................................................................................................... 23 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. It is our recommendation 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 will be required to make a change to 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 NOTE See Captive Portal Attributes Overview on page 25 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 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 The logout request path in the external portal to the controller should be changed: From: https://sip:9998/logout Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 23 WISPr Support for ZoneDirector Login WISPr Support for ZoneDirector Login Overview To: https://sip:9998/SubscriberPortal/hotspotlogout?uip=10.20.30.40 24 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A Captive Portal Attributes • Captive Portal Attributes Overview...........................................................................................................................25 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. NOTE In case the external portal is in HTTPS, Apple CNA will not work. It works only for HTTP redirect. Redirection Attributes The table lists these parameters provided by controller's captive portal redirection. NOTE See WISPr Support for ZoneDirector Login Overview on page 23 for login and logout details. TABLE 9 Redirection attributes Attributes Description client_mac Encrypted UE Mac address. NOTE The format of the MAC Address is defined at 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 • Un-Auth-SSL-Captive – In case of HTTPS, Captive Portal is performing a “double redirect”. Adding this value to identify this flow or 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. Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A 25 Captive Portal Attributes Captive Portal Attributes Overview TABLE 9 Redirection attributes (continued) Attributes Description 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 3rd party AP, this attribute will be included instead of WLAN and will include the zone ID where the SSID is configured to in the controller. zoneName AP zone name of the UE's associated to 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. 26 Ruckus SmartCell Gateway 200 Virtual SmartZone High Scale and SmartZone 300 Hotspot WISPr Reference Guide Part Number: 800-71572-001 Rev A The Smart Client • The Smart Client Overview...................................................................................................................................... 27 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: < head> < meta http-equiv="content-type" content="text/html; charset=UTF-8"> < /head> < body>