Create a guest portal
This guide sets up a captive portal for a guest SSID such as Corp-Guest.
At the end, a visitor’s device joins the SSID, is redirected to the Airgate
portal, registers or logs in, and gets internet access for the time you
choose. When the access ends, the device is sent back to the portal.
How it works
Section titled “How it works”Airgate supports two ways to release a device after the portal login. Pick the one your network devices support.
| Login model | How the device gets access | Typical devices |
|---|---|---|
| MAC caching + CoA (default, “server-initiated”) | The guest SSID uses MAC authentication. An unknown device gets a captive-portal role or a redirect. After the portal login, Airgate stores the login on the device record (MAC caching) and sends a RADIUS CoA. The device authenticates again and now matches the internet rule. | Aruba switches (AOS-CX, AOS-S), Aruba Instant and AOS 8/10 with an external captive portal, Cisco IOS-XE and Catalyst 9800 (CWA), Arista, Extreme |
| Web login | The portal page posts the user name and a one-time password to the network device’s own login URL, or redirects to the vendor’s grant URL. The device then sends a normal RADIUS PAP request to Airgate. | Aruba controllers and Instant (internal portal), Cisco WLC (EWA/LWA), Meraki, Ruckus, Fortinet, Juniper Mist, ExtremeCloud IQ |
The MAC caching model in detail:
1. Device joins Corp-Guest -> MAC authentication -> Airgate2. No valid portal login yet <- Accept + captive-portal role / redirect3. Browser opens the portal -> https://airgate.contoso.com/portal/contoso/corp-guest?mac=...4. Guest registers or logs in -> Airgate writes Endpoint:Access_Valid_Till, status Known5. Airgate sends CoA (reauth) -> NAD re-runs MAC authentication6. Access_Valid_Till is ahead <- Accept + internet role7. Access ends -> Access_Valid_Till moved to now, reauth -> back to step 2Before you begin
Section titled “Before you begin”- The switches, APs or controllers of the guest network are added under
Network › Switches and APs with a RADIUS shared secret. For the
MAC caching model, also turn on RADIUS CoA / Disconnect (RFC 5176) on
the RADIUS, CoA & RadSec tab and check the CoA port (default
3799, Cisco IOS1700). See Change of Authorization. - Guests can reach the Airgate portal host from the guest VLAN before they
log in: DNS and TCP 443 to your Airgate address (in this guide
airgate.contoso.com). - The console certificate (Certificates › Server certificates › Console (HTTPS)) is from a public CA, so phones open the portal without a certificate warning.
- An administrator role with
guest:writefor the portal andpolicy:writefor the access policy.
Step 1: Create the portal
Section titled “Step 1: Create the portal”-
Open Guests › Guest portal and select New portal.
-
In General:
-
Portal name:
Corp-Guest. URL slug is filled in from the name (corp-guest); it becomes the last part of the portal URL. -
Portal type: choose one card.
Type What the visitor does Self-registration Fills in a form and gets an account. Optionally a sponsor receives the password in Teams. Guest login Logs in with an account created by an operator, in bulk, or on a Wi-Fi pass. Accept terms Accepts the terms of use. Airgate creates a password-less account for the device. -
Role: the role of the accounts this portal creates (default
[Guest]). -
Account lifetime: for example
1 day. This is how long the access lasts; No expiry is possible but not recommended. -
When an account expires: what happens at the end (see Expiry). Default Delete and logout (4).
-
Authentication service (optional): run logins through a WEBAUTH or APPLICATION service instead of only the guest accounts.
-
After login, go to: a URL, or empty to send guests to the page they first asked for.
-
-
In Branding, pick a Skin and set the texts and colours. See Guest portal skins.
-
For a self-registration portal, adjust Form fields (the default form is full name, e-mail, mobile phone and company). Fields named
name,email,phone,company,sponsor_nameandsponsor_emailfill the account; any other name becomes a custom field, available in policy asGuestUser:<name>. -
In Terms of use, edit the text and turn on Guests must accept the terms to log in / register if you need it. Accept-terms portals always require it.
-
In Login & network, set the login model and the network device:
Field Value Login model MAC caching + CoA or Web login MAC caching Days a device stays authorized after login. 0= until the account expires, at most 30 days. Never beyond the account expiry.Post-login CoA Reauthenticate (role change, default), Bounce port (wired VLAN change) or Disconnect (wireless VLAN change) Success page delay Seconds to wait on the success page (wired port-bounce flows) Redirect MAC trust Session (default): the MAC in the redirect URL must have RADIUS activity in this tenant in the last 15 minutes. Signed: also require a valid Aruba redirect-URL hash. Off (insecure): trust any MAC. Vendor handling Auto-detect or your platform -
In Accounts & devices (self-registration and accept terms):
- User name: E-mail address, Phone number or Random.
- Password: Digits, Letters, Letters and digits or None (password-less), and Password length.
- Allowed e-mail domains: empty allows any domain;
fabrikam.comalso allowseu.fabrikam.com. - Registration limit: one registration per e-mail, phone or device
MAC in this many hours (
0= off).
-
In Receipts, choose whether the receipt page shows the credentials and whether an e-mail or SMS receipt is sent. See Guest e-mail and SMS receipts. To send the password to a host instead, see Sponsor approval in Teams.
-
Select Create portal. The right-hand panel now shows the Public URL, for example
https://airgate.contoso.com/portal/contoso/corp-guest. Copy it.
Step 2: Create the access policy for the guest SSID
Section titled “Step 2: Create the access policy for the guest SSID”MAC caching + CoA model
Section titled “MAC caching + CoA model”-
Open Access › Access policies, tab Network access, and select Add a policy › Blank.
-
Name:
Guest Wi-Fi. Connection: MAC authentication. Wi-Fi networks (SSID):Corp-Guest. -
Under Sign-in, Which devices: Any device (the rules decide, also for devices not known yet).
-
Add two rules with Add a rule:
Order Rule name When Then 1 Portal login validGuest portal login is Still valid (Access_Valid_Till ahead) Allow, Role guest-internet(or a VLAN)2 Send to guest portalno condition Allow, Role guest-portal(Aruba), or Send › An enforcement profile with the redirect (Cisco, below) -
Keep Default on Deny and select Save changes.
-
Move the policy above broader policies with the arrows in the policy list. The first policy that matches handles the sign-in.
A rule without conditions matches every device the policy handles, so rule 2 catches all devices that have no valid portal login.
Cisco (IOS-XE switches, Catalyst 9800) redirect profile. Cisco needs the
redirect in the Access-Accept. In Access › Enforcement profiles select
Add profile, template Cisco RADIUS Enforcement, name
Guest redirect, and add two Cisco-AVPair attributes:
url-redirect-acl=ACL-WEBAUTH-REDIRECTurl-redirect=https://airgate.contoso.com/portal/contoso/corp-guest?mac=%{Connection:Client-Mac-Address-Colon}Cisco IOS appends no client MAC to the redirect, so the ?mac= part is
required. The ACL ACL-WEBAUTH-REDIRECT must exist on the switch or
controller and redirect web traffic while allowing DNS, DHCP and the portal
host. Use this profile in rule 2.
Web login model
Section titled “Web login model”- Open Access › Access policies and select Add a policy › Guests.
- Set Wi-Fi networks (SSID) to
Corp-Guest. The template allows PEAP and PAP and checks accounts in [Guest User Repository]. - Keep the
Guestsrule (Allow, optionally a role or VLAN) and select Save changes.
The network device’s own captive portal redirects to the Airgate portal. After the login, the portal posts the user name and a one-time password back to the device, which then sends a RADIUS PAP request to Airgate.
Step 3: Point the network device at the portal
Section titled “Step 3: Point the network device at the portal”On the guest SSID (or the wired ports), configure the portal URL from Step 1 as the external captive portal or redirect URL:
| Platform | Where |
|---|---|
| Aruba Instant | An external captive-portal profile on the guest SSID. Full example: Server-initiated guest portal on Aruba Instant. |
| Aruba AOS 8 / AOS 10 | The captive-portal profile of the guest role, with the portal URL as the login page. |
| Cisco IOS-XE, Catalyst 9800 (CWA) | The redirect profile from Step 2; MAC filtering with the Airgate RADIUS server. |
| Meraki | Splash page › Click-through or Sign-on with my RADIUS server, with the portal URL as the custom splash URL. Set Vendor handling to Meraki click-through or Meraki sign-on splash. |
| Juniper Mist | External portal with the portal URL; paste the WLAN’s API secret into Mist WLAN API secret. |
| Others | The external portal URL of the WLAN; set Vendor handling to your platform or Generic. |
Also allow guests, before login, to reach DHCP, DNS and the portal host on TCP 443 (walled garden / pre-auth ACL).
Step 4: Preview the portal
Section titled “Step 4: Preview the portal”Select Live preview in the portal editor (or the preview action on the portal card). A one-hour preview link renders the saved portal, even while it is disabled, with a “Preview” banner; forms cannot be submitted. With sample NAD parameters opens it as a network device would.
Access duration and expiry
Section titled “Access duration and expiry”Account lifetime sets the account’s expiry. MAC caching sets how long a device stays released after a login. The device record then holds:
| Endpoint attribute | Value |
|---|---|
Access_Valid_Till |
End of the device’s portal access, in the tenant time zone (YYYY-MM-DD HH:MM:SS) |
MAC-Auth Expiry |
Same instant |
Guest Username, Username |
The guest’s user name |
Guest Role ID |
Numeric id of the guest role |
Guest_SSID |
SSID the device used, when the network device sent it |
The device’s status becomes Known and its owner the guest’s user name.
The rule condition Guest portal login compares Access_Valid_Till with
the current time (Endpoint:Access_Valid_Till GREATER_THAN %{Date:Date-Time}).
A device whose administrator set the status to Disabled is never MAC
cached; the visitor sees “Device not allowed”.
When access ends:
- The account expires (Airgate checks every 30 seconds): the When an
account expires action runs. Stop authenticating (0) keeps the
account, Disable (1) and Delete (3) remove access, and Disable and
logout (2) and Delete and logout (4) also send a CoA Disconnect to
the guest’s active sessions. In every case the device’s MAC caches are
revoked:
Access_Valid_Tillis set to the revocation time. - The MAC cache lapses while the account is still active: the setting Guests › Guest accounts › Defaults › When a device’s MAC cache lapses while it is online decides: Reauthenticate (default) sends a CoA so the device is redirected to the portal again, Disconnect sends a CoA Disconnect, Do nothing waits until the network device re-authenticates by itself.
- An operator disables or deletes the account in Guests › Guest accounts: its MAC caches are revoked in the same way.
Verify
Section titled “Verify”- Join
Corp-Guestwith a test phone. The portal opens. - Register or log in.
- Monitor › Sign-in log: a WebAuth record for the login (Result
Accept), followed by a RADIUS MAC authentication of the same MAC that
matched rule
Portal login valid. - Devices › Devices › the MAC › Attributes:
Access_Valid_Till,Guest Username, status Known. - Monitor › Alerts and events, event
coa.sent: the CoA with resultCoA-ACK. - Guests › Guest accounts: the account, its source and portal.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
| The portal URL returns “not found” | The portal is disabled, or the slug in the network device’s URL is wrong. | Enable the portal; copy the Public URL from the editor. |
| Portal: “Cannot connect your device. The network did not tell us your device’s address.” | The redirect URL carries no client MAC (MAC caching model). | Add the MAC to the redirect (Cisco: ?mac=%{Connection:Client-Mac-Address-Colon}), or use the web login model. |
| Portal: “Device could not be verified” | Redirect MAC trust is Session and the MAC had no RADIUS request in the last 15 minutes, or Signed and the hash is wrong. | Make sure the SSID does MAC authentication against Airgate; for Signed, paste the Aruba url-hash-key into URL hash key. |
| Portal: “Cannot complete the login” (web login) | The vendor’s login target is missing or not allowed. | Set Vendor handling to your platform; add the controller host under Allowed login hosts. |
| After login nothing changes; Sign-in log shows no second MAC authentication | The CoA did not reach the network device. | Turn on RADIUS CoA / Disconnect for the device and check the CoA port and firewall (UDP 3799 or 1700). See the coa.sent event for timeout or CoA-NAK. |
| Sign-in log: Denied: guest portal login check failed with “no portal login yet” | Expected for a new device when there is no catch-all rule 2. | Add rule 2 Send to guest portal, or the guest needs to log in first. |
| Sign-in log: No access policy handles this sign-in | No policy matches the SSID or connection type. | Check the policy’s Wi-Fi networks (SSID) (exact SSID name) and Connection. |
| Sign-in log (WebAuth): Wrong password / No account named “…” | Wrong credentials typed on the portal. | Check the account in Guests › Guest accounts; reset its password. |
| Sign-in log (WebAuth): The account has expired / The account is disabled | The account’s lifetime ended or an operator disabled it. | Extend or enable the account. |
| Portal: “Too many attempts. Please wait a few minutes and try again.” | Rate limit: 60 logins per minute per client address, or 10 failed passwords per user name in 15 minutes. | Wait 15 minutes. |