Group devices with tags

Tags are similar to service accounts but more flexible: you can assign many tags to a device, whereas only a single user can sign in on a device. They let you assign an identity to a device separate from human users. You can use that identity to select devices when creating policies in the tailnet policy file. For example, you can use grants or ACLs to grant nodes access to network resources based on their tags.

Tags are ideal for managing devices you don't want to be tied to a specific user (such as a server hosting a web application) because removing a user also removes all their devices. If you link a service-providing device to a user, you lose that device if you remove the user. Removing a user won't affect the device if you use tags to manage the device instead. Do not use tags to associate a user device with a user account. Tags are not designed to tie individual users to a device. They're intended to manage devices with service account roles. Using tags as a substitute for users poses a security risk because the user's devices will remain on your network even if you remove the user.

Tags provide a way to allow multiple users to manage a device. When you manage devices with users, you must link each device to a single user, which isn't ideal for devices that host shared resources. However, when you manage devices with tags, you can assign one or more users as tag owners with tags. These users can manage all the devices with the tags they own.

Working with tags

Use the following sections to learn about working with tags:

• Define tags.
• Define tag owners.
• Apply tags to a device.
• Apply a tag from another tag.

Define a tag

Before assigning a tag to a device, you must create the tag in the tailnet policy file and define who can use that tag.

The following example creates the tag tag:server and assigns dave@tailscale.com as the sole owner. Only the tag owner can apply the tag.

{
  "tagOwners": {
    "tag:server": ["dave@tailscale.com"],
  }
}

Tailscale ignores tag name case and parses all tags in the tailnet policy file as lowercase.

Define tag owners

You must explicitly define who can use a tag to grant its permissions on a device. You can define tag owners in the tagOwners section of the tailnet policy file.

One tag can be the owner of another tag. For example, tag:deployment can own tag:prod and tag:test.

A tag can also have no owners, which is equivalent to setting the tag owner to autogroup:admins. You apply the ownerless tags to devices from the admin console and as part of an auth key.

The following example shows the tag:infrastructure with no owners.

{
  "tagOwners": {
    "tag:server": ["dave@tailscale.com"],
    "tag:infrastructure": [],
  }
}

Apply a tag to a device

You can tag devices using the admin console, the Tailscale CLI, or the Tailscale API.

Apply a tag to a device in the admin console

You must be an Owner, Admin, or Network admin of a tailnet to tag a device from the admin console. You don't need to re-authenticate because the current user is automatically used to authenticate the device.

To tag a device from the admin console:

1. Open the Machines page in the admin console.
2. Find the row corresponding to the device you are interested in.
3. Select on the menu at the far right, then select the Edit tags option.
4. Add, change, or remove desired tags. To apply a tag, it must already exist in the tailnet policy file.
5. Select Save to apply tags.

Owners, Admins, and Network admins can apply any tag from the admin console even if they don't own the tag.

Apply a tag to a device with the CLI

You can use the Tailscale CLI to add and remove tags from devices running Linux, macOS, or Windows. To tag other devices, use the admin console.

To assign tags to a device using the CLI, run tailscale login command with the --advertise-tags=tag:<tag-name> flag.

sudo tailscale login --advertise-tags=tag:server

To assign multiple tags to a device, pass multiple tags (separated with commas) to the --advertise-tags flag.

sudo tailscale login --advertise-tags=tag:server,tag:development

To remove all tags from a device, use the --advertise-tags= flag without any values.

sudo tailscale login --advertise-tags=

You might need to change the signed-in user on the device if it's already authenticated with another user. To re-authenticate with the current user, add the --force-reauth flag to the command:

sudo tailscale login --advertise-tags=tag:server --force-reauth

Apply a tag to a device using the API

You can apply a tag to a device using the Update device tags method from the Tailscale API.

To apply a tag this way, send a POST request for a device, with the body specifying the desired tags. For example:

curl https://api.tailscale.com/api/v2/device/11055/tags \
-u "tskey-<key>" \
-H "Content-Type: application/json" \
--data-binary '{"tags": ["tag:foo", "tag:bar"]}'

Apply a tag from another tag

You can apply different tags from those in the auth key when you authenticate. However, doing so replaces the device's existing tags.

Applying a tag from another tag is useful for larger infrastructure deployments, where you might need to tag many servers, typically using a deployment tool. For example, you could have your deployment system tagged with tag:deployment-1, which owns both tag:prod-2 and tag:test-2:

  "TagOwners": {
    "tag:deployment-1": ["alice@tailscale.com"],
    "tag:prod-2": ["tag:deployment-1"],
    "tag:test-2": ["tag:deployment-1"],
  },

You could generate an auth key <key-1> with the tag tag:deployment-1, and make it available to the deployment tool. Then, depending on what workload you deploy, the system authenticates the device and applies the correct infrastructure tag, which enforces the correct access controls. When spinning up a new production server, the deployment tool could tag the device as tag:prod-2:

sudo tailscale up --authkey=<key-1> --advertise-tags=tag:prod-2

Authentication and authorization

Tags are authenticated as a user but authorized as a tag. Unlike service accounts, tags aren't a new identity for authentication but rely on existing user identities from your identity provider. Adding a tag to a device replaces the prior user authentication on that device.

After you tag a device, it loses the access permissions of the human user who tagged it and acquires any access permissions granted to its tags. If you log into a device as dave@tailscale.com and tag it with tag:server, the device loses all the network permissions granted to dave@tailscale.com and gains all the access rules for tag:server. Deleting the user who added the device doesn't remove the device.

The user currently signed into Tailscale on the device must be a tag owner of all the tags you assign. If you previously ran tailscale up and signed in as dave@tailscale.com, you can only assign tags that dave@tailscale.com owns.

You might need to re-authenticate if you update the tags for a device by adding, changing, or removing tags. If a device isn't authenticated with a Tailscale account, Tailscale asks you to authenticate as part of the tailscale up operation.

Grants and tags

You can use tags as part of a grants object in your tailnet policy file to target a group of devices with a common tag for the network source (src) or network destination (dst).

The following example grants devices with the prod tag access to devices with the tailsql tag.

{
  "grants": [{
    "src": ["tag:prod"],
    "dst": ["tag:tailsql"],
  }]
}

ACLs and tags

You can use tags as part of access control lists (ACLs) to make it easier to manage which types of devices should be able to communicate. For example, you might tag a production server tag:prod and a production database tag:prod, and allow all tag:prod devices to communicate with each other in your network rather than specifying each device individually.

The following example tailnet policy file lets all devices tagged tag:prod communicate with each other.

{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:prod"],
      "dst": ["tag:prod:*"],
    },
  ],
}

Use tags in ACLs for access control

After you've tagged some devices, you can write access control rules that grant permissions based on tags. The following sections document examples of common use cases. Refer to Network access controls for a complete list of possibilities.

Grant SSH access based on tags

The following example ACL policy grants SSH access to all devices tagged with tag:server for members of the Site Reliability Engineers (SRE) group (group:sre).

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:sre"],
      "dst": ["tag:server:22"],
    }
  ]
}

This single policy automatically adjusts the entire network's access filters when you:

• Tag new devices with tag:server
• Add members to group:sre
• Remove members from group:sre

Create a sandbox for untrusted devices

The following example ACL policy allows all devices tagged with tag:testbed to connect. This creates a lower-security "sandbox" environment for testbed devices while restricting access to higher-security or critical systems in your network.

{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:testbed"],
      "dst": ["tag:testbed:*"],
    }
  ]
}

Grant web servers access to databases

The following example grants web frontends (tag:webserver) and SREs (group:sre) access to database servers (tag:database).

{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:webserver", "group:sre"],
      "dst": ["tag:database:*"],
    }
  ]
}

Use tags in ACL tests

To ensure that the ACLs for your tagged devices are working as expected, you can use ACL tests to verify your tailnet policy file before saving and applying it.

For example, to verify that your tailnet policy file allows users in the group:sre to access devices tagged tag:prod, you might write an ACL like the following example:

"tests": [
  {
    "src": "group:sre",
    "accept": ["tag:prod:1234"],
  },
],

Auth keys and tags

You can use auth keys with tags to automatically apply specific tags to devices when they authenticate.

Use a tag with an auth key

You can specify a tag when connecting a device to a tailnet using an auth key. Using an auth key with a tag lets you automatically tag the device when you authenticate.

1. Generate an auth key with the new tags.
2. Specify that auth key when authenticating a device. The tag is automatically applied.

Generate an auth key with a tag

When you generate a new auth key, you can specify the tags to apply when the auth key is used. A user can only add tags for which they are a tagOwner unless they are an Owner, Admin, or Network admin. You can generate an auth key with a tag using the admin console or the Tailscale API.

To generate an auth key with a tag from the admin console:

1. Open the Keys page in the admin console.
2. Select Generate auth key.
3. Enable adding tags to the auth key.
4. Select Add tags to add tags to the auth key.
5. Select Generate to generate the auth key.

To generate an auth key with a tag using the Tailscale API:

1. Send a POST request to the /api/v2/tailnet/:tailnet/keys endpoint, specifying desired tags as part of the request.

   {
       "capabilities": {
           "devices": {
               "create": {
                   "tags": [
                       "tag:montreal-webserver",
                       "tag:api-server",
                   ]
               }
           }
       },
   }
   

2. The server responds with a JSON message with the generated key in the key member.

   {
     "id": "k123456CNTRL",
     "key": "tskey-k123456CNTRL-abcdefghijklmnopqrstu",
     "created": "2021-12-09T09:20:52Z",
     "expires": "2022-03-09T09:20:52Z",
     "capabilities": {
       "devices": {
         "create": {
           "reusable": false,
           "ephemeral": false,
           "tags": ["tag:montreal-webserver", "tag:api-server"]
         }
       }
     }
   }
   

Then, to use the auth key, pass it to the --authkey flag when you run tailscale login.

sudo tailscale login --authkey=<key>

Authenticate the device with the auth key

If you have an auth key with tags, you do not need to specify the tags when you authenticate. Tailscale automatically applies the tags.

sudo tailscale login --authkey=<key>

To re-tag the device to add or remove tags, you can do one of the following:

• Generate a new auth key with the new set of tags.
• Modify tagOwners.

Key expiry

When you apply a tag to a device for the first time and authenticate it, the tagged device's key expiry is disabled by default.

If you change the tags on the device from the admin console, Tailscale CLI, or the Tailscale API, the device’s key expiry will not change unless you re-authenticate. After you re-authenticate, the device's key expiry will be disabled.

You can enable or disable key expiry on a device from the Machines page of the admin console or by using the Tailscale API.

Common patterns for tag names

Tags let you reflect access patterns and network segments based on your organization's requirements. These access patterns and network segments usually fall into a few common categories. Use consistent patterns for tag names based on these categories to make your ACLs easier to understand and maintain over time. Some common categories of access to consider in your tag names are:

• Server role: for example, application server, database, or queue
• Application name: for example, support console, finance reporting, or operations dashboard
• Environment: for example, production, staging, or development
• Location: for example, americas, emea, or asia-south1

While a device can have many tags assigned to it, tags are not "joined" for the purpose of access rules. For example, you cannot define a rule that allows access to devices with both tag:prod and tag:database. Instead, you can use a composite tag such as tag:prod-database to represent this type of segmented access pattern. Below are some examples of composite tags.