tsidp - Tailscale OpenID Connect (OIDC) Identity Provider

[!CAUTION] This is an experimental update of tsidp. It is under active development and may experience breaking changes.

tsidp is an OIDC / OAuth Identity Provider (IdP) server that integrates with your Tailscale network. It allows you to use Tailscale identities for authentication into applications that support OpenID Connect as well as authenticated MCP client / server connections.

Prerequisites

• A Tailscale network (tailnet) with MagicDNS and HTTPS enabled
• A Tailscale authentication key from your tailnet
• (Recommended) Docker installed on your system
• Ability to set an Application capability grant

Running tsidp

(Recommended) Using the pre-built image

Docker images are automatically published at https://ghcr.io/tailscale/tsidp when releases are tagged.

[!TIP] Replace YOUR_TAILSCALE_AUTHKEY with your Tailscale authentication key in the following commands:

Use an existing auth key or create a new auth key in the Keys page of the Tailscale admin console. Ensure you select an existing tag or create a new one.

Here is an example docker compose YAML file for tsidp:

services:
  tsidp:
    container_name: tsidp
    image: ghcr.io/tailscale/tsidp:latest
    volumes:
      - tsidp-data:/data
    environment:
      - TAILSCALE_USE_WIP_CODE=1 # tsidp is experimental - needed while version <1.0.0
      - TS_STATE_DIR=/data # store persistent tsnet and tsidp state
      - TS_HOSTNAME=idp # Hostname on tailnet (becomes idp.your-tailnet.ts.net)
      - TSIDP_ENABLE_STS=1 # Enable OAuth token exchange
      # Optional: Tailscale auth key for automatic node registration
      # - TS_AUTHKEY=tskey-auth-xxxxx
volumes:
  tsidp-data:

Paste the YAML snippet above into a file named compose.yaml. Once the compose file has been edited to your satisfaction, start tsidp by issuing docker compose up -d. Monitor the result with docker compose logs -f.

Once tsidp has started, visit https://idp.yourtailnet.ts.net in a browser to confirm the service is running.

[!NOTE] If you're running tsidp for the first time it may take a few minutes for the TLS certificate to generate. You may not be able to access the service until the certificate is ready.

[!NOTE] Using OAuth Client Secrets

As an alternative to traditional auth keys, you can use OAuth client secrets for automatic node registration.

Setup:

1. In the Tailscale admin console, create an OAuth client with Auth Keys → Write scope
2. Ensure the advertise tag (e.g. tag:tsidp) is defined in your ACL tagOwners
3. Set TS_AUTHKEY to your OAuth client secret (tskey-client-...)
4. Set TS_ADVERTISE_TAGS (or --advertise-tags) — required when using OAuth client secrets

environment:
  - TS_AUTHKEY=tskey-client-xxxxx
  - TS_ADVERTISE_TAGS=tag:tsidp

[!NOTE] Using Docker Secrets

Passing TS_AUTHKEY as a plain environment variable puts the key in docker inspect output and the container's process environment. To avoid that, mount the key as a Docker secret and point tsidp at the mounted file with TS_AUTHKEY_FILE instead:

services:
  tsidp:
    image: ghcr.io/tailscale/tsidp:latest
    environment:
      - TAILSCALE_USE_WIP_CODE=1
      - TS_STATE_DIR=/data
      - TS_AUTHKEY_FILE=/run/secrets/ts_authkey
    volumes:
      - tsidp-data:/data
    secrets:
      - ts_authkey
secrets:
  ts_authkey:
    file: ./ts_authkey.txt
volumes:
  tsidp-data:

Other Ways to Build and Run

$ make docker-image

If you'd like to build tsidp and / or run it directly you can do the following:

# Clone the Tailscale repository
$ git clone https://github.com/tailscale/tsidp.git
$ cd tsidp

# run with default values for flags
$ TAILSCALE_USE_WIP_CODE=1 TS_AUTHKEY={YOUR_TAILSCALE_AUTHKEY} TSNET_FORCE_LOGIN=1 go run .

Setting an Application Capability Grant

[!IMPORTANT] Access to the admin UI and dynamic client registration endpoints are denied by default.

[!WARNING] tsidp's application capability schema are still in development and may change at anytime.

• Set an Application capability to grant access to the admin UI and DCR endpoints.
• Configure grants in the Access controls page of the Tailscale admin console.
• App capability grants are per request and updated immediately. No need to restart tsidp.

Example

"grants": [
  {
    // Very permissive and suitable only for testing.
    "src": ["*"],
    "dst": ["*"],

    // Example of a grant for tsidp:
    "app": {
      "tailscale.com/cap/tsidp": [
        {
          // allow access to UI
          "allow_admin_ui": true,

          // allow dynamic client registration
          "allow_dcr": true,

          // Secure Token Service (STS) controls
          "users":     ["*"],
          "resources": ["*"],

          // extraClaims are included in the id_token
          // recommend: keep this small and simple
          "extraClaims": {
            "bools": true,
            "strings": "Mon Jan 2 15:04:05 MST 2006",
            "numbers": 180,
            "array1": [1,2,3],
            "array2": ["one", "two", "three"]
          },

          // include extraClaims data in /userinfo response
          "includeInUserInfo": true,
        },
      ],
    },
  },
],

tsidp Configuration Options

The tsidp-server is configured by several command-line flags:

CLI Environment Variables

The tsidp-server binary is configured through the CLI flags above. However, there are several environment variables that configure the libraries tsidp-server uses to connect to the tailnet.

Required

• TAILSCALE_USE_WIP_CODE=1: required while tsidp is in development (<v1.0.0).

Optional

These environment variables are used when tsidp does not have any state information set in -dir <path>.

[!WARNING] Serverless/Stateless Deployment: tsidp requires persistent state storage to function properly in production. Without a persistent -dir, the service will re-register with Tailscale on every restart, lose dynamic OIDC client registrations, and invalidate user sessions. Serverless environments without persistent storage are not recommended for production use.

• TS_AUTHKEY=<key>: Key for registering a tsidp as a new node on your tailnet. Can be a traditional auth key or OAuth client secret (tskey-client-xxx). If omitted, a link will be printed to manually register.
• TS_AUTHKEY_FILE=<path> / -authkey-file <path>: Same as TS_AUTHKEY, but reads the key from a file - useful when your key comes from a Docker/Kubernetes secret instead of an env var. Don't set this alongside TS_AUTHKEY; tsidp will refuse to start rather than guess which one you meant. If the file is missing, tsidp just logs a warning and carries on (it may already be registered from a previous boot). No effect with -use-local-tailscaled.
• TS_ADVERTISE_TAGS=<tags>: Comma-separated advertise tags (e.g., "tag:tsidp,tag:server"). Optional, but required when using OAuth client secrets.
• TSNET_FORCE_LOGIN=1: Force re-login of the node. Useful during development.

Docker Environment Variables

The Docker image exposes the CLI flags through environment variables. If omitted the default values for the CLI flags will be used.

[!NOTE] TS_STATE_DIR and TS_HOSTNAME are legacy names. These will be replaced by TSIDP_STATE_DIR and TSIDP_HOSTNAME in the future.

Application Configuration Guides (WIP)

tsidp can be used as IdP server for any application that supports custom OIDC providers.

[!IMPORTANT] Note: If you'd like to use tsidp to login to a SaaS application outside of your tailnet rather than a self-hosted app inside of your tailnet, you'll need to run tsidp with --funnel enabled.

• Proxmox

TODOs

• (TODO) Grafana
• (TODO) open-webui
• (TODO) Jellyfin
• (TODO) Salesforce
• (TODO) ...

MCP Configuration Guides

tsidp supports all of the endpoints required & suggested by the MCP Authorization specification, including Dynamic Client Registration (DCR). More information can be found in the following examples:

• MCP Client / Server
• MCP Client / Gateway Server

Support

This is an experimental, work in progress, community project. For issues or questions, file issues on the GitHub repository.

License

BSD-3-Clause License. See LICENSE for details.