Tailscale OpenID Connect (OIDC) Identity Provider

https://github.com/tailscale/tsidp
Admin
tsidp is an OpenID Connect (OIDC) and OAuth Identity Provider (IdP) server designed to integrate...
Tokens:52,718
Snippets:320
Trust Score:10
License:BSD-3-Clause
Update:4 days ago
Show doc for...
Tokens:
Raw
### Start and enable Docker

Source: https://github.com/tailscale/tsidp/blob/main/docs/proxmox/README.md

Starts the Docker daemon and configures it to start at boot. Warnings may appear, but a successful start shows `* Starting Docker Daemon ... [ ok ]`.

```bash
rc-service docker start
rc-update add docker boot

```

--------------------------------

### Verify Docker installation

Source: https://github.com/tailscale/tsidp/blob/main/docs/proxmox/README.md

Prints the installed Docker version to confirm Docker is available.

```bash
docker --version

```

--------------------------------

### Start the MCP server example

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-server/README.md

Runs the MCP server on localhost port 9933. Replace idp.YOUR_TAILNET.ts.net with your actual tsidp hostname.

```bash
go run ./mcp-server.go --tsidp idp.YOUR_TAILNET.ts.net
```

--------------------------------

### Clone tsidp repo and open example directory

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-gateway/README.md

Clone the tsidp repository and navigate to the mcp-gateway example directory. Installing uv is recommended to run the Python examples.

```bash
git clone https://github.com/tailscale/tsidp.git
cd tsidp/examples/mcp-gateway/
```

--------------------------------

### Update packages and install dependencies

Source: https://github.com/tailscale/tsidp/blob/main/docs/proxmox/README.md

Run inside the LXC console as root to update Alpine packages and install Docker and Git.

```bash
apk update
apk add docker git

```

--------------------------------

### Example usage of New with server setup

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/idpserver.md

Mirrors the binary's wiring (tsidp-server.go:207-212). Creates a server with stateDir "/var/lib/tsidp", sets server URL to "idp.my-tailnet.ts.net" on port 443, loads funnel clients, and serves over a tsnet TLS listener. Fatal errors are logged on failure.

```go
srv := server.New(lc, "/var/lib/tsidp", false, false, true)
srv.SetServerURL("idp.my-tailnet.ts.net", 443)
if err := srv.LoadFunnelClients(); err != nil {
    log.Fatalf("load clients: %v", err)
}

ln, err := ts.ListenTLS("tcp", ":443") // tsnet listener
if err != nil {
    log.Fatal(err)
}
if err := (&http.Server{Handler: srv}).Serve(ln); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Run tsidp Docker container for MCP Gateway demo

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-gateway/README.md

Starts the tsidp server in a Docker container with the required environment variables for the MCP Gateway example. The output shows the server starting and printing a login URL for authentication.

```bash
$ docker run -it --rm --name tsidp \
  -v tsidp-mcp-gateway-demo:/data \
  -e TS_STATE_DIR=/data \
  -e TS_HOSTNAME=tsidp-mcp-gateway-demo \
  -e TSIDP_ENABLE_STS=1 \
  -e TAILSCALE_USE_WIP_CODE=1 \
  -e TSIDP_LOG=debug ghcr.io/tailscale/tsidp:latest
```

```text
2025/12/03 18:36:18 tsnet running state path /data/tailscaled.state
2025/12/03 18:36:18 tsnet starting with hostname "tsidp-mcp-gateway-demo", varRoot "/data"
2025/12/03 18:36:18 LocalBackend state is NeedsLogin; running StartLoginInteractive...
2025/12/03 18:36:23 To start this tsnet server, restart with TS_AUTHKEY set, or go to: https://login.tailscale.com/a/abcd123456789
2025/12/03 18:36:44 INFO tsidp server started server_url=https://tsidp-mcp-gateway-demo.<YOUR-TAILNET>.ts.net
2025/12/03 18:36:48 AuthLoop: state is Running; done
```

--------------------------------

### Run tsidp via Docker

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-server/README.md

Starts the tsidp container with required environment variables and volume mount. Ensure you replace YOUR_TAILSCALE_AUTHKEY with your actual auth key. The command runs in detached mode and exposes port 443.

```bash
docker run -d \
  --name tsidp \
  -p 443:443 \
  -e TS_AUTHKEY=YOUR_TAILSCALE_AUTHKEY \
  -e TSNET_FORCE_LOGIN=1
  -e TAILSCALE_USE_WIP_CODE=1 \
  -v tsidp-data:/var/lib/tsidp \
  tsidp --hostname=idp --dir=/var/lib/tsidp
```

--------------------------------

### Start the MCP inspector

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-server/README.md

Launches the MCP inspector version 0.16.3 due to a bug in the latest version as of 2025/09/13.

```bash
npx @modelcontextprotocol/inspector@0.16.3
```

--------------------------------

### Clone the tsidp repository

Source: https://github.com/tailscale/tsidp/blob/main/docs/proxmox/README.md

Creates the source directory and clones the tsidp repository from GitHub.

```bash
mkdir -p /usr/local/src && cd /usr/local/src
git clone https://github.com/tailscale/tsidp.git

```

--------------------------------

### Run tsidp directly with Go

Source: https://github.com/tailscale/tsidp/blob/main/README.md

Clones the repository and runs tsidp with default flag values. Requires setting TAILSCALE_USE_WIP_CODE=1 and a valid TS_AUTHKEY; TSNET_FORCE_LOGIN=1 forces login flow.

```bash
# 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 .
```

--------------------------------

### Verifier output example for OIDC flow

Source: https://github.com/tailscale/tsidp/blob/main/cmd/verifier/README.md

Example output from the verifier showing the full OIDC flow: fetching metadata, registering a client, user authorization, token exchange, ID token verification, introspection, userinfo, and STS token exchange. Includes sample ID Token Claims, Introspection Response, and UserInfo Response.

```text
Step 1: Fetching provider metadata from https://idp.ts001.ts.net...
✅ Success. Authorization Endpoint: https://idp.ts001.ts.net/authorize

Step 2: Dynamically registering a new client...
✅ Success. Registered Client ID: fbd8dfa7f58205920cec45320fd9f35e

Step 3: Awaiting user authorization...
Generated Authorization URL with state=Rb-LHoG2ANhIqCpoKGxiv2bi1HoC-Xp3L04qu6Isyws= and nonce=a6HGEBl0ifBl6W5x8pAQA-b8zKnHQxCXvCgb5lNeu8o=

Attempting to GET the authorization URL directly...
✅ Success: Provider sent a redirect. This is expected for the tsidp flow.

Step 4: Handling redirect and extracting parameters...
✅ Success. Received authorization code: 36412d452218d1e7126b...

Step 5: Exchanging code for tokens...
✅ Success. Received Access Token: fd8ab6d67d3423ad12ae...

(Critical Step) Verifying ID Token signature and claims...
✅ Signature is valid.
✅ All claims are valid.
✅ Success. ID Token is valid. User Subject (sub): userid:<redacted>

Step 6: Introspecting the access token...
✅ Success. Introspection response received.

Step 7: Calling userinfo endpoint...
✅ Success. UserInfo response received.

Step 8: Performing STS token exchange...
✅ Success. Received exchanged token: d7caca739d794734067d...

---------------------- OIDC FLOW COMPLETE ----------------------

✅ All steps completed successfully!

---------------------- OIDC FLOW COMPLETE ----------------------

✅ All steps completed successfully!

--- ID Token Claims ---
{
  "iss": "https://idp.ts001.ts.net",
  "sub": "userid:0001",
  "aud": [
    "bb136f58ee4838e95c93c0aaf92712e0"
  ],
  "exp": 1757562670,
  "iat": 1757562370,
  "nonce": "PCfK0jy6O3VF4onpNzz2T5sTIlZtQW_94TsQFYFfIbE=",
  "email": "",
  "name": ""
}

--- Introspection Response ---
{
  "active": true,
  "aud": [
    "bb136f58ee4838e95c93c0aaf92712e0"
  ],
  "client_id": "bb136f58ee4838e95c93c0aaf92712e0",
  "exp": 1757562670,
  "iat": 1757562370,
  "iss": "https://idp.ts001.ts.net",
  "jti": "1f3895486339092e61cf70fe46a62afc",
  "nbf": 1757562370,
  "sub": "7743467757367193",
  "token_type": "Bearer",
  "username": "<redacted>"
}

--- UserInfo Response ---
{
  "email": "<redacted>@tailscale.com",
  "name": "Some User",
  "picture": "https://lh3.googleusercontent.com/a/ACg8ocKBPEaUhLFl6CBXu9mfNUpe3I_mW8m-FBzHwVfEaSfklNwqQelz=s96-c",
  "sub": "<redacted>",
  "username": "my_username"
}

```

--------------------------------

### Run with auth-key file and STS enabled

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/cli.md

Starts tsidp-server with a data directory, hostname, STS enabled, an auth-key file from secrets, and an advertise tag.

```bash
tsidp-server \
  -dir /data \
  -hostname idp \
  -enable-sts \
  -authkey-file /run/secrets/ts_authkey \
  -advertise-tags tag:tsidp
```

--------------------------------

### tsidp-server CLI flags example

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/configuration.md

Example invocation of the tsidp-server binary with common flags: -dir, -hostname, -enable-sts, and -log. Flags override environment variables and fallback defaults; -dir persists state, -hostname sets the tailnet hostname, -enable-sts enables RFC 8693 token exchange, and -log sets logging level.

```bash
tsidp-server -dir /data -hostname idp -enable-sts -log debug
```

--------------------------------

### GetVersion usage example

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/server.md

Prints the version string, e.g. "v0.0.0-...", a 7-char VCS hash, or "dev". The -version flag of the binary prints this value and exits.

```go
fmt.Println(server.GetVersion()) // e.g. "v0.0.0-...", a 7-char VCS hash, or "dev"
```

--------------------------------

### Build tsidp Docker image

Source: https://github.com/tailscale/tsidp/blob/main/README.md

Builds the tsidp container image using the Makefile target. Run from the project root after cloning the repository.

```bash
$ make docker-image
```

--------------------------------

### Run MCP server with uv

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-gateway/README.md

Run the MCP server in a new terminal window. It starts on localhost port 8001 and requires the auth server URL with your tailnet name. The output shows the server starting and listening on http://localhost:8001.

```bash
cd server
$ uv run mcp-auth-server --auth-server-url https://tsidp-mcp-gateway-demo.<YOUR-TAILNET>.ts.net/
2025-12-03 10:43:59,271 - INFO - Creating MCP server with required scopes: ['openid']
2025-12-03 10:43:59,271 - INFO - Token verifier endpoint: https://tsidp-mcp-gateway-demo.<YOUR-TAILNET>.ts.net/introspect
2025-12-03 10:43:59,271 - INFO - Resource server URL: http://localhost:8001
2025-12-03 10:43:59,280 - INFO - MCP server ready - OAuth client: <CLIENT_ID>
2025-12-03 10:43:59,280 - INFO - Server will require scopes: ['openid']
2025-12-03 10:43:59,280 - INFO - Discovery endpoints available at http://localhost:8001/.well-known/
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
2025-12-03 10:43:59,296 - INFO - StreamableHTTP session manager started
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:8001 (Press CTRL+C to quit)
...
```

--------------------------------

### Docker Compose configuration for tsidp

Source: https://github.com/tailscale/tsidp/blob/main/README.md

Defines the tsidp service using the pre-built image with persistent state, hostname, and optional auth key. Requires replacing YOUR_TAILSCALE_AUTHKEY with a valid key. Start with 'docker compose up -d' and monitor with 'docker compose logs -f'.

```yaml
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:
```

--------------------------------

### MCP Tool Call Example

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-gateway/README.md

Shows listing available tools and calling oauth_details and multiply via the gateway. The output includes tool descriptions and JSON responses with authentication details.

```text
mcp>: list
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool          ┃ Description                                                         ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ debug_auth    │ Debug authentication by showing both header and context token info. │
│               │                                                                     │
│               │ This tool helps diagnose authentication issues by displaying        │
│               │ what token is in the Authorization header vs what's in the context. │
│               │                                                                     │
│               │ Returns:                                                            │
│               │     Dictionary with detailed auth debugging information             │
│               │                                                                     │
│ multiply      │ Multiply two numbers.                                               │
│               │                                                                     │
│               │ This tool requires OAuth authentication and returns the product     │
│               │ of two input numbers along with authentication context.             │
│               │                                                                     │
│               │ Args:                                                               │
│               │     a: First number to multiply                                     │
│               │     b: Second number to multiply                                    │
│               │                                                                     │
│               │ Returns:                                                            │
│               │     Dictionary with result and authentication info                  │
│               │                                                                     │
│ oauth_details │ Get OAuth authentication details for the current client.            │
│               │                                                                     │
│               │ Returns all available OAuth token information that the server       │
│               │ knows about the authenticated client.                               │
│               │                                                                     │
│               │ Returns:                                                            │
│               │     Dictionary with OAuth client and token details                  │
│               │                                                                     │
└───────────────┴─────────────────────────────────────────────────────────────────────┘

mcp>: call oauth_details
{
  "authenticated": true,
  "client_id": "8cc2afcec17ed1928086b1c8d4587dac",
  "scopes": [
    "openid",
    "profile",
    "email"
  ],
  "expires_at": 1764789340,
  "resource": "http://localhost:8001",
  "request_id": "6",
  "token_type": "Bearer",
  "current_time": 1764789300,
  "time_until_expiry": 40,
  "is_expired": false,
  "token_preview": "e5d3ea8a...5d8e699d"
}

mcp>: call multiply {"a":2,"b":4}
{
  "operation": "multiplication",
  "inputs": {
    "a": 2.0,
    "b": 4.0
  },
  "result": 8.0,
  "authenticated_as": "8cc2afcec17ed1928086b1c8d4587dac",
  "request_id": "5"
}
```

--------------------------------

### Application capability grant for tsidp admin UI and DCR

Source: https://github.com/tailscale/tsidp/blob/main/README.md

Configures an app capability grant in Tailscale access controls to allow access to tsidp's admin UI and dynamic client registration (DCR) endpoints. Access is denied by default, and grants are applied per request immediately without restarting tsidp. The schema is still in development and may change. The example is very permissive (src and dst are "*") and suitable only for testing. extraClaims are included in the id_token and optionally in the /userinfo response via includeInUserInfo.

```hujson
"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,
        },
      ],
    },
  },
],
```

--------------------------------

### LoadFunnelClients error handling example

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/idpserver.md

Shows how to call LoadFunnelClients and wrap any error, e.g., a corrupt oidc-funnel-clients.json in stateDir, with fmt.Errorf. Use this pattern when you need to propagate the failure with additional context.

```go
if err := srv.LoadFunnelClients(); err != nil {
    // e.g. corrupt oidc-funnel-clients.json in stateDir
    return fmt.Errorf("load funnel clients: %w", err)
}
```

--------------------------------

### Permissive application grant for testing tsidp

Source: https://github.com/tailscale/tsidp/blob/main/cmd/verifier/README.md

Example application grant configuration for testing the Security Token Server. This is very permissive and recommended only for testing and development.

```json
...
"grants": [
  {
    "src": ["*"],
    "dst": ["*"],
    "ip":  ["*"],

    "app": {
      "tailscale.com/cap/tsidp": [
        {
          "users":     ["*"],
          "resources": ["*"],
        },
      ],
    },
  },
...

```

--------------------------------

### Run MCP Auth Gateway with uv

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-gateway/README.md

Starts the MCP gateway on localhost port 8003. Requires the gateway directory and a valid tailnet URL. Output shows the gateway version and URLs.

```bash
cd gateway
$ uv run mcp-auth-gateway --auth-server-url https://tsidp-mcp-gateway-demo.<YOUR-TAILNET>.ts.net/ --mcp-server-url http://localhost:8001
MCP Auth Gateway v0.1.0
Authorization Server: https://tsidp-mcp-gateway-demo.<YOUR-TAILNET>.ts.net/
MCP Server: http://localhost:8001
Gateway URL: http://localhost:8003

...
```

--------------------------------

### Enable Docker container auto-restart

Source: https://github.com/tailscale/tsidp/blob/main/docs/proxmox/README.md

Configures the tsidp container to restart automatically unless it is explicitly stopped. Run after `https://idp...` is working.

```bash
docker update --restart unless-stopped tsidp

```

--------------------------------

### openIDProviderMetadata struct definition

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/types.md

Internal Go struct representing the OIDC discovery response served at GET /.well-known/openid-configuration. Defined in server/oauth-metadata.go:16-32. Fields use views.Slice[string] for JSON arrays and omitempty for optional endpoints.

```go
type openIDProviderMetadata struct {
	Issuer                            string              `json:"issuer"`
	AuthorizationEndpoint             string              `json:"authorization_endpoint,omitempty"`
	TokenEndpoint                     string              `json:"token_endpoint,omitempty"`
	UserInfoEndpoint                  string              `json:"userinfo_endpoint,omitempty"`
	IntrospectionEndpoint             string              `json:"introspection_endpoint,omitempty"`
	RegistrationEndpoint              string              `json:"registration_endpoint,omitempty"`
	JWKS_URI                          string              `json:"jwks_uri"`
	ScopesSupported                   views.Slice[string] `json:"scopes_supported"`
	ResponseTypesSupported            views.Slice[string] `json:"response_types_supported"`
	SubjectTypesSupported             views.Slice[string] `json:"subject_types_supported"`
	ClaimsSupported                   views.Slice[string] `json:"claims_supported"`
	IDTokenSigningAlgValuesSupported  views.Slice[string] `json:"id_token_signing_alg_values_supported"`
	GrantTypesSupported               views.Slice[string] `json:"grant_types_supported,omitempty"`
	TokenEndpointAuthMethodsSupported views.Slice[string] `json:"token_endpoint_auth_methods_supported,omitempty"`
	CodeChallengeMethodsSupported     views.Slice[string] `json:"code_challenge_methods_supported,omitempty"`
}
```

--------------------------------

### LoadFunnelClients method signature

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/idpserver.md

Declares the LoadFunnelClients method on IDPServer. Reads the persisted funnel-client JSON database from <stateDir>/oidc-funnel-clients.json (or ./oidc-funnel-clients.json when stateDir is empty) and replaces the in-memory store. Missing file is treated as success (empty store). As a migration, clients with a legacy single redirect_uri value and no redirect_uris get the value copied into RedirectURIs, and the migrated database is rewritten to disk. Returns nil on success or when the file does not exist; an error if the file cannot be opened (other than not-exist) or decoded, or if persisting a migrated store fails (failed to store migrated clients: %w).

```go
func (s *IDPServer) LoadFunnelClients() error
```

--------------------------------

### ACL application grant rule for MCP resource indicators

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-server/README.md

Adds a permissive ACL rule to allow any user or device on the tailnet to request any resource. For more specificity, change the resources wildcard to http://localhost:9933.

```json
{
  "src": ["*"],
  "dst": ["*"],
  "app": {
    "tailscale.com/cap/tsidp": [
      {
        "users":     ["*"],
        "resources": ["*"],
      },
    ],
  },
},
```

--------------------------------

### oauthAuthorizationServerMetadata struct definition

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/types.md

Internal Go struct representing the RFC 8414 authorization server metadata response. Served at GET /.well-known/oauth-authorization-server; advertises resource_indicators_supported: true (RFC 8707) and authorization_details_types_supported: ["resource_indicators"].

```go
type oauthAuthorizationServerMetadata struct {
	Issuer                             string              `json:"issuer"`
	AuthorizationEndpoint              string              `json:"authorization_endpoint"`
	TokenEndpoint                      string              `json:"token_endpoint"`
	IntrospectionEndpoint              string              `json:"introspection_endpoint,omitempty"`
	RegistrationEndpoint               string              `json:"registration_endpoint,omitempty"`
	JWKS_URI                           string              `json:"jwks_uri"`
	ResponseTypesSupported             views.Slice[string] `json:"response_types_supported"`
	GrantTypesSupported                views.Slice[string] `json:"grant_types_supported"`
	ScopesSupported                    views.Slice[string] `json:"scopes_supported,omitempty"`
	TokenEndpointAuthMethodsSupported  views.Slice[string] `json:"token_endpoint_auth_methods_supported"`
	AuthorizationDetailsTypesSupported views.Slice[string] `json:"authorization_details_types_supported,omitempty"`
	ResourceIndicatorsSupported        bool                `json:"resource_indicators_supported,omitempty"`
	CodeChallengeMethodsSupported      views.Slice[string] `json:"code_challenge_methods_supported,omitempty"`
}
```

--------------------------------

### Docker secrets configuration for tsidp

Source: https://github.com/tailscale/tsidp/blob/main/README.md

Avoids exposing TS_AUTHKEY in docker inspect output by mounting it as a Docker secret and using TS_AUTHKEY_FILE. Requires creating a secret file (e.g., ./ts_authkey.txt) and referencing it in the compose file.

```yaml
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:
```

--------------------------------

### OAuth client secret configuration for tsidp

Source: https://github.com/tailscale/tsidp/blob/main/README.md

Alternative to traditional auth keys for automatic node registration. Requires creating an OAuth client with Auth Keys → Write scope, defining the advertise tag in ACL tagOwners, and setting TS_ADVERTISE_TAGS (or --advertise-tags) when using OAuth client secrets.

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

--------------------------------

### Example tsidp capability grant in tailnet ACL (HuJSON)

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/configuration.md

Shows the full grant object for the `tailscale.com/cap/tsidp` capability. Grants are resolved per request from `WhoIs.CapMap` and update without restart. Admin UI and DCR access are denied by default (403 access_denied) unless granted; localhost requests bypass capability checks.

```hujson
"grants": [
  {
    "src": ["*"],
    "dst": ["*"],
    "app": {
      "tailscale.com/cap/tsidp": [
        {
          "allow_admin_ui": true,
          "allow_dcr": true,
          "users":     ["*"],
          "resources": ["*"],
          "extraClaims": {
            "bools": true,
            "strings": "Mon Jan 2 15:04:05 MST 2006",
            "numbers": 180,
            "array1": [1,2,3],
            "array2": ["one", "two", "three"]
          },
          "includeInUserInfo": true
        }
      ]
    }
  }
]
```

--------------------------------

### ServeOnLocalTailscaled function signature

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/server.md

Registers a foreground Tailscale Serve/Funnel config on an already-running local tailscaled. Returns cleanup func, watcher error channel, and setup error. Fails with specific error messages on serve config, watcher, or session ID issues.

```go
func ServeOnLocalTailscaled(ctx context.Context, lc *local.Client, st *ipnstate.Status, dstPort uint16, shouldFunnel bool) (cleanup func(), watcherChan chan error, err error)
```

--------------------------------

### JWKS Response Example

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/endpoints.md

Example JSON response for the GET /.well-known/jwks.json endpoint. Contains a single RSA key with RS256 algorithm and a kid from signingKey.

```json
{
  "keys": [
    {
      "kty": "RSA",
      "n": "<base64url modulus>",
      "e": "<base64url exponent>",
      "alg": "RS256",
      "use": "sig",
      "kid": "<uint64 kid from signingKey>"
    }
  ]
}
```

--------------------------------

### General development run with TAILSCALE_USE_WIP_CODE and TS_AUTHKEY

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/cli.md

Runs the server in development mode with WIP code enabled, an auth key, and forced login.

```bash
TAILSCALE_USE_WIP_CODE=1 TS_AUTHKEY=tskey-auth-xxxxx TSNET_FORCE_LOGIN=1 go run .
```

--------------------------------

### ServeOnLocalTailscaled

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/errors.md

Starts the OIDC server on a local tailscaled instance. Returns a cleanup function and a watcher. Errors occur if the server cannot be started.

```APIDOC
## ServeOnLocalTailscaled

### Description
Starts the OIDC server on a local tailscaled instance. Returns a cleanup function and a watcher. Errors occur if the server cannot be started.

### Method
Function

### Endpoint
`ServeOnLocalTailscaled` (server package)

### Parameters
- `ctx` (context.Context) - Required - Context for the server lifecycle.
- `lc` (*tailscale.LocalClient) - Required - Local tailscaled client.
- `st` (*tailscale.ServeConfig) - Required - Serve configuration.
- `port` (int) - Required - Port to listen on.
- `bool` (bool) - Required - Additional flag.

### Return Value
- `cleanup` (func()) - Cleanup function to stop the server.
- `watcher` (*tailscale.Watcher) - Watcher for serve config changes.
- `err` (error) - Error if server fails to start.

### Error Handling
- Any error indicates a failure to start; fail fast in a host app.

### Example
```go
cleanup, watcher, err := server.ServeOnLocalTailscaled(ctx, lc, st, 443, false)
if err != nil {
    log.Fatalf("serve on local tailscaled: %v", err)
}
defer cleanup()
```
```

--------------------------------

### New

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/idpserver.md

Constructs a new IDPServer instance with the provided configuration. It initializes empty token stores and does not set a server URL until SetServerURL is called.

```APIDOC
## New

### Description
Constructs a new IDPServer instance with the provided configuration. It initializes empty token stores and does not set a server URL until SetServerURL is called.

### Method
Constructor

### Signature
```go
func New(lc *local.Client, stateDir string, funnel, localTSMode, enableSTS bool) *IDPServer
```

### Parameters
- **lc** (`*local.Client`) - Required - Tailscale local client used for `WhoIs` identity lookups and certificate/serve operations
- **stateDir** (`string`) - Optional - Directory for persisted state (signing key file, funnel clients file). May be empty. Default: `""` (current directory)
- **funnel** (`bool`) - Optional - Whether the server is reachable via Tailscale Funnel (affects which requests are treated as funnel requests). Default: `false`
- **localTSMode** (`bool`) - Optional - Use a local tailscaled instead of tsnet; changes remote-address resolution to `X-Forwarded-For`. Default: `false`
- **enableSTS** (`bool`) - Optional - Enable the RFC 8693 token-exchange grant type. Default: `false`

### Return Value
Returns a fully initialized `*IDPServer` with empty token stores (`code`, `accessToken`, `refreshToken`, `funnelClients` maps created) and no server URL set yet.

### Example
```go
srv := server.New(lc, "/var/lib/tsidp", false, false, true)
srv.SetServerURL("idp.my-tailnet.ts.net", 443)
if err := srv.LoadFunnelClients(); err != nil {
    log.Fatalf("load clients: %v", err)
}

ln, err := ts.ListenTLS("tcp", ":443") // tsnet listener
if err != nil {
    log.Fatal(err)
}
if err := (&http.Server{Handler: srv}).Serve(ln); err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### GET /clients/

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/endpoints.md

Lists all clients. The `Secret` field is always empty. Returns a 405 for other HTTP methods.

```APIDOC
## GET /clients/

### Description
Lists all clients. The `Secret` field is always empty. Returns a 405 for other HTTP methods.

### Method
GET

### Endpoint
/clients/

### Response
#### Success Response (200)
- **client_id** (string) - Client identifier.
- **client_name** (string) - Client name.
- **redirect_uris** (array) - List of redirect URIs.
- **created_at** (string) - Creation timestamp.
- **Secret** (string) - Always empty.

#### Response Example
[
  {
    "client_id": "client-123",
    "client_name": "My Client",
    "redirect_uris": ["https://example.com/callback"],
    "created_at": "2023-01-01T00:00:00Z",
    "Secret": ""
  }
]

### Error Responses
- **401 access_denied** - Not available over funnel.
- **403 access_denied** - Missing `allow_admin_ui` capability grant or context/flag failure.
- **405 Method Not Allowed** - For non-GET methods.
```

--------------------------------

### Run MCP Client with uv

Source: https://github.com/tailscale/tsidp/blob/main/examples/mcp-gateway/README.md

Launches the MCP client pointing to the gateway. On success, an authorization callback should pop up.

```bash
cd client
uv run mcp-auth-client http://localhost:8003/mcp
```

--------------------------------

### GET /clients/{id}

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/endpoints.md

Retrieves a single client by ID. The secret is always empty. Returns 404 if the client is not found.

```APIDOC
## GET /clients/{id}

### Description
Retrieves a single client by ID. The secret is always empty. Returns 404 if the client is not found.

### Method
GET

### Endpoint
/clients/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Client ID.

### Response
#### Success Response (200)
- **client_id** (string) - Client identifier.
- **client_name** (string) - Client name.
- **redirect_uris** (array) - List of redirect URIs.
- **secret** (string) - Always empty.

#### Response Example
{
  "client_id": "client-123",
  "client_name": "My Client",
  "redirect_uris": ["https://example.com/callback"],
  "secret": ""
}

### Error Responses
- **401 access_denied** - Not available over funnel.
- **403 access_denied** - Missing `allow_admin_ui` capability grant or context/flag failure.
- **404 not_found** - Client not found.
```

--------------------------------

### GET /userinfo

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/endpoints.md

OIDC UserInfo endpoint. Returns claims about the authenticated user. Requires a valid bearer access token.

```APIDOC
## [GET] /userinfo

### Description
OIDC UserInfo endpoint. Returns claims about the authenticated user. Requires a valid bearer access token.

### Method
GET

### Endpoint
/userinfo

### Authentication
- **Authorization**: Bearer <access_token> (required) - Access token from the in-store access-token map.

### Response
#### Success Response (200)
- **sub** (string) - Always present; node user string.
- **name** (string) - Display name.
- **picture** (string) - Profile picture URL.
- **email** (string) - Derived from `realishEmail(loginname)`.
- **username** (string) - Local part of login name.
- **extra claims** (object) - From capability rules with `includeInUserInfo: true` (only those rules), merged via `withExtraClaims`.

#### Response Example
{
  "sub": "user123",
  "name": "John Doe",
  "picture": "https://example.com/avatar.png",
  "email": "john@example.com",
  "username": "john"
}

### Errors
- **400 invalid_request** - Missing/malformed Authorization header, tagged nodes not supported, failed to unmarshal capability, or failed to process user claims.
- **401 invalid_token** - Unknown token or token expired (token purged on expiry).
- **405 invalid_request** - Method not GET.
- **500 server_error** - Failed to encode user info.

Error responses include `WWW-Authenticate` header per RFC 6750.
```

--------------------------------

### GET /.well-known/oauth-authorization-server

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/endpoints.md

Retrieves the OAuth 2.0 Authorization Server Metadata in RFC 8414 format. No authentication is required and CORS is enabled.

```APIDOC
## [GET] /.well-known/oauth-authorization-server

### Description
Retrieves the OAuth 2.0 Authorization Server Metadata in RFC 8414 format. No authentication is required and CORS is enabled.

### Method
GET

### Endpoint
/.well-known/oauth-authorization-server

### Response
#### Success Response (200)
- **response_types_supported** (array) - Supported response types
- **grant_types_supported** (array) - Supported grant types
- **scopes_supported** (array) - Supported scopes
- **token_endpoint_auth_methods_supported** (array) - Supported token endpoint authentication methods
- **resource_indicators_supported** (boolean) - Indicates support for resource indicators
- **authorization_details_types_supported** (array) - Supported authorization details types
- **registration_endpoint** (string) - Registration endpoint (tailnet-only)

```

--------------------------------

### userInfo struct (userinfo response)

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/types.md

Internal struct for the userinfo response. Built by serveUserInfo; Sub is always set to the node user string, while Name, Picture, Email (via realishEmail), and Username are included when available and are not scope-gated. extraClaims from capability rules with IncludeInUserInfo: true are merged on top.

```go
type userInfo struct {
	Sub      string `json:"sub"`
	Name     string `json:"name,omitempty"`
	Email    string `json:"email,omitempty"`
	Picture  string `json:"picture,omitempty"`
	Username string `json:"username,omitempty"`
}
```

--------------------------------

### New

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/server.md

Creates a new IDPServer instance with the provided local client, state directory, and configuration flags.

```APIDOC
## New

### Description
Creates a new IDPServer instance with the provided local client, state directory, and configuration flags.

### Function Signature
```go
func New(lc *local.Client, stateDir string, funnel, localTSMode, enableSTS bool) *IDPServer
```

### Parameters
- **lc** (*local.Client) - Required - Local Tailscale client for the running tailscaled.
- **stateDir** (string) - Required - Directory for storing state.
- **funnel** (bool) - Required - Whether to enable Funnel (public exposure).
- **localTSMode** (bool) - Required - Whether to run in local Tailscale mode.
- **enableSTS** (bool) - Required - Whether to enable Security Token Service (STS).

### Returns
- **&IDPServer** - Pointer to the newly created IDPServer instance.
```

--------------------------------

### New

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/server.md

Creates a new IDPServer instance with the given local client, state directory, and configuration flags.

```APIDOC
## New

### Description
Creates a new IDPServer instance with the given local client, state directory, and configuration flags.

### Signature
`func New(lc *local.Client, stateDir string, funnel, localTSMode, enableSTS bool) *IDPServer`

### Parameters
- **lc** (*local.Client) - Required - The Tailscale local client used for backend operations.
- **stateDir** (string) - Required - Directory for storing server state.
- **funnel** (bool) - Required - Whether to enable Funnel mode.
- **localTSMode** (bool) - Required - Whether to run in local Tailscale mode.
- **enableSTS** (bool) - Required - Whether to enable Security Token Service.

### Returns
- **IDPServer** - A new IDPServer instance.
```

--------------------------------

### GET | POST /authorize

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/endpoints.md

The interactive authorization endpoint for the authorization-code flow. It validates the client and user, and redirects to the client's redirect URI with an authorization code.

```APIDOC
## [GET | POST] /authorize

### Description
The interactive authorization endpoint for the authorization-code flow. It validates the client and user, and redirects to the client's redirect URI with an authorization code.

### Method
GET | POST

### Endpoint
/authorize

### Parameters
#### Query Parameters (form-encoded body equivalent for POST)
- **client_id** (string) - Required - Registered client ID
- **redirect_uri** (string) - Required - Must exactly match one of the client's `redirect_uris`
- **scope** (string) - Optional - Space-delimited; validated against `openid`,`email`,`profile`. Empty defaults to `openid`
- **state** (string) - Optional - Opaque state, echoed back
- **nonce** (string) - Optional - Stored and placed in the id_token
- **code_challenge** (string) - Optional - PKCE challenge; `code_challenge_method` defaults to `"plain"` when absent; only `plain`/`S256` allowed
- **response_type** (string) - Not validated by this handler
- **resource** (string) - Not consumed at this endpoint

### Response
#### Success Response (302)
Redirects to `redirect_uri?code=<hex>&state=<state>` with a 5-minute valid authorization code.

#### Error Response (400)
- **error** (string) - `invalid_client` if client_id is unknown or mismatched
- **error** (string) - `invalid_request` if redirect_uri is missing or mismatched, or if required parameters are missing

#### Error Response (401)
- **error** (string) - `access_denied` if request is over Funnel

#### Error Response (405)
- **error** (string) - `invalid_request` if method is not GET or POST

#### Error Response (500)
- **error** (string) - `server_error` if WhoIs fails or redirect URI parsing fails

#### Redirect Errors (302)
- **error** (string) - `access_denied` if node is tagged
- **error** (string) - `invalid_scope` if unsupported scopes
- **error** (string) - `invalid_request` if PKCE method is invalid

```

--------------------------------

### ServeHTTP(w http.ResponseWriter, r *http.Request)

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/api-reference/idpserver.md

Dispatches incoming HTTP requests to the route mux. Satisfies http.Handler, so the server can be mounted directly or behind the standard library.

```APIDOC
## ServeHTTP(w http.ResponseWriter, r *http.Request)

### Description
Dispatches incoming HTTP requests to the route mux. Satisfies http.Handler, so the server can be mounted directly or behind the standard library.

### Method
Function

### Signature
`func (s *IDPServer) ServeHTTP(w http.ResponseWriter, r *http.Request)`

### Parameters
- **w** (http.ResponseWriter) - Required - Response writer
- **r** (*http.Request) - Required - Incoming request

### Behavior
Lazily builds the route mux via `lazyMux.Get(s.newMux)` and dispatches. Satisfies `http.Handler`, so the server can be mounted directly or behind the standard library. All route handlers and their request/response contracts are documented in [endpoints.md](../endpoints.md).

Error responses are generated by the internal `writeHTTPError` helper (`server/server.go:470`): JSON (`{"error": ..., "error_description": ...}`) when the `Accept` header contains `application/json`, otherwise `text/plain` (`Error <code>: <error> - <description>`), always with `Cache-Control: no-store` and `Pragma: no-cache`. Status codes `403`/`401` are logged at Warn, `500` at Error, everything else at Debug.
```

--------------------------------

### GET /.well-known/jwks.json

Source: https://github.com/tailscale/tsidp/blob/main/_autodocs/endpoints.md

Retrieves the JSON Web Key Set (JWKS) containing the public key used to verify ID token signatures. No authentication is required and CORS is enabled.

```APIDOC
## [GET] /.well-known/jwks.json

### Description
Retrieves the JSON Web Key Set (JWKS) containing the public key used to verify ID token signatures. No authentication is required and CORS is enabled.

### Method
GET

### Endpoint
/.well-known/jwks.json

### Response
#### Success Response (200)
- **keys** (array) - JSON Web Key Set with a single key
  - **kty** (string) - Key type (RSA)
  - **n** (string) - Base64url modulus
  - **e** (string) - Base64url exponent
  - **alg** (string) - Algorithm (RS256)
  - **use** (string) - Key usage (sig)
  - **kid** (string) - Key ID (uint64 kid from signingKey)

#### Response Example
```json
{
  "keys": [
    {
      "kty": "RSA",
      "n": "<base64url modulus>",
      "e": "<base64url exponent>",
      "alg": "RS256",
      "use": "sig",
      "kid": "<uint64 kid from signingKey>"
    }
  ]
}
```

#### Error Response (500)
- **error** (string) - `server_error` when no signing key can be loaded/generated

```

--------------------------------

### Run the verifier with STS and IDP flags

Source: https://github.com/tailscale/tsidp/blob/main/cmd/verifier/README.md

Command to run the verifier, enabling the Security Token Server (sts) flow and pointing at an identity provider. Replace the -idp URL with your own provider.

```bash
$ go run . -sts -idp https://idp.ts0000.ts.net
```
Tokens:
Raw