UAM

From wiliGear wiki

Jump to: navigation, search

Contents

Universal Access Method

Universal Access Method (UAM) is a simple Web browser based user authentication method. On initial HTTP request to any Web site (except for white list entries, refer to section White/Black List Configuration of the respective document WILI-S Configuration Reference Manual for details), client’s browser is redirected to the authentication page. After logging in, user is provided with additional set of pages with session statistics and log-out function.

UAM pages are:

  • Login Page – subscriber authentication page, allows the user to login to the network.
  • Status Page – user’s session status page.

These pages can be served by internal WILI Web server or by external Web Application Server.


Universal Access Method Overview

Login Page

When using internal UAM, the Login page is the first page a Hotspot subscriber receives when he starts his Web browser and enters any URL. To get access to the network, the user should enter his authentication settings: login name and password and click the login button:


Image:uam1.jpg


Access Controller could be shared by several Wireless Internet Service Providers (WISP). They are uniquely identified by specifying WISP domain name in addition to subscriber user name when logging in. Access Controller can be configured to send authentication and accounting information to different Authentication, Authorization, and Accounting (AAA) servers associated with different WISP domains.

Image:info.jpg Subscriber login formats available on WILI-S:
  • username
  • username@WISPdomain
  • WISPdomain/username

Status Page

The status page contains detailed subscriber’s session information and provides function for logging out of the network:

Image:uamscreen2.jpg


Username – name of the authenticated user.

MAC address – MAC address of the client station.

IP address – IP address of the client station.

Session time – session time user has spent in current session.

Remaining session time – remaining current session time.

Upload bytes – number of bytes transferred towards the client station.

Remaining upload bytes – number of bytes that can be transferred towards the client station until session is terminated (constant zero means no bound is currently active on the transferred data).

Download bytes – number of bytes sent by the client station.

Remaining download bytes – number of bytes that can be sent by the client station until session is terminated (constant zero means no bound is currently active on the transferred data).

Max upload bandwidth – maximum bandwidth throughput limit for packets sent by the client station.

Max download bandwidth – maximum bandwidth throughput limit for packets sent towards the client station.

Idle time – time since the last transmitted packet from client station.

Remaining idle time – remaining idle time until session is terminated.

Interface name – name of the interface client is connected to.

Remaining total bytes – total number of bytes that can be transferred until session is terminated (constant zero means no bound is currently active on the transferred data).

Refresh – click the button to refresh the subscriber session information.

Logout – click the button to explicitly logout from the network.


Customize UAM Pages

There is a possibility to customize UAM pages according your needs. The WILI software versions starting 3.54 web interface is performed using skins; UAM pages are included in the skin archive and may be easily changed.

Image:info.jpg

The UAM pages customizing requires basic HTML and some PHP knowledge.

Follow the steps to change look and functionality of UAM pages:

  1. Download current skin archive (on device web management interface go to menu Skins, select active skin and click Download).
  2. Extract all files from the skin archive.
  3. Go to uam directory.
  4. HTML pages are in view subdirectory, stylesheets and images are in images subdirectory.
  5. Make your changes (HTML, images, stylesheet - given directories are just suggestion, other subdirectories may be used, but we recommend to keep everything in parent directory uam)
  6. Return one level up from uam directory.
Image:saukt.jpg

Do not forget to update version.txt changing version numbers and/or name. If you will try to upload skin with same version name and numbers, it may fail to overwrite (built-in skins are not overwritable, need update at least version numbers)

  1. Archive all skin files to tar or tgz archive.
  2. Upload archive to device (on device web management interface go to menu Skins, choose archive file using Borwse… button and click Upload button).
  3. Activate new uploaded skin (on device web management interface go to menu Skins, select active skin and click Activate).
Image:info.jpg The .cgi files can be modified only if PHP knowledge is available. Note that modification of .cgi files can affect the web management functionality.
Image:saukt.jpg The lib directory is designed to work with internal device functionality and should not be modified when changing UAM pages.



Extended UAM

The external UAM allows an external Web Application Server (WAS) to intercept and take part in the user authentication process by externally logging-in and logging-out the user as necessary. It also provides a means to query subscriber’s session information.

See the diagram and the description below for an explanation of how the extended UAM process works:

Portal version 1

Network topology: Access Controller (AC) and Portal (WAS) are in the same subnet. Client communication direct to the AC isn't allowed.

Image:Diagram.jpg

Any attempt to access the Internet using HTTP(S) (1) is intercepted by device and client’s Web browser is redirected to the defined Login URL on the WAS (2 & 3). After direct communication is established between the client and the WAS and the user has entered his/her credentials (4), the WAS instructs the device to authenticate the user (5). At this stage, the shared secret is used to establish the secure connection between the WAS and the device. The device sends a RADIUS (Remote Authentication Dial In User Service) access request to the appropriate server (6), receives the response (7) and informs the WAS about authentication status. The WAS then informs the client of the authentication result (8) and if authenticated, the client is granted access to the Internet.

Portal version 2

Network topology: Access Controller (AC) is located in private network and Portal (WAS) is located on remote server, but doesn't have direct access or routes back to the AC. In that case client during authentication is redirected back to the AC and initiated authentication. On AC suppose to be granted HTTPS or HTTP access for client.

Image:Diagramabnw.png


Any attempt to access the Internet using HTTP(S) (1) is intercepted by AC and client’s Web browser is redirected to the defined Login URL on the WAS (2 & 3). After direct communication is established between the client and the WAS and the user has entered his/her credentials (4), the WAS initiates user redirection directly to AC (5). At this stage user sends his credentials directly to AC (6). AC sends a RADIUS (Remote Authentication Dial In User Service) access request to the appropriate server (7), receives the response (8) and informs the WAS about authentication status. The WAS then informs the client of the authentication result (9) and if authenticated, the client is granted access to the Internet.

Image:saukt.jpg The WAS location URL specified for the welcome page redirect must be included in the white list. Refer to section White/Black List Configuration of the respective document WILI-S Configuration Reference Manual for details.

Remote authentication must be enabled and the shared secret must be configured for extended UAM to work.

Image:info.jpg Shared secrets must be the same on the WAS server and the WILI device to allow the opening of a secure SSL session between the WAS and the WILI-S based device.


UAM Login URLs

UAM login URL can be configured in the WILI configuration file and should point to WAS portal. On first Web access subscriber’s browser is redirected to the specified login URL. Different parameters can be added to the URL string to pass them to WAS. This includes several special placeholders the WILI automatically replaces with their respectable values. The following table summarizes the available placeholders:

Placeholder Description
%nasid Returns the ID assigned to the NAS.
%wanip, %nasip Returns the IP address of the NAS interface the authentication request is sent from. %nasip is used as an alias for %lanip in new implementation.
%wanport, %sslport Returns the secure port number on the NAS where subscriber login information should be sent to for authentication.
%nasip, %lanip Returns the IP address of the NAS interface the subscriber's computer is connected to.
%nasifc Returns the NAS interface name the subscriber's computer is connected to.
%clientip Returns the IP address of the subscriber's computer.
%clientmac, %mac Returns the MAC address of the subscriber's computer.
%clienturl, %ourl Returns the original URL requested by the subscriber.
%clientlang, %lang Returns the Web browser language that is set on subscriber's computer.

Note: In new portal implementations only bold placeholders should be used. Duplicate placeholders are included only for backwards compatibility and in future versions may be removed. Parameter %nasifc is optional, but it should be sent back to NAS from portal for better performance.


Examples:

1. General URL:

  <URL><?|&>clientlang=%clientlang&nasid=%nasid&nasip=%nasip&nasifc=%nasifc&clientip=%clientip&clientmac=%clientmac&wanport=%wanport&ourl=%ourl

1. Specific URL with no default parameters overridden:

 https://<WAS_IP>:<WAS_PORT>/portal.cgi?subscriber_key1=subscriber_value1&subscriber_key2=subscriber_value2

2. Specific URLs with nasip and wanport default parameters overrid:

 https://<WAS_IP>/portal.php?customer_key1=customer_value1&customer_key2=customer_value2&nasip=192.168.2.3&wanport=9000
 https://<WAS_IP>:<WAS_PORT>/portal.asp?user_ip=customer_value1&customer_key2=customer_value2&nasip=<overid nasip by value>&wanport=<overid wanport by value>

3. Specific URL with nasip and wanport default parameters overridden and placeholders used:

 https://<WAS_IP>:<WAS_PORT>/portal.cgi?customer_key1=%clientip&customer_key2=%ourl&nasip=<overid nasip by value>&wanport=<overid wanport by value>


There are two network scenarios when default parameters play different roles and should be overwritten in some cases.

1. Assume that the WILI device is not behind a masquerading device, and that its IP address is 192.168.2.2. The subject domain name in its SSL certificates is wilibox.domain.com. The Host HTTP header should be set to one of:

 Host: wilibox.domain.com:443
 Host: 192.168.2.2:443

2. Assume that the WILI device is behind a masquerading device. The masquerading device has the address 192.168.10.3, and the device has the address 192.168.2.2. A NAT mapping is defined on the masquerading device that redirects traffic received on port 443 to 192.168.2.2:443. The login application on WAS must send its requests to 192.168.10.3, which results in a HTTP Host header that contains one of the following:

 Host: natting.router.com:443
 Host: 192.168.10.3:443

When this request is forwarded to the WILI device, it will be rejected. To solve the problem, the login application on WAS must forge the host HTTP header. This is easily done by plugging in the values returned by the %nasip and %wanport placeholders:

 Host: %nasip:%wanport

The WILI device sends the username and password to the RADIUS server to authenticate the subscriber. If authentication is successful, the subscriber's IP or MAC address is used to grant wireless/wired network access to the subscriber's computer. The WILI device returns a positive or negative answer for the subscriber login, along with the relevant URLs that may be needed by the login application on WAS in order to redirect the subscriber to either a Welcome page or a Login error page located on the WAS. This information is returned as standard plain/text with key-value content. The login application on WAS must parse this information to retrieve the response. All possible responses are described below.

Authentication Results

1. Remote user log-on produces XML output.

 <logon>
   <status>string</status>
   <error>numeric</error>
   <description>string</description>
   <replymessage>string</replymessage>
 </logon>

Response statuses and error codes:

<status> <error> <description>
"Ok" 0 "User logged on."
"Not checked" 100 "Logon information not checked."
"No IP" 101 "No user IP address supplied."
"No username" 102 "No username supplied."
"Disabled" 103 "Remote authentication is disabled."
"Bad secret" 104 "Bad shared secret supplied."
"No password" 105 "No user password supplied."
"No IP/MAC" 106 "No user IP and/or MAC address supplied."
"Ok" 110 "User already logged on."
"Failed to authorize" 111 "Failed to authorize user."
"Bad password" 112 "Bad username or/and password."
"Network failed" 113 "Network connection failed."
"Accounting error" 114 "Accounting error."
"Too many users" 115 "Too many users connected"
"Unknown authorization error" 120 "Unknown authorization error"


Responses from RADIUS are served with the following response line:

 <replymessage>string</replymessage>

If there are multiple RADIUS messages, the line will be repeated to output all RADIUS responses. Example:

 <logon>
   <status>Failed to authorize</status>
   <error>111</error>
   <description>Failed to authorize user.</description>
   <replymessage>User password is expired.</replymessage>
   <replymessage>Can not authenticate user, because user is disabled.</replymessage>
 </logon>

In case, RADIUS did not respond with custom messages, replymessage tag will not be added to XML output.


2. Remote user log-off produces XML output.

 <logoff>
   <status>string</status>
   <error>numeric</error>
   <description>string</description>
 </logoff>

Response statuses and error codes:

<status> <error> <description>
""Ok"" 0 "User logged off."
"Not checked" 100 "Logoff information not checked."
"No username" 102 "No username supplied"
"Disabled" 103 "Remote authentication is disabled."
"Bad secret" 104 "Bad shared secret supplied."
"No IP/MAC" 106 "No user IP and/or MAC address supplied."
"No user by MAC" 121 "User with supplied MAC not found."
"No user by IP" 122 "User with supplied IP address and username not found."
"No user by IP and MAC" 123 "User with supplied IP, MAC addresses and username not found."
"Failed to logoff" 131 "Failed to logoff user."
"Cannot resolve IP" 132 "Cannot resolve user IP"
"Unknown logoff error" 140 "Unknown logoff error"


3. Remote user status produces XML output.

 <ppstatus>
    <status>string</status>
    <error>numeric</error>
    <description>string</description>
    <entry id="1">string</entry>
    <entry id="2">string</entry>
    <entry id="3">string</entry>
    <entry id="4">string</entry>
    <entry id="5">string</entry>
    <entry id="6">string</entry>
    <entry id="7">string</entry>
    <entry id="8">string</entry>
    <entry id="9">string</entry>
    <entry id="10">string</entry>
    <entry id="11">string</entry>
    <entry id="12">string</entry>
    <entry id="13">string</entry>
    <entry id="14">string</entry>
    <entry id="15">string</entry>
    <entry id="16">string</entry>
  </ppstatus>

Response statuses and error codes:


<status> <error> <description>
"Ok" 0 "Got user status."
"Not checked" 100 "Status information not checked."
"No IP" 101 "No user IP address supplied."
"No username" 102 "No username supplied."
"Disabled" 103 "Remote authentication is disabled."
"Bad secret" 104 "Bad shared secret supplied."
"No IP/MAC" 106 "No user IP and/or MAC address supplied."
"No user by MAC" 121 "User with supplied MAC not found."
"No user by IP" 122 "User with supplied IP address not found."
"No user by IP and MAC" 123 "User with supplied IP and MAC addresses not found."
"No user by IP and username" 141 "User with supplied IP address and username not found."


Provided detailed information by ID:

<id> <decription>
1 User name
2 User IP address
3 User MAC address
4 Session time
5 Session ID
6 User idle time
7 Output bytes
8 Input bytes
9 User domain
10 Remaining bytes
11 Remaining output bytes
12 Remaining input bytes
13 Bandwidth upstream
14 Bandwidth downstream
15 Remaining session time
16 Remaining total bytes


When there were no errors and user statistics was received successfully the following XML output will be produced:

 <ppstatus>
   <status>Ok</status>
   <error>0</error>
   <description>Got user   status.</description>
   <entry   id="1">g17</entry>
   <entry   id="2">192.168.2.117</entry>
   <entry   id="3">200347C92B63</entry>
   <entry   id="4">00:00:05</entry>
   <entry   id="5">3E64C7967A36</entry>
   <entry   id="6">00:00:03</entry>
   <entry   id="7">0   bytes</entry>
   <entry   id="8">0   bytes</entry>
   <entry   id="9">testlab</entry>
   <entry   id="10">unlimited</entry>
   <entry   id="11">unlimited</entry>
   <entry   id="12">unlimited</entry>
   <entry   id="13">32   Mbps</entry>
   <entry   id="14">32   Mbps</entry>
   <entry   id="15">04:59:55</entry>
   <entry   id="16">unlimited</entry>
  </ppstatus>

External UAM portal sample source code

Download sample portal code version 1

Download sample portal code version 2 (since v5.23)

Download sample portal code version 3 (since v5.26)

Personal tools