-
Network Policy Controller
UAM/RADIUS Guide
-
2 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
1. Introduction ..................................................................................................................................... 3
1.1. Terminology ............................................................................................................................... 3
2. Web Authentication ......................................................................................................................... 5
2.1. Redirect URL Parameters............................................................................................................ 5
2.2. UAM Login URL .......................................................................................................................... 5
2.3. UAM Logout URL ........................................................................................................................ 6
3. UAM/RADIUS Call Flow..................................................................................................................... 7
4. RADIUS ............................................................................................................................................. 8
4.1. Authentication Request Attributes ............................................................................................. 8
4.2. Authentication Response Attributes ........................................................................................... 9
4.3. Accounting Attributes ............................................................................................................... 10
4.4. VSA Dictionary .......................................................................................................................... 13
-
3 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
1. Introduction This document describes the UAM and RADIUS functionality supported by the Global Reach Network Policy
Controller.
1.1. Terminology
Network Policy Controller
The Network Policy Controller or NPC provides the services required by Wireless service providers (WISPs),
such as AAA/RADIUS, captive portal redirect, ACLs, bandwidth shaping etc.
Universal Access Method
The universal access method (UAM) is frequently used by WISPs (Wireless Internet Service Provider) to
allow access to a wireless network or access to another network while roaming.
The roaming customer uses a regular web browser to access a login page on the captive portal where he
can fill in his credentials (typically his username and password) to gain access to the network.
MAC Address
A media access control address (MAC address) is a unique identifier assigned to network interfaces for
communications on the physical network segment. MAC addresses are used as a network address for most
IEEE 802 network technologies, including Ethernet and Wi-Fi.
User Equipment (UE)
Defines a device that is used directly by an end-user to communicate and interact with the Wi-Fi service.
Walled Garden
The purpose of a walled garden is to restrict access to services for unauthorized users, allowing access to
the external captive portal and other services required for the UE to authorize with the Wi-Fi service.
Captive Portal
A captive portal is a Web page that the user of a public-access network is obliged to view and interact with
before access is granted. Captive portals are typically used by business centers, airports, hotel lobbies,
coffee shops, and other venues that offer free Wi-Fi hot spots for Internet users.
AAA Server
RADIUS servers use the AAA protocol to manage network access in the following two-step process, also
known as an AAA transaction. AAA stands for authentication, authorization and accounting.
RADIUS
Remote Authentication Dial In User Service (RADIUS) is a networking protocol that provides centralized
Authentication, Authorization, and Accounting (AAA) management for users who connect and use a
network service.
-
4 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
Access Point
A wireless Access Point (AP) is a device that allows wireless devices to connect to a wired network using
Wi-Fi, or related standards. The AP usually connects to a router (via a wired network) as a standalone
device, but it can also be an integral component of the router itself.
-
5 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
2. Web Authentication
Before a user can be authorized access through the NPC, the UE must first authenticate via the UAM
provided by the Web Authentication service. After redirection to the captive portal, the UE is required to
authenticate with the NPC using the Web Authentication service described in this section.
2.1. Redirect URL Parameters
Contained within the initial redirect URL to the captive portal (shown in Figure 1), are query string
parameters used to identify the UE and the session, described in Figure 2.
Figure 1.
https://www.mycaptiveportal.com/?mac=00:11:22:33:44:55&state=3&sid=00112233-4455-6677-8899-
aabbfdf5f0af&vlan=1&bssid=cc:dd:ee:ff:00:11&orig_url=http%3a%2f%2fwww.google.com%2f
Figure 2.
mac The MAC address of the UE formatted as a UTF-8 string of colon delimited hex octets.
state The authorization state for the UE. State 3 indicates authorized, State 2 indicates
authorized with HTTP/HTTPS redirect and State 1 indicates fully authorized.
sid Uniquely identifies the session for accounting purposes
vlan Specifies the 802.1q VLAN for which the UE was discovered.
bssid Indicates the MAC address of the AP that the user is associated to at the time of
redirection.
orig_url The URL the UE requested prior to redirection to the captive portal.
2.2. UAM Login URL
The host name for the UAM Login URL is configurable but a default of gateway.wifi-portals.com is provided
by the NPC along with an SSL certificate issued by a trusted root CA for secure authentication. When using
a custom hostname with SSL enabled, an appropriate SSL certificate from a trusted root CA is required. A
certificate from a self-signed CA is also supported but results in a security warning to the user during
authentication.
The UAM Login URL accepts the parameters described in Figure 3 either as part of the query string for a
HTTP GET request or as part of a HTTP POST with a Content-Type of application/x-www-form-urlencoded.
An example UAM Login URL is shown in Figure 4.
Figure 3.
username Username to be sent in the Access-Request to the AAA.
password Password to be sent in the Access-Request to the AAA.
-
6 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
Figure 4.
https://gateway.wifi-portals.com/login?username=joe&password=secret
The UE is redirected to the captive portal redirect URL following an unsuccessful authentication attempt.
As part of the query parameters, the NPC will include the Reply-Message contained within the Access-
Request if specified or an internal error code indicating the reason for failure. Following a successful
authentication, the UE is redirect to the success URL configured on the NPC.
2.3. UAM Logout URL
The UE has the ability to terminate the session by calling the UAM Logout URL (Figure 5). This results in the
session being terminated, an appropriate Accounting-Stop being transmitted to the AAA and the UE being
redirected back to the portal.
Figure 5.
https://gateway.wifi-portals.com/logout
-
7
DHCP Discover
DHCP O�er
DHCP Request
DHCP ACK
HTTP/GET
http://www.google.com
Access-Request
Access-Reject
HTTP/302 redirect
https://www.mycaptiveportal.com/?mac=00:11:22:33:44:55&state=3
HTTP/GET
https://www.mycaptiveportal.com/?mac=00:11:22:33:44:55&state=3
HTTP/GET
https://gateway.wi�-portals.com/login?username=joe&password=secret
Access-Request
Access-Accept
(Update UE as authorised)
Accounting-Start
Accounting-Response
HTTP/GET
https://www.mycaptiveportal.com/success
MAC authentication enables the NPC to update UE as authorised by sending Access-Accept from AAA/RADIUS.
PortalAAA/RADIUSNPCUE
Accounting-Interim
Accounting-Response
HTTP/302 redirect
https://www.mycaptiveportal.com/success
HTTP/302 Redirect
https://gateway.wi�-portals.com/login?username=joe&password=secret
HTTP/GET
http://www.google.com
HTTP/302 redirect
http://www.google.com
Periodically, the NPC will transmit Accounting-Interim to the AAA/RADIUS.
User registers or pays for WiFi access.
-
8 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
4. RADIUS 4.1. Authentication Request Attributes
User-Name
This attribute indicates the name of the user to be authenticated. It is present in all Access-Requests sent
to the remote AAA. For MAC authentication, the username is the MAC address of the UE.
Service-Type
The Service-Type attribute indicates the method of authentication requested. For MAC authentication, this
is set to Framed. A value of Login indicates that the UE specified a username and password to authenticate
itself.
Calling-Station-Id
This attribute indicates the MAC address of the UE, formatted as a UTF-8 string of colon delimited hex
octets. For example: 00:11:22:33:44:55.
Called-Station-Id
This attribute indicates the MAC address of the NPC interface that the UE was discovered on, formatted as
a UTF-8 string of colon delimited hex octets. For example, 66:77:88:99:AA:BB.
Acct-Session-Id
Specifies a UTF-8 encoded string that uniquely identifies the session for accounting purposes.
NAS-Identifier
The NAS-Identifier attribute contains the identity of the NPC. This consists of the NPC’s hostname and the
captive portal interface. For example, npc-01:eth1.829
Odyssys-VLAN-ID
Specifies the VLAN for which the UE was discovered on.
Odyssys-Called-Station-BSSID
The NPC supports discovery of sessions via RADIUS Access-Requests that originate from an AP or WLAN
controller. When configured, this attribute contains the MAC address of the AP that the user is connected
to at the time the authentication request was transmitted.
Chargable-User-Identity
The RADIUS server (a RADIUS proxy, home RADIUS server) may include the CUI attribute in the Access-
Accept packet destined to a roaming partner.
-
9 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
Message-Authenticator
This attribute is used to sign the authentication request with a digest. The AAA server must calculate the
correct value for the message authenticator and discard the request if the values do not match. For more
information about the Message-Authenticator attribute and digest algorithms, please refer RFC 3579.
4.2. Authentication Response Attributes
Class
Specifies octets of arbitrary length to be sent in all Accounting corresponding to the session.
WISPr-Bandwidth-Min-Up
Minimum guaranteed transmit rate (bps).
WISPr-Bandwidth-Min-Down
Minimum guaranteed receive rate (bps).
WISPr-Bandwidth-Max-Up
Limits the maximum transmit rate (bps) for the UE.
WISPr-Bandwidth-Max-Down
Limits the maximum receive rate (bps) for the UE.
WISPr-Session-Terminate-Time
The time when the user should be disconnected in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZD). If TZD is
not specified local time of the NPC is assumed. For example the session to terminate on 18 December 2001
at 7:00 PM UTC would be specified as 2001-12-18T19:00:00+00:00.
Odyssys-Portal-Redirect
Specifies the number of seconds after the session has started for which the UE should be redirected to the
captive portal. After this period has elapsed, the UE will be redirected to the portal for HTTP/HTTPS
requests, until instructed otherwise. Other traffic is allowed to traverse the NPC as usual. A value of 0 will
immediately redirect the UE on first and subsequent HTTP/HTTPS request, until instructed otherwise.
Odyssys-Portal-Redirect-Interval
Specifies the interval in seconds for which the UE should be redirected to the captive portal. After this
period has elapsed, the UE will be redirected to the portal for HTTP/HTTPS requests, until instructed
otherwise. Other traffic is allowed to traverse the NPC as usual.
Framed-Pool
When present in an Access-Accept and NAT pooling is enabled on the NPC, this specifies the NAT pool to
allocate a NAT address and ports from.
-
10 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
Odyssys-Authentication-Error
This attribute specifies a numerical error code for translation before being displayed to the user after an
unsuccessful login attempt.
Reply-Message
This attribute specifies a UTF-8 string to display to the user following an unsuccessful login attempt.
4.3. Accounting Attributes
Framed-IP-Address
This attribute indicates the IP address that was assigned to the UE during DHCP.
Class
This attribute contains the value of the Class attribute that was received in the Access-Accept.
Calling-Station-Id
This attribute indicates the MAC address of the UE, formatted as a UTF-8 string of colon delimited hex
octets. For example: 00:11:22:33:44:55.
Called-Station-Id
This attribute indicates the MAC address of the NPC interface that the UE was discovered on, formatted as
a UTF-8 string of colon delimited hex octets. For example, 66:77:88:99:AA:BB.
NAS-Identifier
The NAS-Identifier attribute contains the identity of the NPC. This consists of the NPC’s hostname and the
captive portal interface. For example, npc-01:eth1.829.
Acct-Status-Type
This attribute specifies the type of accounting record. The NPC supports the Start, Stop or Interim
accounting types.
Acct-Delay-Time
This attribute indicates how many seconds the NPC has been trying to send this accounting record for, and
can be subtracted from the time of arrival on the server to find the approximate time of the event
generating this Accounting-Request. This attribute is provided for backwards compatibility with old AAA
servers. It’s suggested to use the Event-Timestamp attribute.
Acct-Input-Octets
This attribute indicates how many octets have been received by the UE over the course of this service
being provided.
-
11 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
Acct-Input-Gigawords
This attribute indicates how many times the Acct-Input-Octets counter has wrapped around 2^32 over the
course of this service being provided.
Acct-Output-Octets
This attribute indicates how many octets have been transmitted by the UE over the course of this service
being provided.
Acct-Output-Gigawords
This attribute indicates how many times the Acct-Output-Octets counter has wrapped around 2^32 over
the course of this service being provided.
Acct-Session-Id
Specifies a UTF-8 encoded string that uniquely identifies the session for accounting purposes.
Acct-Session-Time
This attribute indicates how many seconds the UE has received service for. This is present in records where
the Acct-Status-Type is set to Interim and Stop.
Acct-Input-Packets
This attribute indicates how many packets have been received by the UE over the course of this service
being provided.
Acct-Output-Packets
This attribute indicates how many packets have been transmitted by the UE over the course of this service
being provided.
Acct-Terminate-Cause
This attribute indicates how the session was terminated, and can only be present in Accounting-Request
records where the Acct-Status-Type is set to Stop. Possible values transmitted from the NPC are Session-
Timeout, Idle-Timeout, Admin-Reset.
Event-Timestamp
The timestamp containing the time the Accounting-Request was first generated. Specified as Epoch Time,
the time in seconds since January 1, 1970 00:00 UTC.
Framed-Pool
If NAT pooling is enabled on the NPC, this contains the name of the NAT pool that the UE was assigned to.
Chargeable-User-Identity
The RADIUS server (a RADIUS proxy, home RADIUS server) may include the CUI attribute in the Access-
Accept packet destined to a roaming partner.
-
12 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
Odyssys-VLAN-ID
Specifies the VLAN for which the UE was discovered on.
Odyssys-NAT-Address
When NAT pooling is enabled on the NPC, this indicates the NAT IP address allocated to the UE.
Odyssys-NAT-Port-Start
When NAT pooling is enabled on the NPC, this indicates the NAT start port allocated to the UE.
Odyssys-NAT-Port-End
When NAT pooling is enabled on the NPC, this indicates the NAT end port allocated to the UE.
Odyssys-Session-State
This attribute indicates the current state of the UE session. The following are possible states;
Unauthenticated, Authenticated or Authenticated-MAC (authenticated with redirect).
-
13 Global Reach Technology Limited | @GlobalReachLtd | globalreachtech.com
4.4. VSA Dictionary
For enable a AAA/RADIUS server to interpret Odyssys VSAs, the dictionary must be installed. Figure 6
below shows the dictionary formatted for most open source RADIUS servers.
Figure 6.
#
# Odyssys Radius Attributes
# Copyright (C) 2011-2015 Global Reach Technology Limited
#
VENDOR Odyssys 39393
BEGIN-VENDOR Odyssys
ATTRIBUTE Odyssys-VLAN-ID 1 integer
ATTRIBUTE Odyssys-NAT-Address 2 ipaddr
ATTRIBUTE Odyssys-NAT-Port-Start 3 integer
ATTRIBUTE Odyssys-NAT-Port-End 4 integer
ATTRIBUTE Odyssys-Portal-Redirect 5 integer
ATTRIBUTE Odyssys-Portal-Redirect-Interval 6 integer
ATTRIBUTE Odyssys-Interim-Update-Type 7 integer
ATTRIBUTE Odyssys-Session-State 8 integer
ATTRIBUTE Odyssys-Called-Station-BSSID 9 string
VALUE Odyssys-Session-State Unauthenticated 0
VALUE Odyssys-Session-State Authenticated 1
VALUE Odyssys-Session-State Authenticated-MAC 2
VALUE Odyssys-Interim-Update-Type VLAN 1
VALUE Odyssys-Interim-Update-Type State 2
VALUE Odyssys-Interim-Update-Type BSSID 3
END-VENDOR Odyssys
-
Global Reach Technology Ltd
Craven House, 121 Kingsway
London WC2B 6PA
T +44 (0) 207 831 5630
Copyright © Global Reach Technology Limited
All rights reserved.
Global Reach and the Global Reach logo are registered trademarks.