Privilege separation and roles — least privilege on the firewall

A firewall that grants every operator full administrative privilege is a firewall where any compromised operator account is a compromise of the entire firewall. The production answer is privilege separation: designing roles so that each operator has the minimum set of permissions needed to do their job, and no more.

This lesson covers how to apply least privilege to OPNsense access, how the GUI and API enforce page-level and endpoint- level permissions, how to separate read, write and admin rights by role, and the anti-patterns that grant excessive privilege.

What least privilege means on a firewall

Least privilege is the principle that every operator (and every process) should have exactly the permissions needed to do their job, and no more. On a firewall, this translates to:

• A network engineer does not need access to certificate management.
• A security operator does not need access to routing configuration.
• A monitoring operator does not need to change firewall rules — they need to read them.
• A break-glass admin needs everything, because their job is recovery when the normal paths have failed.

The practical expression is a set of roles, each with the permissions for a specific operational responsibility, and operators assigned to the role that matches their responsibility.

How OPNsense enforces permissions

OPNsense enforces permissions at two levels.

GUI pages. Each GUI page (Firewall → Rules, Services → DHCPv4, System → Trust, etc.) is associated with one or more privileges. When an operator loads a page, the GUI checks whether the operator’s groups include the privilege required for that page. If not, the page is hidden or returns “Access denied”.

API endpoints. Each API endpoint (/api/firewall/filter/addRule, /api/trust/cert/search, and so on) is similarly gated by a privilege. API clients authenticate with an API key/secret pair presented as HTTP Basic credentials; the privilege check runs after authentication succeeds and before the endpoint executes.

The two checks fail differently, and the difference is the first thing to read when an automation stops working: a 401 means the credentials themselves were rejected, while a 403 means they were accepted and the account behind them lacks the privilege the endpoint requires.

The mapping of pages to privileges is defined in the OPNsense code; the mapping of groups to privileges is what the operator controls.

$ configctl group show admins

name: admins
description: Administrators with full GUI access
privileges:
- firewall.rule.* 
- interfaces.* 
- system.* 
- trust.* 
- services.* 
- vpn.*

Designing roles

A production role design maps to operational responsibility. A starting point for an estate of any size:

The exact mapping depends on the estate. The principle: each role has the privileges for one operational responsibility. Operators assigned to that role get the privileges; operators outside that role do not.

Page-level vs API-level privileges

OPNsense enforces permissions in both the GUI and the API. A role must be designed for both. Common patterns:

• GUI-only operator: uses the web interface, never the API. Has GUI page privileges but does not need an API key.
• API-only service account: a monitoring system that polls OPNsense for metrics. Has an API key with the minimum privileges needed for the polling endpoints. Does not need GUI access.
• Both: an operator who uses the GUI for most work and the API for scripted tasks. Has both GUI privileges and an API key.

API keys are configured under System → Access → Users → [user] → API keys. Each key can be scoped to specific privileges, which is the production answer: a monitoring API key with *.*.get privileges, an automation key with firewall.rule.* privileges, and so on.

Privilege separation in workflows

The practical test of a role design: walk through common operator workflows and confirm the operator has the permissions needed, and only those permissions.

Workflow 1: an operator adds a firewall rule.

• Needs: firewall.rule.add, firewall.rule.edit.
• Does not need: routing, certificates, user management, service configuration.

Workflow 2: a security operator investigates an alert.

• Needs: system.log.*.get, ids.alert.*.get.
• Does not need: configuration changes of any kind.

Workflow 3: a network engineer troubleshoots routing.

• Needs: system.routing.*.get, system.diagnostics.*.get.
• May also need: firewall.rule.*.get (read rules while diagnosing).
• Does not need: certificate management, user management.

Workflow 4: a break-glass operator recovers from external identity failure.

• Needs: everything, because the normal paths have failed.

Each workflow maps to one role or to a small set of roles. Operators outside the workflow do not have the role. The blast radius of any one operator’s compromised account is the union of the roles they hold.

Anti-patterns

Five anti-patterns show up repeatedly.

1. Single admin role for everyone. Every operator gets admins. Privilege separation is theoretical. Anti-pattern.
2. Wildcard privileges on a non-admin role. A custom role with system.* or firewall.*. The role looks narrower than admins but in practice has admin-equivalent reach. Anti-pattern.
3. API keys with admin privileges for monitoring. A monitoring system polls with full admin API keys. The keys can change firewall rules if the monitoring system is compromised. Anti-pattern.
4. Read-only role that can change configuration via diagnostics. A role designed as read-only but the operator can use System → Diagnostics → Commands to run shell commands. The read-only role is not actually read-only. Anti-pattern.
5. Sharing one account across roles. Two operators share an account because their permissions overlap. Audit attribution is lost. Anti-pattern.

Summary

• Least privilege means every operator has the minimum permissions needed. A compromised account is bounded by the role it holds.
• OPNsense enforces permissions at the GUI page level and the API endpoint level. Design roles that cover both.
• Design role groups that map to operational responsibility: admins, neteng, secops, monitoring, vpnops.
• Read-only roles are worth the design effort. Most monitoring and debugging workflows can run read-only.
• API keys are bearer credentials. Scope them to the minimum privileges needed; rotate, audit, revoke on compromise.