Captive Portal Configuration¶
The captive portal is the login page that guests see immediately after connecting to the hotspot network (step 4 in the User Access Flow). It handles user onboarding, authentication method selection, and branding/customization.
This guide covers portal creation, login method configuration, and visual customization to match your venue’s brand.
Portal Overview¶
RansNet HSG provides a fully customizable captive portal with:
- Multiple pre-built templates — Professional designs for hotels, retail, F&B, and corporate venues
- Flexible login methods — Username/password, OTP (email/SMS), direct access, payment gateway, and more
- Full branding control — Custom logo, colors, background images, terms of service, and promotional content
- Multi-instance support — Each hotspot instance can have a different portal, allowing different branding and login methods per VLAN/venue
Creating a Portal¶
Step 1: Select a Template¶
Navigate to CAPTIVE PORTAL → Portal Templates. HSG provides standard templates designed for common use cases.
Click Use to start a new portal from the selected template.
Step 2: Name the Portal¶
Give the portal a unique name (no spaces, no special characters). This name is used in hotspot instance configuration and portal management.
Step 3: Access the Portal List¶
All created portals are listed in CAPTIVE PORTAL → Portal List.
Click View to preview the portal and copy its URL. Use this URL when configuring the hotspot instance. Refer to Hotspot Instance Configuration — hotspot-portal.
Portal Backend Settings¶
Navigate to CAPTIVE PORTAL → Portal List and click Edit on the portal. The Portal Backend Setting page has three tabs:
| Tab | What It Sets |
|---|---|
| Login Option | How users sign in, what they can buy, the payment gateway, and how emails and SMS are sent |
| Settings | Portal type, pre-shared key, sticky, captcha, language, account status link, self-registration passwords and OTP limits, and the user information fields |
| Survey Form | Optional questions shown before login |
Each tab is divided into sections. Each section has its own Save and Cancel buttons, and Select All / Unselect All for its options. A setting with a checkbox in front of it is used only while that checkbox is ticked. Unticked, the portal uses the default shown in the field (e.g. the RansNet mail server).
Settings Tab¶
Portal Settings¶
| Setting | Description | Options / Default |
|---|---|---|
| Select portal type (default mbox) | The hotspot controller the portal works with | mbox (RansNet HSG/HSA/UA/UAP, default), WiFiDog, CoovaChilli (Teltonika, Peplink). For third-party routers, see Third-Party Hotspot Routers. |
| Enable portal pre-shared key | Secret shared with the hotspot controller; the portal checks every redirect with it | Must match the hotspot's portal key (hotspot-portal <url> key <key> on HSG, or the UAM secret on a third-party router) |
| Enable portal sticky | Seamless re-login for returning devices, see Portal-sticky | Off |
| Enable captcha for login page | Shows a picture code on the login, OTP, PIN code, click-through, registration and reset pages | Off |
| Enable captcha for payment purchase | Shows a picture code on the purchase pages (Buy Data, Buy Access Plan, Top Up Data) | Off. A portal saved before this setting existed uses the login page setting. |
| Select portal frame size | Width of the login form on the screen | Small (default), Medium, Large |
| Select supported languages | Languages users can switch to on the portal | English (default); choose several |
| Enable account status link on login page | Shows an Account Status link below the login button, to the page where users check their usage and change their password. See Account Status. | Off |
| Account status URL | Address of the account status page | Unticked: /hotspot/acctinfo/ on the login page's own address. Tick and enter a full https:// URL when the page is elsewhere (e.g. on the RADIUS server or under a host name with a valid certificate). |
Note
The former Redirect URL and Slideshow settings were removed from this page and are cleared on the next save. To send users to a page after login, use the redirect-url command on the hotspot instance (see Hotspot Instance — redirect-url).
Portal-sticky¶
Portal-sticky is one of two methods for enabling seamless re-login (the other being client-sticky). After a user's first successful authentication, when the same user returns on the same device during the account validity period, the captive portal auto-logs them in — without requiring them to re-enter their username and password.
Enable portal-sticky on a per-portal basis using the Enable portal sticky setting in Portal Settings above.
Portal-sticky vs. Client-sticky
Both features deliver seamless re-login, but they work differently and suit different deployments. Choose based on your gateway design and whether you need Wi-Fi marketing features.
| Aspect | Portal-sticky | Client-sticky |
|---|---|---|
| Auto-login performed by | Captive portal | HSG hotspot engine |
| Triggered by | A browsing session (web connection only); most mobile devices trigger this automatically via CNA | Any connection — web or non-web |
| Deployment support | On-premise and cloud (local gateway can be HSG, HSA, or UAP) | On-premise only (local HSG gateway) |
| Marketing redirect after re-login | Yes — can redirect to a marketing URL or banner/ads page | No — user gets full access immediately, no redirect |
| Session validity | Keep sticky sessions (portal cookies) in Data Maintenance, since first or last login | Configurable via start or last days (set via CLI) |
| Best for | Venues needing Wi-Fi marketing while keeping seamless access | Large venues (airports, hotels) where marketing is not required and maximum seamlessness matters |
Note
Portal-sticky is disabled by default and is enabled per portal. For deployments where the auto-login must work for any connection type (not just web), or for fully transparent roaming across VLANs, use client-sticky instead — or combine both for large venues prone to mass-reconnection events. Portal-sticky is not available with the CoovaChilli portal type.
Email and SMS Self-registration¶
These settings apply to accounts that users create themselves by email or SMS (see Email Self-registration and SMS Self-registration).
| Setting | Description | Default |
|---|---|---|
| Password definition | Random Generated: the portal creates the password and sends it. User Defined: the user chooses it at registration. | Random Generated |
| Password length / Type | Length (2–20) and character set (Numeric, Alpha, AlphaNumeric) of generated passwords | 6, Numeric |
| Password expiry after (hours) | The account stops working after this many hours | No expiry |
| Default country | Country code preselected for mobile numbers | Singapore (+65) |
| Validate email/SMS via OTP | Users must enter a one-time PIN sent to their email or mobile before the account is created | Off |
| Retry interval (minutes) | Time before a user can request a new OTP | 10 |
| Retry max limit | OTP requests allowed before the user is locked out | 3 |
| Lock duration (minutes) | How long a locked-out user must wait | 1440 |
| Confirm mobile/email for OTP sending | The user confirms the address or number before the OTP is sent | Off |
User Information¶
Choose which details the portal asks for during click-through login and registration (name, email, mobile, gender, company and others). Set each field to Required, Optional or Hidden (default).
Login Option Tab¶
The Login Option tab defines how users authenticate and what they can buy. Several sign-in methods can be enabled on the same portal, and each one has its own purchase options.
Tip
Combine multiple login methods on the same page to accommodate different user preferences. For example, offer both "username/password" for returning guests and "Email OTP" for new visitors.
Pre-created Accounts¶
| Option | Description |
|---|---|
| Sign in with username and password | For accounts created by the administrator in User Management, by import, or through the API. |
| Username Prefix | Prefixes users choose from or that are added to the username (e.g. room- for hotel guests). Enter them comma delimited and choose how the prefix is asked. |
| Purchases (choose one, optional) | Post-paid data top-up: users add data from the Data Top-up Plans without paying online; it is billed outside the portal, and the login page shows a Top up data link. Prepaid data top-up via payment gateway: users pay online for a Data Top-up Plan; the data is added to their account and nothing else changes. Prepaid access plan via payment gateway: users pay online for an access plan; the account is reset to the plan (accounts with Auto quota management are refused). |
| Sign in with a PIN code | Users sign in with a PIN only, with optional PIN Code Prefix. |
When to use:
- Hotel guest Wi-Fi (room number + last name via PMS sync)
- Staff/corporate Wi-Fi (pre-created accounts)
- Members-only venues (loyalty program members), with prepaid data or plan purchases
- Any scenario where users have pre-defined accounts
Click-through Login¶
Users connect without credentials.
| Option | How It Works | Use Case |
|---|---|---|
| Click to connect (accept the terms) | The portal shows a Connect button. Clicking it grants access with the default demouser account. |
Free/public Wi-Fi in lobbies, waiting areas |
| Require user information | The portal asks for the User Information fields before granting access. The details are stored for analytics and marketing. | Build a guest database for F&B and retail venues |
| Default hotspot username / password | Sign users in with this account instead of demouser, to give this portal its own access profile and reports. Create the user in User Management first. |
Several portals on the same gateway |
| URL triggered login | Users who first open a page starting with the Triggering URL (e.g. via a QR code) are logged in without seeing the portal. | QR code-based access in retail, restaurants, events |
Video Demo: Direct Access & QR Code Configuration
Email Self-registration¶
Users sign in with their email address. Choose one mode:
| Mode | User Journey | Use Case |
|---|---|---|
| One-time PIN (OTP) on every sign-in | User enters email, receives an OTP, enters it to connect. Every login needs a new OTP. Optional Username Prefix and Require user information. | Casual visitors, no account kept |
| Register with an OTP, then sign in with email and password | First visit: register and validate the email. Later: email + password (generated or user defined, see Settings). | Build a customer database; repeat visitors |
| Register with an OTP, then sign in with email only | First visit: register and validate the email. Later: email only. | Frictionless repeat access for known customers |
| Register by purchase only (no free sign-up) | New users must buy first: the account is created with their email after payment and the password is emailed with the receipt. Choose what they buy under Purchases: prepaid data top-up or prepaid access plan. Tick Confirm email (user types it twice) to catch typing mistakes. | Paid-only Wi-Fi without pre-created accounts |
| Show Reset Password link on login page | Adds a Reset Password link. Unticked, users change or recover their password on the Account Status page. |
Prerequisites:
- Email delivery set in Email and SMS Delivery (or the RansNet mail server default)
- Optional: restrict to specific email domains
Video Demo: Email OTP Self-Registration Setup
SMS Self-registration¶
The same modes as email, with the mobile number as the username: One-time PIN (OTP) on every sign-in, Register with an OTP, then sign in with mobile number and password, Register with an OTP, then sign in with mobile number only, and Register by purchase only (no free sign-up) with Confirm mobile number (user types it twice). With purchase only, the password is sent by SMS.
Prerequisites:
- SMS gateway set in Email and SMS Delivery
Video Demo: SMS OTP Self-Registration Configuration
Purchase Plans and Payment Gateway¶
Users buy Wi-Fi data or access plans online. What each sign-in method sells is chosen under its Purchases options above; this section sets the plans and the payment gateway they share.
| Setting | Description |
|---|---|
| Data Top-up Plans | Data users can add: quota, unit, price and currency per plan. Prepaid top-up offers only plans with a price; post-paid top-up offers them all. |
| Monthly top-up limit per user | Most data a user can add in a calendar month, post-paid and prepaid together (e.g. 50GB). Unticked: no limit. |
| Access plans for sale | Shown for information: access plans are Access Profiles with a price, set in HOTSPOT USERS → Access Profile → Billing. |
| Payment gateway | Needed by every prepaid option and by Register by purchase only. |
| Payment provider | Airwallex (cards, Alipay, WeChat Pay), PayPal (PayPal checkout and Alipay), MPGS, Midtrans, MPesa, Ooredoo. Enter the provider's credentials in the fields shown. |
| Test payment gateway | Checks the credentials entered on the page against the provider (before saving) and reports whether they work in live or sandbox mode. |
| Sandbox (test) mode | Payments go to the provider's test service with test credentials: no real money is charged, and the purchase pages show a test-mode notice. Turn it off, with live credentials, before going live. |
Purchase pages:
| Link on the Login Page | Page | What the User Does |
|---|---|---|
| Buy data | Buy Data | Signs in (or enters email / mobile number), chooses a Data Top-up Plan and pays. The data is added to the account. |
| Buy access plan | Buy Access Plan | Chooses an access plan and pays. A new account is created (email / SMS purchase only) or the existing account is reset to the plan. |
| Top up data | Top Up Data | Post-paid: chooses a Data Top-up Plan without paying online. |
After payment, the provider returns the user to the portal, which adds the purchase, sends the receipt and logs the user in. If a provider page does not return (e.g. some WeChat Pay pages), the user can tap Back or reconnect to the Wi-Fi: the login page completes the paid order within the provider's return window (15 minutes for Airwallex).
Prerequisites:
- Subscription with a supported payment provider, and its credentials
- Access plans and/or Data Top-up Plans with prices
- The provider's domains allowed before login on the hotspot (bypass domains on HSG, walled garden on third-party routers)
Refer to Payment Gateway Integration for the end-to-end setup.
Email and SMS Delivery¶
How the portal's emails (OTPs, registration and payment receipts) and SMS are sent, shared by all methods.
| Setting | Description |
|---|---|
| SMTP server | Your mail server: sender name, host, username, password, security and port. Unticked, or a field left empty: the RansNet mail server setting. |
| SMS gateway | SMS provider and its credentials. Needed by SMS OTP and SMS purchases. |
| Allowed recipient email domains | Comma delimited, e.g. @company.com. Unticked: any domain. |
| Allowed recipient mobile numbers | Country codes or prefixes, e.g. 65, 60. Unticked: any number. |
Branding & Customization¶
Customize the portal appearance to match your venue’s brand without requiring a web designer.
Navigate to CAPTIVE PORTAL → Portal List, select your portal, and click the Portal Name to enter customization mode.
Customizable Elements:
- Logo — Upload your venue’s logo (displayed on login page)
- Colors — Brand colors for buttons, text, backgrounds
- Background Image — Splash page or login page wallpaper
- Terms of Service — Custom ToS text that users must accept
- Welcome Text — Custom greeting message on login page
- Promotional Content — Advertisements or promotional banners
- Footer Links — Custom links (privacy policy, support, etc.)
- Slideshow — Auto-rotate multiple background images
Preview & Test: Use the Preview button frequently to see changes in real-time across different screen sizes (mobile, tablet, desktop).
Video Demo: Customizing Captive Portal
Best Practices¶
Login Method Selection¶
- High-traffic venues (malls, airports) — Use direct access or OTP for frictionless guest experience
- Hotels — Use PMS integration (auto-created accounts) for seamless room-based login
- Retail/F&B — Use email/SMS OTP to build customer database for repeat visits and marketing
- Corporate Wi-Fi — Use standard login with pre-created staff accounts
- Mixed audience — Combine methods (standard + direct access) to serve different user types
Branding & UX¶
- Keep it simple — Minimize fields; only ask for essential information
- Mobile-first design — Test portal on phones; ensure buttons and text are large and tappable
- Fast load time — Optimize logo and background image sizes; avoid large multimedia
- Clear ToS — Display privacy policy and data usage terms upfront
- Support contact — Always provide help/support information on portal or redirect after login
Security¶
- Use HTTPS — Portal redirects should use secure HTTPS, not HTTP
- Validate inputs — Email/SMS fields require valid format before OTP is sent
- Rate limit OTP — Prevent brute force; limit OTP attempts per user per time window
- Secure credentials — Payment gateway credentials and pre-shared keys should be rotated periodically
- Logout links — Provide explicit logout option on portal welcome page to clear sessions
Verification¶
After configuring your portal, test the complete login flow:
- Preview Portal — Click Preview in portal customization to see the live login page
- Verify Branding — Confirm logo, colors, and text display correctly
- Test Login Method — Test your chosen login method end-to-end:
- Standard login: enter test credentials
- OTP: verify email/SMS is received
- Direct access: verify "Connect" button grants access
- Payment: tick Sandbox (test) mode, click Test payment gateway, then complete a test purchase with the provider's test account
- Test Redirect — Verify successful login redirects to configured post-login URL
- Test on Mobile — Open portal on phone; verify layout and buttons are mobile-friendly
Related Features¶
- Hotspot Instance Configuration — Link portal to a hotspot instance (VLAN)
- Third-Party Hotspot Routers — Use the portal and RADIUS with Peplink, Teltonika and other CoovaChilli routers
- User Management — Create and manage user accounts for standard login method
- Hotspot Authentication Methods — Detailed authentication mechanism and RADIUS integration
- Hotel Wi-Fi Integration — End-to-end guide for PMS-based guest Wi-Fi with automated portal