Grants

You can define how your Tailscale network (called a tailnet) works using tools like the tailnet policy file. The tailnet policy file consists of multiple sections, each with a different purpose. At the core of the tailnet policy is the grants array. Each entry grants source the specified capabilities on the destination. You can use the grants object to grant capabilities at the IP 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.

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 or node 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 IP layer capabilities. You can use any of the following selectors to grant access to IP 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.

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"],
  }]
}