ACL Tags

In Tailscale’s original security policy ACLs, each node’s permissions were defined by the user who had logged into the node. This is useful for access control of end user devices, but creates a problem for servers. Since every node, including a server, needs to be authenticated as some account (usually an IT or devops administrator), the server would inherit that user’s permissions, which is usually not what you want.

ACL tagging is the solution to this problem.

Tag owners

First, in the ACL configuration, you need to define a set of “tag owners”: the user accounts which are allowed to refer to a certain tag. To avoid confusion as we add new features, all tag names must start with tag:.

// Define some static groups of users, to refer to from other sections.
"Groups": {
    "group:montreal-admins": [
        "user1@example.com",
        "user2@example.com",
    ],
    "group:global-admins": [
        "all-powerful@example.com",
    ],
},

// Define who is allowed to use which tags.
"TagOwners": {
    // Everyone in the montreal-admins or global-admins group are
    // allowed to tag servers as montreal-webserver.
    "tag:montreal-webserver": [
        "group:montreal-admins",
        "group:global-admins",
    ],
    // Only a few admins are allowed to create API servers.
    "tag:api-server": [
        "group:global-admins",
    ],
},

Tagged ACL rules

Once tag owners are defined, you can refer to them from ACL rules:

"ACLs": {
    //
    // ... other ACL rules ...
    //

    // All users in Montreal are allowed to access the Montreal web
    // servers.
    {
        "Action": "accept",
        "Users": ["group:montreal-users"],
        "Ports": ["tag:montreal-webserver:80,443"],
    },

    // Admins are allowed to access ssh on Montreal web servers.
    {
        "Action": "accept",
        "Users": ["group:montreal-admins", "group:global-admins"],
        "Ports": ["tag:montreal-webserver:22"],
    },

    // Montreal web servers are allowed to make outgoing connections to
    // the API servers, but only on https port 443.
    // In contrast, this doesn't grant API servers the right to initiate
    // any connections.
    {
        "Action": "accept",
        "Users": ["tag:montreal-webserver"],
        "Ports": ["tag:api-server:443"],
    },
},

Tagging your nodes

Finally, once your tags and ACLs are defined, you can start to re-tag your nodes using the --advertise-tags option to tailscale up. Right now, only Linux-based servers can have tags. A node can request multiple tags, if you separate them with commas.

sudo tailscale up --advertise-tags tag:montreal-webserver,tag:api-server

To undo the tagging operation, re-run tailscale up without the extra flag:

sudo tailscale up

Subnet ACLs

You can now specify subnets in the security policy configuration wherever an IP address could be used before. That means you can use them in the Hosts, Users, or Ports sections, as follows.

// Hostname aliases to be used in other sections
"Hosts": {
    "myhost": "1.2.2.1",     // regular host definition
    "mynet":  "1.2.3.4/24",  // subnet definition
},

"ACLs": {
    //
    // ... other ACL rules ...
    //

    // Servers on mynet and 192.168.1.0/24 are allowed to access
    // hosts on both networks.
    {
        "Action": "accept",
        "Users": ["mynet", "192.168.1.0/24"],
        "Ports": ["mynet:*", "192.168.1.0/24:*"],
    },

    // We can also grant subnet access to users, groups, and tags.
    // In this case, we restrict access to only port 443.
    {
        "Action": "accept",
        "Users": ["group:admins", "user1@example.com",
                  "tag:api-servers"],
        "Ports": ["mynet:443", "myhost:443"],
    },
},

Pre-authenticated keys

Pre-authenticated keys (“auth keys”) allow you to bring up new nodes without doing an interactive login. This is most useful when spinning up containers, IoT devices, or using infrastructure-as-code systems like Terraform.

Auth keys are straightforward to use:

1. First, as a network admin, generate an auth key using the key generator admin page. You can choose “One-off Node Authentication” (a key that can only be used once) or “Node Authentication” (a key that can be used multiple times). This page also gives you the ability to revoke existing keys.

   Warning: be very careful with multi-use keys! These can be very dangerous if stolen. They’re best kept in a key vault product specially designed for the purpose.

2. When you bring up a node, use the --authkey option to supply the key and bypass interactive login:

   sudo tailscale up --authkey tskey-abcdef1432341818

A node authorized in this way will stay authorized, even after you delete the auth key from the admin panel. To deauthorize the node, delete it from the machines admin page.