How authentik becomes the sign-in source for self-hosted NetBird
A team running self-hosted NetBird that wants one identity source and group-based access policies can use authentik as an OAuth2/OpenID provider for NetBird. authentik authenticates the users, issues the tokens, and passes group membership to NetBird, so access rules can follow the groups your directory already maintains. The integration follows the NetBird guide in the authentik integrations catalog, which configures an OAuth2/OpenID provider for NetBird. Treat that guide as the starting checklist, then confirm each setting against the NetBird version you deploy.
The work divides across three components. The authentik provider holds the client registration, redirect URIs, scopes and the signing key. NetBird's embedded Dex identity provider receives the OIDC flow from the NetBird dashboard and management service, and it is where you point the external provider settings. The NetBird management API then applies group-based policies to peers. Before you begin, confirm with the NetBird self-hosting quickstart how your release wires the authentik issuer into its configuration, because the redirect URI and issuer must match exactly in both systems. Also decide which authentik groups will map to NetBird access groups, since that mapping drives every later policy.
NetBird's own SSO and MFA support is a feature of the product, separate from whether you self-host it. The NetBird pricing page places SSO and MFA with an enterprise identity provider, along with SCIM provisioning and audit event logging, in the Team tier, so confirm which tier your organization needs before you rely on those capabilities. Self-hosting does not remove the need to check licensing: the NetBird repository uses different licenses for different directories, and you should review the license terms that apply to the components you run.
What you need before configuring the NetBird provider in authentik
Most failed NetBird OIDC setups trace back to a missing prerequisite rather than a wrong setting. Work through these items in order, because the authentik release, the NetBird domain and the group design each shape the provider settings you enter later.
Confirm a supported authentik release
Check the authentik security policy before you plan the upgrade or install. It lists 2026.5.x and 2026.8.x as the lines currently receiving security fixes, and the project announces security releases at least 24 hours in advance. Pick a version on a supported line, and confirm that the NetBird integration guide you follow matches that release, since provider screens and field names can change between versions.
Run a self-hosted NetBird with a public domain
The NetBird self-hosting quickstart needs a Linux VM with at least 1 CPU and 2 GB of memory, a public domain, and Docker with the Compose plugin. The combined configuration runs management, signal, relay and STUN, so the dashboard and API must be reachable at the domain you will register in authentik. Note the exact domain now, because it becomes part of the redirect URIs.
Open the required network ports
Open TCP 80 and 443 for the dashboard, the Traefik reverse proxy and Let's Encrypt certificate issuance, and UDP 3478 for STUN. Test each port from outside your network, not only from the server itself. Blocked ports usually show up as clients that cannot register or relay, which can look like an SSO fault during login testing.
Check DNS and TLS for the dashboard
Confirm that the public name resolves to the NetBird host and that the certificate chain is valid when you open the dashboard in a browser. authentik redirects the browser back to NetBird after sign-in, so a certificate warning or a stale DNS record will break the flow. Check the certificate expiry date and the hostname on the certificate, then repeat the check from a network outside your data center.
Create admin accounts in both systems
You need an administrator in authentik who can create providers, applications, groups and service accounts, and an administrator in NetBird who can change identity provider settings and access policies. Keep a local NetBird admin in the embedded identity provider until the SSO login works end to end, so a misconfigured provider does not lock every administrator out. Record who holds each account and where the credentials are stored.
Design authentik groups before sync
Decide which authentik groups will map to NetBird groups and access policies before you enable sync. Group names in authentik become the basis for NetBird access control, so inconsistent or overly broad groups are hard to undo later. Write down the group names, the members of each group and which NetBird policies each group should drive, and agree that list with the people who approve access.
Confirm redirect URIs and scopes
Do not copy redirect URIs, client settings or scopes from memory or from an older guide. Check them against the current authentik NetBird integration guide and the NetBird documentation for your release, then record the exact values you will enter. Mismatched redirect URIs are a common cause of failed logins, so confirm them before you start the provider configuration.
Configure authentik and NetBird in the order that avoids redirect errors
This sequence connects a self-hosted NetBird instance to authentik so that browser login, device enrolment and API access each work before the next one depends on them. Each step ends with a check you can run before moving on. Confirm every URL, client value and path in your own environment against the NetBird and authentik guides before you start.
Confirm the NetBird deployment and public domain
The platform team confirms that the self-hosted NetBird instance is running on a Linux VM with a public domain, TCP ports 80 and 443 open, UDP port 3478 open and Docker with the Compose plugin installed, as the NetBird self-hosting quickstart describes. Record the exact dashboard URL, because the redirect URI in authentik must match it character for character. Check: the NetBird dashboard loads over HTTPS at that domain, and the certificate is valid. Confirm the domain and any reverse proxy in front of it with your network team before creating anything in authentik.
Create the OAuth2/OpenID provider and application
An authentik administrator creates an OAuth2/OpenID provider and an application bound to it, following the NetBird guide in the authentik integrations catalog. Set the redirect URI to the NetBird dashboard callback path shown in that guide, using your confirmed domain and scheme. Save the client ID and client secret in your secrets store, and note the provider's OpenID discovery URL. Check: the provider and application both appear in authentik, and the redirect URI in the saved provider matches the NetBird callback exactly, with no trailing slash differences.
Enable device authorization on the provider
On the same provider, the administrator enables the device authorization settings that NetBird needs for command-line and device enrolment, using the options named in the NetBird integration guide. Confirm the scopes and client type the guide specifies, because these settings are what the NetBird client uses when a user enrols a device. Check: the provider saves with device authorization enabled, and the settings page shows the values you recorded. No login test is run yet, since NetBird is not yet pointed at this provider.
Point NetBird's identity provider at authentik
The NetBird administrator updates the identity provider section of the self-hosted NetBird configuration to use authentik as an OIDC provider. Enter the issuer or discovery URL from the authentik provider page, the client ID and the client secret, following the NetBird guidance for your release. Restart the NetBird services so the new configuration loads, since a stale configuration is a common cause of login loops. Check: the management service starts without configuration errors in its logs, and the NetBird login page offers authentik as the sign-in method.
Test a browser login to the dashboard
A test user who is assigned to the authentik application opens the NetBird dashboard in a fresh browser session and signs in through authentik. The user should be redirected to authentik, authenticate, and return to the NetBird dashboard without an error page. If the browser reports a redirect URI mismatch, compare the URI in the authentik provider with the callback NetBird sends, and correct only the value that differs. Check: the test user reaches the dashboard, and the user appears in NetBird's user list with the expected identity.
Enrol a device through device authorization
The test user enrols a device with the NetBird client, which starts the device authorization flow, approves the request in the browser through authentik, and completes enrolment. Use a non-production machine first so that any mistake in the device settings stays contained. Check: the device appears as a connected peer in the NetBird dashboard, it is linked to the test user, and it can reach a second peer or the dashboard's peer status shows it online. If enrolment fails after the browser step succeeds, review the device authorization settings from the third step.
Create the management API service account and test it
An authentik administrator creates a service account for NetBird's management API and generates its token, then the NetBird administrator uses that token for automation such as group sync or inventory. Grant the service account only the groups and permissions that NetBird's API documentation requires for the calls you plan to make. Store the token in your secrets store, and make a read-only request such as listing peers using the token. Check: the request returns a successful response and the data matches the peer you enrolled, which confirms the token and the API address are correct before group sync is configured.
Which authentik groups and claims map to NetBird groups and access policies
This table compares each identity element authentik sends to NetBird with the NetBird object it becomes and the access decision it affects. Read it as a checklist to confirm before you enable group sync, because claim names and mapping behavior change between NetBird versions. The main takeaway is that access policies depend on the group names and membership you choose in authentik, so design those names first.
| Identity element | What it maps to in NetBird | What to confirm or decide |
|---|---|---|
| User identity (subject and email claims) | The NetBird user record created or matched at first OIDC sign-in | Confirm which claim NetBird uses as the user identifier in your version, and whether email is required for matching existing users |
| Group membership claim | NetBird groups synchronized from the authentik groups in the token | Confirm the claim name and that group values are included in the ID token or userinfo response for your provider settings |
| Group naming convention | NetBird group names used in access policies and routes | Use a fixed prefix such as netbird- in authentik so only intended groups sync and policy names stay readable |
| Service account for the management API | API access that lets management read or update users and groups | Grant only the permissions needed for group sync, and store its token in a secret manager rather than a config file |
| Access policy rules | Which NetBird groups can reach which peers, routes and exit nodes | Map each authentik group to one policy purpose, and review policies after every group change |
| Removed or disabled users | Users lose sign-in and group membership when authentik no longer lists them | Test deprovisioning in a lab: confirm whether peers are removed, kept or left connected, and how long sessions last |
| NetBird version | Behavior of claims, group sync and API calls | Test on the version you run, currently v0.81.2 or later per the NetBird releases page, and recheck after each upgrade |
Hardening the authentik to NetBird trust relationship
The authentik to NetBird connection is a trust relationship: authentik issues identities that NetBird accepts for admin and user access to your mesh network. The cards below cover the secrets that hold that trust together, how far the API account reaches, where redirects are allowed to go, how MFA is enforced, and how you keep a way back in if authentik is unavailable.
Protect the client secret and API token
The OIDC client secret and the service account token that NetBird uses to call authentik are both credentials that can change who gets access. Store them in a secrets manager or an encrypted configuration store, not in shell history, Compose files committed to Git, or chat threads. Restrict who can read them in authentik and in your NetBird host, and plan a rotation step that updates both sides together. Confirm which values your NetBird configuration file reads at startup so rotation does not leave a stale copy behind.
Scope the API service account
The service account exists so NetBird can read group membership for sync, not so it can administer authentik. Give it a dedicated user, the minimum role needed to read users and groups, and no superuser or flow-editing permissions. Review the token's expiry and who can see it in the authentik admin interface. Illustratively, if the account can change flows or create users, a compromise of the NetBird host would become a compromise of your identity provider, so confirm the permission set against the integration guide before you grant it.
Restrict redirect URIs to the dashboard
In the authentik OAuth2/OIDC provider, list only the exact redirect URI that your NetBird dashboard uses, including scheme, host and path. Avoid wildcards and avoid listing development or staging hostnames on a production provider. Redirect matching is where an attacker would try to receive an authorization response, so a narrow list is the main control here. Recheck the list after every change to the public domain or reverse proxy.
Enforce MFA in authentik
NetBird's own documentation lists SSO and MFA support, but the second factor that matters for this integration is the one authentik enforces before it issues a token. Attach an authenticator stage to the login flow used by the NetBird provider, and decide whether it applies to every user or to administrators only. Check that users who cannot enroll a factor are blocked rather than silently allowed through, and test the flow with a fresh account.
Keep a local admin path
If authentik or its database is down, users who sign in through OIDC cannot reach the NetBird dashboard. Keep at least one local administrator account in NetBird's embedded identity provider, or document another recovery path, and store its credentials offline. Test that the path works before you need it. Confirm with NetBird how the embedded Dex provider and external SSO providers coexist in your version, because the fallback depends on that behavior.
Plan audit logging separately
NetBird's pricing page places SSO and MFA with an enterprise identity provider on the Team tier, and lists audit event logging with SCIM provisioning on that same tier. Those are product features, not a complete audit trail. Decide where authentik's login events, NetBird's activity events and proxy logs are retained, who reviews them, and how long they are kept. Confirm with NetBird which events are exported and whether your plan includes them.
Testing SSO, device login and group sync before users depend on it
Test the full identity path with a pilot group before any production user signs in. Create a small pilot group in authentik, bind it to the NetBird OIDC application, and have each pilot user complete a browser sign-in to the NetBird dashboard. Confirm that the NetBird account is created with the expected email and that group membership arrives in the token claims that NetBird reads for access policies. Then enroll one device through the browser flow, using a setup key only where your policy requires it, and confirm the peer appears in the NetBird admin UI under the right user. Record whether the device registers on the first attempt, because retries often point to redirect URI or device authorization settings that differ from the NetBird quickstart values.
Next, test that access changes follow group changes. Pick one pilot user who currently reaches a test machine through a group-based access policy, remove that user from the authentik group, and confirm that the NetBird access policy no longer allows the connection. Check whether the change needs a fresh sign-in or a token refresh, and note the delay you observe, because your users will experience the same gap. Then test expiry and revocation: disable the pilot user in authentik and confirm that the NetBird session ends and that the peer cannot reconnect. Also confirm that the removal of a user in NetBird does not silently recreate the account on next sign-in. Each step should produce a dated entry with the authentik and NetBird versions, the test user, the expected result and the observed result.
Keep this test log as the regression suite for every upgrade. Check the authentik release you run against the authentik security policy, which lists the supported versions receiving security fixes and says security releases are announced at least 24 hours in advance, so schedule a retest within that window. For authentik feature upgrades, confirm the sequential upgrade rule in the release notes and retest the whole sequence, not only the latest step. For NetBird, repeat the sign-in, device enrollment, group removal and revocation tests after each upgrade, since the management service and dashboard change together. Ask your team to confirm the NetBird release notes and any breaking changes for the version you are moving to before the upgrade window opens.
Common NetBird SSO failures and what buyers ask before hiring help
Why does NetBird show a redirect URI mismatch after connecting authentik?
A redirect URI mismatch means the redirect URI registered on the authentik OAuth2/OpenID provider does not match the callback URL NetBird sends during sign-in. The usual cause is a difference in scheme, hostname, port or trailing slash between your NetBird domain and the value entered in authentik. Compare the redirect URI in the authentik provider with the one NetBird expects for your public domain, then correct whichever side is wrong and retry in a private browser window. Also check that the domain in your NetBird configuration matches the domain users actually open, because a stale domain from an earlier test deployment causes the same error.
What causes a NetBird discovery URL error with authentik?
A discovery URL error usually means NetBird cannot retrieve the OpenID configuration document from the issuer address you supplied. Check that the issuer URL points to the authentik application's OpenID configuration endpoint, that it resolves from the NetBird server, and that the TLS certificate chain is trusted by that host. If NetBird runs in a container, confirm that the container can reach authentik over the network and that its CA bundle includes your private CA when you use one. Fetching the discovery URL with curl from the NetBird host is the fastest way to separate a network or certificate problem from a configuration typo.
Why is the device code not accepted during NetBird login?
A device code is rejected when the device authorization flow is not enabled on the authentik provider, when the client identifier in NetBird does not match the provider, or when the code expired before the user entered it. Confirm that the NetBird provider in authentik uses the device authorization grant, that the device flow settings match what NetBird's documentation expects for your version, and that the verification URL is reachable from the user's browser. Codes are short-lived, so a user who waits before entering one will see a rejection even when the configuration is correct. Retry the enrollment from a fresh code before changing settings.
Why does NetBird group sync stop updating after authentik group changes?
Group sync stops updating when the group claim is missing from the token, when the claim name differs from what NetBird reads, or when the user is not a member of a group included in the scope or mapping. Check the scope definition on the authentik provider, decode a sample ID token to confirm the groups claim is present, and compare the group names with the names used in NetBird access policies, since these comparisons are case sensitive. Also confirm when NetBird refreshes group membership on sign-in, because a user already logged in may keep old group assignments until the next token refresh. Test with a single user and a single group before widening the change.
What does a service account permission denied error mean for NetBird?
A permission denied error from the management API means the service account token is valid but lacks the role or group rights needed for the requested call, such as reading users or groups. Review the authentik user or group that backs the service account, the token's expiry, and the NetBird API access granted to that identity. Keep the service account limited to the calls your sync and automation need, and record which permissions it holds, because a later change to its group membership can silently remove access. Rotate the token through your secret store rather than pasting it into configuration files.
What drives the cost of a NetBird SSO integration with authentik?
The cost is driven by how much of the deployment is new work and how many systems must be confirmed. The main components are the authentik provider and application setup, NetBird configuration and access policy design, the management API service account, group sync testing, and the verification and handover of runbooks. Costs rise with multiple user populations, custom group models, existing sign-in or device posture requirements, and whether authentik and NetBird are already running in production. Costs fall when a clear group model and test users exist before work starts. Ask any provider for a fixed-scope written quote that lists each component separately, and state which items are one-time and which recur, such as upgrades and retainer support.
How long does a NetBird and authentik OIDC integration take?
The duration depends on the number of user groups, whether a self-hosted NetBird and authentik are already running, and how many environments must be tested. No duration is stated in the researched facts for this integration, so ask for a timeline in the written scope rather than relying on a generic figure. A simple single-tenant setup on running infrastructure moves faster than a rollout that adds group sync, device approval policies, and access rules across several teams. Ask for the timeline to show separate phases for design, staging tests, cutover and post-cutover review.
What must our internal team provide before an SSO engagement starts?
Your team should provide a working NetBird deployment or a confirmed plan to deploy it, a running authentik instance with administrator access, the public domain and DNS control for NetBird, and a list of target groups with their intended access. You also need a test user set for each group, a secret store for the service account token, and a named owner who can approve changes to identity and network policy. Confirm where logs will be read and who responds to sign-in failures after go-live, because these answers shape the acceptance tests. A written list of these inputs helps a partner scope the work accurately.
Can our own team set up NetBird SSO with authentik without a partner?
Yes, a capable team can complete the integration in-house if it has administrator access to both platforms, a clear group model, and time to test. The NetBird guide in the authentik integrations catalog and NetBird's self-hosting documentation cover the core settings. Risk rises when the team has not previously run OIDC in production, when device authorization and group sync must work together, or when staff turnover could leave no one who understands the setup. Decide based on who will own the configuration after go-live, and whether that owner can test device login, group changes and API permissions.
Which self-hosting tasks stay with us and which move to NetBird Cloud?
With self-hosted NetBird, your team handles backups, upgrades, scaling, the Linux host, the public domain, and the open ports, as NetBird's self-hosting quickstart states. The quickstart calls for ports 80 and 443 over TCP and 3478 over UDP, and Docker with the Compose plugin. NetBird Cloud is the managed version and needs no servers or domain, so operational duties for infrastructure, patching and backups move to NetBird. Identity responsibilities differ too: a self-hosted deployment can run its embedded Dex provider or connect external SSO, while the cloud plan's SSO and MFA features depend on the plan you choose. Confirm which responsibilities your organization is willing to own before choosing a deployment model.
How a fixed-scope NetBird SSO engagement is defined
A written scope is what turns this integration into a fixed-scope engagement, so it should name every system involved before any work starts. At minimum that means the authentik instance and its version, the NetBird deployment and its version, the OAuth2/OpenID provider and application that NetBird will use, the group model that drives access policies, and the service account used for the management API. It should also state whether the work covers only the identity link or includes the NetBird peers, routes and access policies that depend on it. Ask the provider to list which NetBird groups map to which authentik groups, who approves changes to that mapping, and whether SCIM provisioning or only login is in scope. Those lines decide most of what the quote covers.
The scope should also describe the test plan and the handover. The test plan should cover sign-in for each group, a user outside every group being refused, a removed user losing access, the service account's permissions being limited to what the integration needs, and device enrollment from the platforms your teams actually use. The handover should include the configuration as built, the group mapping table, the steps to rotate the service account credential, and the runbook for upgrades on both sides, since authentik and NetBird release independently. Confirm that the written scope names who receives these documents and in what format.
DeployOpen does not publish prices, and a quote follows from the written scope. Cost depends on how many systems and groups are in scope, how many test cases you require, and whether your environment has existing SSO or network constraints that need discovery. The one-time work is the build, testing and handover. Ongoing support after go-live is available as a retainer, which covers upgrades and changes to group mapping for as long as you need them. Ask for the quote to separate one-time items from recurring retainer items so you can compare it with the cost of keeping this in-house.
Hand over the NetBird SSO setup to operations
This sequence turns a working authentik and NetBird OIDC setup into a documented, monitored and recoverable service that an operations team can run without the people who built it. Each step ends with an artifact that proves it is complete.
Document provider settings and secret locations
The build engineer records every authentik OAuth2/OIDC provider setting used for NetBird, including the client ID, redirect and allowed URIs, the device authorization settings, signing key choice, scopes and the group claim mapping. For each secret, such as the client secret, the management API service account token and the NetBird configuration values, the record names where it lives, who can read it and which system consumes it. Done when an operator who did not build the setup can locate every value and trace it to its consumer from the document alone.
Store secrets in a managed vault
Move the client secret, the service account token and any database credentials out of shell history, chat threads and personal notes into the secret store your organization already operates. Restrict read access to named operator roles and record the access policy beside the provider documentation. Confirm that the self-hosted NetBird configuration file is readable only by the account that runs the containers. Done when a secret read from the vault is the only way the running services receive these values.
Schedule secret rotation and test it
Set a rotation calendar for the OIDC client secret, the management API service account token and the database password, and assign an owner for each. Confirm with NetBird and authentik documentation how a rotated client secret is applied to both sides, and whether a token change requires a restart of the management container. Rehearse one rotation in a non-production copy before the first scheduled change. Done when the rotation runbook has been executed once in a test environment with the expected services reconnecting.
Monitor authentik and NetBird releases
Subscribe the operations mailbox or ticket queue to the authentik and NetBird release feeds on GitHub, and to the authentik security policy so security releases are not missed. Record which authentik release line is supported for security fixes and which NetBird version your deployment runs. Each release notice is triaged against the provider settings document, since OIDC or device authorization behavior can change between versions. Done when a named owner receives both feeds and has logged a first triage of the current versions.
Back up both configurations and the database
Back up the authentik PostgreSQL database, which holds authentik configuration and data except uploaded files, and the NetBird combined configuration and its data store. Store copies outside the host that runs them, encrypt them, and keep the secret store backup separate from the application backups. Confirm the backup frequency and retention with your own policy, since none is set by this guide. Done when a restore of both systems into a test environment has been completed and the NetBird admin login works against the restored data.
Write the lockout runbook
Document how to recover access when the OIDC provider is unavailable, a group sync removes an administrator, or a certificate or client secret expires. Include an emergency local administrator path for both authentik and NetBird, where the product supports one, and state who may invoke it and how the use is logged. Keep the steps specific to the commands, screens and config keys your environment uses. Done when the runbook has been walked through by a second operator who can complete the recovery steps without assistance.
Confirm the handover with operators
Run a joint review in which the build team walks operations through the provider document, the secret inventory, the rotation calendar, the release feeds, the backup restore and the lockout runbook. Record open questions with an owner and a date agreed by your team, and confirm where the documents are maintained. Done when the operations lead signs off that each artifact exists, has an owner and has been tested at least once.
How DeployOpen delivers authentik and NetBird integrations
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, so authentik and NetBird run where your team controls them. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Written scope names the NetBird version, authentik version and hosting model before any configuration begins.
- Scope lists which NetBird groups map to authentik groups and which access policies depend on them.
- Scope states who owns the management API service account, its credentials and rotation after handover.
How we build
- We configure the authentik OAuth2/OpenID provider and application for NetBird, then validate redirect and device authorization settings.
- We wire NetBird's embedded Dex identity provider or external SSO settings to authentik, and test each login path.
- We set up group sync and check that access policies in NetBird match the groups users receive from authentik.
How we hand over
- Handover includes the configuration record, the service account inventory and the group-to-policy mapping in writing.
- Test results cover sign-in, MFA behavior, device enrollment and group membership changes for representative users.
- Runbooks describe backups, upgrade order for authentik and NetBird, and where each setting lives in your environment.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the fixed-scope engagement ends.
- Upgrade planning covers checking supported authentik release lines and NetBird release notes before each change.
- Your team keeps operational ownership, and we document the steps so internal staff can run recovery procedures.
