How authentik becomes the LDAP authentication server for OPNsense
A firewall team that wants OPNsense administrator logins and VPN user checks to draw on the directory authentik already governs has a clear supported path: the authentik LDAP provider, served through an LDAP outpost. The authentik OPNsense integration guide describes authenticating OPNsense users against an authentik LDAP provider, so the integration is built around LDAP binds and searches rather than a SAML or OIDC login redirect. That distinction matters for planning, because OPNsense consumes whatever the LDAP server returns during a bind and search, and it has no view of how authentik itself authenticated the user.
OPNsense uses the LDAP result in two places. For administrators, it decides whether a bind succeeds and which group membership, if any, is mapped to an administrative role in the web interface. For VPN users, it confirms that the account exists and is allowed to authenticate through the configured authentication server. authentik remains the source of truth for the user accounts, group memberships, passwords and account status. Disabling a user or removing a group in authentik is the change that should stop access, so the team should confirm with the integration guide which group attributes OPNsense reads and how it matches them to roles before promising administrators a specific mapping.
Before building anything, confirm three points against the current authentik OPNsense integration guide and the authentik LDAP provider documentation: the OPNsense version your firewalls run, the LDAP fields and group object classes the guide expects, and whether the outpost will be reachable from the firewall management and VPN segments. Those answers decide the bind account, search base and TLS settings described in the sections that follow.
What you need in place before configuring OPNsense against authentik
Five pieces must exist before OPNsense can bind to authentik: the identity platform, the LDAP outpost, a bind account, the users and groups OPNsense will read, and a TLS plan. Each card below covers one of them and the checks to run before you open the OPNsense console.
Choose the authentik deployment path
Docker Compose suits a test environment or small-scale production, and the authentik guide positions it that way. Its documented minimum is 2 CPU cores and 2 GB of RAM. For production on Kubernetes, the Helm chart bundles PostgreSQL for demonstration and testing only, so plan a separately managed PostgreSQL before go-live. Decide this first, because it sets how the LDAP outpost is hosted and how upgrades run.
Confirm the authentik release line
Check the authentik security policy before choosing a version. The supported lines receiving security fixes are 2026.5.x and 2026.8.x, and security releases are announced at least 24 hours ahead. Confirm which line your environment will run, and confirm the OPNsense version you have, since the integration depends on both sides working together.
Place the LDAP outpost where OPNsense can reach it
The OPNsense LDAP server setting points at a host and port, so the LDAP outpost must be reachable from the OPNsense firewall over the network path you intend to use. Map which firewall rules, VLANs or NAT entries allow that traffic, and confirm the outpost can reach authentik's core services. Avoid exposing the LDAP port to untrusted networks.
Create a dedicated bind account
OPNsense needs a service account to search the directory before it authenticates users. Create a separate authentik user for this purpose, grant it only the read access the LDAP provider requires, and do not reuse a human administrator account. Record who owns the password and how it will be rotated, because every OPNsense login depends on this bind succeeding.
Prepare users and groups in authentik
OPNsense maps directory groups to administrator and VPN roles, so group membership must be correct before you configure the mapping. Define one group for firewall administrators and separate groups for each VPN population, and assign only the users who need each role. Confirm group names exactly as they will appear in the LDAP search results, since mismatched names are a common cause of failed role mapping.
Plan the certificate for LDAP over TLS
Credentials sent over plain LDAP are exposed, so plan LDAPS or StartTLS from the start. Decide which certificate authority issues the outpost certificate, make sure OPNsense trusts that CA, and confirm the certificate name matches the host you enter in OPNsense. Assign an owner for renewal, because an expired certificate will block all firewall and VPN logins at once.
Configuring the authentik LDAP provider and OPNsense in sequence
This sequence builds an LDAP provider and outpost in authentik, then points OPNsense at it so administrators and VPN users sign in with their directory credentials. Each step ends with a check you can run before moving on, so a fault is found where it was introduced.
Create the LDAP provider and application
In the authentik admin interface, an identity administrator creates an LDAP provider with a base DN that matches your directory layout, then creates an application that uses it. Set the bind mode and search mode deliberately, and bind the provider to the application so the outpost can serve it. The step is complete when the provider appears in the application list with its base DN and the expected flow bindings shown on its settings page.
Deploy the LDAP outpost
The platform team deploys an LDAP outpost that connects back to the authentik server, using the deployment method that matches your environment (the Docker Compose or Kubernetes guides both cover outposts). The outpost must be reachable from OPNsense on the LDAP port you choose, and it should be assigned the LDAP provider created in the previous step. The step is complete when the outpost shows as connected in the authentik admin interface and its logs show no connection errors.
Create a read-only bind account
Create a dedicated service user in authentik for OPNsense to bind with, and give it no administrative rights. Place it in a group that is not used for user access decisions, and record the password in your secrets store rather than in a ticket. The step is complete when that account can perform a bind test against the outpost from a machine that resembles the OPNsense host, and a bind with a wrong password fails.
Set the base DN and search scope
Confirm the base DN and search scope on the LDAP provider so that OPNsense queries only the users and groups it needs. Narrow the scope to the organizational unit or group that holds administrators and VPN users, rather than the whole tree, and note the exact DN values you enter. The step is complete when a search from the outpost host for a known test user returns that user's entry and no entries outside the intended scope.
Configure the LDAP authentication server in OPNsense
In OPNsense, an administrator adds a new LDAP authentication server under the user manager settings. Enter the outpost address, the port that matches the provider, the bind DN and password for the read-only account, the base DN, and the user name attribute that authentik exposes. Use the TLS option your TLS design requires, and do not disable certificate checks to make the connection work. The step is complete when the server saves without error and the built-in connection test reports a successful bind.
Test an administrator login
Assign the LDAP server to the OPNsense administrator login path, then sign in with a test account that belongs to the administrator group in authentik. Confirm that the account receives the privilege level you intended, and that a user outside the group cannot reach the administrative pages. Keep a local emergency administrator account in place until this test passes and you have recorded the fallback procedure. The step is complete when the admin login succeeds, the expected privileges appear, and the non-admin test account is refused.
Test a VPN user login
Using a standard test user from the VPN group, authenticate through the OPNsense VPN service configured to use the same LDAP server. Check that the user is allowed in, and that a user outside the group is refused, since group membership controls who gets through. Review the OPNsense authentication log and the outpost log together to confirm the lookup and bind occurred as expected. The step is complete when both the allowed and refused tests produce the outcomes you designed and the logs match them.
Mapping authentik users and groups to OPNsense admin and VPN roles
This table compares the LDAP attributes and authentik group memberships that OPNsense receives with the OPNsense objects they should map to, such as local users, groups and privileges. Read each row as a design decision to make on the OPNsense side before the bind account goes live. The main takeaway is that authentik supplies identities and group membership, while OPNsense decides what those groups can do, so the mapping must be written down and confirmed against the authentik OPNsense guide first.
| Attribute or object | What authentik supplies | What to decide in OPNsense | What to confirm before rollout |
|---|---|---|---|
| User identifier | The username attribute returned by the LDAP provider for each user | Which field matches the OPNsense local username and whether existing local accounts will collide | Username format and case handling in the authentik guide |
| Display name | The name attribute for each user | Whether the name is shown in audit and session views only or used in any policy | Attribute names the LDAP provider exposes in your version |
| Email address | The mail attribute for each user | Whether email is needed at all for admin or VPN login (often it is not) | Whether the attribute is returned in your authentik release |
| Group membership | Group objects and memberships returned through the LDAP search | Which authentik groups map to OPNsense groups, and which groups grant no access | Exact group attribute and search base used by the guide |
| Administrator privileges | Membership in a dedicated admin group in authentik | Which OPNsense privileges the admin group receives, kept to the minimum needed | Privilege names in your OPNsense version and a tested emergency admin path |
| VPN user access | Membership in a VPN group in authentik | Which VPN authentication server and access rules this group can use, separate from admin rights | Whether VPN users need only a login and no OPNsense UI privileges |
| Local emergency account | Nothing; this account stays local | Keep at least one local administrator that does not depend on LDAP reachability | Recovery steps tested while authentik is offline |
Choosing LDAP transport and TLS settings for OPNsense
The first decision is whether OPNsense sends bind credentials and directory queries over plain LDAP, over LDAPS (LDAP wrapped in TLS from the first byte), or over LDAP upgraded to TLS with StartTLS. Plain LDAP is the simplest to configure, but the bind password and user lookups cross the network unencrypted. It is only defensible when the path between OPNsense and the outpost stays on a tightly restricted management segment that only administrators can reach. LDAPS and StartTLS both encrypt the session, and both require OPNsense to validate a certificate. Whichever you choose, confirm in the authentik LDAP provider documentation which transports your outpost version offers, and confirm the port and mode in your own deployment rather than assuming defaults.
- Plain LDAP: Lowest setup effort, but credentials are readable by anyone who can observe the segment.
- LDAPS: Encrypted from connection start, with one TLS handshake and a fixed port.
- StartTLS: Begins as plain LDAP and upgrades, so a misconfigured client can silently fall back.
- Segment restriction: Plain LDAP is acceptable only if switches, VLANs and access rules confine it to named hosts.
- Documented choice: Record the transport, the reason and the owner in your change record.
Before you lock in the choice, confirm what your outpost version supports and what your security policy requires for administrator credentials.
With LDAPS or StartTLS, OPNsense checks that the certificate presented by the outpost chains to a certificate authority it trusts and that the certificate matches the hostname it connects to. If either check fails, the connection breaks and authentication stops, often with a generic error. The authority can be an internal CA that your organization already operates, or a dedicated CA created for this service. A public CA is usually unnecessary for an internal outpost, and it adds an external dependency for a service that should stay inside your network. Plan who issues and renews the certificate, because an expired certificate is a common cause of a sudden outage.
- Chain completeness: Install the intermediate and root certificates in OPNsense so the chain validates.
- Hostname matching: The name in the configuration must match a subject alternative name on the certificate, so use DNS names and not bare IP addresses unless the certificate includes that address.
- Trust store placement: Add the CA to OPNsense's certificate manager and select it in the LDAP authentication server settings.
- Renewal ownership: Assign a named owner and a calendar reminder before the outpost certificate expires.
- Revocation: Confirm how your internal CA publishes revocation information and whether OPNsense can reach it.
Confirm the certificate requirements for your outpost version in the authentik documentation before you issue the certificate.
Authentication traffic flows from the OPNsense interfaces that handle administration and VPN logins to the authentik outpost. For administrator logins, the source is usually the management interface. For VPN users, the source is the interface where the VPN service authenticates, which may be a different subnet. Each source needs a rule allowing TCP to the outpost on the LDAP or LDAPS port, and nothing else should be allowed toward it from those networks. The outpost must also reach the authentik server or database it depends on, so trace the full path rather than only the first hop.
- Source subnets: List the management network and each VPN address pool that performs LDAP lookups.
- Destination: Allow only the outpost address and port, not the whole server segment.
- Return traffic: Stateful rules normally cover replies, but confirm this in your firewall policy.
- Outpost dependencies: Confirm the outpost can reach the authentik core service it connects to.
- Egress from the outpost: Restrict outbound traffic from the outpost to what it needs.
Confirm the exact ports, direction and rule order in your environment with a test from each source subnet before you rely on the path.
Firewall rules for LDAP are easy to get wrong because the authentication failure appears on the login page, not in the firewall logs. Before go-live, test each source network separately. An administrator on the management VLAN may succeed while a VPN user from another pool fails because that pool has no permitting rule. Use the firewall's live log while a test login runs, and confirm that the traffic is allowed by the intended rule and not by a broad any-to-any rule that would remain after the project.
- Per-source tests: Attempt a bind and a user search from every subnet that will use the service.
- Live logs: Watch the firewall log during a test so you can see which rule matches.
- Remove broad rules: Delete temporary any-to-any rules created for testing.
- Negative tests: Confirm that an unauthorized subnet cannot reach the outpost port.
- Change control: Record each rule with its source, destination, port and owner.
Confirm your firewall's rule evaluation order and logging options in the vendor documentation, since these vary between platforms and versions.
Securing the bind account, admin access and lockout risk
An LDAP integration gives OPNsense a live path to your directory, so the bind account, the network path to the outpost and the admin login all need deliberate limits. The cards below cover the controls to decide before go-live and the recovery path to test before you need it.
Scope the bind account to reads
The bind account is the identity OPNsense uses to search the directory, so give it read access to users and groups under the search base and nothing more. Do not reuse a human administrator account or a service account that also writes to other applications. Confirm in the authentik LDAP provider documentation how the bind user is created and which search permissions it receives. Review its group memberships after each change to the outpost configuration.
Keep a local emergency admin
If authentik, the outpost or the network path to it fails, OPNsense administrators can be locked out of the web interface. Keep at least one local administrator account on OPNsense that does not depend on LDAP, store its credentials offline, and test that it still logs in after each change. Confirm how OPNsense ranks local and LDAP-backed users when both exist with the same name, and document the recovery steps for your team.
Restrict network paths to the outpost
Only OPNsense and the hosts that must reach the LDAP outpost should be able to open the LDAP port on it. Use firewall rules on the segment where the outpost runs to allow the OPNsense address and deny other sources, and avoid exposing LDAP to the internet or to user networks. Check the outpost's listening address and port in your deployment, and confirm that authentication requests from VPN clients never reach the LDAP port directly.
Protect the bind password
The bind password appears in the OPNsense authentication server configuration, so anyone with access to that configuration can read it. Generate a long random password, store it in a secrets manager, limit who can view OPNsense backups, and rotate it on a schedule and after any staff change. Confirm whether your OPNsense backup encryption covers this value before you share or archive configuration files.
Plan for LDAP MFA limits
A plain LDAP bind carries a username and password and no second factor step, so MFA on an LDAP login is not a given. Some authentik MFA methods can be combined with LDAP bind passwords, but the method, the password format and the client behavior must be confirmed for your chosen method in the authentik MFA documentation. Test each VPN and admin login path with the factor you intend to require before you rely on it.
Test lockout and failover behavior
A small number of failed binds, expired passwords or an outpost restart can lock users out of VPN access or admin sessions. Write down which accounts can be disabled in authentik, how long a failed bind lock lasts, and what happens to active VPN sessions when the outpost is unreachable. Run a scripted test of each case in a staging environment, and record the expected result so on-call staff can act quickly.
Why OPNsense LDAP logins fail against authentik and how to fix them
This table lists the failures most often seen when OPNsense authenticates against an authentik LDAP provider, with the likely cause and the first fix to try for each. Read it as a triage sheet: match the symptom you see in OPNsense or the authentik logs to a row, then check the provider settings it points to. The main takeaway is that most failures trace back to a small set of settings: the bind account, the base DN and scope, the certificate name, and the group attribute.
| Symptom | Likely cause | First fix to try |
|---|---|---|
| Bind fails with invalid credentials | The bind DN is not the full DN of the service account, or the password was rotated in authentik but not in OPNsense | Copy the service account's full distinguished name from authentik and re-enter its current password in OPNsense; confirm the account is active and not expired |
| Bind succeeds but search returns no users | The base DN is wrong or the search scope does not reach the users' location in the directory tree | Compare the base DN with the search base configured on the authentik LDAP provider and widen the scope if users sit in a sub-container |
| Users are not found for some accounts only | The user lacks the attributes the search filter expects, or the account is inactive or outside the bound application | Check that the user is assigned to the provider's application and that the search filter matches the attributes present on that user |
| TLS handshake fails or certificate name error | OPNsense connects to a hostname that does not appear in the certificate, or the CA certificate is not trusted by OPNsense | Use the hostname on the certificate in the OPNsense server entry and import the issuing CA into OPNsense's trust store before retesting |
| Login works but group-based access is missing | Group membership is not returned in the attribute OPNsense reads, or the group names in authentik do not match the groups mapped in OPNsense | Review the group attribute and group DN settings on the LDAP provider, then match the exact group names in OPNsense's group mapping |
| Admin user locked out after a change | A change to the bind account, search base or authentication server left no working local administrator | Keep a local administrator account in OPNsense before any change and test each change with a second session before closing the first |
| Login is slow or times out intermittently | The LDAP outpost cannot reach the authentik server or the connection is limited by the network path | Confirm the outpost's connectivity to authentik and the port OPNsense uses, then review the authentik outpost logs for connection errors |
Questions buyers ask before configuring OPNsense with authentik LDAP
What drives the effort of an OPNsense LDAP integration with authentik?
Effort rises with the number of decisions the directory has to support, not with the LDAP setting screens themselves. The main drivers are the group design (how many groups map to OPNsense administrator privileges and VPN access), the number of OPNsense instances that will bind to the same provider, the TLS and network changes needed so OPNsense can reach the authentik outpost securely, and the number of VPN users whose login behavior must be tested. Each additional OPNsense instance adds its own bind account, search settings and verification pass. Ask any provider to break its quote down by these items so you can see which ones you are paying for.
How long does an OPNsense and authentik LDAP setup take?
Duration depends on how quickly the directory design is agreed and how many OPNsense instances and user populations are involved. The fastest path is a single OPNsense instance, an existing authentik deployment, and a group model that is already documented. Delays usually come from waiting for approval of group-to-privilege mappings, from firewall rules that must be changed through a change process, and from certificate issuance for the LDAP connection. Ask for a timeline in the written scope that lists these dependencies as separate milestones, with your own approval points marked.
What does our internal team need to provide before the work starts?
Your team needs to supply the directory and access information that only you hold. This includes the user and group data authentik will expose, the names of the groups that should receive OPNsense administrator or VPN access, the network rules that allow OPNsense to reach the authentik LDAP outpost, and the certificate authority or certificate material used for TLS. You also need a named approver for privilege mappings, because granting administrator rights through LDAP is a security decision. Confirm these inputs in writing at the start so delays do not appear mid-build.
Can our team configure OPNsense and authentik LDAP without a partner?
Yes, a capable team with authentik and OPNsense experience can do this alone, and the official authentik integration guide for OPNsense is the starting point. The parts most often underestimated are the bind account design, the search base and group filters, testing that administrator and VPN users receive the correct privileges, and verifying TLS end to end. A partner is useful when your team lacks time, when several OPNsense instances must be consistent, or when you want the configuration documented and handed over. Decide based on who will operate the result after go-live.
Does the OPNsense LDAP integration require authentik Enterprise?
The authentik pricing page lists three editions: Open Source (free, community Discord only), Enterprise at $5 per user per month billed annually plus $0.02 per external user per month, and Enterprise Plus starting at $20k annually. Its list of Enterprise-only features includes Google Workspace and Microsoft Entra ID integrations, mTLS client certificate authentication, privileged access management, password history, enhanced audit logging and ticket-based support for subscriptions over $1k. The pricing page does not list the LDAP provider as Enterprise-only, but confirm your exact edition requirements against the current pricing page and the OPNsense integration guide before you commit to a plan.
What should be in the written scope for this integration?
A written scope should name the authentik version and deployment type, each OPNsense instance in scope, the LDAP provider settings, the bind account and its permissions, the search base and group mapping rules, the TLS configuration, the list of user groups and their OPNsense privileges, and the test cases that prove administrator and VPN logins behave correctly. It should also state what is excluded, such as MFA design, other firewalls or other directories, and who signs off privilege mappings. Most engagements are fixed-scope, so ask for these items to be agreed in writing before work begins and for any change to them to be recorded as a scope change.
What breaks most often after an authentik LDAP bind goes live on OPNsense?
The most common failures are an incorrect bind distinguished name or password for the service account, a search base that does not include the users or groups being tested, group filters that match nothing, and TLS certificate names that do not match the hostname OPNsense connects to. Users may also log in successfully but receive no privileges because their group membership was not mapped. Check each of these with a test account before enabling broad access, and keep a local OPNsense administrator account available for recovery. Plan to review the bind account's permissions and group mappings whenever directory structure changes.
How DeployOpen scopes and delivers the OPNsense LDAP integration
DeployOpen plans and implements authentik and OPNsense LDAP authentication inside your own infrastructure, with the authentik deployment, LDAP provider, bind account and OPNsense configuration documented together. Engagements are fixed-scope, so the written scope fixes what is delivered before work starts.
How we scope
- Confirm which OPNsense functions authenticate against LDAP: administrator login, VPN users, or both
- Record the authentik version, hosting model and whether the server runs in Docker Compose or Kubernetes
- Agree the LDAP search base, groups to map, and whether a dedicated bind account is permitted
- Document the TLS approach, certificate authority and OPNsense hosts that must trust it
How we build
- Create the LDAP provider and outpost in authentik, then bind the application to the agreed users and groups
- Configure the OPNsense LDAP authentication server and map authentik groups to OPNsense privileges
- Test administrator login, VPN login and lockout behavior against a non-production OPNsense instance first
- Verify that group membership changes in authentik take effect for OPNsense sessions as expected
How we hand over
- Deliver a written configuration record covering provider settings, bind account scope and group mappings
- Provide a rollback procedure that keeps a local OPNsense administrator account available during cutover
- Document the test cases used, with results, so your team can repeat them after changes
- Walk your administrators through troubleshooting steps for failed binds and missing group membership
How we support
- Review the authentik security policy and release notes before scheduling any version change
- Plan outpost and OPNsense updates together so LDAP connectivity is retested after each change
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Ask any support provider to confirm response terms in writing, since DeployOpen publishes no SLAs
