How authentik signs users in to a Headscale control server
If your team runs Headscale and wants users to sign in with your central identity provider instead of local Headscale accounts, authentik is connected as an OAuth2/OpenID provider for Headscale. The authentik integrations catalog documents this method, and Headscale supports basic OIDC login, so the browser flow sends users to authentik and returns them to Headscale with an identity. Headscale is a self-hosted, open-source implementation of the Tailscale control server, licensed under BSD-3-Clause, which means the integration sits entirely inside infrastructure you operate.
Headscale does a limited amount with what authentik returns. It uses the login to identify the user and updates that user's profile from the identity provider. It does not use OIDC groups in ACLs, and autogroups are only partly supported. Plan access control accordingly: group membership in authentik will not by itself restrict which nodes can reach which resources. Confirm the current ACL and autogroup behavior against the Headscale features documentation for the version you deploy, since the project publishes separate stable and development documentation.
Before you build, decide who is allowed to register nodes, which email domains or user groups may sign in, and whether your team will manage user identities in authentik or in Headscale. Also confirm which Headscale release you will run. The project's releases page lists the latest version, and the Headscale README advises against running Headscale behind reverse proxies or in containers, so check that your hosting layout follows that guidance before you wire up the redirect URL.
What you need in place before configuring Headscale and authentik
Three components have to be ready before any OIDC settings are touched: a supported authentik release on PostgreSQL, a Headscale version you have verified, and a public HTTPS name that both browsers and nodes can reach. Confirm each item in your own environment first, because a gap in any one of them shows up later as a login loop or a failed node registration.
Headscale version to deploy
The latest Headscale release noted for this guide is v0.29.5, published October 13, 2026. Pin the exact version you test with, then read its release notes for changes to OIDC settings, configuration keys and database behavior before you copy any example config. Earlier point releases were published on September 23, 2026 and July 29, 2026, so check which one your team has already validated. Record the version in your change ticket so later upgrades start from a known state.
Supported authentik release line
Run an authentik release from a line that still receives security fixes. The security policy lists 2026.5.x and 2026.8.x as supported, and the project announces security releases at least 24 hours in advance, so plan a maintenance window for that notice. Confirm the release you deploy against the current security policy and the authentik upgrade notes before you start, since OIDC provider behavior can change between releases.
Running authentik with PostgreSQL
authentik needs a server container, a worker container and PostgreSQL, which holds all configuration and data except uploaded files. Confirm that the instance you will use for Headscale is reachable, that the worker is running, and that you can sign in to the admin interface as a user who can create providers and applications. For production, use a separately managed PostgreSQL rather than the database bundled with a test Helm chart. Note that authentik no longer uses Redis, so do not plan around a Redis dependency.
Public HTTPS hostnames
Plan two distinct names: one for authentik, which browsers reach to sign in, and one for Headscale, which nodes and browsers reach over HTTPS to register. The Headscale server URL must be the address clients will use, so it cannot be a private name that only your office resolves. Confirm DNS records, certificate validity and that the issuer URL in the OIDC settings matches the authentik hostname exactly, including the trailing path.
Reverse proxy and container caveat
The Headscale README states that the project does not support or encourage running Headscale behind reverse proxies or in containers. Your layout may still need a proxy for TLS termination, so treat this as a risk to assess, not a detail to skip. Check the current Headscale documentation for your exact topology, record the decision and its owner, and test node registration from outside your network before you rely on the setup.
Test users and groups in authentik
Before you configure Headscale, create a small set of test users in authentik with known group memberships, and confirm which claims your OIDC provider returns. Headscale updates user profiles from the identity provider, but OIDC groups cannot be used in ACLs, so group membership will not control tailnet policy in this setup. Decide how you will separate access in the policy file instead, and confirm that those accounts can complete a sign-in before you involve real staff.
Configure the authentik provider and Headscale OIDC settings in order
This sequence creates the authentik OAuth2/OpenID provider and application for Headscale, transfers the client credentials into the Headscale configuration, enables basic OIDC login, and confirms a first browser sign-in works end to end.
Confirm the Headscale server and URLs
Before touching authentik, fix the public URL where Headscale will be reached, the URL authentik will redirect users back to, and the issuer URL that Headscale will use to find authentik. Check the Headscale version you plan to run against the project's release notes, since the most recent published release is v0.29.5. Your team owns this step because the URLs must match DNS and TLS certificates you control. Headscale's own documentation says it is not supported behind reverse proxies or in containers, so confirm your hosting approach against the Headscale README before you proceed. You are done when you have written down the server URL, the redirect URI and the issuer URL, and each one resolves over HTTPS from the client network.
Create the OAuth2/OpenID provider in authentik
In the authentik admin interface, create an OAuth2/OpenID provider following the authentik Headscale integration guide. Set the redirect URI to the callback address Headscale expects, choose the signing key and the scopes the guide specifies, and bind the provider to an application. Your team performs this step in authentik, and it is done when the provider and application both appear in the admin interface and the provider page shows the client ID and client secret.
Copy the client ID, secret and redirect URI
Copy the client ID, client secret and the exact redirect URI from the authentik provider page into a secure secret store, not into a shared document. Compare the redirect URI character by character with the value Headscale will use, including the scheme, host, port and path, because a single mismatch causes the login to fail at the callback. Your team handles this step. It is done when the three values are stored in your secret manager and you can show that the redirect URI matches the Headscale server URL you recorded earlier.
Set the OIDC issuer and credentials in Headscale
Edit the Headscale configuration file to enable the OIDC section, then set the issuer URL pointing at the authentik application for Headscale, along with the client ID and client secret. Load the client secret from your secret store or an environment variable rather than writing it in plain text where others can read the file. Confirm the key names against the current Headscale configuration reference for your release. The step is complete when the configuration validates and Headscale starts without errors in its log.
Enable basic OIDC login
Keep the first configuration to basic OIDC login. Headscale supports basic OIDC login and updates user profiles from the identity provider, but OIDC groups cannot be used in ACLs in the current feature set, so do not plan group-based access at this stage. Restart or reload Headscale using your normal service process, then request the Headscale login endpoint from a browser. The step is done when the request returns a redirect to the authentik sign-in page rather than an error.
Test the first browser login
Sign in with a test user that belongs to the authentik application. Complete authentication in authentik, allow the redirect back to Headscale, and watch the Headscale log for the callback. Check that the user appears in Headscale with the name and profile fields supplied by authentik. The step is done when the browser shows a successful login result and the user record is present and current in Headscale.
Record the working configuration for upgrades
Store the working configuration, the authentik provider settings and the test results in your change record, with the Headscale and authentik versions you tested. Note which settings you will need to recheck on each Headscale or authentik upgrade, particularly the redirect URI and the OIDC section. Your team owns this record. It is done when another engineer could repeat the login test from the record alone.
How user identity and profile data map into Headscale
Headscale takes its user identity from the OIDC login, and it cannot write access rules against OIDC groups. When a user signs in through authentik, Headscale reads the identity the provider returns and uses it to create or match a Headscale user, then updates that user's profile from the provider on later logins. Access decisions therefore have to rest on Headscale users and tags, not on the group memberships authentik holds. Before you write any ACL, confirm in the current Headscale OIDC documentation which claims Headscale reads, which claim serves as the stable user identifier, and whether profile fields such as name or email are refreshed on every login. Changing the claim used for identity after users have registered can create duplicate or orphaned Headscale users, so settle this before the first production login.
Plan the access model around that constraint. Group membership in authentik can still decide who is allowed to sign in to Headscale at all, because the OIDC settings in this integration can restrict login by group and domain, but it does not carry through into the tailnet's policy. Autogroups are only partly supported, so do not build rules that depend on them for critical access. A practical approach is to map each team to a set of Headscale users and apply tags to nodes that carry a role, such as servers or subnet routers, then write the ACL against those users and tags. Confirm with the Headscale features page which autogroups and grants work in your target version before you commit to a design.
Test the mapping with a small set of accounts before onboarding the wider organization. Sign in with a user from each group, check the Headscale user list for the expected name and identifier, change a profile attribute in authentik and confirm whether it propagates on the next login, and verify that a user outside the allowed groups is refused. Record the result for each case. Because Headscale's documentation is published separately for stable and development versions, check the version you run against the matching documentation set, since claim handling is the kind of detail that changes between releases.
Mapping authentik claims and groups to Headscale users and policy
This table compares what authentik can send to Headscale during OIDC login with what Headscale can do with it. Supported items affect how users appear and sign in, while items marked as not supported cannot drive access rules. Confirm each row against the Headscale version you run before you design access policy around it.
| Mapping | What authentik sends or controls | Status in Headscale |
|---|---|---|
| Basic OIDC login | Authorization code flow to the Headscale callback using the provider client ID and secret | Supported, the documented basic OIDC login path |
| Profile updates | Name and email claims read at login, used to refresh the Headscale user profile | Supported, profiles update from the identity provider on login |
| Username or email as user identity | Claim chosen as the identifier that Headscale maps to a user name | Confirm in your version which claim Headscale uses and whether changes in authentik rename existing users |
| Group membership in ACLs | Groups claim sent in the ID token or userinfo response | Not supported, OIDC groups cannot be referenced in ACL rules |
| Application assignment | Access to the authentik application and its bindings for the Headscale provider | Enforced in authentik before login, not visible to Headscale policy |
| Autogroups | Not controlled from authentik claims | Partly supported, confirm which autogroups behave as expected in your release |
| Access decisions and ACLs | Decisions made from authentik policy bindings and groups | Written as Headscale ACLs or grants with user, tag or host selectors, not group claims |
| Tags and node ownership | Not sent by authentik | Assigned on the Headscale side with tags, confirm the tagging workflow for your team |
Securing the login and the control server
Two components need protection here: the authentik login that issues identities, and the Headscale control server that exchanges WireGuard public keys, assigns client addresses and sets the boundaries between users. A weak point in either one affects every node on the tailnet. The cards below cover the checks to make before and after go-live.
Serve everything over HTTPS
Both the authentik endpoint and the Headscale server URL should use HTTPS with certificates your team controls and renews. The OIDC redirect back to Headscale and the token exchange depend on it, and clients will refuse to register against a control server they cannot reach securely. Confirm the public Headscale URL in the client configuration matches the one you published, including the port.
Match redirect URIs exactly
The redirect URI registered on the authentik OAuth2/OIDC provider must match the Headscale callback address character for character, including scheme, host, port and path. A trailing slash or a mismatched hostname produces login failures that look like identity errors. Treat any wildcard or extra redirect entry as a deliberate exception that someone reviews.
Store the client secret outside config files
The OIDC client secret lets Headscale exchange authorization codes for tokens, so anyone holding it can impersonate the relying party. Keep it in a secrets store or an environment variable supplied at runtime, restrict read access to the Headscale service account, and rotate it through authentik when staff with access leave. Avoid pasting it into shared tickets or chat.
Limit access to intended groups
Bind the authentik application to a policy or group so that only the users who should join the tailnet can start the OIDC flow. Headscale's current OIDC support does not use groups in ACLs, so this authentik-side restriction is the main gate on who can sign in. Test with one user outside the group to confirm the denial.
Enforce MFA in authentik
Require a second factor in the authentik authentication flow for the application, not only in the Headscale client. Because Headscale relies on the identity provider for the login, the strength of the MFA policy determines who can register a device. Review which factors your authentik edition and flow permit, and confirm enrollment and recovery paths cannot bypass the check.
Protect the Headscale host itself
Headscale controls node registration, IP assignment and user boundaries, so compromise of the server can add rogue nodes or reshape access. Harden the host, limit administrative access, back up the database and keys, and restrict who can reach its management interface. The Headscale README says it does not support running behind reverse proxies or in containers, so confirm your hosting design against that guidance before production.
Keep an admin path during IdP outages
If authentik is unavailable, existing nodes keep working, but new registrations and re-authentication may fail. Plan a documented administrative route, such as a local Headscale command-line workflow using pre-authenticated keys held by named operators, so the tailnet can still be managed. Test that route before you need it and store its credentials under the same controls as the client secret.
Common failures when Headscale login with authentik does not work
This table pairs each common failure in authentik and Headscale OIDC sign-in with its likely cause, the fix to try first, and the log to check. Work through the rows in order, since a redirect or issuer error hides later problems. The main takeaway is that most failures sit in URL and trust settings, and that OIDC groups do not restrict Headscale ACLs.
| Failure | Likely cause | Fix and where to look |
|---|---|---|
| Redirect URI mismatch after clicking sign in | The callback URL registered in the authentik OAuth2/OpenID provider does not exactly match the Headscale server URL and callback path in its OIDC settings. | Copy the callback URL from the Headscale OIDC configuration into the authentik provider, matching scheme, host, port and trailing slash. Check the authentik provider and browser error page. |
| Wrong issuer URL or discovery failure | The issuer value points to the authentik application page, a different slug, or an HTTP address, so Headscale cannot load the OpenID configuration. | Set the issuer to the exact issuer URL shown on the authentik provider and confirm it returns a discovery document in a browser. Check Headscale startup logs for OIDC discovery errors. |
| Client ID or client secret rejected | The secret was rotated in authentik or copied with extra whitespace, or the client type does not match the Headscale configuration. | Re-copy the client ID and secret from the authentik provider, store them in the Headscale configuration without trailing spaces, and restart Headscale. Check the authentik event log for failed token requests. |
| TLS certificate not trusted | Headscale or the browser does not trust the certificate chain of the authentik or Headscale hostname, often because the chain is private or incomplete. | Install the internal CA on the Headscale host and client devices, or serve a complete chain. Confirm with a command-line TLS check before retrying login. Check Headscale logs for x509 errors. |
| Login works but users cannot reach Headscale | An authentik application binding or policy denies the user, so the authorization step never completes for that account. | Review the policy bindings on the authentik application and confirm the test user passes them. Check the authentik event log for policy denials tied to the application. |
| Node registration fails after browser login | Headscale is behind a reverse proxy or inside a container the Headscale README does not support, so callbacks or the node registration URL resolve to the wrong address. | Run Headscale on a host with a direct, correctly configured server URL where possible, or confirm your proxy setup is supported. Check the server URL in the Headscale configuration and the Headscale logs during registration. |
| Expecting OIDC groups to restrict ACLs | Headscale does not support OIDC groups in ACLs, so group claims from authentik do not limit which nodes can reach which resources. | Plan access with Headscale ACLs and grants that reference supported identities, and treat authentik groups as a sign-in gate only. Confirm the current group support in the Headscale features documentation before designing access. |
| Profile details or user names look stale | Headscale updates user profiles from the identity provider at login, so changes in authentik appear only after the user signs in again. | Ask the user to sign out and sign in, then confirm the claim values sent by authentik. Check the authentik user attributes and scope configuration. |
Questions teams ask before connecting Headscale to authentik
How much effort does connecting Headscale to authentik take?
The effort depends mostly on three things: how well your team already knows authentik and Headscale, how your network is laid out, and how many groups you need to control access. A team that has run both before can usually work from the configuration steps directly. A team new to either product should expect to spend most of the time on the OIDC provider settings, the redirect URLs and the test login path, since those are where first attempts tend to fail. Ask any partner to break the quote into provider configuration, Headscale configuration, group and domain rules, node registration testing and handover documentation.
How long does the integration take?
Duration follows scope. A single OIDC sign-in with one group and one email domain on a test Headscale instance is a much smaller job than a production rollout with several groups, a staged user migration and a documented rollback. Timing also depends on how quickly your team can provide a stable hostname, a valid certificate, admin access to both systems and a set of test users. Ask for a timeline tied to a written scope, and check which steps depend on your own change windows or approvals.
What does our team need to supply before the work starts?
Plan to provide a public hostname for the Headscale server that clients can reach, a certificate that browsers and Tailscale clients trust, administrative access to the authentik instance and to the Headscale host, and a small group of test users with different group memberships. You will also need the names of the groups and email domains that should be allowed to join the tailnet. Confirm with the Headscale documentation how your chosen version expects the server URL and OIDC settings to be written before you request access, because mismatches in those values are a common cause of delayed testing.
Can our own team do this integration without a partner?
Yes, if you have people comfortable with OIDC clients, reverse proxies or certificate handling, and with editing Headscale's configuration file. The integration itself is not a large build. The risks sit in access control: a wrong group or domain rule can let the wrong people join the network, and a wrong redirect URL can lock everyone out. Teams that build internally usually benefit from a written test plan that covers allowed users, denied users and a node registration from a browser. A partner is useful when the team lacks time, when the network design is complex, or when the result must be documented for an audit.
Do we need authentik Enterprise for this integration?
The supplied pricing page lists Enterprise-only features such as Google Workspace and Microsoft Entra ID integrations, mTLS client certificate authentication and enhanced audit logging, but it does not state that a Headscale OIDC login depends on any of them. Confirm this against the current authentik documentation and your own requirements before buying a license. Check especially whether you need audit logging for access reviews, whether your identity source is one of the Enterprise integrations, and whether the open-source edition meets your support expectations.
Does the Headscale OIDC login control which devices or users can reach which networks?
Not fully. Headscale supports basic OIDC login and updates user profiles from the identity provider, but OIDC groups cannot be used in ACLs, and autogroups are only partly supported. That means group membership in authentik can decide who is allowed to sign in, while fine-grained access between nodes must be defined in Headscale's own policy. Plan your access model with this limit in mind, and verify it against the Headscale feature documentation for the version you deploy.
What is the main operational risk after go-live?
The main risk is a change on either side that silently breaks sign-in or changes who can join. Upgrades to authentik or Headscale, certificate renewals, changes to the hostname and edits to group names in authentik can all stop registrations. Keep a documented procedure for rotating the OIDC client secret, renewing certificates and testing login after each upgrade. Headscale's releases are published separately, so review them before updating, and make sure someone owns the check after every change.
How DeployOpen scopes and delivers the Headscale and authentik integration
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and that includes wiring authentik to a Headscale control server over OIDC. Each engagement starts from a written scope that sets out the authentik and Headscale versions, the groups and domains allowed to sign in, and the nodes that must register through the browser.
How we scope
- We confirm the Headscale and authentik versions, hosting model and reverse proxy arrangement before any configuration is written.
- We agree which users, groups and email domains may sign in, and how node registration access will be limited.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before work starts.
How we build
- We configure the authentik OAuth2/OIDC provider and application for Headscale, then set the matching Headscale OIDC settings in your environment.
- We test sign-in, profile updates and node registration through the browser with accounts from each permitted group and a denied account.
- We check that the ACL policy references only identities Headscale can actually use, since OIDC groups cannot be used in ACLs.
How we hand over
- You receive written configuration records for authentik, Headscale and the redirect and callback settings, kept in your own systems.
- We document the node registration steps and the known limits of the integration so your operators can repeat them.
- We walk your platform and security teams through the test results and the upgrade checks they will run themselves.
How we support
- Ongoing support, version upgrades and continuous testing are available as a retainer after handover.
- Retainer work can cover planned Headscale and authentik upgrades, with checks on sign-in and registration after each change.
- Confirm with us in the quote which support hours, response expectations and upgrade reviews the retainer includes.
