Tailscale
Purpose
Synchronises devices, users, and ACL groups from Tailscale so you can track connectivity paths and zero-trust posture.
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
- In the Tailscale admin console, go to Settings → Trust credentials and create a new credential.
- Choose OAuth, set the description to
subimage, and continue to Scopes. - 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)
- General → Policy File → Read (
- Generate the credential and copy the client secret. It looks like
tskey-client-<clientid>-...and is only shown once. - 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
- In the Tailscale admin console → Settings → Keys, generate an API access token and copy it.
- 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:readdevices:posture_attributes:read(required dependency forpolicy_file:read)users:readpolicy_file:readfeature_settings:read- Services read access, shown as General → Services → Read in the Tailscale trust credential wizard
- Broad read scope:
all:readalso 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.