How authentik authenticates pfSense users over LDAP
Authentik can serve as the account source for pfSense administrators and VPN users through an LDAP provider, with an LDAP outpost answering pfSense's authentication requests. Instead of creating local pfSense accounts for each person, your team points pfSense at authentik as an LDAP authentication server, so people sign in with the credentials they already use. The supported route is the one described in the authentik pfSense integration guide: an LDAP provider in authentik, an LDAP outpost that exposes it to the network, and a service account that pfSense uses to bind and search. Your sign-in path then depends on that outpost being reachable from the firewall and on the bind account having read access to the users and groups you intend to match. From pfSense's side, LDAP is an authentication server, not a federated login. pfSense sends a bind request with the user's name and password, then searches the directory to confirm the account and read group membership. This is a password-based bind, so SAML-only behavior such as redirecting the browser to an identity provider login page does not apply here. Administrator and VPN logins both go through this same password check, which means any second factor has to be carried inside the password field, a design covered in the MFA section of this page.
Before you build, confirm the following in your own environment rather than assuming them. Check the pfSense version you run, because the LDAP authentication server screens, group handling and certificate options differ between releases, and confirm each setting against the integration guide and your pfSense documentation. Confirm that your authentik version is one that receives security fixes, using the supported versions listed in the authentik security policy. Finally, confirm which authentik groups should map to pfSense administrator privileges and which should map to VPN access, since those mappings determine who can change the firewall and who can only connect through it.
What you need in place before configuring pfSense
The LDAP outpost is the piece pfSense talks to, and it depends on a working authentik server, a worker and a database behind it. Settle the deployment, the network paths, the names and certificates, and the group structure first, because each one changes the pfSense settings you enter later.
Server, worker and PostgreSQL
An authentik deployment runs a server container (core plus an embedded outpost), a worker container for background tasks, and PostgreSQL, which holds all configuration and data except uploaded files. Docker Compose is documented for test setups and small-scale production, and needs at least 2 CPU cores and 2 GB of RAM. The Helm chart bundles a PostgreSQL meant for demonstration and testing, so plan a separately managed PostgreSQL for production. Confirm which deployment method your environment will use before you create the LDAP provider.
Confirm the pfSense version
The authentik pfSense guide describes the LDAP authentication server setup in the pfSense web interface. Before you build the provider, record the exact pfSense release your firewall runs and check the menu paths and field names against the integration guide for that release. Note also whether the firewall administrators and VPN users will use the same authentication server or separate ones, since this decides how many LDAP servers you configure.
Network paths to the outpost
pfSense must reach the LDAP outpost on the LDAP port or on LDAPS. Map the path from the firewall's management and VPN interfaces to the host or cluster where the outpost runs, and confirm that any intermediate firewall rules allow the traffic. Decide whether pfSense will use plain LDAP only inside a trusted segment or LDAPS everywhere, because the bind password travels on that connection. Verify the port the outpost listens on in your deployment before you write any rule.
DNS names and TLS certificates
pfSense validates the certificate presented by the LDAP endpoint when you use LDAPS, so the name you enter must match a name on the certificate. Create an internal DNS record for the outpost, issue a certificate that covers it, and make sure the issuing CA certificate can be imported into pfSense as a trusted CA. Confirm with your PKI or certificate team whether your CA is public or private, and whether revocation checks are possible from the firewall.
Service account and bind credentials
pfSense binds to the directory with a service account whose password is set in the LDAP authentication server settings. Plan a dedicated authentik user for this purpose with the least rights that allow search, and record who owns its password and how it rotates. Treat the MFA code appended to the bind password as a design decision: the code is only as current as the moment it is typed, so confirm how pfSense sends that value and how your users will enter it before rollout.
Admin and VPN group structure
Agree the groups before you configure pfSense, because pfSense maps directory groups to privileges and VPN access. Create separate groups for firewall administrators and VPN users, and decide who belongs to each. Keep at least one local pfSense administrator account outside LDAP so that a directory outage or a bad group change cannot lock you out of the firewall. Write down the group names exactly as they appear in authentik, since they must match the values you enter on the firewall.
Configuring the authentik LDAP provider, service account and outpost
This sequence builds a read-only LDAP path from authentik to pfSense, with each stage checked before the next one depends on it. The result is a pfSense LDAP authentication server that authenticates administrators and VPN users against authentik groups.
Create a read-only service account
An authentik administrator creates a dedicated service user for pfSense to bind with, kept separate from any personal account. Give it a strong, generated password and no membership in administrative groups, so it can search the directory but cannot change users or policies. Record the account's distinguished name, since pfSense needs it as the bind DN. Check that the account exists, is active, and is not a superuser before moving on.
Create the LDAP provider
In the authentik admin interface, create an LDAP provider and set its base DN, which pfSense will use as the search base. Choose the bind mode and search mode that match how pfSense performs lookups, and confirm the service account is allowed to bind through the provider's settings. Review the provider's TLS and certificate options now, because changing them later affects every client. The provider is complete when it saves without errors and its base DN matches the directory tree you plan to search.
Bind the provider to an application
Create an application in authentik for pfSense and attach the LDAP provider to it, so that the outpost knows which directory to serve for that application. Limit access with a policy or group binding if only some users should authenticate to pfSense. Confirm the application appears in the list with the LDAP provider shown as its provider. The step is done when the application and provider are linked and access bindings reflect your intended user population.
Deploy or assign the LDAP outpost
Deploy an LDAP outpost on a host that can reach both authentik and the pfSense network, following the authentik outpost documentation for your platform. Assign the application to that outpost in the admin interface. The outpost must show as connected and healthy in the outposts list. Tell your team to confirm the pfSense network can reach the outpost's LDAP listening port, because a connected outpost that pfSense cannot reach still fails at login.
Test the bind and search from the outpost host
From the outpost host, run an LDAP bind with the service account's distinguished name and password, then run a search under the base DN. Verify that the bind succeeds and that the search returns the users and the groups you expect, including the groups you will use for pfSense privilege mapping. If the bind fails, check the bind DN format and the account's active state before changing anything else. Do not continue until the bind and a group-filtered search both return the expected results.
Configure the LDAP authentication server in pfSense
In pfSense, open System, User Manager, Authentication Servers and add an LDAP server. Enter the outpost address, the same base DN, the service account's bind DN and password, and the search filter that selects the users and groups you want. Use the TLS setting that matches your outpost configuration, and confirm the port. Save the server but do not yet assign it to any privileges. The check is that the server saves and shows as configured.
Verify with Test Authentication
Use the Test Authentication function on the pfSense authentication server with a known test user from the authentik group you scoped for pfSense. A successful result should show the user's groups as returned by the directory. Then test a user who should be denied and confirm the attempt fails. Record both results. Only after these tests pass should you map groups to pfSense administrator or VPN privileges and move to a live login.
How code-based MFA fits into an LDAP bind password
An LDAP bind carries one secret: the password the client sends with the bind request. A one-time code can only be added to that password if the authentik flow and the pfSense LDAP client both support a combined format, typically the password followed by the code in the same field. Many LDAP clients do not offer a second input for a code, so do not assume MFA is in effect until you have tested the exact password-plus-code behavior in your environment. Confirm with the pfSense documentation for your version and with the authentik LDAP provider settings how the code is expected to be concatenated, and whether the flow accepts it on every bind or only on some.
Codes are time-limited, so the user must type the password and a fresh code at the moment of login, and a code that expires during a slow connection will fail. Clock drift between the authentik hosts and the user's device can also make valid codes appear invalid, so check time synchronization on the server and the authenticator before go-live. Failed attempts count toward lockout policies, so a user who retries with stale codes can lock themselves out of administrator access. Plan a documented recovery path and review the lockout thresholds in the flow before the first user is enrolled.
Because a lockout or a broken flow can remove every administrator's ability to sign in to pfSense, keep a static fallback account that is stored in the pfSense local user database, with a strong password held outside the directory, and test it before you enforce MFA. For alternatives that handle second factors more predictably, compare the authentik MFA and passwordless topic and the RADIUS-based VPN login with MFA topic, since those approaches separate the code from the password differently. Record which option you chose and why, because the choice affects every pfSense login path.
Mapping authentik groups and attributes to pfSense LDAP fields
This table pairs each authentik object with the LDAP field or pfSense setting that reads it. Work through it top to bottom when building the LDAP provider and outpost, then confirm the pfSense side with a test login from a user in each group. The main takeaway is that admin and VPN rights should come from separate authentik groups, so a VPN-only user cannot reach the administrative interface.
| Item | authentik side | pfSense side |
|---|---|---|
| Login name | Username field on the user, exposed by the LDAP provider | Username attribute on the LDAP authentication server, must match the value the outpost returns |
| Display name | Name field on the user | Informational only for login, confirm which attribute the outpost maps |
| Email field on the user | Used for notices and mapping, not required for the bind to succeed | |
| Search base | Base DN of the LDAP provider, covering the users and groups pfSense needs | Base DN and authentication containers must point to the same directory tree |
| Group object class | Groups returned by the outpost as group objects | Group object class must match what the outpost emits, confirm in the integration guide before testing |
| Admin privileges | Illustrative: a group such as pfsense-admins | Local pfSense group holding admin privileges, LDAP membership is checked against it |
| VPN access | Illustrative: a separate group such as vpn-users | Group referenced in the VPN authentication configuration, kept apart from admin groups |
| Second factor | Code entered after the password through the bind flow | Users enter password and code together, confirm pfSense passes the combined value unchanged |
Securing the bind account, transport and privileges
The LDAP provider gives pfSense a read path into authentik, so the bind account, the transport, the network route and the admin fallback all decide how much damage a leak or outage can cause. The cards below cover each control and what to confirm before pfSense is pointed at the outpost. Most of them are configuration choices you make in both products, not licensed features.
Read-only service account with narrow search base
The bind account is the credential pfSense stores in its LDAP authentication server settings, so treat it as the most exposed secret in this design. Create a dedicated service account in authentik that can read only the users and groups pfSense needs, and set the LDAP provider search base to the smallest tree that contains them. Confirm the account cannot write objects or read unrelated users before you save the bind password.
LDAPS or StartTLS with a trusted certificate
Bind credentials and user passwords must not travel in clear text between pfSense and the outpost. Choose LDAPS or StartTLS, then issue the outpost certificate from a CA that pfSense already trusts or import that CA into pfSense's certificate manager. Check that the certificate name matches the host name pfSense uses, because a name mismatch often looks like a generic bind failure.
Outpost reachable from pfSense only
The LDAP outpost should accept connections from the pfSense interface address and nothing else. Apply firewall rules on the host or network that runs the outpost so that only the pfSense LAN or management address can reach the LDAP port, and block other sources by default. Revisit the rule whenever the pfSense address or the outpost host changes.
Local emergency administrator on pfSense
If the LDAP path, the outpost or authentik itself fails, administrators must still reach the webConfigurator. Keep a local administrator account in pfSense with a strong, offline-stored password and test that it logs in before you change the default authentication server. Do not use the same password as any directory account, and record who can retrieve the credential.
Group-restricted webConfigurator access
Being able to authenticate is not the same as being allowed to administer the firewall. Map only a named administrators group from authentik to a pfSense privilege group, and confirm that members of VPN or general user groups cannot sign in to the webConfigurator. Review the group membership list on a schedule, since group drift in the directory changes firewall access without any pfSense change.
Licensing does not change this design
The LDAP provider and outpost used for this integration are part of the open-source edition, so mTLS client certificates and the other enterprise-only features are not needed here. Check the authentik pricing page to confirm which edition your organization uses and whether any feature you rely on is licensed differently. Ask your vendor or DeployOpen to confirm this against your version before purchase decisions are made.
Why pfSense LDAP logins fail after setup
This table pairs each common failure with its likely cause and the check or fix to run first. Work through the rows in order, since a broken bind or base DN hides every later problem. Most failures trace back to the bind account, the search base, or the outpost path, so start there before changing group or MFA settings.
| Symptom | Likely cause | Check or fix |
|---|---|---|
| Bind fails or pfSense rejects the service account | Wrong bind DN, or the service account password was rotated or typed differently in pfSense | Compare the bind DN with the value shown on the authentik LDAP provider and the service account, then re-enter the password in pfSense and save |
| Users cannot be found, so every login is refused | Base DN or user search filter does not match where authentik places users, so the search returns nothing | Confirm the base DN matches the LDAP provider's base DN and that the filter targets user objects; test the search with a directory browser using the same bind account |
| pfSense cannot reach the LDAP endpoint | Outpost host or port is unreachable from the firewall, or a rule on the path blocks the connection | From pfSense, confirm the outpost address and LDAP port are reachable; check firewall rules between pfSense and the outpost host and any network segmentation in between |
| LDAP connection fails only over TLS | pfSense does not trust the certificate presented by the outpost, or the name pfSense connects to does not match the certificate | Import the issuing CA into pfSense's certificate manager, confirm the hostname in the LDAP settings matches the certificate, and check the certificate has not expired |
| Users log in but lack admin or VPN rights | Group membership is not resolving, so pfSense does not map the user to the expected group or privilege | Verify the user is a member of the group in authentik, confirm the group is included in the LDAP provider's group output, and check the pfSense group name matches exactly |
| Login works for some users but MFA codes are rejected | Time drift between the device and the authentik server, or a code reused or outside its validity window | Synchronize server and authenticator clocks with NTP, retry with the current code, and confirm the code is appended to the password in the format the LDAP provider expects |
What teams ask before connecting pfSense to authentik
Is authentik free to use for pfSense LDAP authentication?
The Open Source edition of authentik is free, and the repository places most of its code under the MIT license. The authentik pricing page lists Enterprise at $5 per user per month billed annually, plus $0.02 per external user per month, and Enterprise Plus starting at $20k annually. Before you build, confirm in the pricing and license documents that the LDAP provider you plan to use is available in the edition you choose, because some features are limited to paid editions. Licensing of the software is separate from the cost of the engineering work to configure it.
What drives the effort of a pfSense LDAP integration?
Effort rises with the number of pfSense instances, the complexity of your group design, the TLS setup and how MFA behaves for each login path. Each pfSense instance needs its own LDAP authentication server entry, and each one must be tested for administrator and VPN logins. Group design decides which accounts can reach the webConfigurator and which can connect to VPN, so mapping groups cleanly takes more discussion than the configuration itself. TLS needs a certificate that pfSense trusts, and MFA through a code appended to the bind password needs a clear rule for users and help desk staff.
Can our team set up authentik with pfSense without a partner?
Yes, a team with administration experience in authentik, LDAP and pfSense can follow the authentik pfSense integration guide and build the setup internally. The guide covers the LDAP provider, a service account and an LDAP outpost. The parts most often left to chance are the search base, the group filters, the certificate chain and the lockout behavior after failed code entries. If your team has not run an LDAP outpost before, or has no spare time for testing across pfSense, a fixed-scope engagement can cover planning, build, test and handover in writing.
What do we need to provide before the work starts?
You need network access from the outpost to authentik and from pfSense to the outpost on the LDAP ports you use, plus administrator access to the pfSense instances. A pfSense change window is needed because authentication settings affect logins to the firewall itself, so keep a local administrator account available. You also need named owners for each group that controls admin or VPN access, who can confirm membership rules and approve test accounts. Ask your team to confirm where the authentik server and outpost will run, since that affects latency and firewall rules.
How long does a pfSense LDAP integration take?
The duration depends on the scope agreed in writing, including how many pfSense instances are involved, how many groups need mapping and whether MFA is part of the first release. There is no fixed timeline that applies to every environment, so a quote should state the phases, the test cases and the change windows as part of the written scope. Ask for a plan that separates a lab test from production cutover, since that is where most schedule risk sits.
What goes wrong when MFA is added to the LDAP bind password?
The most common problem is that a password with an appended code works for the first login but fails once the code window passes, or when a client caches the old password. Some pfSense login paths also cache or retry credentials, which can lock accounts faster than expected. Test administrator logins, VPN logins and failed code attempts separately, and confirm how the lockout policy in authentik interacts with those retries before you open access to users. Keep a local emergency account on each pfSense instance.
Does LDAP over pfSense meet our compliance access control requirements?
An LDAP integration can support access control and authentication requirements, but it does not by itself satisfy a specific control. DeployOpen prepares systems, configuration and evidence for compliance assessments, but it does not issue audit reports or certifications, and independent auditors decide whether a control is met. Ask your assessor which evidence they expect, such as group membership records, login logs and change records, and plan to collect them during the build.
Should we use SAML instead of LDAP for pfSense?
Choose the protocol based on what pfSense supports in your version and what your users need. LDAP is the path covered by the authentik pfSense integration guide, and it works with the LDAP provider and outpost. Confirm current pfSense support for SAML or other methods in your release notes before you decide, because the decision affects how MFA is enforced and how groups are passed. Document the choice and the reason in your change record.
Where to confirm the pfSense LDAP steps
The authoritative next read for this topic is the authentik pfSense integration guide, which walks through the LDAP provider, the service account and the LDAP outpost that pfSense binds to. Read it before you change anything on the firewall, and use it as the reference for the order of steps. Pair it with the authentik LDAP provider documentation when you need the provider options in detail, such as the search base, the bind mode and how group membership is exposed to the client. Where the two sources differ, follow the documentation for the authentik release you run and raise the difference with your implementation partner or with authentik.
Confirm the menu paths, field labels and authentication server settings against the pfSense version you run, since pfSense menus and the LDAP authentication server form change between releases. Note the exact pfSense version in your change record, and check the authentik release in your environment against the current release list on GitHub before you copy any value from a guide that may be older. Test the bind password format that carries your code-based MFA in a lab first, because the way pfSense handles the bind credential, and whether a failed bind locks the service account, determines how you troubleshoot later.
Keep a short verification record alongside your configuration: which guide version you followed, which pfSense and authentik versions you tested, and which administrator and VPN test accounts you used. This gives your security or compliance team evidence of what was configured and why, and it gives the next person a clear starting point when an upgrade on either side changes a field name.
How DeployOpen scopes and delivers authentik with pfSense
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including authentik. For pfSense LDAP authentication, we scope the LDAP provider, service account, outpost, groups and MFA design in writing before any configuration changes are made in your environment.
How we scope
- Written scope names the authentik version, the outpost hosting model and the pfSense instances in use.
- Scope lists which pfSense roles, administrators and VPN user groups authenticate through the LDAP outpost.
- Scope records how code-based MFA is carried in the bind password and who approves that design.
How we build
- We create the LDAP provider, service account and search base with least-privilege bind permissions.
- We map authentik groups to pfSense privilege levels and VPN access, and test each group separately.
- We verify TLS settings, bind behavior and failed-login handling against a non-production pfSense instance first.
How we hand over
- Handover includes a configuration record covering provider settings, service account scope and group mappings.
- Runbooks describe how to rotate the service account password and update the MFA bind password format.
- Test evidence shows which accounts log in, which are denied and how lockout and recovery were checked.
How we support
- Post-handover support can be arranged as a retainer covering authentik upgrades and pfSense changes.
- We review the LDAP outpost and authentik release notes before planned upgrades, as part of agreed scope.
- Ask us to confirm response expectations and included upgrade work in the written retainer terms.
