Local users and groups — the firewall’s first identity store

OPNsense needs to know who is connecting to it and what they are allowed to do. The answer is an identity store: a database of users and groups that the firewall consults when an operator logs into the GUI, connects over SSH, or hits an API endpoint.

The simplest identity store is local — users and groups defined on the firewall itself. The full production answer is an external identity store (LDAP, RADIUS, TACACS+) that the firewall consults. The two are not mutually exclusive; most production deployments use local accounts for break-glass access and an external store for day-to-day operators.

This lesson covers how to design local users and groups, how group membership grants permissions, how local compares with external stores, and the operational discipline for managing local accounts at scale.

Local vs external identity

OPNsense supports three identity sources:

• Local: users and groups stored in the firewall’s own database. Authentication happens on the firewall.
• External (LDAP, RADIUS, TACACS+): the firewall consults an external server when authenticating. The user records live in the external system.
• Hybrid: the firewall tries external first, falls back to local if external is unavailable. (Often called “external with local fallback”.)

A local account that exists regardless of the external identity server is essential for break-glass access — the operator locked out by an LDAP outage, a RADIUS server crash, or a misconfigured TACACS policy. Every production OPNsense deployment should have at least one local admin account whose password is stored in a sealed envelope in a safe.

Creating local users

Local user management lives under System → Access → Users. The fields:

• Username: the login name. Should be unique across the estate if operators have multiple firewalls.
• Password: stored as a hash (bcrypt or argon2) in the firewall’s database. Use a strong, unique password per user. Do not share accounts.
• Full name: descriptive.
• E-mail: used for alerts, password recovery, audit notifications.
• Group membership: a user can belong to one or more groups. The groups grant permissions.
• Certificate: optionally, a user certificate for certificate-based authentication.

$ configctl user show admin

username: admin
fullname: Default Administrator
email: ops@example.com
groups: [admins]
disabled: false
shell: /usr/local/sbin/opnsense-shell
created: 2026-01-15T08:00:00+00:00

Designing the group structure

Groups in OPNsense map to roles. The default groups:

• admins: full GUI access, all configuration, all services. The break-glass group and the senior operator group.
• operators: read-only access to most configuration, plus the ability to manage their own sessions. Suitable for monitoring operators who need to see but not change.
• users: very limited access; suitable for captive portal users and similar limited contexts.

For production, the default groups are a starting point. The operator typically designs additional groups to match the estate’s role structure:

A user can belong to multiple groups. The permissions are the union — a user in admins and readonly gets full admin permissions.

User lifecycle

A local user goes through a lifecycle:

1. Provisioning. Create the user, assign group membership, set an initial password (or a one-time recovery link). Communicate the credentials through an out-of-band channel.
2. Active use. The operator logs in, works, makes changes. The firewall logs the actions with the username. Audit trails are preserved.
3. Password rotation. Periodic rotation per policy. OPNsense can be configured with a password expiry, but most production estates rely on the operator to rotate.
4. Off-boarding. Disable the user, archive the audit trail, rotate any shared secrets the user had access to. Do not delete the user record immediately — audit trails need to attribute past actions.

Local accounts at scale

A single firewall with five operators is fine for local accounts. A fleet of fifty firewalls with two hundred operators is not — the operator changes per firewall, the password rotation is per firewall, and the audit trail is per firewall.

The escalation is to an external identity store. The external store (LDAP, RADIUS, TACACS+) holds the canonical user records; the firewall consults the external store at authentication time. The local accounts on the firewall shrink to a small set of break-glass accounts; the day-to-day operators authenticate via the external store.

The remaining lessons in this part of the course cover the external stores and the failure modes that come with them.

Summary

• Local users and groups are the firewall’s first identity store. Every production OPNsense should have local break- glass accounts that work regardless of external store availability.
• Group membership grants permissions. Design groups to map to roles (admins, neteng, secops, readonly).
• Do not share admin accounts. One account per operator, with permissions derived from group membership.
• For multi-firewall estates with many operators, escalate to an external identity store. Keep local accounts for break-glass only.