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 name, e.g. example.com |
tailscale_base_url |
No | API base URL (default https://api.tailscale.com/api/v2) |
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.