Grants

Tailscale’s access control methodology follows the least privilege and zero trust principles. There are two ways to define access controls for your tailnet: access control lists (ACLs) and grants. Both methods follow a deny-by-default principle and are defined in the tailnet policy file using a declarative huJSON syntax.

The grants system combines network layer and application layer capabilities into a shared syntax. As a result, it offers enhanced flexibility and fine-grained control over resource access. Each grant only requires a source and a destination. Because Tailscale takes a deny-by-default approach, each grant has an implied accept action.

{
  "grants": [
    // Grants can still define network layer access controls
    {
      "src": [<list-of-sources>], // These sources (devices or users)
      "dst": [<list-of-destinations],  // can access these destination devices
      "ip": [<list-of-ports-or-protocols>], // using the following ports or protocols
    }

    // But they can also define application layer capabilities
    {
      "src": [<list-of-sources>], // These sources (devices or users)
      "dst": [<list-of-destinations],  // can access these destination devices
      "ip": [<list-of-ports-or-protocols>], // using the following ports or protocols,
      "app": {<list-of-application-capabilities>} // and once they have access, they are granted these application permissions.
    }
  ]
}

Each entry grants the source (src) specified capabilities on the destination. You can use the grants object to grant capabilities at the network layer (ip) or the application layer (app). The Tailscale policy engine compiles all capabilities and sends them to each Tailscale client. Each client then caches the policies locally to improve performance and reduce reliance on the coordination server.

Reference

The grants section of your tailnet policy file is an array of objects, where each object must have a network source field (src) and a network destination field (dst). Grant objects can optionally include the ip, app, or srcPosture fields.

• src: An array of selectors that define the source of the grant.
• dst: An array of selectors that define the destination of the grant.
• ip (Optional): An array of strings that define the network-layer capabilities to grant.
• app (Optional): A map of strings to arrays of objects that define the application-layer capabilities to grant.
• srcPosture (Optional): An array of device posture conditions to further restrict the src.
• via (Optional): A reference to one or more devices to route traffic through. Learn more about route filtering with Via.

src

The src field is an array of selectors that define the target network sources. A network source is the device or node that initiates a network communication or sends data packets.

You can use any of the following selectors to define the network source

dst

The dst field is an array of selectors that define the destination of the grant. A network destination refers to the device, user, or target that receives the data packets from the source.

You can use any of the following selectors to define the network destination:

ip

The ip field is an array of strings that grant network layer capabilities. You can use any of the following selectors to grant access to network layer capabilities:

app

The app field is an optional field that maps strings to arrays of objects that define the application layer capabilities to grant. The strings are the application layer capabilities to grant, and the objects are the parameters for those capabilities.

The specific application (such as TailSQL) defines the names of capabilities names in the format <domainName>/<capabilityName>.

• The domainName groups capabilities into namespaces to avoid collisions with other applications.
• The capabilityName defines the specific capability. For example, the TailSQL application defines the tailscale.com/cap/tailsql capability.

The specific application also defines the parameters for each capability. The Tailscale policy engine treats these parameters as opaque JSON objects. The policy engine compiles the parameters and sends them to the Tailscale clients but does not validate them. The Tailscale clients can then use these parameters to make authorization decisions locally.

srcPosture

The srcPosture field is an array of device posture conditions you can use to further restrict the network source (src). For example, you can use srcPosture to restrict access to only devices running a specific version of the Tailscale client.

via

Via introduces routing awareness to grants by letting you include a via field to specify how Tailscale can route the destination (dst) from the source (src).

You can use the via syntax to define the exit nodes, subnet routers, or app connectors a source can access when they use a specific destination. For example, you can create a grant that forces traffic through a specific exit node when it goes from the engineering team group to the GitHub app connector.

Example scenario

The following scenario demonstrates connecting an application (TailSQL) to Tailscale and fine-tuning access to TailSQL based on tags and groups.

In this example scenario, the tailnet has the following configured:

• A prod group for the production team.
• An analytics group for the analytics team.
• A TailSQL application tagged with tailsql and running on port 443.
• A Prometheus server tagged with prom.

The final example grants group:prod access to all TailSQL data sources, grants group:analytics access to the TailSQL warehouse data source, and allows Prometheus to monitor TailSQL.

{
  "grants": [
    {
      "src": ["group:prod"],
      "dst": ["tag:tailsql"],
      "ip": ["443"],
      "app": {
          "tailscale.com/cap/tailsql": [
            {
                "dataSrc": ["*"],
            }
          ]
      },
    },
    {
      "src": ["group:analytics"],
      "dst": ["tag:tailsql"],
      "ip": ["443"],
      "app": {
          "tailscale.com/cap/tailsql": [
            {
                "dataSrc": ["warehouse"],
            }
          ]
      },
    },
    {
      "src": ["tag:prom"],
      "dst": ["tag:tailsql"],
      "ip": ["443"],
    },
  ]
}