tsidp

tsidp is a Tailscale-integrated OpenID Connect (OIDC) identity provider that lets you use Tailscale identities to authenticate into applications that support OpenID Connect as well as MCP client/server connections. Running tsidp via the official Docker image ensures the IdP participates in your tailnet and can issue tokens for your services. By configuring TS_STATE_DIR, TS_HOSTNAME, and optional TS_AUTHKEY (for automatic node registration or OAuth client secrets), you can enable persistent state, proper TLS certificate provisioning, and seamless integration with your Tailnet ACLs and DCR flows. Once started, tsidp exposes OIDC endpoints for login, token exchange (STS when enabled), and user info, and it can be extended or tuned via the provided flags and environment variables. This setup is suitable for development and testing in a Tailnet environment and can be adapted for production with persistent storage and proper TLS handling.

Prerequisites:

• Docker (and Docker Compose if you prefer a compose-based workflow)
• A Tailnet with MagicDNS and HTTPS enabled
• A Tailscale authentication key if you want automatic node registration

Installation steps:

1. Install Docker

• Follow your OS-specific instructions from https://docs.docker.com/get-dstarted/

2. Pull and run tsidp via Docker (single container example)

• Use the docker run command (as shown in the MCP config example) or create a docker-compose file.

Example using docker run:

# Start tsidp container (adjust as needed for your environment)
docker run -d --name tsidp \
  -e TAILSCALE_USE_WIP_CODE=1 \
  -e TS_STATE_DIR=/data \
  -e TS_HOSTNAME=idp \
  -e TSIDP_ENABLE_STS=1 \
  -v tsidp-data:/data \
  ghcr.io/tailscale/tsidp:latest

If you prefer docker-compose:

version: '3.8'
services:
  tsidp:
    image: ghcr.io/tailscale/tsidp:latest
    container_name: tsidp
    environment:
      - TAILSCALE_USE_WIP_CODE=1
      - TS_STATE_DIR=/data
      - TS_HOSTNAME=idp
      - TSIDP_ENABLE_STS=1
    volumes:
      - tsidp-data:/data
volumes:
  tsidp-data:

3. Start the service

• If using docker run: the container is started in detached mode with -d as shown above.
• If using docker-compose: run docker compose up -d or docker-compose up -d depending on your setup.

4. Verify startup

• Visit https://idp.yourtailnet.ts.net in a browser (adjust hostname to match your Tailnet) to confirm the service is running. If TLS certificates are still provisioning, allow a few minutes for issuance.

5. Optional: register an auth key or client secrets

• If you want automatic node registration, provide a TS_AUTHKEY. You can also use OAuth client secrets by passing a value starting with tskey-client- via TS_AUTHKEY. See the tsidp README for details.

Tips and notes:

• TS_STATE_DIR controls where tsidp stores its persistent data (tsnet state, registrations, and sessions). Use a mounted volume to ensure persistence across restarts.
• The TS_HOSTNAME value determines the Tailnet hostname the IdP advertises (will become <hostname>.your-tailnet.ts.net).
• Enable TSIDP_ENABLE_STS=1 if you need OAuth token exchange (STS) capabilities.
• For development, you may need TAILSCALE_USE_WIP_CODE=1; this is required for tsidp <1.0.0 but may be unnecessary in newer releases.
• If you run tsidp for the first time, TLS certificate provisioning can take a few minutes. Be patient and avoid clearing data during initial setup.
• Always consider persisting state and rotating keys securely. Stateless/serverless deployments may re-register with Tailnet on restart and lose dynamic client registrations.
• Environment variables can be overridden at runtime via the Docker environment or in your orchestration system (e.g., Kubernetes) if you adapt the container to your platform.