Tailscale identity

Introduction

Identity is core to Tailscale as a platform and enables identity-aware connectivity for your Tailscale network (known as a tailnet). Identity ties users, devices, and traffic together so you can enforce access based on who and what is connecting.

User identity is a digital identity for an entity (such as a user or a process). An identity provider (IdP) authenticates the entity and establishes the user identity. Tailscale itself doesn't provide user identity. Instead, Tailscale delegates user authentication to native or custom OpenID Connect (OIDC) identity providers. Tailscale trusts the identity provider to authenticate the user identity.

Tailscale does however establish node identity. A node identity binds a user's identity to a specific device. So within Tailscale, a user has an identity, but a node also has an identity. As an example, user Amelie with email Amelie@example.com has a user identity provided by whichever IdP is configured for their email. When Amelie uses that email to log in to Tailscale on a laptop named Amelie-laptop, Tailscale relies on the IdP to verify the user identity. Tailscale then creates a node identity that ties the user identity to the Amelie-laptop device (the device itself, not the name of the device). The node identity is based on a cryptographic key pair. Tailscale uses the node identity when creating a tunnel between two nodes to ensure they know exactly who they are connecting to.

A tailnet is the collection of nodes which are allowed to connect, and with what access. Tailscale takes into account both the user identity and the node identity when determining what network access to grant.

Traditional network security was often based on IP addresses with the assumption that an IP address represented a single device. However, on the modern internet, IP addresses are ephemeral. Instead, Tailscale's security model is based on user identity, tags, and node identity. (Tailscale does provide stable IP addresses though.)

The following sections provide information about how Tailscale identity is used.

Define access control

Each Tailscale connection is based on identity. You can define access control policies at the network layer and application layer using grants based on this Tailscale identity. Grants reside in the tailnet policy file, which is a centralized human JSON (HuJSON) configuration file that stores parameters, policies, and settings for your tailnet.

A grant relies on a source (src) and destination (dst) that defines who can access what in your tailnet. Both fields accept a wide range of selectors that identify users, devices, groups, or IP address ranges.

You can specify sources using selectors like:

• Specific email addresses (Amelie@example.com) for individual users.
• Groups (group:engineering) for user groups.
• Tags (tag:database) for device groups.
• Roles (autogroup:admin) for administrative users.

Similarly, you can define destinations using the same types of selectors, plus special selectors like autogroup:internet.

For more information, refer to Grants.

Use Tailscale identity for authentication into applications

tsidp is an OIDC and OAuth compliant identity provider server that integrates with your tailnet. tsidp lets you use Tailscale identities for authentication into applications that support OpenID Connect as well as authenticated Model Context Protocol (MCP) client / server connections.

As another example, features like Tailscale Serve surface identity information as HTTP headers, so backends on your tailnet can identify which Tailscale user made a request.

Embed Tailscale into a Go program

tsnet is a library that lets you embed Tailscale inside a Go program. With tsnet, you can programmatically make direct connections to devices on your tailnet, just like any other device in your tailnet would. A significant advantage of tsnet is that it lets you have multiple applications, each registered as their own node, running at the same time and on the same device. Each tsnet application is its own Tailscale node, complete with its own IP address, access control rules, and even user identity.

Device ownership and authentication

Device ownership and authentication differ between user and non-user devices.

User devices

When a Tailscale user logs in to a new device (that is, a device not previously joined to a tailnet), an identity provider authenticates the user, including using any multifactor authentication settings configured for the IdP. Tailscale itself is not an identity provider and instead integrates with any IdP that is compliant with the OIDC spec.

Once logged in, the authenticated identity is part of any Tailscale connection for the user. The user "owns" the device from a tailnet perspective. If the user is removed from the tailnet, so are all devices that they own.

Tagged devices

For devices that shouldn't be owned by a user (such as a server, an IoT device, a process running in a Docker container, and others), Tailscale provides tags. Tags let you attach identity to non-user devices and also let you manage access control policies based on purpose. For example, you could apply the tag:webserver tag to a server that serves as a web server, and also apply the tag:internal-access tag to the same server if it is used only for internal access.

An authentication key (auth key) is how Tailscale can authenticate a non-user device (as well as a user device) without requiring an interactive login. Individual users or an OAuth client can create an auth key. An auth key authenticates a device to the specific tailnet in which the auth key was generated.

The owner of a device authenticated by an auth key is either the user that created the auth key, or one or more tags that the user specified when creating the auth key. Tagging a device results in the user previously associated with the device no longer owning the device. The identity used for any Tailscale connection by a tagged device is the set of tags assigned to the device.

An authenticated user or tagged device is a necessary component of a node.

How a node gets created

A node's underpinning is based on cryptographic keys, which Tailscale creates by using the WireGuard® protocol. Once a node is created, the node provides identity for an authenticated entity, the device to which it is tied, and the tailnet to which the node belongs.

When you install the Tailscale client on a device, Tailscale creates a machine public/private key pair. When the Tailscale control plane needs to interact with a device, it uses the machine key to cryptographically verify the identity of a device. A machine's private key never leaves its device. Tailscale handles machine keys automatically, so users don't need to interact with them.

A node is an authenticated entity (such as a user or a process) that is bound to a specific device, through knowledge of the device's machine private key. The first time an entity uses the Tailscale client to authenticate on a device, Tailscale creates a node public/private key pair on behalf of the authenticated entity. Tailscale validates the device's identity through its machine key, and relies on an entity's authentication to form the node.

A node's private key never leaves its device. The Tailscale control plane collects and distributes only node public keys.

The control plane distributes a given node's public key to all other nodes it is allowed to communicate with. When two nodes on a tailnet communicate with each other, WireGuard uses their node keys to verify node authenticity and to establish end-to-end encryption.

Like machine keys, Tailscale handles node keys automatically, so users generally don't need to interact with node keys when using Tailscale or administering a tailnet.

A tailnet's nodes appear in the Machines page of the Tailscale admin console.

Identity's role in secure connections

When a node (the source) makes a connection request to another node (the destination), the tailscaled daemon running on the destination node can look up the source's Tailscale IP address and therefore determine which user or tags own the source node. Specifically, tailscaled looks for the IP address in the network map (netmap) that each node receives from the control plane. Among other things, each node's netmap contains the set of nodes for which it can connect, as permitted by grants in the tailnet policy file.

tailscaled can determine which user or tags own the source node, so tailscaled creates rules based on any grants and ports allowed for the source. tailscaled then directs WireGuard to establish the secure connection between the nodes, as described in How connections are secured.

A destination application responding to the source can use the LocalAPI to communicate with tailscaled to get more information about the source. The LocalAPI lets you get information such as which particular node made the request, its Tailscale IP address, and which user or set of tags own the source. The LocalAPI also lets you get information about any grants that the tailnet policy file permits for the source.

If you are using Tailscale Serve, which lets you proxy traffic to a local service, you can use identity headers to get the Tailscale user associated with the source. Identity headers are populated only for users, not tagged devices.

Also with Tailscale Serve, you can use app capabilities headers to get the application capabilities permitted for the source (applies to both user devices and tagged devices). Application capabilities provide fine-grained permissions for specific features and functionality operating at higher application layers. This enables precise control over what actions nodes can perform, rather than just which network connections they can establish.

Tailscale identity is completely part of this flow, available to applications.

How connections are secured

A secure connection between two nodes relies on WireGuard public/private key pairs. Each node is aware of the public keys of the nodes for which it has access, because the Tailscale control plane distributes the public keys. When two nodes try to connect, WireGuard uses the node keys to cryptographically authenticate the nodes. If node authentication succeeds, WireGuard creates a symmetric key. WireGuard distributes the symmetric key to only those two nodes. The nodes use the symmetric key to encrypt and decrypt the packets that are exchanged during the connection.

For more information about the cryptographic underpinnings for establishing a secure connection, refer to Key management characteristics of the Tailscale Control Protocol and WireGuard's Protocol topic.

Tailscale automatic management of keys

Using WireGuard without Tailscale requires users to manually generate and distribute the keys that make end-to-end encryption possible. Tailscale, built on top of WireGuard, automatically handles key generation and distribution, so users benefit by not needing to perform the manual steps.

How devices, nodes, and user accounts relate

A single device can be registered with multiple tailnets. The Tailscale client lets you choose with tailnet to use. For example, you can switch between your personal tailnet and your company tailnet. Each of those are separate logical nodes, as they each have their own node key. They are also tied to different identities, such as your personal email address versus your work email address.

A node however belongs to only a single tailnet. For example, a user's laptop operating system can be an active node in only one tailnet at a time. However, if that user's laptop is running Tailscale in Docker containers or in tsnet applications in userspace mode, it is possible for multiple Tailscale clients, each running as their own node, to run on a single laptop. Each of these clients runs as a separate service with different IP addresses, access control rules, and user identity.

A user may have multiple email accounts, for example, a personal email account and a work email account. From Tailscale's perspective, these accounts are distinct and unrelated, even if the user logs in to those accounts on the same device.

Tailnet examples

Joining a tailnet on a new device

In this example, Amelie has approval to join the yak-bebop tailnet. Amelie installs the Tailscale client on a laptop named Amelie-laptop. During installation, Tailscale creates a machine key for the laptop, and now Tailscale knows this laptop through its machine key (it doesn't matter what the machine name is). Next, Tailscale prompts Amelie to log in. Specifically, the Tailscale client presents a URL provided by the Tailscale control plane to Amelie in the laptop's preferred web browser, and an OAuth 2.0 flow is done over TLS. Amelie logs in as Amelie@example.com and is authenticated by the identity provider set up for their email address. Because this is the first authentication of Amelie@example.com on Amelie-laptop, Tailscale creates a tailnet node based on the authenticated Amelie@example.com entity tied to the machine key that was just created. As part of creating the node, Tailscale creates a node public/private key pair. The Tailscale control plane sends the node public key to the nodes for which this new node has access. The control plan sends to the new node the public keys of the nodes for which the new node has access. This lets the new node connect to other nodes on tailnet yak-bebop.

If tailnet yak-bebop requires device approval, Tailscale won't distribute the node public key, nor share public keys from other devices with Amelie-laptop, until a yak-bebop network administrator provides approval for the Amelie-laptop device.

Switching between tailnets

In this example, Amelie has approval to join both the yak-bebop tailnet and the cat-crocodile tailnet. Amelie has already installed the Tailscale client on the device named Amelie-workstation but has not authenticated yet. Because Tailscale knows this device through its machine key, it doesn't matter what the device name is. When Amelie logs in as Amelie@example.com, Amelie is prompted to choose between tailnet yak-bebop and tailnet cat-crocodile. If Amelie chooses the tailnet yak-bebop and successfully authenticates, the device is connected to the yak-bebop tailnet. Similarly, if Amelie chooses the tailnet cat-crocodile, the device is connected to the cat-crocodile tailnet. The device, now authenticated for the Amelie@example.com email address and tied to the machine key on Amelie-workstation, can connect to other devices in the selected tailnet.

If the tailnet that Amelie chooses requires device approval, Tailscale won't distribute the new node's public key, nor share public keys from other devices to the new node, until a yak-bebop network administrator provides approval for the new node.

Amelie can continue to choose which tailnet they want to use on the Amelie-workstation laptop. The Tailscale client knows which tailnet the node is in, and a node can connect to only a single tailnet at any given time. When switching between tailnets, Tailscale will use the appropriate node key for the selected tailnet.

After the initial node creation, the Tailscale client will re-use the associated node key for connections, until the user re-authenticates. Re-authentication results in a new node public/private key pair.

Using different user accounts

In this example, Amelie has a personal email account and a work email account, and uses the same laptop to log in to Tailscale. Note that Tailscale permits only one user account at a time to log in to Tailscale on the laptop.

When Amelie logs in to Tailscale by using the personal email account, the resulting node is in the tailnet associated with the personal email account, with no knowledge of the tailnet associated with the work email account. Similarly, when Amelie logs in to Tailscale by using the work email account, the resulting node is in the tailnet associated with the work email account, with no knowledge of the tailnet associated with the personal email account.