How to Set Up Voucher-Based Guest WiFi Authentication on UniFi Controller

Set up voucher-based guest WiFi authentication on UniFi Controller by creating a guest network and configuring voucher settings.

To begin, ensure your UniFi Controller is updated and your network devices are connected and configured properly.

Understanding Voucher-Based Guest WiFi Authentication

Voucher-based guest WiFi authentication provides a secure way to offer internet access to guests without compromising your network's security.

This method involves generating vouchers that contain a unique code and expiration date, which guests can use to access your WiFi network.

Benefits of Voucher-Based Authentication

The benefits of voucher-based authentication include a high level of security, flexibility, and ease of use.

This method also allows you to control access to your network and monitor guest activity, making it an ideal solution for businesses and organizations.

Technical Overview of Voucher-Based Authentication

Voucher-based authentication uses a unique code and expiration date to authenticate guests and provide access to your WiFi network.

This method is based on the IEEE 802.1X standard, which provides a framework for port-based network access control.

Configuring UniFi Controller for Guest WiFi

Configure your UniFi Controller to enable guest WiFi by navigating to the Settings section and selecting Guest Control.

Here, you can create a new guest network and configure its settings, such as the network name, password, and authentication method.

It is essential to configure your network settings correctly to ensure seamless connectivity and security.

Consider consulting the official UniFi documentation or seeking guidance from a network expert if you are unsure about any configuration settings.

Step-by-Step Configuration Guide

To configure your UniFi Controller for guest WiFi, follow these steps:

Navigate to the Settings section and select Guest Control.

Create a new guest network and configure its settings, such as the network name and password.

Configuring Network Settings

Configure your network settings to ensure seamless connectivity and security.

This includes setting up the network name, password, and authentication method.

Configuring Guest Network Settings

Configure your guest network settings to control access to your network and monitor guest activity.

This includes setting up the guest network name, password, and authentication method.

Creating Vouchers for Guest WiFi Authentication

To create vouchers, navigate to the Guest Control section and select Vouchers.

Here, you can generate new vouchers and configure their settings, such as the voucher code, expiration date, and duration of access.

It is crucial to keep your vouchers secure to prevent unauthorized access to your network.

Consider using a secure method to distribute vouchers to your guests, such as printing them on paper or sending them via email.

Generating Vouchers

To generate vouchers, navigate to the Vouchers section and select Generate Voucher.

Here, you can configure the voucher settings, such as the voucher code, expiration date, and duration of access.

Configuring Voucher Settings

Configure your voucher settings to specify the authentication method and other parameters, such as the voucher expiration date and access duration.

It is vital to test your voucher settings to ensure they are working correctly and providing secure access to your guest WiFi network.

Configuring Voucher Settings and Authentication

Configure your voucher settings to specify the authentication method and other parameters, such as the voucher expiration date and access duration.

It is vital to test your voucher settings to ensure they are working correctly and providing secure access to your guest WiFi network.

Consider consulting the official UniFi documentation or seeking guidance from a network expert if you encounter any issues with your voucher settings.

To further enhance your network's security, consider learning about powering your WiFi router with a battery or exploring the differences between stabilizer vs UPS for power protection.

Authentication Methods

There are several authentication methods available, including voucher-based, password-based, and certificate-based authentication.

Each method has its own benefits and drawbacks, and the choice of authentication method will depend on your specific network requirements.

Security Considerations

When configuring voucher settings and authentication, it is essential to consider security best practices to prevent unauthorized access to your network.

This includes using secure protocols, such as HTTPS, and configuring firewalls to restrict access to your network.

Technical Comparison of Voucher-Based Authentication Methods

When choosing an authentication method, consider the security level and complexity of each option to determine the best fit for your network.

For additional security measures, consider exploring Mikrotik security configuration best practices.

DomineTec Tip: Regularly review and update your network's security settings to ensure the highest level of protection against potential threats.

Step-by-Step Guide to Configuring Voucher-Based Guest WiFi Authentication

1. Navigate to the UniFi Controller and select the Settings section.
2. Configure the guest network settings, including the network name and password.
3. Enable voucher-based authentication and generate new vouchers.
4. Configure the voucher settings, including the expiration date and access duration.
5. Test the voucher settings to ensure they are working correctly.

By following these steps, you can successfully configure voucher-based guest WiFi authentication on your UniFi Controller.

Configuring Voucher Settings

Configure your voucher settings to specify the authentication method and other parameters, such as the voucher expiration date and access duration.

It is vital to test your voucher settings to ensure they are working correctly and providing secure access to your guest WiFi network.

Troubleshooting Issues

To troubleshoot issues with voucher-based authentication, consult the official UniFi documentation or seek guidance from a network expert.

Regularly review and update your network's security settings to ensure the highest level of protection against potential threats.

Advanced Voucher Management and API Integration

Integrating UniFi voucher systems with external applications requires leveraging the UniFi Controller's API. This method allows for automated voucher generation, status queries, and bulk operations, extending functionality beyond the graphical user interface.

Access to the UniFi API is typically performed via HTTP POST requests to specific endpoints. Authentication uses the controller's administrator credentials, often requiring a login session cookie for subsequent requests.

Automated Voucher Generation via API

To programmatically create vouchers, send a POST request to the /api/s/default/cmd/hotspot endpoint. The payload must include the command create-voucher along with desired parameters.

Parameters like cmd, expire, quota, and note define the voucher's characteristics. For instance, expire specifies validity duration (e.g., "8h" for 8 hours) and quota sets the number of devices per voucher (e.g., "1" for single use).

• Endpoint Example: https://[CONTROLLER_IP]:8443/api/s/default/cmd/hotspot
• JSON Payload Example: {"cmd":"create-voucher", "expire":"8h", "quota":"1", "note":"Conference Guest", "n":"10"}. This generates 10 vouchers valid for 8 hours, usable by one device each.
• Response: The API returns a JSON object containing the voucher codes and their properties upon successful creation. Parse this response to retrieve and distribute the generated vouchers.

Error handling is crucial; monitor API responses for non-200 HTTP status codes or error messages within the JSON body. Common issues include incorrect authentication tokens or malformed request payloads.

Voucher Status and Deletion via API

Querying the status of existing vouchers is achievable by sending a GET request to /api/s/default/stat/voucher. This endpoint provides details on all active and expired vouchers.

To revoke or delete a specific voucher, a POST request to /api/s/default/cmd/hotspot with the delete-voucher command is used. The voucher's unique ID, obtained from a status query, must be included in the request body.

• Deletion Payload Example: {"cmd":"delete-voucher", "voucher_id":"[VOUCHER_UNIQUE_ID]"}. This targets a specific voucher for removal.

Implement robust API key management and secure communication channels (HTTPS) to protect sensitive controller access. Regularly review API logs for unauthorized access attempts or unusual activity patterns.

RADIUS Integration for Advanced Voucher Security and Auditing

Integrating a RADIUS server with UniFi's voucher system enhances security, provides centralized authentication logs, and allows for more granular policy enforcement. This setup can supplement or replace basic voucher validity checks with external authentication mechanisms.

While UniFi vouchers handle initial access, a RADIUS server can be configured to perform secondary authentication or enforce specific network policies based on voucher attributes. This is particularly useful for compliance requirements or detailed session logging.

UniFi Controller RADIUS Profile Configuration

Navigate to the UniFi Controller's Settings, then "Profiles," and create a new RADIUS Profile. Specify the IP address of your RADIUS server and its shared secret.

For guest networks, enable "RADIUS assigned VLAN" if your RADIUS server is configured to assign VLANs dynamically. This allows guests with different voucher types to be placed into distinct network segments.

• RADIUS Server IP: Enter the IP address of your FreeRADIUS or other RADIUS server.
• Port: Typically 1812 for authentication and 1813 for accounting.
• Shared Secret: A strong, complex string known only to the UniFi Controller and the RADIUS server.

Apply this RADIUS profile to your Guest Hotspot settings. Under "Guest Control," enable "RADIUS Authentication" and select the newly created profile.

FreeRADIUS Server Configuration for Voucher Integration

On your FreeRADIUS server, configure a client entry for your UniFi Controller's IP address in /etc/freeradius/3.0/clients.conf. Ensure the shared secret matches the one configured in UniFi.

For voucher-like authorization, modify /etc/freeradius/3.0/users or use a database module. Entries can map specific voucher codes or attributes to RADIUS user accounts and assign policies.

• clients.conf entry:

  client unifi_controller {
      ipaddr = [UNIFI_CONTROLLER_IP]
      secret = [SHARED_SECRET]
      nas_type = other
  }

• users file example:

  VOUCHER_CODE_XYZ User-Password := "some_password_or_empty"
      Reply-Message = "Welcome Guest",
      Service-Type = Login-User,
      WISPr-Bandwidth-Max-Down = 10000000,
      WISPr-Bandwidth-Max-Up = 5000000,
      Tunnel-Type = VLAN,
      Tunnel-Medium-Type = IEEE-802,
      Tunnel-Private-Group-ID = "10"

This configuration assigns specific bandwidth limits and places the user into VLAN 10 upon successful RADIUS authentication. The voucher code itself can serve as the username for RADIUS lookup.

Enable RADIUS accounting in UniFi's guest control to send session start and stop records to the RADIUS server. This provides detailed audit trails for guest network usage.

Deep Dive into Guest Policies, Firewall Rules, and QoS for Voucher Networks

Effective management of voucher-based guest networks requires meticulous configuration of guest policies, firewall rules, and Quality of Service (QoS) settings. These controls ensure security, fair resource allocation, and optimal user experience.

UniFi's guest network functionality automatically isolates guests from corporate networks, but additional rules are often necessary for specific access requirements or enhanced security postures.

Granular Firewall Rules for Guest Access

Under "Guest Control," UniFi provides "Pre-Authorization Access Restrictions" and "Post-Authorization Restrictions." These are critical for defining what guests can access before and after voucher authentication.

Pre-authorization rules typically allow access only to the UniFi Controller (for captive portal redirection) and DNS servers. Post-authorization rules dictate allowed internet access and block internal network resources.

• Pre-Auth Whitelist: Add the IP address of your UniFi Controller (often the same as the gateway) and any external DNS servers (e.g., 8.8.8.8, 1.1.1.1). This ensures guests can reach the captive portal and resolve domain names.
• Post-Auth Blacklist: By default, guest networks are isolated. However, explicitly blocking specific internal subnets (e.g., 192.168.1.0/24) provides an additional layer of security assurance.

Consider specific use cases where guests might need access to certain internal services, like a local printer or an information kiosk. Create specific firewall rules to permit this access while maintaining overall isolation.

Firewall rule order matters; more specific rules should precede broader ones. Regularly review and test these rules to prevent unintended access or connectivity issues.

Quality of Service (QoS) and Bandwidth Management

UniFi allows for per-user bandwidth limits to prevent individual guests from monopolizing network resources. Configure these limits under "Guest Control" in the "Bandwidth Limit" section.

Set both download and upload limits to ensure a fair share of bandwidth for all connected guests. For example, a 5 Mbps download and 2 Mbps upload limit can be applied to all voucher users.

• Per-Client Bandwidth Restrictions: Enable "Enable bandwidth limit" and specify desired rates in Mbps. These limits apply to each device connected via a voucher.
• Rate Limiting Impact: Excessive rate limiting can lead to a poor user experience, especially with video streaming or large downloads. Balance security with usability requirements.

For more advanced QoS, consider using UniFi's Smart Queues (if available on your gateway device, like a USG or UDM). Smart Queues prioritize certain traffic types and minimize bufferbloat, improving overall network responsiveness.

Segmenting guest traffic onto a dedicated VLAN also helps with QoS, as it allows for specific firewall rules and bandwidth allocations to be applied to that entire network segment.

Troubleshooting Complex Voucher Scenarios and Performance Issues

Diagnosing issues with voucher-based guest WiFi can involve multiple layers, from network connectivity to UniFi Controller configuration and client device behavior. A systematic approach is essential for efficient resolution.

Common problems include vouchers not being accepted, captive portal redirection failures, and slow network performance after authentication. Each requires specific diagnostic steps.

Voucher Acceptance and Captive Portal Troubleshooting

If a voucher is not accepted, first verify its validity: check expiration, usage quota, and correct code entry. Confirm the voucher status in the UniFi Controller under "Hotspot Manager" -> "Vouchers."

Ensure the guest network is correctly configured to use voucher authentication. Verify that the "Guest Policy" is enabled and the "Authentication" method is set to "Voucher" within the Guest Control settings.

• DNS Resolution: Clients must be able to resolve the UniFi Controller's hostname or IP address to load the captive portal. Check client DNS settings and UniFi's pre-authorization access rules.
• Controller Reachability: Use a ping or traceroute from a network device (e.g., another client, a UniFi AP via SSH) to the UniFi Controller's IP address. Network connectivity issues prevent portal loading.
• Firewall Interference: Confirm no intermediate firewalls are blocking HTTP/HTTPS traffic from the guest VLAN to the UniFi Controller's captive portal port (default 8880/8843).

If the captive portal fails to redirect, inspect client browser settings for pop-up blockers or security extensions that might interfere. Test with multiple client devices and operating systems.

Review UniFi Controller logs (/usr/lib/unifi/logs/server.log on Linux controllers) for errors related to guest authentication or hotspot events. These logs often provide specific failure reasons.

Performance Degradation After Voucher Authentication

Slow speeds post-authentication can stem from various sources, including bandwidth limits, wireless interference, or upstream internet congestion. Systematically eliminate potential bottlenecks.

Check the "Bandwidth Limit" settings under "Guest Control" in the UniFi Controller. Ensure the configured limits are appropriate for the expected guest usage and available internet bandwidth.

• Wireless Environment: Analyze the RF environment using UniFi's built-in RF Environment scan or a dedicated WiFi analyzer tool. High channel utilization or co-channel interference impacts performance.
• AP Overload: Monitor the number of clients connected to individual Access Points. Excessive client density on a single AP can lead to performance degradation due to airtime contention.
• Upstream Bottleneck: Verify the internet service provider's connection speed. Perform a speed test from a wired device connected directly to the gateway to rule out ISP-related issues.

Examine UniFi Network Application's "Statistics" section for client-specific bandwidth usage and AP load. This helps identify resource-intensive clients or overloaded access points.

Ensure firmware on UniFi devices (Controller, APs, Gateway) is up-to-date. Firmware updates often include performance improvements and bug fixes relevant to guest network functionality.

High-Availability and Scalability Considerations for Large-Scale Voucher Deployments

Deploying voucher-based guest WiFi in large venues or multi-site environments demands careful planning for high availability, scalability, and robust performance. Redundancy and proper network segmentation are paramount.

A single point of failure in the UniFi Controller or network infrastructure can disrupt guest access for hundreds or thousands of users. Proactive design mitigates these risks.

UniFi Controller High Availability

For mission-critical deployments, consider a highly available UniFi Controller setup. While UniFi does not offer native active-active clustering, strategies exist for achieving redundancy.

Self-hosted controllers can be deployed on virtual machines with underlying hypervisor-level HA (e.g., VMware vSphere HA, Proxmox HA). This ensures the VM restarts on another host if the primary fails.

• Database Backup and Restore: Implement regular automated backups of the UniFi Controller database. In a failure, a new controller instance can be spun up and the database restored.
• DNS Redundancy: Use a DNS entry (e.g., unifi.yourdomain.com) that can be quickly pointed to a standby controller's IP address in a disaster recovery scenario.
• Cloud Key Gen2 Plus: While not fully redundant, a Cloud Key Gen2 Plus with its internal battery backup offers some resilience against power fluctuations. For true HA, self-hosted solutions are preferred.

Consider a warm-standby approach where a secondary controller is kept updated with the primary's configuration. Manual failover involves updating DNS and activating the standby controller.

For distributed deployments, multiple UniFi Controllers can manage separate sites. UniFi's multi-site management allows a single login to oversee all controllers, but each site operates independently.

Scalable Network Design and AP Placement

In large venues, proper Access Point (AP) placement and density are crucial for supporting a high number of concurrent voucher users. Conduct a thorough site survey to identify optimal locations and avoid coverage gaps or excessive overlap.

Deploying APs with varying radio power levels and channel assignments minimizes co-channel interference and maximizes airtime efficiency. Utilize 5 GHz bands where possible for higher capacity and less interference.

• AP Density: Plan for a higher AP density than typical office environments to accommodate many simultaneous clients. Consider the "clients per AP" metric during design.
• VLAN Segmentation: Implement dedicated VLANs for guest traffic. This isolates guest traffic, simplifies firewall rules, and allows for specific QoS policies to be applied to the guest segment.
• Gateway Capacity: Ensure your UniFi Security Gateway (USG/UDM) or third-party router has sufficient processing power and throughput to handle the aggregate guest traffic and deep packet inspection if enabled.

For high-density environments, consider UniFi HD or XG series APs, specifically designed for greater client capacity. Offload guest portal functionality to a dedicated external server if the controller is heavily loaded.

Regularly monitor network performance metrics, including client counts per AP, channel utilization, and latency, to identify potential bottlenecks before they impact user experience.

Frequently Asked Questions

What is voucher-based guest WiFi authentication?

Voucher-based guest WiFi authentication is a method of providing secure internet access to guests using unique vouchers that contain a code and expiration date.

This method offers a high level of security and flexibility, making it an ideal solution for businesses and organizations.

How do I configure voucher settings on UniFi Controller?

To configure voucher settings, navigate to the Guest Control section and select Vouchers.

Here, you can generate new vouchers and configure their settings, including the voucher code, expiration date, and access duration.

What are the benefits of using voucher-based authentication?

The benefits of using voucher-based authentication include a high level of security, flexibility, and ease of use.

This method also allows you to control access to your network and monitor guest activity.

Can I use voucher-based authentication with other authentication methods?

Yes, you can use voucher-based authentication with other authentication methods, such as password-based or certificate-based authentication.

However, it is essential to configure the authentication methods correctly to ensure seamless connectivity and security.

How do I troubleshoot issues with voucher-based authentication?

To troubleshoot issues with voucher-based authentication, consult the official UniFi documentation or seek guidance from a network expert.

Regularly review and update your network's security settings to ensure the highest level of protection against potential threats.

Security Best Practices

When configuring voucher-based authentication, it is essential to consider security best practices to prevent unauthorized access to your network.

This includes using secure protocols, such as HTTPS, and configuring firewalls to restrict access to your network.

Network Configuration

Configure your network settings to ensure seamless connectivity and security.

This includes setting up the network name, password, and authentication method.