UAM

UAM
Contents
1 Universal Access Method 1.1 Universal Access Method Overview 1.1.1 Login Page 1.1.2 Status Page 1.1.3 Customize UAM Pages 1.2 Extended UAM 1.2.1 Portal version 1 1.2.2 Portal version 2 1.2.3 UAM Login URLs 1.2.4 Authentication Results 1.2.5 External UAM portal sample source code

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 Universal Access Method 1

UAM settings: login name and password and click the login button:

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. 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:

Login Page

UAM

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). Status Page 3

UAM 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. 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. 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).

Customize UAM Pages

UAM The .cgi files can be modified only if PHP knowledge is available. Note that modification of .cgi files can affect the web management functionality. 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.

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 Extended UAM 5

UAM 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.

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.

Portal version 1

UAM 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. 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 %nasid Description

Returns the ID assigned to the NAS. Returns the IP address of the NAS interface the authentication request is sent %wanip, %nasip from. %nasip is used as an alias for %lanip in new implementation. %wanport, Returns the secure port number on the NAS where subscriber login information should be %sslport 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, Returns the MAC address of the subscriber's computer. %mac %clienturl, Returns the original URL requested by the subscriber. %ourl %clientlang, Returns the Web browser language that is set on subscriber's computer. %lang 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&cl

1. Specific URL with no default parameters overridden:

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

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

UAM

https://<WAS_IP>/portal.php?customer_key1=customer_value1&customer_key2=customer_value2&nasip=192 https://<WAS_IP>:<WAS_PORT>/portal.asp?user_ip=customer_value1&customer_key2=customer_value2&nas

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

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>

UAM Login URLs

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

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

<error> 0 100 101 102 103 104 106

<description> "Got user status." "Status information not checked." "No user IP address supplied." "No username supplied." "Remote authentication is disabled." "Bad shared secret supplied." "No user IP and/or MAC address supplied." 10

UAM "No user by MAC" "No user by IP" "No user by IP and MAC" "No user by IP and username" 121 122 123 141 "User with supplied MAC not found." "User with supplied IP address not found." "User with supplied IP and MAC addresses not found." "User with supplied IP address and username not found."

Provided detailed information by ID: <id> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 <decription> User name User IP address User MAC address Session time Session ID User idle time Output bytes Input bytes User domain Remaining bytes Remaining output bytes Remaining input bytes Bandwidth upstream Bandwidth downstream Remaining session time 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>

Authentication Results

11

UAM

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)

External UAM portal sample source code

12