setup

Tailscale

Purpose

Synchronises devices, users, and ACL groups from Tailscale so you can track connectivity paths and zero-trust posture.

tip

Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.

Required Fields

Provide one of tailscale_oauth_client_secret or tailscale_token. Always set tailscale_org.

Field Secret? Description
tailscale_token Yes Tailscale API access token. Leave blank if using OAuth.
tailscale_oauth_client_secret Yes Tailscale OAuth client secret (format tskey-client-<clientid>-...). Subimage derives the client ID from this value before running Cartography.
tailscale_org No Your Tailnet ID, e.g. T1234CNTRL. See Tailnet ID.
tailscale_base_url No API base URL (default https://api.tailscale.com/api/v2)

Tailnet ID

Set tailscale_org to the Tailnet ID under Settings → General in the Tailscale admin console, such as T1234CNTRL.

Tailnets created before October 2025 also show a Legacy ID, such as example.com, and the Tailscale API accepts either one. If the module already syncs with the legacy ID, keep it: Subimage identifies the tailnet in the graph by this value, so switching to the Tailnet ID adds a second tailnet instead of renaming the first.

Setup Steps

Option A — OAuth client

  1. In the Tailscale admin console, go to Settings → Trust credentials and create a new credential.
  2. Choose OAuth, set the description to subimage, and continue to Scopes.
  3. For the simplest setup, choose All - Read. For least privilege, choose Custom scopes and enable these read-only scopes:
    • General → Policy File → Read (policy_file:read)
    • General → Users → Read (users:read)
    • General → Services → Read
    • Devices → Core → Read (devices:core:read)
    • Devices → Posture Attributes → Read (devices:posture_attributes:read)
    • Settings → Feature Settings → Read (feature_settings:read)
  4. Generate the credential and copy the client secret. It looks like tskey-client-<clientid>-... and is only shown once.
  5. In Subimage, set tailscale_oauth_client_secret (the secret or its AWS Secret ARN), tailscale_org, and — optionally — tailscale_base_url. Save the module.

Subimage passes the derived client ID and client secret to Cartography. Cartography uses the OAuth client credentials flow to obtain a short-lived access token at sync time and refreshes it if it expires during a long sync.

Option B — API token

  1. In the Tailscale admin console → Settings → Keys, generate an API access token and copy it.
  2. In Subimage, set tailscale_token (the token or its AWS Secret ARN), tailscale_org, and — optionally — tailscale_base_url. Save the module.

OAuth Scopes

  • Recommended least-privilege scopes:
    • devices:core:read
    • devices:posture_attributes:read (required dependency for policy_file:read)
    • users:read
    • policy_file:read
    • feature_settings:read
    • Services read access, shown as General → Services → Read in the Tailscale trust credential wizard
  • Broad read scope: all:read also works, but grants more access than Subimage needs today.

Tailscale requires policy_file:read to be combined with devices:core:read and devices:posture_attributes:read.

feature_settings:read lets Subimage read your device posture integrations (CrowdStrike, Intune, and other posture providers). Without it, Subimage syncs the rest of the tailnet and skips them.