OPNsense - Captive Portal für Gäste-WLAN

Aus maxTechCorner

Auf einen Blick

Gilt fürOPNsense 26.1 und 26.7 (Services → Captive Portal, im Kern enthalten)
BereichIT-Security
Dauerca. 45 Minuten (Gästenetz mit Vouchern und eigener Anmeldeseite)
RechteAdministrator (OPNsense-WebUI)
StandOktober 2026 (OPNsense 26.7.5)

Das Captive Portal in OPNsense leitet Geräte in einem Netz – typischerweise im Gäste-WLAN – zuerst auf eine Anmeldeseite, bevor sie ins Internet dürfen. Die Anmeldung erfolgt per Voucher (Zugangscode), mit lokalen Benutzern, über RADIUS oder LDAP/Active Directory – oder ohne Anmeldung als reine Bestätigungsseite (Splash Page). Zeitlimits, eigene Designs, Freigaben für bestimmte Geräte und die Integration moderner Portal-Standards (RFC 8908/8910) sind ebenfalls an Bord.

Dieser Artikel zeigt Aufbau und Einrichtung eines Gästenetzes mit Captive Portal auf OPNsense 26.7: Netzplanung, Zone, Anmeldeverfahren und Voucher, eigene Anmeldeseite, HTTPS und RFC 8910, automatische Firewall-Regeln, Hochverfügbarkeit und Fehlersuche.

Einsatzzwecke und Funktionsumfang

  • Gäste-WLAN in Büros, Praxen, Hotels, Campingplätzen oder Veranstaltungen
  • BYOD-Netze mit Anmeldung über Active Directory oder RADIUS
  • Nutzungsbedingungen bestätigen lassen (Splash Page)
Funktion Beschreibung
Zonen Ein Portal je Schnittstelle oder mehrere Schnittstellen in einer Zone; jede Zone mit eigenem Design und eigenen Einstellungen
Anmeldung Voucher, lokale Benutzer, RADIUS (inkl. Accounting), LDAP/Active Directory, Kombinationen – oder keine (Splash Page)
Zeitlimits Idle Timeout und Hard Timeout; Wiederverbindung innerhalb der Laufzeit ohne erneute Anmeldung
Freigaben Geräte per MAC-Adresse oder IP-Adresse/Netz ohne Anmeldung zulassen (z. B. Drucker, Kassensysteme)
Templates eigene Anmeldeseite als ZIP-Paket (Logo, Texte, Nutzungsbedingungen)
Sessions Live-Ansicht der angemeldeten Geräte, Bandbreite und Restlaufzeit von Vouchern
Captive Portal auf der OPNsense: Gäste im WLAN-VLAN werden auf die Anmeldeseite umgeleitet (HTTP an Port 9000+Zone, HTTPS an 8000+Zone), melden sich per Voucher, RADIUS oder LDAP an und landen im Alias __captiveportal_zone_0; erst dann gelten die normalen Regeln – Internet ja, Firmennetz nein.

Planung des Gästenetzes

  • Eigenes Netz für Gäste: eigene SSID im WLAN, die auf ein eigenes VLAN (z. B. GUEST, 192.168.10.0/24) zeigt. Das Captive Portal kontrolliert den Zugang, die Trennung vom Firmennetz übernehmen die Firewall-Regeln.
  • DHCP für das Gästenetz, z. B. mit Dnsmasq (kurze Lease-Zeit, eigene Domain wie guest.internal).
  • DNS: Die Gäste nutzen Unbound auf der Firewall – optional mit Blocklisten (z. B. Schadsoftware, Jugendschutz) als eigener Policy für das Gästenetz.
  • Bandbreite bei Bedarf mit dem Traffic Shaper begrenzen (Pipe für das Gästenetz plus Obergrenze pro Gast), damit Gäste die Leitung nicht auslasten.

Schritt 1: Firewall-Regeln für das Gästenetz

Die Weiterleitung auf das Portal und die Sperre nicht angemeldeter Geräte erzeugt OPNsense automatisch. Was angemeldete Gäste dürfen, legen die normalen Firewall-Regeln fest. Firewall → Rules, Interface GUEST (Reihenfolge beachten):

  1. Block: Quelle GUEST net → Ziel interne Netze (Alias mit den RFC-1918-Netzen bzw. LAN, Server, Management).
  2. Pass: Quelle GUEST net → Ziel any (Internet).

Damit erreichen Gäste nach der Anmeldung nur das Internet, nicht aber Firmennetz oder Weboberfläche der Firewall.

Schritt 2: Anmeldeverfahren vorbereiten

Die Anmeldequellen werden unter System → Access → Servers angelegt und in der Zone ausgewählt:

Verfahren Einrichtung Einsatz
Voucher Server vom Typ Voucher (optional Use simple passwords, Länge von Benutzername/Passwort) Gäste, Hotels, Veranstaltungen
Lokale Benutzer Local Database; optional Enforce local group in der Zone kleine Umgebungen, Mitarbeitende mit eigenen Geräten
RADIUS Server vom Typ Radius (z. B. FreeRADIUS auf der OPNsense oder NPS), optional Accounting zentrale Benutzerverwaltung, Zeit- und Volumenkontingente
LDAP Server vom Typ LDAP (Active Directory) BYOD mit Firmenkonto
Keine in der Zone keine Anmeldequelle wählen Splash Page mit Nutzungsbedingungen

Schritt 3: Zone anlegen

Services → Captive Portal → Administration, Reiter Zones → +:

Feld Empfehlung
Enabled aktiv
Zone number wird automatisch vergeben (Zone 0, 1 …); bestimmt Alias und Ports
Interfaces das Gäste-VLAN, z. B. GUEST
Authenticate using z. B. Voucher – leer = keine Anmeldung (Splash Page)
Idle timeout z. B. 60 Minuten ohne Aktivität
Hard timeout z. B. 480 Minuten; bei Vouchern zusätzlich deren Gültigkeit
Concurrent user logins aus, wenn ein Zugang nur auf einem Gerät gleichzeitig gelten soll
SSL certificate / Hostname Zertifikat für die Anmeldeseite und passender Name, z. B. portal.example.com (siehe Schritt 6)
Allowed addresses / Allowed MAC addresses Geräte, die ohne Anmeldung durchdürfen (Drucker, Infoterminals)
Client roaming aktiv (Standard) – nötig für IPv6, da Clients mehrere Adressen nutzen
Custom template eigene Anmeldeseite (Schritt 5)

Speichern und Apply. Ab jetzt landen nicht angemeldete Geräte im Gästenetz auf der Anmeldeseite.

Schritt 4: Voucher erzeugen

Services → Captive Portal → Vouchers → Create vouchers:

  • Validity: Nutzungsdauer ab der ersten Anmeldung, z. B. 1 day oder 1 week (auch eigene Werte in Stunden/Minuten)
  • Expires in: spätester Zeitpunkt, bis zu dem der Voucher eingelöst sein muss (oder never)
  • Number of vouchers und Groupname (z. B. Messe-2026-10)

Nach Generate wird eine CSV-Datei mit Benutzernamen und Passwörtern heruntergeladen. Sie lässt sich per Serienbrief (Word, LibreOffice) zu ansprechenden Zugangskarten mit Logo verarbeiten. In der Übersicht werden Restlaufzeit, Status und Ablauf je Voucher angezeigt; abgelaufene Voucher und ganze Gruppen lassen sich löschen oder vorzeitig sperren.

Schritt 5: Eigene Anmeldeseite (Template)

Im Reiter Templates das Standard-Template herunterladen (ZIP), Logo, Farben, Texte und Nutzungsbedingungen anpassen, als neues ZIP hochladen und in der Zone unter Custom template auswählen. Hinweise:

  • Ein Hinweis auf Nutzungsbedingungen bzw. die Datenschutzinformation gehört auf die Seite; ggf. eine Checkbox zur Bestätigung ergänzen.
  • Die Seite kompakt halten – sie wird oft auf Smartphones in einem Mini-Browser angezeigt.
  • Externe Ressourcen (Schriften, Bilder von fremden Servern) vermeiden, da Gäste vor der Anmeldung keinen Internetzugang haben.

Schritt 6: HTTPS und moderne Portal-Erkennung (RFC 8910)

Ohne Zertifikat läuft die Anmeldeseite unverschlüsselt über HTTP. Empfohlen ist ein öffentlich vertrauenswürdiges Zertifikat – z. B. über den ACME-Client – und ein Hostname in der Zone, der intern auf die Gäste-Adresse der Firewall auflöst (Host Override in Unbound).

Moderne Geräte, insbesondere iOS, erkennen Portale zunehmend über den Standard RFC 8910 statt über umgeleitete HTTP-Anfragen. Dafür sendet der DHCP-Server im Gästenetz die Option 114 mit der Adresse der Portal-API: 

https://portal.example.com/api/captiveportal/access/api

Alternativ direkt auf den Webserver der Zone: https://portal.example.com:8000/api/captiveportal/access/api für Zone 0 (Port = 8000 + Zonennummer). Der Endpunkt meldet dem Gerät, ob es noch angemeldet werden muss, die Portal-Adresse und die Restlaufzeit. Die Option wird im jeweiligen DHCP-Server als eigene Option gesetzt (bei Dnsmasq unter DHCP options, bei Kea im Reiter Options).

Automatische Firewall-Regeln

Seit OPNsense 25.1.4 arbeitet das Captive Portal vollständig mit PF statt IPFW. Die Regeln sind dadurch in der Oberfläche sichtbar und werden protokolliert, und angemeldete Geräte stehen im Alias __captiveportal_zone_<Zonennummer> (einsehbar unter Firewall → Diagnostics → Aliases, verwendbar in eigenen Regeln). Automatisch erzeugt werden:

Regel Wirkung
HTTP-Umleitung TCP 80 nicht angemeldeter Geräte → 127.0.0.1:9000+Zone
HTTPS-Umleitung TCP 443 zur Firewall → 127.0.0.1:8000+Zone
DNS DNS zur Firewall erlaubt, damit Namen aufgelöst werden können
Portal-Zugriff Ports 8000+Zone und 9000+Zone zur Firewall erlaubt
Sperre aller übrige Verkehr nicht angemeldeter Geräte wird blockiert

Diese Regeln haben Vorrang vor eigenen Regeln. Für Sonderfälle (z. B. DNS-Umleitung auf einen anderen Port) lassen sie sich mit Disable firewall rules in der Zone abschalten und nach dem Muster der Dokumentation selbst anlegen.


Hinweis

IPv6 im Portal

Das Captive Portal unterstützt IPv6-only- und Dual-Stack-Netze. Voraussetzungen laut Dokumentation:

  • Client roaming in der Zone aktiv (Standard) – alle Adressen eines Geräts (Link-Local, Privacy-Adressen, IPv4) werden nach der Anmeldung freigeschaltet; das geschieht im Hintergrund mit kurzer Verzögerung.
  • Hostwatch unter Interfaces → Neighbors → Automatic Discovery aktiviert.
  • Ein Hostname in der Zone mit passendem DNS-Eintrag (AAAA) für die Firewall.

Betrieb und Hochverfügbarkeit

  • Sessions (Services → Captive Portal → Sessions): angemeldete Geräte je Zone, Bandbreite, Restlaufzeit; Sitzungen lassen sich hier manuell trennen.
  • Log File: Anmeldungen und Fehlversuche.
  • In einem HA-Cluster wird die Portal-Konfiguration über System → High Availability synchronisiert; Gateway, DNS und Portal-Hostname zeigen auf die CARP-Adresse des Gästenetzes. Nach einem Failover müssen sich Gäste unter Umständen erneut anmelden.
  • Für Zeit- oder Volumenkontingente pro Benutzer eignet sich RADIUS mit Accounting (Always send accounting requests).

Rechtliches und Sicherheit

  • Trennung von Gästen und Firmennetz strikt über Firewall-Regeln; zusätzlich im WLAN Client Isolation aktivieren, damit Gäste sich nicht gegenseitig erreichen.
  • Nutzungsbedingungen und Datenschutzhinweise auf der Anmeldeseite; Logs nur so lange aufbewahren, wie es erforderlich und zulässig ist.
  • Vouchers nicht wiederverwenden und regelmäßig abgelaufene Gruppen löschen.
  • HTTPS mit gültigem Zertifikat, damit Anmeldedaten (z. B. AD-Passwörter) nicht im Klartext übertragen werden.
  • Optional DNS-Blocklisten (Schadsoftware, Jugendschutz) und Bandbreitenbegrenzung für das Gästenetz.

Typische Probleme und Lösungen

Symptom Ursache und Lösung
Anmeldeseite erscheint nicht Gerät ruft nur HTTPS-Seiten auf (keine Umleitung möglich) – eine HTTP-Adresse aufrufen bzw. RFC 8910 (Option 114) einrichten; Zone nicht aktiv oder falsche Schnittstelle.
Zertifikatswarnung auf der Anmeldeseite Selbst signiertes Zertifikat oder Hostname passt nicht zum Zertifikat – öffentliches Zertifikat per ACME und passender Hostname.
Hostname wird nicht aufgelöst Host Override in Unbound fehlt oder Gäste nutzen einen fremden DNS-Server.
Nach der Anmeldung kein Internet Pass-Regel für das Gästenetz fehlt bzw. Block-Regel für interne Netze ist zu weit gefasst (z. B. any).
iPhones zeigen das Portal nicht oder hängen im Anmeldefenster RFC 8910 (DHCP-Option 114) und gültiges Zertifikat einrichten.
IPv6-Geräte verlieren nach der Anmeldung den Zugang Client roaming oder Hostwatch deaktiviert.
DNS-Umleitung im Portalnetz funktioniert nicht mehr (seit 25.1.4) Portweiterleitung mit Filter Rule Association = Pass anlegen.
Voucher wird abgelehnt Voucher abgelaufen (Expires in) oder Validity aufgebraucht, falscher Voucher-Server in der Zone.

Fazit

Das Captive Portal der OPNsense ist eine vollständige Hotspot-Lösung ohne Zusatzkosten: Gäste melden sich per Voucher, RADIUS oder Active Directory an, Zeitlimits und eigene Anmeldeseiten sind schnell eingerichtet, und seit dem Wechsel auf PF sind alle Regeln transparent. Für einen sicheren Betrieb sind ein eigenes Gäste-VLAN, klare Firewall-Regeln zur Trennung vom Firmennetz, ein gültiges Zertifikat und – für moderne Geräte – die DHCP-Option 114 entscheidend.

Unterstützung von m.a.x. it

Sie möchten ein sicheres Gäste-WLAN mit Voucher-System oder einen BYOD-Zugang mit Active-Directory-Anmeldung aufbauen? m.a.x. it unterstützt Sie als OPNsense-Gold-Partner mit OPNsense-Firewall-Services von m.a.x. it und einer Managed Firewall von m.a.x. it.

Siehe auch

Links und Quellen


Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung? Kontakt aufnehmen

Abgerufen von „http://techcorner.max-it.de/index.php?title=OPNsense_-_Captive_Portal_für_Gäste-WLAN&oldid=4071“