Infrastructure

Tailscale

Connect Tailscale to Ploy to manage users and groups via your Tailscale ACL (tailnet policy file). Ploy imports your Tailscale users, reads group memberships from your ACL policy, and can update user roles and group assignments.

Before you start

You need Owner or Admin access to your Tailscale tailnet, because creating an OAuth client with user and policy-file scopes requires admin permissions. You will collect three values to paste into Ploy: your tailnet name, an OAuth client ID, and an OAuth client secret.

Step 1: Find your tailnet name

In the Tailscale admin console, go to Settings then General. Your Tailnet name is shown there. It looks like example.com or tailXXXX.ts.net.

Step 2: Create an OAuth client

  1. In the Tailscale admin console, open the Trust credentials page (under Settings; in older consoles this was OAuth clients under Settings then Keys).

  2. Select Credential, then choose OAuth.

  3. Give it a description, for example Ploy integration.

  4. Add the scopes Ploy needs (listed below), then select Generate credential.

  5. Copy the Client ID and Client Secret now. The secret is shown only once.

Scopes to add:

  • users — set to Read to import users, names, roles, and status. Set to Read and Write only if you want Ploy to change user roles.

  • policy_file — set to Read to read group memberships from your ACL. Set to Read and Write only if you want Ploy to update group memberships.

For read-only visibility (scanning only), set both scopes to Read. For automations where Ploy changes roles or group memberships, set both to Read and Write. When you select policy_file, Tailscale automatically adds a devices:core:read dependency scope. This is expected, leave it enabled.

Important: Keep the client secret secure. Ploy stores it encrypted, but if you regenerate it in Tailscale you will need to update the integration in Ploy.

Step 3: Connect in Ploy

  1. In Ploy, go to Integrations and select Tailscale.

  2. Enter your Tailnet Name from Step 1.

  3. Enter your Client ID from Step 2.

  4. Enter your Client Secret from Step 2.

  5. Save and run the connection test. A successful test confirms Ploy can read your tailnet's users.

What Ploy syncs

  • Users — display name, login name, role, status, device count, last seen time, and current connection status.

  • Groups — group names and memberships from your ACL policy.

  • Roles — owner, admin, member, it-admin, network-admin, billing-admin, and auditor.

What you can automate

These require the Read and Write scopes from Step 2.

  • Change a user's role in Tailscale.

  • Manage group memberships by updating Tailscale ACL files.

Limitations and caveats

  • Removing a role in Ploy demotes the user to member. It does not delete the user from Tailscale.

  • ACL updates use ETag-based locking. Simultaneous changes to the same tailnet's ACL can conflict, but Ploy retries on conflict.

Troubleshooting

Connection test fails. Verify your tailnet name, client ID, and client secret are correct. If you regenerated the secret in Tailscale, update it in Ploy. Confirm the OAuth client has at least users Read and policy_file Read access to your tailnet.

Users or groups not appearing. Check that your OAuth client has the users and policy_file scopes. If the ACL policy is empty or has no groups defined, Ploy will not import any groups.

Role or group changes fail. Confirm the OAuth client has the Read and Write variant of users and policy_file. Another tool or admin may have updated the ACL at the same time. Wait a moment and retry.

Was this helpful?
Was this helpful?