Quiconnect tutorial: WISPr basics ­ March 2007

Quiconnect Tutorial: Implementing basic functionalities  
of Wireless Internet Service Provider (WISP) Roaming

Purpose and Scope of this Document
This document explains how to implement basic functionality of Wireless Internet Service Provider 
(WISP) roaming. The precise scope of this tutorial is the adaptation of a landing page to allow 
roaming customers’ Smart client connections. Its intended audience are  Network Operators, who 
wish to offer this functionality to visiting subscribers.
It is not intended to replace the WISPr official guideline [1]: Wi­Fi Alliance, "Best Current 
Practices for Wireless Internet Service Provider (WISP) Roaming", http://www.wi­
fi.org/opensection/wispr.asp, February 2003.

Introduction
The basic principal of WISPr is to allow smart clients to be able to connect to an operator's network 
without the subscriber having to provide credentials at every connection. 
Smart clients receive XML messages that describe the different steps required to log on so that the 
subscriber can get connected.
The basic goal behind WISPr is for smart clients to be able to connect to an operator's network 
without the user having to go through any browsing experience.
Smart clients receive XML messages that describe the different steps for logging in in order to get 
connected. We have chosen to only go through the basic messages that a smart client should 
understand that are:
• Initial redirect
• Authentication notification
• Logoff notification

These messages are sufficient for a functional implementation of WISPr. For a more thorough 
understanding of the WISPr protocol, please refer to the WISPr document.
In order to make an existing system WISPr compliant, the easiest way is to update the pages that the 
user would see when logging in through a browser and to add the information that the smart client 
requires to get connected automatically.
The XML messages that a smart client expects should be embedded within an HTML comment so 
that they do not disturb the existing user experience.

Connection scenarios
Hereafter are two scenarios of a successful login as well as a failed login that describe what the 
exchanges are between the smart client, the NAS(gateway) and the service provider's AAA server.

1
 Quiconnect tutorial: WISPr basics ­ March 2007

Login Request : Successful case

 Client      Gateway       AAA
   |­­­­­­­­­­­>|               1. Arbitrary http GET
   |<­­­­­­­­­­­|               2. Redirect Login URL
   |­­­­­­­­­­­>|               3. POST credentials
                |­­­­­­­­­­>|   4. Access­Request (RADIUS)
                |<­­­­­­­­­­|   5. Access­Accept (RADIUS)
   |<­­­­­­­­­­­|               6. Success Notification
                |­­­­­­­­­­>|   7. Accounting­Start (RADIUS)
                |<­­­­­­­­­­|   8. Accounting­Response (RADIUS)
                .
                .              Internet Access Enabled
                .
   |­­­­­­­­­­­>|               9.  GET Logoff URL
                |­­­­­­­­­­>|   10. Accounting­Stop (RADIUS)
                |<­­­­­­­­­­|   11. Accounting­Response (RADIUS)
   |<­­­­­­­­­­­|               12. Logoff Notification
 
1. The smart client starts by requesting any URL.
2. The NAS sees that the client isn't authenticated and redirects it to the landing page that 
contains the 'initial redirect' XML message (embedded into an HTML comment tag)
3. The smart client then posts the user's credentials to the login URL contained in the 'initial 
redirect' message.
4. Standard radius protocol
5. Standard radius protocol
6. The NAS sends an answer back to the smart client with an 'authentication notification' XML 
message that contains the status of the authentication and the logoff URL if the login was 
successful.
7. Standard radius protocol
8. Standard radius protocol
9. The smart client requests the logoff URL as received in the previous XML message.
10. Standard radius protocol
11. Standard radius protocol
12. The NAS sends an answer back to the smart client with a 'logoff notification' XML message 
that tells the client if the logoff was successful.

2
 Quiconnect tutorial: WISPr basics ­ March 2007

Login Request: Reject

 Client      Gateway       AAA
   |­­­­­­­­­­­>|                1. Arbitrary http GET
   |<­­­­­­­­­­­|                2. Redirect Login URL
   |­­­­­­­­­­­>|                3. POST credentials
                |­­­­­­­­­­>|    4. Access­Request (RADIUS)
                |<­­­­­­­­­­|    5. Access­Reject (RADIUS)
   |<­­­­­­­­­­­|                6. Failure Notification

1. The smart client starts by requesting any URL.
2. The NAS sees that the client isn't authenticated and redirects it to the landing page that 
contains the 'initial redirect' XML message (embedded into an HTML comment tag)
3. The smart client then posts the user's credentials to the login URL contained in the 'initial 
redirect' message.
4. Standard radius protocol
5. Standard radius protocol
6. The NAS sends an answer back to the smart client with an 'authentication notification' XML 
message that contains the status of the authentication and a textual description of why the 
authentication failed.

Smart Client exchanges
The dialogue between the NAS and the smart client is made up of:
• An initial request, which is a standard HTTP GET request.
• Sending the user credentials to the NAS through an HTTP POST. The characteristics of the post 
are described below.
• Receiving XML messages from the NAS in the HTTP responses. The different messages that the 
NAS can send are also described below.

Credentials post
The Smart Client shall send a secure HTTP POST operation to the login URL returned in the 
Redirect message. Since the post will be using https, it should be assumed that port 443 would be 
used if not specified otherwise as part of the LoginURL.

The POST parameters shall be as follows:
• UserName: the full user id including appropriate routing prefixes.
• Password: the user’s password.
• button: HTML form button identifier (always equals to “Login”).
• OriginatingServer: the original (before redirect) URL requested by the smart client.
• FNAME: HTML form name (always equals to 0).

3
 Quiconnect tutorial: WISPr basics ­ March 2007

XML message description
All messages sent to the smart client by the NAS should at least contain a message type and a 
response code.

The message types shall be one of the following values:

Message type Message meaning
100 Initial redirect message
120 Authentication notification
130 Logoff notification

The response code shall be one of the following values:

Response code Response meaning
0 No error
50 Login succeeded (Access ACCEPT)
100 Login failed (Access REJECT)
150 Logoff succeeded
255 Access gateway internal error

Here is a description of the different fields each of the XML messages should contain:

Initial redirect

Information name Field format/value
Access procedure <AccessProcedure>
  Procedure Version
</AccessProcedure>
Location Identifier <AccessLocation>Location ID</AccessLocation>
Location Name <LocationName>
  User readable location name
</LocationName>
Login URL <LoginURL>https://Login_URL</LoginURL>
Abort Login URL <AbortLoginURL>
  https://Abort_Login_URL
</AbortLoginURL>
Message Type <MessageType>Message type</MessageType>
Response <ResponseCode>Response code</ResponseCode>
                     

4
 Quiconnect tutorial: WISPr basics ­ March 2007

Authentication reply 

Information name Field format/value
Message Type <MessageType>Message type</MessageType>
Response <ResponseCode>Response code</ResponseCode>
Logoff URL <LogoffURL>https://Logoff_URL</LogoffURL>
Reply Message <ReplyMessage>Reply message</ReplyMessage>
(optional)
 

Logoff reply

Information name Field format/value
Message Type <MessageType>Message type</MessageType>
Response <ResponseCode>Response code</ResponseCode>

Full WISPr messages

WISPr messages examples
Here are some examples of proper WISPr messages. Italic values must be replaced by appropriate 
ones.

Activation ­ Redirect Reply
<?xml version="1.0" encoding="UTF­8"?>
<WISPAccessGatewayParam
     xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance"
     xsi:noNamespaceSchemaLocation="http://NAS_Address/WISPAccessG
atewayParam.xsd">
  <Redirect>
    <AccessProcedure>1.0</AccessProcedure>
    <AccessLocation>Hotspot identifier</AccessLocation>
    <LocationName>
      NAS location 
    </LocationName>
    <LoginURL>http://NAS_Address/login/</LoginURL>
    <MessageType>100</MessageType>
    <ResponseCode>0</ResponseCode>
  </Redirect>
</WISPAccessGatewayParam>

5
 Quiconnect tutorial: WISPr basics ­ March 2007

Authentication Reply – Login successful
<?xml version="1.0" encoding="UTF­8"?>
<WISPAccessGatewayParam
     xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance"
     xsi:noNamespaceSchemaLocation="http://NAS_Address/WISPAccessG
atewayParam.xsd">
  <AuthenticationReply>
    <MessageType>120</MessageType>
    <ResponseCode>50</ResponseCode>
    <ReplyMessage>Authentication Success</ReplyMessage>
    <LogoffURL>http://NAS_Address/logoff/</LogoffURL>
  </AuthenticationReply>
</WISPAccessGatewayParam>

Authentication Reply – Login rejected
<?xml version="1.0" encoding="UTF­8"?>
<WISPAccessGatewayParam
     xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance"
     xsi:noNamespaceSchemaLocation="http://NAS_Address/WISPAccessG
atewayParam.xsd">
  <AuthenticationReply>
    <MessageType>120</MessageType>
    <ResponseCode>100</ResponseCode>
    <ReplyMessage>Invalid Password</ReplyMessage>
    <LogoffURL>http://NAS_Address/logoff/</LogoffURL>
  </AuthenticationReply>
</WISPAccessGatewayParam>

Logoff Reply(Logoff Successful)
<?xml version="1.0" encoding="UTF­8"?>
<WISPAccessGatewayParam
     xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance"
     xsi:noNamespaceSchemaLocation="http://NAS_Address/WISPAccessG
atewayParam.xsd">
  <LogoffReply>
    <MessageType>130</MessageType>
    <ResponseCode>150</ResponseCode>
  </LogoffReply>
</WISPAccessGatewayParam>

6
 Quiconnect tutorial: WISPr basics ­ March 2007

Logoff Reply (Logoff failed – Access Gateway internal error)
<?xml version="1.0" encoding="UTF­8"?>
<WISPAccessGatewayParam
     xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance"
     xsi:noNamespaceSchemaLocation="http://NAS_Address/WISPAccessG
atewayParam.xsd">
  <LogoffReply>
    <MessageType>130</MessageType>
    <ResponseCode>255</ResponseCode>
  </LogoffReply>
</WISPAccessGatewayParam>

Insertion of WISPr messages into an HTML page
WISPr messages must be embedded in an HTML page, within an HTML comment tag, as shown 
below (Example of a successful logoff reply):

<html>
  <head>
    <title>Logoff successful</title>
  </head>
  <body>
    You have successfully logged out.
    <!­­
      <?xml version="1.0" encoding="UTF­8"?>
      <WISPAccessGatewayParam
           xmlns:xsi="http://www.w3.org/2001/XMLSchema­instance"
           xsi:noNamespaceSchemaLocation="http://NAS_Address/WISPA
ccessGatewayParam.xsd">
        <LogoffReply>
          <MessageType>130</MessageType>
          <ResponseCode>150</ResponseCode>
        </LogoffReply>
      </WISPAccessGatewayParam>
    ­­>
  </body>
</html>

Reference documents 
1. Wi­Fi Alliance, "Best Current Practices for Wireless Internet Service Provider (WISP) Roaming", 
http://www.wi­fi.org/opensection/wispr.asp, February 2003