How authentik signs Tailscale users in over OIDC
Your team wants tailnet sign-in governed by your own identity provider, so that joining the tailnet, and leaving it, follows the same account lifecycle as your other applications. The supported route is a custom OIDC provider on the authentik side, following the authentik Tailscale integration guide. That guide requires a WebFinger endpoint at /.well-known/webfinger on the domain of the administrator's email address, because Tailscale uses that domain to discover which identity provider handles a given user. Before any other work, confirm which domain your administrator accounts use, who controls DNS and web hosting for it, and whether that host can serve the endpoint over HTTPS.
At a high level, a user enters their work email in the Tailscale login page. Tailscale resolves the domain through WebFinger, redirects the browser to the authentik OIDC provider, and authentik authenticates the user with whatever flow and MFA stages you have configured. The identity Tailscale receives back determines the user's tailnet identity. This page covers both sides together: the authentik provider, application, scopes and claims, and the Tailscale admin console settings that accept them. Plan the two sides as one change, because a mismatch in the issuer URL, redirect URI or email domain will stop sign-in for every user at once.
Two things need an owner before you start. First, the people who will change Tailscale settings need an admin role there, and API tokens used for automation are created on the Keys page by Owners, Admins, IT admins or Network admins, expire after 1 to 90 days, and should be scheduled for renewal. Second, you need a plan for users who already sign in with another identity provider, since an existing Tailscale account is tied to the login method it was created with. Confirm with Tailscale how its current login method switch works for your tailnet plan, and test that path with a non-administrator account before moving the wider user base.
What you need before configuring the tailnet
Four things have to be in place before any Tailscale setting changes: a supported authentik release, a Tailscale plan that covers the features you need, admin rights on the tailnet, and a public HTTPS domain that matches your administrator's email address. The cards below cover each one, plus the Keys page for teams that automate the setup.
Supported authentik version
Run an authentik release that is still in its supported window. The security policy lists 2026.5.x and 2026.8.x as the lines receiving security fixes, and the project announces security releases at least 24 hours in advance. Confirm the exact version against the release list before you start, and plan the upgrade path first if your instance is older. Changing the OIDC provider on an outdated instance adds a second moving part to troubleshoot.
Tailscale plan for in-scope features
Pick the plan before you design the identity flow. Per Tailscale's pricing page, SCIM provisioning starts at Standard, and network flow logs and log streaming require Premium. ACL groups are capped at 3 on Personal, 10 on Standard and 300 on Premium, so a larger group model may force a plan change. Ask Tailscale to confirm current plan limits and whether your user count fits the Personal tier.
Admin roles on the tailnet
The person making changes needs an role that can edit identity and access settings. Tailscale API tokens can only be created by Owners, Admins, IT admins and Network admins, so an ordinary user account will not be enough for the setup or for automation. Keep at least two people with an administrative role so a single lockout does not leave the tailnet unmanaged. Record who holds each role before the cutover.
Public HTTPS domain for WebFinger
Tailscale needs to find your identity provider from the administrator's email address, so authentik must answer a WebFinger request at /.well-known/webfinger on the domain of that address. The endpoint has to be reachable over public HTTPS with a certificate that clients trust. Confirm that the domain in your administrator email matches the domain you host, and that your reverse proxy forwards that path to authentik without a redirect.
Keys page for API tokens
Create API access tokens on the Keys page of the Tailscale admin console only if you automate the configuration, for example with the Terraform provider. Tokens expire after 1 to 90 days, so choose the shortest lifetime your pipeline can tolerate and set a renewal owner. Store the token in your secrets manager, never in the repository that holds the Terraform code.
Configuration sequence for authentik and Tailscale
This sequence takes a tailnet from its current login method to authentik as a custom OIDC identity provider, with each step checked before the next one starts. The result is a tested sign-in path that reaches every user only after a non-admin account has completed a login.
Publish the WebFinger endpoint on your domain
Tailscale needs to find your identity provider from the domain in the administrator's email address, so the first change is a WebFinger document served at /.well-known/webfinger on that domain. Your web or DNS team publishes it, pointing the issuer to your authentik OAuth2/OpenID provider. Check it by requesting the endpoint over HTTPS from outside your network and confirming that the response is valid JSON that names the correct authentik issuer. Do not continue until that response is consistent from a browser and from a command-line client.
Create the OAuth2/OpenID provider in authentik
In authentik, create an OAuth2/OpenID provider and an application that uses it, following the Tailscale guide in the authentik integrations catalog. Your identity administrator sets the client type, redirect URI, signing key and scopes as that guide describes, and records the client ID and client secret in a secrets store. Confirm the result by opening the provider's OpenID configuration document from authentik and checking that the issuer, authorization and token endpoints match what you published in WebFinger.
Register the OIDC settings in Tailscale
In the Tailscale admin console, an Owner or Admin enters the custom OIDC configuration using the issuer, client ID and client secret from authentik, and the redirect URI displayed by Tailscale must match the one registered in the authentik provider. Keep the existing login method active until the test in a later step passes, so a misconfiguration does not lock out administrators. The check is that the admin console saves the configuration without an error and that the tailnet reports the new identity provider as configured.
Map identity claims and scopes
Decide which claims Tailscale uses to identify users, typically the verified email address, and confirm that authentik releases that claim and the scopes Tailscale requests. Also decide how group membership will be expressed, because group-based ACL rules depend on the claims your tailnet can read and on the ACL group limits of your Tailscale plan. Check the claims by decoding an ID token from a test login and confirming that the email, verification flag and any group values appear exactly as expected. Record the mapping so that later changes to authentik attributes do not silently alter access.
Test sign-in with a non-admin account
Create or pick a standard user in authentik who is not an administrator of the tailnet and sign in to Tailscale through the new OIDC path from a clean browser session. Confirm that the user lands on the correct tailnet, that the device they register appears in the admin console, and that the ACL rules you expect apply to them. Also test a denied case, such as an account outside the allowed domain or group, and confirm it cannot join. Keep at least one existing administrator session open throughout the test so you retain a recovery path.
Enable the policy for all users
After the non-admin tests pass, switch the tailnet to the authentik sign-in policy for all users and communicate the change to the people who must re-authenticate. Confirm the change by repeating the sign-in test for two or three users from different groups and checking the admin console's user list for the expected identity source. Then review the existing login method and decide with your identity team whether to retire it, noting that removing it removes your fallback path.
Choosing between a new tailnet and an existing one
A tailnet that already has users and devices carries state you cannot simply discard. Each enrolled device is tied to the identity that registered it, so changing the sign-in path affects how people authenticate and may affect how their devices are recognized. Plan the cutover so that existing owners can still reach the admin console during the change. Confirm with Tailscale's documentation how device ownership behaves when a user's identity source changes, because that determines whether re-enrollment is needed.
- Device ownership: confirm whether devices stay attached to the same user record after authentik becomes the identity provider, or whether users must re-register them.
- Admin access: keep at least one owner account that does not depend on the new OIDC login until the cutover is verified.
- Active sessions: expect users to sign in again and plan for devices that need to reconnect.
- Change window: agree a window with the people who use the network, since an identity change affects every user at once.
Before choosing an approach, count the affected users and devices and ask Tailscale which changes take effect on each device.
A new tailnet built for authentik begins with no legacy identities or device registrations. You can define users, groups and the ACL policy against the authentik identity model before anyone joins, then test sign-in with a small pilot group. The trade-off is that people and devices must move onto the new tailnet deliberately, and the old tailnet stays in service until they do. This path suits a network that is small enough to rebuild or one where the current setup already causes operational friction.
- Clean policy design: write access rules around groups from authentik before the first device joins.
- Pilot before rollout: enroll a small group of administrators and test sign-in, access revocation and device reconnection.
- Parallel operation: keep the old tailnet running until every workload that depends on it has moved.
- Automation from day one: define the policy and tags as code, for example with the Tailscale Terraform provider, so later changes are reviewed.
Before you start, list the subnet routes and devices that must be rebuilt, and decide how long the two tailnets will run side by side.
Tailscale's plan tiers decide which identity and visibility features you can use. Per the Tailscale pricing page, Personal is free for up to 6 users, Standard costs $8 per user per month, Premium costs $18 per user per month, and Enterprise is custom priced. SCIM provisioning starts at Standard, while network flow logs and log streaming require Premium. ACL groups are capped at 3 on Personal, 10 on Standard and 300 on Premium, so a larger group structure can force a tier change.
- Personal: free for up to 6 users, with ACL groups capped at 3.
- Standard: $8 per user per month, adds SCIM provisioning and MDM, EDR and XDR posture integrations.
- Premium: $18 per user per month, adds log streaming, network flow logs and just-in-time access, with up to 300 ACL groups.
- Tagged resources: 50 are included, and extra tagged resources cost $1 per month each, so count servers and routers before choosing a tier.
- Session recording: SSH, Kubernetes and database session recording is sold as a PAM platform extension through sales.
Ask Tailscale for a quote that lists your user count, tagged resources and any extensions, and confirm current tier limits on the Tailscale pricing page before you commit.
An existing ACL policy often names users by email address or group. When the identity source changes, those strings may no longer match what authentik sends, and rules can silently stop applying as intended. A new tailnet avoids most of this because the policy is written against the new source from the start. An existing tailnet needs a reference audit before cutover, including every rule that names a user or group.
- Identity strings: rules that name users by email address need review if the identity source or email domain changes.
- Group names: groups delivered from authentik must match the names in the policy exactly, and they count against the tier's ACL group limit.
- Tags: tags are assigned to devices rather than to people, so they can carry over, but confirm how tagged devices are owned after the change.
- Policy as code: keep the ACL policy in version control and apply it through automation so broken references appear in review before cutover.
Export the current policy, list every user and group reference, and test each one against the new identity source before you move anyone.
How authentik claims map to tailnet users and groups
This table compares the identity attributes authentik can pass to Tailscale with the tailnet concepts they feed, and notes where plan limits decide whether group-based access is available. Read it before designing your ACL policy, because the group caps on each plan shape how many groups you can use. Confirm the exact claim names in the current authentik Tailscale guide before you configure the provider.
| Identity attribute | Tailnet concept it feeds | What to confirm or check |
|---|---|---|
| User email | Tailnet user identity and the domain match used during sign-in | Confirm the email claim name in the authentik guide; the WebFinger domain must match the administrator's email domain |
| Display name | User name shown in the Tailscale admin console | Confirm the claim name and whether it is populated for all source directories you use |
| Groups | Group membership referenced in ACL policy rules | Confirm the claim name and format; group-based ACLs depend on the plan and its group cap |
| ACL groups on Personal | Maximum of 3 ACL groups per tailnet | Plan limit from Tailscale pricing; map only the groups you need for access rules |
| ACL groups on Standard | Maximum of 10 ACL groups per tailnet | Plan limit from Tailscale pricing; plan the group model before rollout |
| ACL groups on Premium | Maximum of 300 ACL groups per tailnet | Plan limit from Tailscale pricing; check current limits before large directory mappings |
| Group-based ACLs on Personal | Limited to 3 groups, which may not cover per-team access | Confirm with Tailscale whether your tailnet plan meets your group model |
| Claims not mapped to a tailnet concept | No effect on ACL rules until mapped in policy | Test with a pilot user and inspect the resulting user and group membership in the admin console |
Moving users from another IdP without locking out admins
The most important decision in this move is that at least one Owner account stays able to sign in through the original login path until every admin has proven the authentik login works. Switching the tailnet's identity provider changes how people authenticate, and a mistake in the OIDC settings can leave no one able to change the ACL policy or the admin console. Before you touch the identity provider, record which accounts hold the Owner, Admin, IT admin and Network admin roles, confirm each one can sign in through the current provider, and keep that path active for the whole cutover window.
Match users by verified email, not by display name or username. The authentik Tailscale guide requires a WebFinger endpoint on the domain of the administrator's email address, so the domain you publish and the domain on each user's account must agree. Export the current user list, compare it with the authentik users you have created or imported, and resolve mismatches (aliases, changed surnames, shared mailboxes) before cutover. Group membership is the other part of identity you must carry over: create the groups in authentik and confirm the names the OIDC claims will send, because ACL rules written against groups will fail silently if the names differ.
Stage the change with a small test group first, and make the group mapping a prerequisite for ACL changes rather than a follow-up. Move a few non-admin test users, confirm their sign-in, device access and the ACL outcomes they are meant to receive, then widen the group. Confirm in the Tailscale documentation for your plan how existing users re-authenticate, whether devices must re-register, and what happens to devices already in the tailnet, because these behaviors determine how long the cutover takes and who must act. Do not assume they match the behavior described for other plans or for Headscale.
Hardening the authentik to Tailscale trust path
Once authentik signs users in to your tailnet, its security depends on who can sign in, how the WebFinger domain and TLS certificate are protected, and how Tailscale administrators and API tokens are managed. The cards below cover the controls to apply and the checks to run before you rely on the integration for network access.
Restrict the OIDC application to intended groups
Bind the authentik application to a policy or group that contains only the people who should join the tailnet, rather than every authentik user. Review who is in that group on a schedule, because anyone who can authenticate to the application can sign in to Tailscale. Confirm in your own environment that removing a user from the group ends their next sign-in, and decide how long existing device sessions should remain valid after offboarding.
Enforce MFA for administrators
Require a second factor for every authentik account that can administer the tailnet, and consider applying the same requirement to all members of the tailnet group. Authorization flows in authentik can be scoped so the stronger policy applies to the administrator group only. Test the enrollment path for new administrators, since a user who cannot complete MFA setup should not be able to reach the Tailscale login.
Protect the WebFinger domain and TLS certificate
The WebFinger endpoint at /.well-known/webfinger on your email domain is publicly reachable by design, so it must be served over valid TLS from infrastructure you control. Whoever controls that domain or its certificate can redirect the sign-in flow, so restrict DNS and certificate management to a small team, monitor certificate expiry, and log changes to the reverse proxy that serves the endpoint.
Scope Tailscale API tokens tightly
API access tokens are created on the Keys page of the admin console and expire after between 1 and 90 days. Choose the shortest expiry your automation can tolerate, and create tokens only for accounts holding the Owner, Admin, IT admin or Network admin role. Record which token drives which automation, such as Terraform, and rotate it before expiry rather than letting it lapse mid-change.
Keep a recovery owner account
Keep at least one Tailscale Owner account that does not depend on the authentik application being available, so an authentik outage, misconfiguration or lockout cannot prevent access to the admin console. Store its credentials and any recovery method under your normal emergency access controls, test that it still signs in after changes to the OIDC settings, and review it whenever administrator membership changes.
Check group-based ACLs against your control server
If you compare Tailscale with a self-hosted control server, note that Headscale does not support OIDC groups in its ACLs, so group-based access rules from authentik cannot be enforced there in the same way. Confirm which access model your team needs before choosing a platform, and test one group-based rule end to end on Tailscale before writing the policy for production.
Common failures in the authentik and Tailscale login path
This table lists the failures most likely to block sign-in to a tailnet through authentik, with the probable cause, the check to run and the fix for each. Work down the rows in the order a login travels: discovery, redirect, identity, claims, then the switch from another identity provider.
| Failure | Likely cause | Check and fix |
|---|---|---|
| WebFinger returns the wrong document | The /.well-known/webfinger response on the administrator's email domain points to a different issuer or is missing the expected link relation | Request the WebFinger URL with curl and confirm the JSON names the authentik issuer for this tailnet. Correct the reverse proxy or static route for that domain, then retry sign-in. |
| WebFinger fails TLS | The domain serves an expired, self-signed or incomplete certificate chain, or redirects WebFinger to plain HTTP | Check the certificate chain and expiry from outside your network. Install the full chain on the proxy serving that domain and remove any HTTP redirect on the WebFinger path. |
| Redirect URI mismatch | The redirect URI registered in the authentik OAuth2/OIDC provider does not exactly match the callback Tailscale sends, including scheme, host and trailing slash | Compare the registered redirect URI with the value shown in the Tailscale setup and with the authentik provider settings. Edit the provider so the strings match exactly, then retry. |
| Email domain does not match the WebFinger domain | The user signs in with an address on a domain that has no WebFinger record, so Tailscale cannot find the identity provider | Confirm each user's email domain against the domain that serves WebFinger. Either publish the record for that domain or ask the user to use the domain the tailnet expects. |
| Group claims missing, so ACLs deny access | The authentik provider does not include the groups claim in the ID token or userinfo response, or the scope that carries it is not requested | Sign in as a test user and inspect the returned token claims. Add the groups scope and mapping to the provider, then confirm the group names match the identifiers used in the tailnet policy file. |
| Group names differ from policy names | Groups are renamed in authentik, or the policy refers to a display name where the claim carries a slug or internal name | Compare the exact claim values with the group references in the policy file. Align the names on one side, and avoid renaming groups that policy depends on without a review. |
| Sign-in loop after an IdP switch | Existing tailnet users still hold sessions or identity links from the previous provider, so the new issuer does not match the stored identity | Test with a user who has never signed in to the tailnet and with one who has. Remove or re-link the old identity records for affected users, clear browser sessions, then sign in again. |
| Users fall outside the intended access after the switch | Users keep old group membership or role assignments from the previous provider, or the authentik groups were never populated | Review each user's group membership in authentik before cutover and compare it with the access list. Populate the groups first, then migrate users in a small test group. |
Questions teams ask before connecting authentik to Tailscale
What does it cost in licensing to connect authentik to Tailscale?
Licensing has two parts, and you pay each vendor separately. authentik Open Source is free and its main code is under the MIT license, so the OIDC integration with Tailscale needs no authentik license fee. 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. Tailscale's pricing page lists Personal free for up to 6 users, Standard at $8 per user per month and Premium at $18 per user per month, with custom Enterprise pricing. Confirm with each vendor which features your chosen tier includes, for example SCIM provisioning, which Tailscale lists from Standard, and log streaming, which it lists under Premium. Your implementation work is a separate cost and is quoted from your written scope.
Which Tailscale and authentik features do I need before I budget?
Start by listing what your tailnet must do, because that decides the tiers on both sides. The features that most often change the budget are:
- SCIM user and group provisioning, which Tailscale lists from its Standard plan
- Network flow logs and log streaming, which Tailscale lists under Premium
- Group-based ACLs, where Tailscale caps ACL groups at 3 on Personal, 10 on Standard and 300 on Premium
- Enterprise integrations in authentik, such as directory sources, which the authentik pricing page lists as Enterprise features
Confirm each item against the current Tailscale pricing page and the authentik pricing page before you commit to a tier.
How long does the authentik and Tailscale integration take?
No duration has been established for this integration, so treat any number you hear as unverified. The work length depends on how many identity sources you move, how many groups map to ACL rules, whether you already run a Tailscale tailnet, and whether you migrate users from another identity provider. A tailnet with a single domain and a few groups is a shorter job than one that moves a large user base and rewrites its access policy. Ask any partner for a written timeline tied to a written scope, and check it against your change calendar and your user-communication needs.
What does my team need to provide for the integration?
Plan for access and decisions, not just servers. Your team needs administrator access to the authentik instance and to the Tailscale admin console, a domain you control for the WebFinger endpoint at /.well-known/webfinger, and a named owner for the Tailscale ACL policy. You also need a list of which groups should receive which access, a decision on how users from your current identity provider move over, and a test group of users who can confirm sign-in before everyone switches. If you manage Tailscale settings as code, confirm with Tailscale's Terraform provider documentation how ACL and tag changes will be tracked.
Can my own team set up authentik with Tailscale without a partner?
Yes, if your team already runs authentik and understands OAuth2 and OIDC, the core steps are documented by authentik and Tailscale. The first sign-in test is quick to repeat, but the risk sits in the policy side: a wrong group mapping or ACL can lock users out or expose hosts. Teams that run this in-house usually need a rollback plan, a test tailnet or a limited user group, and someone who can read the authentik logs when sign-in fails. Check the authentik integration guide for Tailscale first, then decide whether your staff can cover those steps within your own schedule.
When should we bring in a partner for this work?
Bring in a partner when the integration touches several systems at once or when your change window is tight. Common triggers include migrating users from an existing identity provider, combining Tailscale with other VPN or firewall sign-ins, meeting audit evidence requirements, or running authentik in a high-availability setup with separate PostgreSQL. DeployOpen plans, implements, documents and supports self-hosted open-source platforms in your own infrastructure, and most engagements are fixed-scope with written scope, deliverables and timelines agreed before work starts. DeployOpen does not publish prices, so a quote follows from the written scope.
Does Tailscale's own control plane or the authentik setup hold my users' data?
The answer depends on how you deploy each part, so confirm it in writing before rollout. authentik is self-hosted, and its architecture stores configuration and data in PostgreSQL, which you operate in your own infrastructure. Tailscale is a hosted control plane unless you choose a self-hosted alternative, and the Headscale README notes that its control server, which exchanges WireGuard keys and assigns IP addresses, is self-hosted in that model. Ask Tailscale about where its control plane stores tailnet metadata, and map the answer to your data handling and compliance obligations.
When to plan an authentik and Tailscale integration as a managed project
Plan this integration as a managed project when the tailnet affects many users or devices and the change must be reversible, documented and checked before anyone relies on it. The work has three distinct parts that fail in different ways: the WebFinger endpoint at /.well-known/webfinger on the domain of the administrator's email address, the OIDC provider and application in authentik, and the move of existing users and their access rules from another identity provider. DeployOpen plans and implements this work inside your own infrastructure, including the authentik hosts, DNS and reverse proxy you control. Scope, deliverables and timelines are agreed in writing before work begins, so the WebFinger and DNS changes are named, owned and signed off before anyone touches a production zone.
The scoping stage is where most avoidable delay happens. Confirm which domain holds the administrator email addresses, who can edit its DNS and web server, and whether the endpoint can be served without disturbing other sites on that host. Confirm which authentik version you run and whether it is one of the supported release lines in the security policy, since the upgrade path affects where the Tailscale provider settings are kept. Decide who the Tailscale Owners and Admins will be before the switch, because API access tokens can only be created by those roles and expire after 1 to 90 days, which affects any automation built around them.
Validation should use a test group of users who can sign in through authentik while the existing identity provider stays active for everyone else. Check that each test user reaches the tailnet, that devices register, and that access rules behave as the ACL policy expects. Keep the rollback path explicit: the previous provider and its settings stay available until the test group and then the full user population have been verified. Handover should leave runbooks for the DNS record, the OIDC client secret rotation, adding and removing users, and the steps to restore the previous sign-in path. Ask for these runbooks to be part of the written deliverables rather than a later follow-up.
How DeployOpen scopes, delivers and supports this integration
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure. For authentik and Tailscale OIDC integration, we agree a written scope first, build the WebFinger endpoint and OIDC provider in your environment, then hand over the configuration and runbooks your team needs to operate it.
How we scope
- Confirm which authentik instance, domain and administrator email domain the WebFinger endpoint will serve.
- Agree which tailnet, plan tier and Tailscale admin roles are in scope for the change.
- Record the user migration path from your current identity provider in the written scope before work starts.
How we build
- Configure the authentik OAuth2/OpenID provider and application to match the Tailscale integration guide.
- Publish the WebFinger endpoint on your domain and verify its response before enabling sign-in.
- Test sign-in with pilot accounts, group behavior and tailnet access rules in a non-production tailnet first.
How we hand over
- Deliver a written configuration record covering provider settings, redirect URIs, WebFinger routes and access policy mappings.
- Document the user move from the previous identity provider, including rollback steps and the cutover sequence.
- Walk your administrators through sign-in troubleshooting and the checks to repeat after authentik upgrades.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and periodic checks of the integration are available as a retainer.
- Ask for the support boundaries, response arrangements and change process in writing as part of your quote.
