Docs / Admin

Server role accounts with ACL tags

Tags let you assign an identity to a device that is separate from human users. This is most useful when adding servers to your Tailscale network: you usually want servers to be identified based on what they do, not based on which member of your ops team happened to enroll it.

Other systems sometimes call this a “role account”, to signify that the identity is based on the device’s role, not a human identity. Tags are similar to role accounts, but more flexible: whereas a device can only be signed in as a single user, you can assign many tags to a device.

A device’s identity is the combination of all its tags, and allows you to construct elaborate attribute-based access control (ABAC) rules using Tailscale’s network ACL system.

Once a device has been tagged, it loses the access permissions of the human user who tagged it, and acquires any access permissions granted to its tags. In other words, if you log into a device as [email protected] and then tag it with tag:server, the device no longer has any of the network permissions granted to [email protected], and instead is subject to the access rules for tag:server.

This feature is currently in beta. During the beta it is possible to re-tag a node without reauthenticating. This means someone with root access on the device can change or delete tags (subject to the tagOwners policy) at any time. This could be used to get access that would normally not be available to the node. When this feature is officially supported, it will require an interactive login when changing tags.

Setting up a tag

Before you can assign a tag to a device, you have to tell Tailscale which users are allowed to assign that tag. This is because tags usually get referenced in access control rules, so the ability to assign a tag to a device translates to granting new access permissions to that device. As such, Tailscale requires you to explicitly define who is allowed to use a tag to grant its permissions on a device.

Tag owners are defined in the ACL policy file, which you can edit through the admin console, or through the Tailscale API. You can find the full documentation on tag owners in the ACL reference manual.

To get started, here is a short example of an ACL policy file that assigns the single owner [email protected] to the tag tag:server:

{
  // (other ACL policy entries here)

  "tagOwners": {
    "tag:server": ["[email protected]"]
  }
}

Tagging a device

We currently only support tagging devices via CLI, including Linux, macOS, and Windows devices. You assign tags to a device by adding the --advertise-tags option to tailscale up. That is, if you initially added the device to your network by running…

sudo tailscale up

… then you would convert that device to a tagged device by running:

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

If you want to assign multiple tags to a device, comma-separate them like this:

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

The currently signed-in user must be an owner of all the tags you assign. That is, if you previously ran tailscale up and signed in as [email protected], you can only assign tags that are owned by [email protected].

If your device is not currently signed in, you’ll be asked to authenticate as usual as part of the tailscale up operation.

To undo the tagging operation and revert the device to being identified by its authenticated user, use the --advertise-tags flag without any value:

sudo tailscale up --advertise-tags=

If the device is already logged in, and you need to change the signed-in user because the current user doesn’t have tag ownership, add the --force-reauth flag to the command:

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

You can then log in again as the appropriate user.

Tags combine well with authentication keys, allowing you to automate provisioning of a device with tags:

sudo tailscale up --authkey=KEY --advertise-tags=tag:server

Using tags for access control

Once you’ve tagged some devices, you can write access control rules that grant permissions based on tags. You can consult the ACL reference manual for a full list of possibilities, but here are a few simple examples of access rules we’ve found useful.

This rule grants SSH access to all devices tagged as servers, for members of the SRE group:

{
  "acls": [
    {
      "action": "accept",
      "users": ["group:sre"],
      "ports": ["tag:server:22"]
    }

    // Other access rules here...
  ]

  // Other policy configuration here...
}

This single rule will automatically adjust the entire network’s access filters as new devices are tagged with tag:server, or as members are added or removed from group:sre.

This rule allows devices tagged with tag:testbed to communicate freely with each other:

{
  "acls": [
    {
      "action": "accept",
      "users": ["tag:testbed"],
      "ports": ["tag:testbed:*"]
    }

    // Other access rules here...
  ]

  // Other policy configuration here...
}

This kind of rule is very useful to create lower-security “sandbox” environments within your network, in which communication is not restricted, but with a strict perimeter that prevents testbed devices from communicating with more important systems.

Of course, you can mix up source and destination tags. For example, this rule grants web frontends and SREs access to database servers:

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

    // Other access rules here...
  ]

  // Other policy configuration here...
}

Last updated