Kiwire docs

Appearance

Cisco WLC ​

How to connect a Cisco wireless LAN controller, AireOS (2500/3500/5500/8500 series, vWLC) or Catalyst 9800, to Kiwire using external web authentication.

Device type in KiwireCisco WLC
Redirect URLhttps://<kiwire-host>/login/cisco_wlc
RADIUSauth 1812 / acct 1813 (UDP)
Identity must equalThe guest SSID name, as the WLC sends it in the wlan parameter. Also the WLC's NAS-Identifier, so set the NAS-ID to the SSID name too (see below)
Disconnect / live changes (CoA)Yes, port 3799 (enable CoA / RFC 3576 on the WLC)
Data capsTime limits only (Session-Timeout)

Read Controller identity and Virtual NAS once before your first installation. The Cisco WLC is the one type where the Identity is not a device name or MAC.

How a guest logs in through Cisco WLC and Kiwire The guest joins the Wi-Fi and opens a page. The Cisco WLC device redirects the browser to Kiwire at /login/cisco_wlc. Kiwire shows the portal and the guest signs in. Kiwire hands the login back to the device: POST to switch_url. The device then asks Kiwire over RADIUS, identifying itself with NAS-ID = the SSID name. Kiwire accepts and returns the profile's limits, the device lets the guest out and starts sending accounting. Later, Kiwire can disconnect the guest or change their limits with CoA on port 3799.Guest devicephone, laptopCisco WLCAireOS or Catalyst 9800Kiwireportal + RADIUSInternetafter acceptance1 JOINS THE SSID, OPENS A PAGE2 REDIRECT TO/login/cisco_wlc3 PORTAL PAGE — THE GUEST SIGNS IN4 HAND-BACK:POST to switch_url5 RADIUS REQUEST — IDENTITY =NAS-ID = the SSID name6 ACCEPT + PROFILE LIMITS7 GUEST IS LET OUT; ACCOUNTING STARTS8 LATER: DISCONNECT / CHANGE LIMITS (CoA, PORT 3799)
Steps 2 and 4 are the controller's side of the portal, step 5 is its RADIUS side. When the page loads but the login never completes, the break is almost always at step 4 (the login address) or step 5 (the Identity or the shared secret).

The Identity is the SSID name ​

When a WLC sends a guest to an external web-auth page, it adds switch_url (its own login address), client_mac, ap_mac, wlan and redirect. Kiwire's Cisco WLC login config reads the wlan parameter, which is the SSID name, as the controller ID. So Kiwire finds your organisation from the SSID name.

RADIUS is looked up separately, by the NAS-Identifier the WLC sends. By default that is the WLC's system name. You have two choices:

  • Recommended: one record. Set the WLC's NAS-ID for the guest WLAN to the same text as the SSID name. One Device Controller record with Identity = the SSID name then matches both lookups.
  • Two records. Leave the NAS-ID as the system name and add two records: Identity = the SSID name, and Identity = the NAS-Identifier. Both need the same Shared Secret Key, and both count toward your licence.

The Identity must be unique across the whole Kiwire platform, and at least 4 characters. A common SSID name such as Guest WiFi may already be registered by another organisation. Give the guest SSID a distinctive name, for example Acme Hotel Guest. The match is exact apart from upper/lower case, and spaces count.

One WLC with several guest SSIDs needs one record per SSID name.

Before you start ​

From Kiwire:

  • The RADIUS server address shown in the Setup Guide checklist (Before you add your controller › RADIUS Authentication & Accounting). Below it is written <radius-server-ip>.
  • Your <kiwire-host>: the host name of your portal. Portals › Troubleshoot › Controller Test shows it in the Test URL field. For the pre-authentication ACL you also need the IP address(es) it resolves to.
  • A <shared-secret> of 64 characters or fewer.

On the WLC:

  • Admin access to the GUI or CLI.
  • A virtual interface address (AireOS) or a global parameter-map virtual IP (9800). Cisco recommends an address from 192.0.2.0/24. The WLC's login address in switch_url uses it.
  • For disconnects: an address of the WLC that Kiwire can reach.

On the controller ​

Menu names and commands vary between firmware versions; the values are what matter.

AireOS ​

  1. RADIUS authentication server. Security › AAA › RADIUS › Authentication › New:
    • Server IP Address: <radius-server-ip>
    • Shared Secret: <shared-secret>
    • Port Number: 1812
    • Server Status: Enabled
    • Support for CoA (RFC 3576): Enabled
    • Network User: checked
  2. RADIUS accounting server. Security › AAA › RADIUS › Accounting › New: same address and secret, port 1813.
  3. Pre-authentication ACL. Security › Access Control Lists › New, for example KIWIRE-PREAUTH. Add rules that permit, in both directions:
    • DNS (UDP 53) to your DNS server;
    • HTTPS (TCP 443) and HTTP (TCP 80) to the IP address(es) of <kiwire-host>;
    • the addresses of anything else your portal loads, if you can (see Walled garden and redirect).
  4. The guest WLAN. WLANs › Edit (your guest SSID):
    • Security › Layer 2: None (open), unless your policy needs otherwise.
    • Security › Layer 3: Layer 3 Security: Web Policy, Authentication.
    • Preauthentication ACL: KIWIRE-PREAUTH.
    • Over-ride Global Config: enabled. Web Auth type: External (Redirect to external server). URL: https://<kiwire-host>/login/cisco_wlc
    • Security › AAA Servers: select the authentication and accounting servers from steps 1 and 2.
    • Advanced › NAS-ID: the SSID name (see above), if your version shows this field.
    • Apply.
  5. The WLC checks web-auth logins over RADIUS with PAP by default (Controller › General › Web Radius Authentication). Leave it on PAP.

Catalyst 9800 ​

  1. RADIUS server and group. Configuration › Security › AAA › Servers / Groups: add a RADIUS server (<radius-server-ip>, key <shared-secret>, auth port 1812, acct port 1813) and a server group containing it.

  2. Method lists. Configuration › Security › AAA › AAA Method List: an Authentication list of type login using the group, and an Accounting list of type identity using the group.

  3. CoA. Under AAA Advanced › Dynamic Authorization (CLI aaa server radius dynamic-author), add Kiwire as a client with the same <shared-secret>. Kiwire does not show the address its disconnects come from: ask Synchroweb support for it.

  4. Web-auth parameter map. Configuration › Security › Web Auth → add a parameter map, type webauth:

    • Redirect URL for login: https://<kiwire-host>/login/cisco_wlc
    • Portal IPV4 Address: the IP address of <kiwire-host>. The 9800 builds the pre-authentication ACL from this.
    • Redirect Append for Client MAC Address: client_mac
    • Redirect Append for WLAN SSID: wlan
    • Redirect Append for AP MAC Address: ap_mac

    The same in CLI:

    parameter-map type webauth KIWIRE
 type webauth
 redirect for-login https://<kiwire-host>/login/cisco_wlc
 redirect portal ipv4 <kiwire-host-ip>
 redirect append client-mac tag client_mac
 redirect append wlan-ssid tag wlan
 redirect append ap-mac tag ap_mac

    The tag names matter: without client_mac and wlan Kiwire cannot identify the guest or the site.

  5. The guest WLAN. Configuration › Tags & Profiles › WLANs → your guest SSID → Security › Layer3: Web Policy on, Web Auth Parameter Map KIWIRE, Authentication List = the login list from step 2.

  6. Policy profile. On the policy profile used by the WLAN, set the Accounting List from step 2. In the AAA policy it uses, set the NAS-ID option to the SSID, so the NAS-Identifier equals the SSID name.

In Kiwire ​

  1. Admin › System › Device Controller → add a record:

    • Vendor: Cisco WLC
    • Identity: the guest SSID name, exactly as broadcast
    • Shared Secret Key: <shared-secret>
    • Under Advanced Configuration: IP Address = the WLC's address that Kiwire can reach, COA Port = 3799.

    If you kept the WLC's system name as NAS-ID, add a second record with that name as Identity, the same Vendor and the same secret.

  2. Check the redirect parameters. The Cisco WLC login config is maintained by Synchroweb. It reads client_mac, redirect, switch_url and wlan. See The redirect and the login config.

  3. Zones and journeys. Under Portals › Captive Portal › Zones Mapping, a zone rule on NAS ID or SSID = the SSID name selects this WLAN. See Controllers and zones and Designers and journeys.

After a successful login Kiwire sends the guest's browser back to switch_url with username, password, redirect_url, buttonClicked=4 and err_flag=0, as Cisco's external web-auth requires. The WLC then checks the credentials with Kiwire over RADIUS.

Test it ​

  1. Portals › Troubleshoot › Controller Test → Start Capture, then connect a phone to the guest SSID and open an http:// page. Check that client_mac, switch_url and wlan arrive and that the controller ID (the SSID name) is registered to your organisation. On a 9800, a missing wlan or client_mac means the redirect-append tags are missing.
  2. Log in as a guest. If the portal accepts the login but the WLC shows its own failure page, check the RADIUS server, secret and NAS-ID.
  3. Reporting › Login › Active Session: the session should appear once accounting arrives.

Limits to know ​

  • SSID names are Identities. Renaming the SSID breaks logins until the record in Kiwire is renamed. Two organisations cannot register the same SSID name.
  • Add records before the device goes live. Kiwire accepts a new record straight away. If the device already sent RADIUS requests before its record existed, they can keep failing for up to an hour. See Controller identity and Virtual NAS.
  • Pre-authentication ACLs use IP addresses. If the address of <kiwire-host> changes, update the ACL (AireOS) or Portal IPV4 Address (9800). Fonts and other hosts your portal loads may not be reachable before login. The page still works but may look plainer. Use a DNS-based ACL where your version supports it.
  • No data caps. Kiwire has no Cisco data attribute. Session length comes from Session-Timeout. Other Cisco attributes can be added to the profile's Custom attributes (Cisco template).
  • Few Kiwire sites use a Cisco WLC. Tell Synchroweb support before your first deployment so the first logins can be watched.

Vendor reference ​

Last updated:

Kiwire platform documentation

Synchroweb