wifi flips → vpn rips. 🛜 your FortiGate SSL-VPN connects itself the second you hop on sketchy Wi-Fi, and dips the moment you're back on a network you trust. zero babysitting, zero FortiClient GUI, zero
--insecure-sslnonsense.
Built for the UCalgary VPN 🎓, but it's gateway-agnostic — point it at any FortiGate gateway that does SAML SSO and you're set. There's a UCalgary preset so locals can skip the config entirely.
You're at a café ☕. You join the Wi-Fi. Normally you'd remember the VPN after your first request leaks in the clear, fumble open FortiClient, click through a GUI that breaks every macOS update. Nah. This watches your SSID and handles it for you:
flowchart TD
Join([Join Wi-Fi network]) --> Watcher[Hammerspoon Watcher]
Watcher --> Check{SSID Trusted?}
Check -- Yes --> Chill[🏛 Chill, tunnel stays down]
Check -- No --> Portal[Captive-Portal Check]
Portal --> Dial[openfortivpn --saml-login]
Dial --> Auth[Browser pops ➜ SSO + MFA]
Auth -->|SAML Cookie| Up[⚡ Tunnel up. Cooked-proof ✓]
style Join fill:#2dd4bf,stroke:#0d9488,stroke-width:2px,color:#0f172a
style Chill fill:#64748b,stroke:#475569,stroke-width:1px,color:#ffffff
style Up fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#ffffff
style Check fill:#f59e0b,stroke:#d97706,stroke-width:1px,color:#0f172a
- 📞 the dial:
openfortivpn(--saml-login) — a protocol client, not a GUI we have to puppet. - 🧠 the brain: Hammerspoon watches Wi-Fi + runs the state machine + gives you a menubar.
- 🔑 the login: your default browser. password manager + Microsoft Authenticator do their thing there.
- 🛡️ the trust: the gateway cert is pinned, not vibe-checked. more in Security.
- 🍎 macOS 13+ (Apple Silicon or Intel — we detect which)
- 🍺 Homebrew — we use it, but we won't install it behind your back (it touches admin + your shell profile, that's a you decision)
- 📦 everything else (
openfortivpn≥ 1.21, Hammerspoon) the installer grabs for you
brew install rahit/tap/fortivpn-auto
fortivpn-auto install --preset ucalgary # UCalgary squadbrew pulls openfortivpn + the Hammerspoon cask for you. The install step
does the per-Mac wiring a formula can't (config, Spoon, scoped sudoers,
LaunchAgent) — it needs sudo and your gateway details, so it's its own step.
Not at UCalgary? Bring your own gateway:
curl -fsSL https://raw.githubusercontent.com/rahit/fortivpn-auto/main/vpn.conf.example -o ~/vpn.conf
$EDITOR ~/vpn.conf # GATEWAY_HOST, GATEWAY_PORT, TRUSTED_SSIDS
fortivpn-auto install --config ~/vpn.confprefer to run from source (audit-first)?
git clone https://github.com/rahit/fortivpn-auto.git
cd fortivpn-auto
./bin/fortivpn-auto install --preset ucalgaryThe installer is idempotent ♻️ (re-run it all day, nothing breaks) and allergic to clobbering your stuff:
- already have a
~/.hammerspoon/init.lua? we don't touch it — we drop a Spoon and append a tiny sentinel-guarded block that coexists with your setup. - existing openfortivpn config? backed up 💾 (timestamped) before we write.
- the sudoers grant goes in only after
visudosays the syntax is valid — a malformed sudoers file can lock you out ofsudo, so we never raw-cpit.
sudo prompts once (for that sudoers step). Want to launch Hammerspoon yourself
and skip the auto-start agent? add --no-agent.
Grant these to Hammerspoon:
- 📍 Location Services — yes, Location, for a VPN tool. since macOS Sonoma,
reading your Wi-Fi network name is gated behind it. skip this and the watcher
silently thinks you have no Wi-Fi and ghosts you. the Spoon throws the
prompt on launch → smash Allow. no prompt? open the Hammerspoon Console:
then toggle Hammerspoon on under System Settings → Privacy & Security → Location Services.
hs.location.start()
- ♿ Accessibility + 🔔 Notifications — allow if asked. Notifications is just for the status banners; no glaze.
did it work? Hammerspoon Console → hs.wifi.currentNetwork() should return
your SSID, not nil. nil = Location Services isn't granted. that's it,
that's the whole gotcha.
fortivpn-auto doctor # read-only health check, green/yellow/red on every part
fortivpn-auto doctor --dry-run # + gateway reachability & captive-portal probe (no dial)doctor literally draws you a results bar 📊 so you know at a glance. Then the
real test: yeet yourself off trusted Wi-Fi (phone hotspot is easiest). Menubar
goes VPN ⋯ → VPN ⟳, browser pops for SSO, you MFA, menubar hits VPN ✓.
Back on home Wi-Fi → VPN 🏛, tunnel drops. Logs live rent-free in
~/Library/Logs/fortivpn-auto.log.
| menubar | meaning |
|---|---|
VPN ⏸ |
idle, no Wi-Fi |
VPN 🏛 |
on a trusted network, chilling |
VPN ⋯ / VPN ⟳ |
probing / connecting |
VPN ✓ |
tunnel up, you're routed |
VPN ✗ |
it flopped — check the log, hit Force connect |
| key | required | what it does |
|---|---|---|
GATEWAY_HOST |
✅ | FortiGate hostname (no scheme/port) |
GATEWAY_PORT |
✅ | SSL-VPN port (usually 10443) |
TRUSTED_SSIDS |
✅ | bash array of SSIDs where the VPN should chill (no connect) |
TRUSTED_CERT |
— | pin a specific SHA-256; empty = fetch + pin the live cert at install |
OPENFORTIVPN_BIN |
— | override binary path; empty = auto-detect |
REALM |
— | SAML realm segment, if your gateway demands one |
PERSISTENT_RECONNECT |
— | seconds between auto-reconnect attempts (default 25; 0 = off) |
KEEPALIVE_INTERVAL |
— | ping through the tunnel every N s to dodge an idle timeout (0 = off) |
KEEPALIVE_HOST |
— | keepalive target; empty = the tunnel's gateway peer |
START_DELAY / RETRY_DELAY / MAX_RETRIES |
— | state-machine tuning |
FortiGate EV certs renew annually. When that drops, the next connect fails with Gateway certificate validation failed (you'll get a notification too):
fortivpn-auto refresh-cert # grabs the live digest, re-pins after you confirmWe never fall back to --insecure-ssl. That disables cert validation
entirely and hands you to whoever owns the café router — on the exact untrusted
Wi-Fi this tool exists for. Hard pass. 🙅
install.sh drops a per-user LaunchAgent that boots Hammerspoon at login and
relaunches it if it crashes (KeepAlive = SuccessfulExit:false) — but if you
deliberately Quit, it stays quit. It's self-healing but not clingy. Beats the
"Launch at login" checkbox because it's scriptable, reversible, and shows up
honestly in System Settings → General → Login Items.
Two different drop causes, two fixes — plus one hard limit:
- Wi-Fi change / transient drop →
PERSISTENT_RECONNECT(default25s). openfortivpn reconnects on its own and reuses the SAML cookie — no re-login — until the gateway expires it. (Note: the number is the retry interval, not a session lifetime; it already loops forever, so keep it short.) - Idle timeout →
KEEPALIVE_INTERVAL(e.g.120s). A small ping through the tunnel keeps the session "active" so the gateway doesn't reap it for inactivity. openfortivpn sends no keepalive of its own, so this is the lever. Only helps an idle timeout. - Hard session cap (can't be beaten) → when the gateway's max-session timer fires, the cookie is dead and a fresh SAML SSO + MFA is mandatory — that's UCalgary IT policy, not something the client can extend. When that happens, the watchdog notices the tunnel has been down too long and restarts for a fresh browser login automatically (rather than looping silently on a dead cookie).
Don't know your gateway's timeouts? Measure: connect, tail -f ~/Library/Logs/fortivpn-auto.log,
and time the drop — once left idle, once kept active (a steady ping). Idle-only drop ⇒
set KEEPALIVE_INTERVAL under that; fixed wall-clock drop regardless ⇒ that's the hard cap.
- 📍 menubar stuck on
VPN ⏸, log spamsSSID is nil→ Location Services not granted. see the manual bit.doctorflags this for you. - 🔑
sudokeeps asking for a password on connect → the sudoers path doesn't match youropenfortivpn. re-runfortivpn-auto install, it auto-detects the real one. - 🌐 browser never opens for SSO → grab the URL from the log (search
saml) and open it by hand; check your default-browser binding. - 🧭 tunnel's up but internal sites won't load → split-DNS. peek at
scutil --dnsfor VPN resolvers on theppp0interface. - 🍪
Failed to retrieve SAML cookie→ usually a stale gateway session or the browser dead-ended on the FortiGate web portal. close those tabs, hit the menubar's Force connect, try again.
fortivpn-auto uninstall # reverses everything, asks before the destructive stuffRemoves the LaunchAgent, the managed init.lua block, the Spoon, and the sudoers grant; optionally the openfortivpn config and the Homebrew formulae. macOS Location/Accessibility entries are left for you to clear in System Settings.
- 📌 pinned, not trusting-by-default.
openfortivpnvalidates the gateway against the SHA-256 pinned in your config. that pin is the one moving part;refresh-cert.shrotates it. - 🎯 minimal sudo. the grant in
/etc/sudoers.d/fortivpn-autois NOPASSWD for exactlyopenfortivpn -c <your-config> --saml-loginand nothing else. argument-scoped, so it can't be repurposed (e.g. to sneak in--insecure-ssl). - 🤐 no secrets on disk. auth is SAML SSO in your browser; this tool persists
nothing.
vpn.confis gitignored so your gateway never lands in a commit.
Bug, or a gateway quirk on your campus? Open an issue with: your macOS
version, openfortivpn --version, and the relevant ~/Library/Logs/fortivpn-auto.log
lines (scrub anything private). 🐛
PRs welcome 🙌 — keep it bash + Lua, and before you push: bash -n bin/* lib/*.sh
and ./bin/fortivpn-auto doctor should be happy. Adding your school? Drop a
presets/<school>.conf and we'll merge it. 🎓
openfortivpn ·
Hammerspoon hs.wifi.watcher
- the
WiFiTransitionsSpoon pattern ·jseifeddine/openfortivpn-macosx(route/DNS reference) · the--cookie-in-stdingist.
MIT — see LICENSE. go wild. 🫡