Tailscale

This document guides you through the different authentication and configuration options for Tailscale with TSDProxy. For a quick comparison of authentication methods, see Authentication Methods.

Authentication Methods

TSDProxy supports three authentication methods with Tailscale: OAuth, OAuth (manual), and AuthKey.

OAuth

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:example" # Optional if tags are defined in each proxy

OAuth (Manual)

tailscale:
  providers:
    default:
      authKey: ""
      authKeyFile: ""

AuthKey

tailscale:
  providers:
    default:
      authKey: "YOUR_GENERATED_KEY_HERE"
      authKeyFile: ""

Funnel

In addition to configuring TSDProxy to enable Funnel, you need to grant permissions in the Tailscale ACL. See Troubleshooting for more details. Also read Tailscale’s Funnel documentation for requirements and limitations.

Tags

• Tags are required for OAuth authentication.
• Tags only work with OAuth authentication.
• Tags can be configured in the provider or service.
• If tags are defined in the provider, they apply to all services.
• If tags are defined in the service, provider tags are ignored.

ACL Auto-Provisioning

When using OAuth authentication with tags, those tags must exist in your Tailscale ACL tagOwners or the proxy will fail to authenticate. Similarly, Funnel requires the funnel node attribute in your ACL nodeAttrs.

TSDProxy can automate both of these:

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:my-service"
      autoProvisionAcl: true

When autoProvisionAcl is true, TSDProxy will:

1. Check each configured tag against your ACL tagOwners.
2. Add any missing tags to tagOwners, owned by autogroup:admin.
3. Ensure the funnel attribute exists in nodeAttrs (if any proxy uses Funnel).

All modifications go through the Tailscale API with ETag-based conflict detection — if another process modifies the ACL concurrently, TSDProxy fails safely instead of overwriting.

What gets added

Given a provider configured with tags: "tag:my-service" and autoProvisionAcl: true, TSDProxy transforms an ACL that lacks both the tag and the Funnel attribute into one that has both.

Before auto-provisioning, a minimal ACL might look like this:

{
  "tagOwners": {
    "tag:existing": ["group:devs"],
  },
  "nodeAttrs": [],
}

After TSDProxy runs, the same ACL contains a new tagOwners entry and a new nodeAttrs entry:

{
  "tagOwners": {
    "tag:existing": ["group:devs"],
    "tag:my-service": ["autogroup:admin"],
  },
  "nodeAttrs": [
    {
      "target": ["tag:my-service"],
      "attr": ["funnel"],
    },
  ],
}

The new tag is always owned by autogroup:admin, which grants management rights to all admins of the tailnet. Existing entries in tagOwners and nodeAttrs are left untouched.

Funnel attribute provisioning

When autoProvisionAcl is true, TSDProxy proactively adds the funnel node attribute on every startup, even if no proxy currently uses Funnel. This avoids a second startup failure later when you enable Funnel on a container.

The check is global. If any entry in nodeAttrs already grants funnel, TSDProxy does nothing. The attribute is only added once, scoped to the first configured tag (or autogroup:member when no tag is set).

The operation is idempotent. Re-running TSDProxy against an ACL that already has the entry leaves it unchanged.

Error scenarios and recovery

Headscale and custom control servers

ACL auto-provisioning uses the Tailscale SaaS policy API (PolicyFile().Get, Validate, Set). Headscale and other alternative control servers do not implement this API, so autoProvisionAcl has no effect when controlURL points elsewhere. OAuth credentials are also a Tailscale SaaS feature, so the prerequisite checks fail before ACL provisioning runs.

With Headscale, manage ACLs manually in the headscale policy file. Tags must exist there before any proxy can authenticate. See Headscale / Custom Control Server for setup details.

Auditing and rollback

Every change TSDProxy makes goes through the Tailscale policy API, which records a revision. Inspect the results in two ways:

• Tailscale admin console: open Access Controls to view the current policy and its revision history.
• CLI: run tailscale acl get to print the current ACL as HuJSON. This requires an OAuth client or API access token with the policy:read scope.

To roll back, set autoProvisionAcl: false and restart TSDProxy. Existing tagOwners and nodeAttrs entries remain in your policy. TSDProxy reverts to read-only mode, logging a warning if a tag is missing instead of adding it. Remove the auto-provisioned entries themselves by deleting them from the policy file in the Tailscale admin console.

Prevent Duplicate Machines

When TSDProxy restarts and the data directory has been lost (e.g. non-persistent Docker volume), Tailscale creates a new machine instead of reconnecting the existing one. This results in duplicate machines in your tailnet, often with a -1 suffix.

The preventDuplicates option (default: false) tells TSDProxy to query the Tailscale API before creating a new node. If an existing device with the same hostname and matching tags is found and is offline, it is deleted first so the new node can take its place.

A boolean option:

Requirements

• OAuth authentication (clientId + clientSecret) — the Tailscale API is not available with auth keys alone.
• Tags must be configured on the provider.

Configuration

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:example"
      preventDuplicates: true

Safety checks

A device is only deleted when all of these conditions are true:

• It has the same hostname as the proxy being created
• It has matching tags
• It is currently offline (ConnectedToControl is false)
• The local tsnet state file is missing (no existing identity to reuse)

Online devices are never deleted.

Certificate Concurrency

When many ephemeral containers restart at once, TSDProxy requests TLS certificates for all of them simultaneously. The Tailscale local API cannot handle this thundering herd, resulting in context deadline exceeded errors and failed certificate generation.

The maxCertConcurrency option (default: 2) limits how many certificate generation requests run in parallel. Requests that exceed the limit wait for a slot and are logged at warn level if delayed by more than one second.

tailscale:
  providers:
    default:
      maxCertConcurrency: 3 # allow up to 3 parallel cert requests

Identity Headers

TSDProxy resolves the Tailscale identity of each incoming request and forwards it to your backend services via HTTP headers. All identity headers are stripped from the incoming request before being set, preventing header injection attacks.

Unauthenticated requests (e.g. via Funnel) will not receive identity headers.

TSDProxy Headers

Standard Auth Headers

These headers are recognized by common reverse-proxy-aware backends (Authelia, OAuth2 Proxy, Traefik, FileBrowser, etc.):

Standard Proxy Headers

Usage Example: FileBrowser

FileBrowser supports proxy authentication out of the box. Configure it to read the X-Forwarded-User header set by TSDProxy:

filebrowser --auth.method=proxy --auth.header=X-Forwarded-User

Users will be automatically logged in with their Tailscale login name.

Shared Tailscale

By default, each proxy gets its own Tailscale connection (tsnet.Server). When you enable shared mode, multiple proxies share a single Tailscale connection, which is useful when you want to conserve Tailscale machine quota or centralize DNS and TLS management.

How it works

• All shared proxies use one tsnet.Server with SNI (Server Name Indication) routing

• Incoming TLS connections are dispatched by domain name to the correct proxy

• Each proxy must have a custom domain set (tsdproxy.domain label or domain in list config) because SNI routing depends on unique domain names

• Only HTTPS ports are supported in shared mode — TCP and plain HTTP ports cannot be multiplexed by SNI and will be rejected at startup

  Note

  SNI routing inspects the TLS ClientHello to determine which domain the client is connecting to. Without TLS, there is no SNI to inspect, so multiple proxies cannot share a single listener on the same port. HTTP redirects (80/http->...) are also excluded because they would conflict when multiple proxies try to bind port 80 on the shared server. If you need TCP or redirect ports alongside shared mode, use a per-proxy Tailscale provider for those containers instead.

• The shared server starts when the first proxy is created and stops when the last proxy is removed

Configuration

defaultProxyProvider: shared

dnsProviders:
  cloudflare:
    provider: cloudflare
    apiToken: "your-cloudflare-api-token"

tlsProviders:
  acme:
    provider: acme
    email: "admin@example.com"

defaultDNSProvider: cloudflare
defaultTLSProvider: acme

tailscale:
  providers:
    shared:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:shared-proxy"
      shared: true
      hostname: "shared-proxy"
  dataDir: /data/

docker:
  local:
    host: unix:///var/run/docker.sock
    defaultProxyProvider: shared

Container labels for shared proxies:

services:
  app1:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app1"
      tsdproxy.domain: "app1.example.com"

  app2:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app2"
      tsdproxy.domain: "app2.example.com"

Requirements

When to use shared mode

• Fewer Tailscale machines in your tailnet
• All domains point to a single Tailscale hostname
• Centralized DNS and TLS management

Services Mode

Services mode uses the Tailscale VIP Services API to automatically assign FQDNs to each proxy. Unlike shared mode, no custom domains, external DNS, or TLS providers are needed — Tailscale handles everything.

How it works

• All services share one tsnet.Server (like shared mode)
• Each proxy is registered as a Tailscale VIP Service
• FQDNs are auto-assigned by Tailscale (e.g. myapp.tailnet-name.ts.net)
• No custom domain support — you cannot set tsdproxy.domain
• No UDP support — only HTTPS, HTTP, and TCP ports
• The shared server starts when the first service is created and stops when the last service is removed

Configuration

defaultProxyProvider: services

tailscale:
  providers:
    services:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:services-proxy"
      services: true
      hostname: "shared-services"
      autoApproveDevices: true
  dataDir: /data/

docker:
  local:
    host: unix:///var/run/docker.sock
    defaultProxyProvider: services

Container labels for services mode proxies:

services:
  app1:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app1"

  app2:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app2"

Requirements

Constraints

• No custom domains — FQDNs are auto-assigned by Tailscale from the tailnet name
• No UDP — VIP Services do not support UDP traffic
• HTTPS, HTTP, and TCP only — all other protocols are rejected at startup
• Mutually exclusive with shared — a provider cannot use both shared: true and services: true

Auto-remove conflicting devices

When switching from per-proxy or shared mode to services mode, existing Tailscale devices may share hostnames with the VIP services being created. This causes the Tailscale API to return a 409 "name is in use but is not a service" error, preventing the proxy from starting.

The autoRemoveConflicts option (default: false) enables automatic removal of conflicting devices when this error is encountered. After removing the device, TSDProxy retries the VIP service creation.

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:example"
      services: true
      hostname: "shared-services"
      autoRemoveConflicts: true

When to use services mode

• You want fewer Tailscale machines without managing external DNS
• Auto-assigned .ts.net FQDNs are acceptable for your use case
• You don’t need UDP or custom domains

Proxy Provider Resolution

1. Per-proxy label (tsdproxy.proxyprovider)
2. Target provider default (defaultProxyProvider)
3. Global default (top-level defaultProxyProvider)
4. First available provider

Proxy Lifecycle