Merge pull request #4 from sundaycarwash/cp/oauth-client

cp · web-flow · commit 621114c1d79d · 2025-10-22T19:54:34.000-07:00
Add support for authenticating against Tailscale using OAuth client secrets
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:tailscale.com)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,12 @@
 ## Unreleased
 
-- Update README.
+- **Add OAuth client support**: The buildpack now supports Tailscale OAuth clients as an authentication method. OAuth client secrets never expire (unlike traditional auth keys which expire every 90 days), making them the recommended approach for Heroku deployments. When using OAuth clients:
+  - Set `TAILSCALE_AUTH_KEY` to your OAuth client secret (starts with `tskey-client-`)
+  - Set `TAILSCALE_ADVERTISE_TAGS` to match the tags configured in your OAuth client (required)
+  - The buildpack automatically configures `ephemeral=true` and `preauthorized=true` for Heroku's dyno lifecycle
+  - Traditional auth keys remain fully supported for backward compatibility
+- **Fix**: `TAILSCALE_ADVERTISE_TAGS` now properly passed to `tailscale up` command
+- Update README with OAuth client setup instructions
 - Upgrade Tailscale (1.76.6)
 
 ## 1.1.2
diff --git a/README.md b/README.md
@@ -4,11 +4,37 @@ Run [Tailscale](https://tailscale.com/) on a Heroku dyno.
 
 ## Usage
 
-To set up your Heroku application, add the buildpack and `TAILSCALE_AUTH_KEY`
-environment variable:
+### OAuth Clients (Recommended)
 
-    $ heroku buildpacks:add https://github.com/sundaycarwash/heroku-buildpack-tailscale
-    $ heroku config:set TAILSCALE_AUTH_KEY="..."
+OAuth clients are the recommended authentication method because they **never expire**, unlike traditional auth keys which expire every 90 days.
+
+**1. Create an OAuth client in Tailscale:**
+   - Go to [Tailscale Admin Console → Settings → OAuth clients](https://login.tailscale.com/admin/settings/oauth)
+   - Click "Generate OAuth client"
+   - Select the `auth_keys` scope (under "Read" section)
+   - Select one or more tags (e.g., `tag:heroku`, `tag:production`)
+   - Save the **Client Secret** (starts with `tskey-client-`)
+
+**2. Configure your Heroku app:**
+
+```bash
+$ heroku buildpacks:add https://github.com/sundaycarwash/heroku-buildpack-tailscale
+$ heroku config:set TAILSCALE_AUTH_KEY="tskey-client-..."
+$ heroku config:set TAILSCALE_ADVERTISE_TAGS="tag:heroku"  # Must match tags from OAuth client
+```
+
+**Note:** The `TAILSCALE_ADVERTISE_TAGS` must match one of the tags you selected when creating the OAuth client.
+
+### Traditional Auth Keys (Legacy)
+
+You can also use traditional auth keys, but note they expire every 90 days:
+
+```bash
+$ heroku buildpacks:add https://github.com/sundaycarwash/heroku-buildpack-tailscale
+$ heroku config:set TAILSCALE_AUTH_KEY="tskey-auth-..."
+```
+
+### Using the SOCKS5 Proxy
 
 To have your processes connect through the Tailscale proxy, you need to use
 the `socks5` proxy provided by `tailscaled`.
@@ -62,9 +88,14 @@ The following settings are available for configuration via environment variables
 - `TAILSCALE_ADVERTISE_EXIT_NODES` - Offer to be an exit node for outbound internet traffic
   from the Tailscale network. Defaults to not advertising.
 - `TAILSCALE_ADVERTISE_TAGS` - Give tagged permissions to this device. You must be listed in
-  \"TagOwners\" to be able to apply tags. Defaults to none.
-- `TAILSCALE_AUTH_KEY` - Provide an auth key[^1] to automatically authenticate the node as your
-  user account. **This must be set.**
+  \"TagOwners\" to be able to apply tags. **Required when using OAuth clients.** Defaults to none
+  for traditional auth keys.
+- `TAILSCALE_AUTH_KEY` - Provide authentication credentials to automatically authenticate the node.
+  **This must be set.** Can be either:
+  - **OAuth client secret** (recommended, starts with `tskey-client-`): Never expires. Requires
+    `TAILSCALE_ADVERTISE_TAGS` to be set. Automatically configured with `ephemeral=true` and
+    `preauthorized=true` for Heroku's dyno lifecycle.
+  - **Traditional auth key** (starts with `tskey-auth-`): Expires every 90 days[^1].
 - `TAILSCALE_HOSTNAME` - Provide a hostname to use for the device instead of the one provided
   by the OS. Note that this will change the machine name used in MagicDNS. Defaults to the
   hostname of the application (a guid). If you have [Heroku Labs runtime-dyno-metadata](https://devcenter.heroku.com/articles/dyno-metadata)
diff --git a/bin/heroku-tailscale-start.sh b/bin/heroku-tailscale-start.sh
@@ -16,6 +16,27 @@ if [ -z "$TAILSCALE_AUTH_KEY" ]; then
 else
   log "Starting Tailscale"
 
+  # Detect if using OAuth client secret (starts with tskey-client-)
+  if [[ "$TAILSCALE_AUTH_KEY" == tskey-client-* ]]; then
+    log "Detected OAuth client secret"
+
+    # OAuth clients require tags to be set
+    if [ -z "$TAILSCALE_ADVERTISE_TAGS" ]; then
+      log "ERROR: TAILSCALE_ADVERTISE_TAGS must be set when using OAuth client authentication"
+      log "OAuth clients require tags. Set TAILSCALE_ADVERTISE_TAGS to match the tags configured in your OAuth client."
+      exit 1
+    fi
+
+    # Append OAuth parameters for Heroku dyno environment
+    # ephemeral=true: Auto-remove nodes when dynos stop (keeps node list clean)
+    # preauthorized=true: Skip manual approval (required for automation)
+    auth_key="${TAILSCALE_AUTH_KEY}?ephemeral=true&preauthorized=true"
+    log "Using OAuth client with ephemeral=true and preauthorized=true"
+  else
+    log "Using traditional auth key"
+    auth_key="${TAILSCALE_AUTH_KEY}"
+  fi
+
   # Only use the first 8 characters of the commit sha.
   # Swap the . and _ in the dyno with a - since tailscale doesn't
   # allow for periods.
@@ -33,16 +54,61 @@ else
   fi
   log "Using Tailscale hostname=$tailscale_hostname"
 
+  # Build the advertise-tags parameter if set
+  if [ -n "$TAILSCALE_ADVERTISE_TAGS" ]; then
+    advertise_tags="--advertise-tags=${TAILSCALE_ADVERTISE_TAGS}"
+  else
+    advertise_tags=""
+  fi
+
   tailscaled -verbose ${TAILSCALED_VERBOSE:-0} --tun=userspace-networking --socks5-server=localhost:1055 &
-  until tailscale up \
-    --authkey=${TAILSCALE_AUTH_KEY} \
-    --hostname="$tailscale_hostname" \
-    --accept-dns=${TAILSCALE_ACCEPT_DNS:-true} \
-    --accept-routes=${TAILSCALE_ACCEPT_ROUTES:-true} \
-    --advertise-exit-node=${TAILSCALE_ADVERTISE_EXIT_NODE:-false} \
-    --shields-up=${TAILSCALE_SHIELDS_UP:-false}
-  do
-    log "Waiting for 5s for Tailscale to start"
+
+  # Retry configuration
+  max_retries=6  # 6 attempts * 5 seconds = 30 seconds max wait time
+  retry_count=0
+
+  while true; do
+    # Try to start Tailscale
+    # On success, tailscale up returns 0 and we break out of the loop
+    # On failure, we capture the output for error detection
+    set +e  # Temporarily disable exit on error
+    tailscale up \
+      --authkey=${auth_key} \
+      --hostname="$tailscale_hostname" \
+      --accept-dns=${TAILSCALE_ACCEPT_DNS:-true} \
+      --accept-routes=${TAILSCALE_ACCEPT_ROUTES:-true} \
+      --advertise-exit-node=${TAILSCALE_ADVERTISE_EXIT_NODE:-false} \
+      --shields-up=${TAILSCALE_SHIELDS_UP:-false} \
+      ${advertise_tags} 2>&1 | tee /tmp/tailscale-up-output.log
+    exit_code=$?
+    set -e  # Re-enable exit on error
+
+    if [ $exit_code -eq 0 ]; then
+      # Success!
+      break
+    fi
+
+    # Failed - check for permanent authentication errors
+    if grep -qi "invalid key" /tmp/tailscale-up-output.log 2>/dev/null; then
+      log "ERROR: Authentication failed - invalid or expired auth key"
+      log "The auth key may have expired (traditional keys expire after 90 days) or been revoked."
+      log "Please generate a new auth key or OAuth client secret and update TAILSCALE_AUTH_KEY."
+      exit 1
+    fi
+
+    # Increment retry counter
+    retry_count=$((retry_count + 1))
+
+    # Check if we've exceeded max retries
+    if [ $retry_count -ge $max_retries ]; then
+      log "ERROR: Tailscale failed to start after $max_retries attempts ($(($max_retries * 5)) seconds)"
+      log "Last error output:"
+      cat /tmp/tailscale-up-output.log 2>/dev/null | indent || true
+      exit 1
+    fi
+
+    # Wait before retrying
+    log "Waiting for 5s for Tailscale to start (attempt $retry_count/$max_retries)"
     sleep 5
   done
 
diff --git a/test/fixtures/heroku-tailscale-start.sh-envs.stdout.txt b/test/fixtures/heroku-tailscale-start.sh-envs.stdout.txt
@@ -1,9 +1,10 @@
 -----> Starting Tailscale
+-----> Using traditional auth key
 -----> Using Tailscale hostname=test-host--
 >>> mocked tailscaled -verbose 1 call <<<
 >>> mocked tailscale call
---authkey=ts-auth-test
---hostname=test-host
+--authkey=tskey-auth-test
+--hostname=test-host--
 --accept-dns=false
 --accept-routes=false
 --advertise-exit-node=true
diff --git a/test/fixtures/heroku-tailscale-start.sh-hostname.stdout.txt b/test/fixtures/heroku-tailscale-start.sh-hostname.stdout.txt
@@ -1,9 +1,10 @@
 -----> Starting Tailscale
+-----> Using traditional auth key
 -----> Using Tailscale hostname=hunter20-another-web-1-heroku-app
 >>> mocked tailscaled -verbose 1 call <<<
 >>> mocked tailscale call
---authkey=ts-auth-test
---hostname=test
+--authkey=tskey-auth-test
+--hostname=hunter20-another-web-1-heroku-app
 --accept-dns=false
 --accept-routes=false
 --advertise-exit-node=true
diff --git a/test/fixtures/heroku-tailscale-start.sh-oauth-with-tags.stderr.txt b/test/fixtures/heroku-tailscale-start.sh-oauth-with-tags.stderr.txt
diff --git a/test/fixtures/heroku-tailscale-start.sh-oauth-with-tags.stdout.txt b/test/fixtures/heroku-tailscale-start.sh-oauth-with-tags.stdout.txt
@@ -0,0 +1,15 @@
+-----> Starting Tailscale
+-----> Detected OAuth client secret
+-----> Using OAuth client with ephemeral=true and preauthorized=true
+-----> Using Tailscale hostname=oauth-test--
+>>> mocked tailscaled -verbose 1 call <<<
+>>> mocked tailscale call
+--authkey=tskey-client-oauth-test?ephemeral=true&preauthorized=true
+--hostname=oauth-test--
+--accept-dns=false
+--accept-routes=false
+--advertise-exit-node=false
+--shields-up=false
+--advertise-tags=tag:heroku
+<<<
+-----> Tailscale started
diff --git a/test/test-heroku-tailscale-start.sh b/test/test-heroku-tailscale-start.sh
@@ -13,36 +13,75 @@ function tailscale() {
   # Sleep to allow tailscaled to finish processing in the
   # background and avoid flapping tests.
   sleep 0.01
+
+  # Extract parameters from the command line
+  local auth_key=""
+  local hostname=""
+  local accept_dns=""
+  local accept_routes=""
+  local advertise_exit_node=""
+  local shields_up=""
+  local advertise_tags=""
+
+  while [[ "$#" -gt 0 ]]; do
+    case $1 in
+      --authkey=*) auth_key="${1#*=}" ;;
+      --hostname=*) hostname="${1#*=}" ;;
+      --accept-dns=*) accept_dns="${1#*=}" ;;
+      --accept-routes=*) accept_routes="${1#*=}" ;;
+      --advertise-exit-node=*) advertise_exit_node="${1#*=}" ;;
+      --shields-up=*) shields_up="${1#*=}" ;;
+      --advertise-tags=*) advertise_tags="${1#*=}" ;;
+    esac
+    shift
+  done
+
   echo ">>> mocked tailscale call
---authkey=${TAILSCALE_AUTH_KEY}
---hostname=${TAILSCALE_HOSTNAME:-test}
---accept-dns=${TAILSCALE_ACCEPT_DNS:-true}
---accept-routes=${TAILSCALE_ACCEPT_ROUTES:-true}
---advertise-exit-node=${TAILSCALE_ADVERTISE_EXIT_NODE:-false}
---shields-up=${TAILSCALE_SHIELDS_UP:-false}
+--authkey=${auth_key}
+--hostname=${hostname}
+--accept-dns=${accept_dns}
+--accept-routes=${accept_routes}
+--advertise-exit-node=${advertise_exit_node}
+--shields-up=${shields_up}${advertise_tags:+
+--advertise-tags=${advertise_tags}}
 <<<"
 }
 
 export -f tailscale
 
 
+# Test 1: Basic sanity test with traditional auth key
 run_test sanity heroku-tailscale-start.sh
+
+# Test 2: Traditional auth key with all env vars
 TAILSCALED_VERBOSE=1 \
-  TAILSCALE_AUTH_KEY="ts-auth-test" \
+  TAILSCALE_AUTH_KEY="tskey-auth-test" \
   TAILSCALE_HOSTNAME="test-host" \
   TAILSCALE_ACCEPT_DNS="false" \
   TAILSCALE_ACCEPT_ROUTES="false" \
   TAILSCALE_ADVERTISE_EXIT_NODE="true" \
   TAILSCALE_SHIELDS_UP="true" \
   run_test envs heroku-tailscale-start.sh
 
+# Test 3: Traditional auth key with hostname generation
 TAILSCALED_VERBOSE=1 \
-  TAILSCALE_AUTH_KEY="ts-auth-test" \
+  TAILSCALE_AUTH_KEY="tskey-auth-test" \
   HEROKU_APP_NAME="heroku-app" \
   DYNO="another_web.1" \
   HEROKU_SLUG_COMMIT="hunter20123456789"\
   TAILSCALE_ACCEPT_DNS="false" \
   TAILSCALE_ACCEPT_ROUTES="false" \
   TAILSCALE_ADVERTISE_EXIT_NODE="true" \
   TAILSCALE_SHIELDS_UP="true" \
-  run_test hostname heroku-tailscale-start.sh
+  run_test hostname heroku-tailscale-start.sh
+
+# Test 4: OAuth client with tags (should succeed)
+TAILSCALED_VERBOSE=1 \
+  TAILSCALE_AUTH_KEY="tskey-client-oauth-test" \
+  TAILSCALE_ADVERTISE_TAGS="tag:heroku" \
+  TAILSCALE_HOSTNAME="oauth-test" \
+  TAILSCALE_ACCEPT_DNS="false" \
+  TAILSCALE_ACCEPT_ROUTES="false" \
+  TAILSCALE_ADVERTISE_EXIT_NODE="false" \
+  TAILSCALE_SHIELDS_UP="false" \
+  run_test oauth-with-tags heroku-tailscale-start.sh
