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.
Warnings about tags
Only use tags for non-human machines. Users can only access and use Tailscale through their designated user accounts. Using tags to annotate user devices is poor practice because a device cannot simultaneously have a user and a tag. Adding a tag to a device removes the associated user. Devices can have tags or a user account, not both.
Use tags to:
- Manage devices you don't have tied to a specific user (such as a server hosting a web application).
- Manage devices you want to allow multiple users to manage.
Do not use tags to:
- Annotate user devices.
- Link a user device with a user.
Working with tags
Use the following sections to learn about working with tags:
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.
When you re-authenticate and tag a device, it generates a new node key for the device. The Tailscale IP for the device does not change.
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:
- Open the Machines page in the admin console.
- Find the row corresponding to the device you are interested in.
- Select on the menu at the far right, then select the Edit tags option.
- Add, change, or remove desired tags. To apply a tag, it must already exist in the tailnet policy file.
- 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.
You cannot remove all tags from a tagged device in the admin console because the device must have an identity. Either assign the device a new tag or re-authenticate to Tailscale from the device.
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 cannot remove tags using the --advertise-tags
flag if the device uses an auth key. Instead, generate a new auth key with the new set of 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.
A device's identity is the combination of all its tags (not the intersection). For example, you might have a device that is both a tag:server
and part of your tag:prod
network. You can assign both tags to the device to manage permissions for these tags separately.
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.
- Generate an auth key with the new tags.
- 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:
- Open the Keys page in the admin console.
- Select Generate auth key.
- Enable adding tags to the auth key.
- Select Add tags to add tags to the auth key.
- Select Generate to generate the auth key.
The Pre-approved option will only display in the dialog if device approval is enabled in your Tailscale network.
To generate an auth key with a tag using the Tailscale API:
-
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", ] } } }, }
-
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 re-authenticate a device tagged before March 10, 2022, its expiry will be 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
, orasia-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.
Tag | Access control |
---|---|
tag:prod-app | To production application servers |
tag:nonprod-db | To non-production database servers |
tag:prod-app-finance-reporting | To the production finance reporting application |
tag:prod-emea-app-support-console | To the production support console application in EMEA |
tag:prod-asiasouth1-ingest-logging | To the production logging ingest endpoint in asia-south1 |