UpdatedApril 17, 2026

SonicOS 7.3.2 Design update: CGI deprecated and replaced with API for Guest authentication

Description

This knowledge base article provides a step-by-step demonstration of a basic Guest Services → Captive Portal configuration. In this setup, the captive portal page is hosted locally on a PC and is designed to handle guest authentication using API-based methods. The hosted webpage includes the necessary API calls to process user credentials, perform basic authentication, and manage HTTP GET and POST requests required to complete the guest authentication workflow.

The objective of this article is to illustrate a simple, functional example that helps understand how API-driven guest authentication operates in a real-world scenario, replacing legacy CGI-based methods.

Resolution

Step 1: Sample Captive Portal HTML file

<html>
	<head>
		<meta name="id" content="login" >
		<style>
			#error_text {
				text-align: center;
				color: red;
			}
		</style>
	</head>
	<script type="text/JavaScript">
	const params = new URLSearchParams(window.location.search);
    const mgmtUrl = params.get('mgmtUrl');
	const reqUrl = params.get('REQ');


	function base64Encode(str) {
		return btoa(unescape(encodeURIComponent(str)));
	}

	async function basicAuthRequest(url, username, password) {
		var credential = base64Encode(username + ':' + password);
		console.warn('baisc=', credential);
		var basicAuthToken = 'Basic ' + credential;
		var errorText = document.getElementById('error_text');
		console.log('enter basicAuthRequest:',url);
		let response = await fetch(url, {
					method: 'POST',
					headers: {
						"Authorization": basicAuthToken,
						"Content-Type": "application/json"
					}
				});
		console.log('get res');
		if (response.ok) {
			const data = await response.json();
			var info = data.status.info[0];
			console.warn('--22--info=', info);
			if (info.redirect_url !== undefined) {
				top.location.href = info.redirect_url;
			} else {
				top.location.href = reqUrl;
			}
			
		} else {
			const errorResp = await response.json();
			var errorInfo = errorResp.status.info[0];
			console.log('11 errorInfo=',errorInfo);
			if (errorText) {
				errorText.innerHTML = errorInfo.message;
			}
		}
	}

	function doLogin() {
		var authUrl = mgmtUrl + '/api/sonicos/auth';
		var username = document.getElementById("userName").value;
		var password = document.getElementById("password").value;
			
		basicAuthRequest(authUrl, username, password);
	}

	</script>
	<body id ="body">
		<form name="standardPass">
			<table width="450" border="0" align="center" cellpadding="0" cellspacing="0" summary="">
				<tr>
					<h2 style="background-color:rgb(255,0,0)">
						<strong>This is my portal server.</strong>
					</h2>
				</tr>
			</table>
			<table width="450" border="0" align="center" cellpadding="0" cellspacing="0" summary="">
				<tr>
					<td class="login_box">
						<table width="100%" border="0" cellspacing="0" cellpadding="0" summary="">
							<tr>
								<table width="354" border="0" cellspacing="0" cellpadding="4" summary="">
									<tr>
										<td><div align="right">Username:</div></td>
										<td>
											<input type="text" id="userName" name="uName" value="" size="26" maxlength="128">
										</td>
									</tr>
									<tr>
										<td><div align="right">Password:</div></td>
										<td>
											<input type="password" id="password" name="pass" size="26" maxlength="63">
										</td>
									</tr>
									<tr>
										<td>&nbsp;</td>
										<td>
											<input type="button" value="Login" class="button" onclick="doLogin()">
										</td>
									</tr>
								</table>
							</tr>
						</table>
					</td>
				</tr>
			</table>
			<table width="450" border="0" align="center" cellpadding="0" cellspacing="0" summary="">
				<tr>
					<div id="error_text">
					<!-- error message here -->
				   </div>
				</tr>
			</table>
		</form>
	</body>
</html>

Step 2: Host the Captive Portal Page

Note:

In this example, the captive portal HTML file is hosted on the same PC that is used for guest authentication testing. The above HTML code is saved in "Index.html".

The provided HTML file should be used as a base template to develop your own customized captive portal. It is recommended to host the portal on a Windows Server using IIS or any other suitable web hosting service. Alternatively, the portal can also be hosted externally on a cloud platform, depending on your deployment requirements.

For demonstration purposes, it is saved internally on a PC used for testing, rename the captive portal HTML file to ‘index.html’ and host it using Python (simplest way):

python -m http.server 80

Access via http://<PC IP> in a browser to make sure the page loads

Step 3: Configure Guest Services

Navigate to Object | Match Objects | Zones | LAN | Guest Services
Enable "Guest Services"
Enable "Captive Portal authentication"
Enable "Pass Networks" and select the DNS object. In this example, google DNS 8.8.8.8 is used

Note:
1. In this example, the Guest services is configured in the LAN zone (This can also be configured on a DMZ/WLAN or any custom zones)
2. In this testbed, the guest client is setup with DNS 8.8.8.8 which is allowed in the "Pass networks". Please check DNS Server used in your setup for the Guest network and allow that server by creating Object in appropriate zone and selecting under "Pass Networks"

Step 4: Configure Captive Portal URL

Click "Configure" button right beside "Captive Portal authentication" which you enabled on Step #2.
Set internal hosted captive portal URL in "Internal Captive Portal Vendor URL". In this example, the hosted page URL is http://192.168.168.30

If you are hosting the Captive portal outside the firewall network (WAN side), then please configure the URL under "External Captive Portal Vendor URL"

Step 5: Create Guest User

Navigate to Device | Local Users & Groups | Local Users | Add user

Create a Guest user, in this example "GuestUser1"

Navigate to "Local Groups" and Edit "Guest Services" and add the created user to this group in "Members" like shown below:"

Step 6: Enable SonicOS API

Navigate to Device | Administration | SonicOS API
Enable "SonicOS API" and "RFC-2617 HTTP Basic Access authentication"

Note: The sample code shared contains the API authentication workflow using Basic authentication.

Step 7: Testing

A. Connect Guest client to the Guest network/zone on which we just configured the Captive Portal authentication.
B. Visit any website on any browser (eg. we used facebook.com in Edge)
C. You will notice a redirection to the captive portal URL as shown below.
D. Enter the guest user credentials (in my example, GuestUser1 and <Password>)