App connectors

An app connector is a device with a tag-based identity that you configure to route traffic for a specific application. App connectors let you control access to third-party and software as a service (SaaS) applications available over your Tailscale network (known as a tailnet) in the same way that you would for self-hosted applications.

When you use an app connector, you specify the applications to make accessible over the tailnet, then add the domains for those applications. Tailscale then forces any tailnet traffic for that application to a device running an app connector before routing it to the application domains.

Using an app connector is useful for applications that only permit access to specific IP addresses through using an allowlist. You can add the IP address of the device running the app connector the allowlist, and all devices in the tailnet will use that IP address when using that application.

Some other common use cases for app connectors include:

• Routing traffic to internal applications that have dynamic IP addresses and can't install Tailscale.
• Routing traffic to SaaS applications, such as GitHub, Linear, or Adobe.

Requirements

Before you tell a device to function as an app connector, you must:

1. Have a specific application in mind. For example, GitHub or Heroku.
2. Configure your tailnet policy file to meet the requirements.
3. Ensure the device meets all the requirements for running as an app connector.

Requirements for the tailnet policy file

Device requirements

Set up an app connector

Setting up an app connector involves selecting a tag, selecting a device that meets the minimum requirements, configuring your tailnet policy file, configuring your device, and adding an app connector in the admin console.

Configure the tailnet policy file

To facilitate using an app connector, you must configure multiple sections of your tailnet policy file. This involves defining tagOwners, autoApprovers, acls, and nodeAttrs.

1. Go to the Access Control page of the admin console.

2. Define a tag to identify app connectors for the specific application (such as GitHub or Heroku). You can do this by defining a tag owner for the tag. The following example defines the github-admins group as an owner of the github-app-connector tag.

   "tagOwners": {
     "tag:github-app-connector": [
       "group:github-admins",
     ],
   },
   

3. Add a rule to the autoApprovers section to automatically approve specific routes for the app connector tag.

   After you configure app traffic to route through an app connector, any DNS request to the configured app domains will trigger route discovery. When an app connector discovers routes, it adds the identified routes and CIDR blocks to the tailnet policy file, to be approved by an administrator.

   You can use the autoApprovers feature to automatically accept discovered routes added to your tailnet policy file.

   The following auto-approval policy automatically approves all IPv4 and IPv6 routes for devices using the github-app-connector tag.

     "autoApprovers": {
     "routes": {
       "0.0.0.0/0": ["tag:github-app-connector"],
       "::/0": ["tag:github-app-connector"],
     },
   },
   

4. Create an access control policy to route application-specific traffic through the app connector tag.

   You must allow tailnet devices to access the routes an app connector advertises. One way to do this is to add an ACL to your tailnet policy file that grants access to autogroup:internet:* for members of the tailnet (which will also grant users access to any exit nodes in the tailnet).

     "acls": [
     {
       "action": "accept",
       "src": ["autogroup:member"],
       "dst": ["autogroup:internet:*"],
     },
   ],
   

5. Configure a node attribute that maps the app connector tag to the application-specific domains. The following example node attribute definition configures the github-app-connector tag for GitHub domains.

     "nodeAttrs": [
     {
       "target": ["*"],
       "app": {
         "tailscale.com/app-connectors": [
           {
             "name": "GitHub",
             "connectors": ["tag:github-app-connector"],
             "domains": [
               "github.com",
               "*.github.com"
             ]
           }
         ]
       }
     }
   ]
   

Configure a device as an app connector

After you ensure your tailnet policy file is configured correctly, and the device meets the minimum requirements, you can configure the device to function as an app connector.

Run the Tailscale client with the --advertise-connector and --advertise-tags flags. The --advertise-connector flag tells the Tailscale process to enable the device to route traffic for specific domains according to the configuration in the tailnet policy file. The --advertise-tags flag tells the Tailscale client to authenticate the device with the provided tags.

You can pass these flags to the tailscale up or the tailscale set commands.

tailscale <up|set> --advertise-connector --advertise-tags=tag:<connector-tag-name>

Make sure to replace the variables in the angle brackets (<>) with the correct values.

Add an app in the admin console

You need to be an Owner, Admin, or Network admin of a tailnet in order to add a domain to an app connector.

1. Open the Apps page of the admin console.
2. Select Add app.
3. In the Name section, input a memorable name for the app.
4. In the Domains section, add a comma-separated list of all the domains relevant to the app.
5. In the Connectors section, select a tag or set of tags referencing the app connectors to use for the app.
6. Select Save.

These settings tell Tailscale to route traffic to the specified domains through the app connector. Traffic to the configured domains will now be carried over the tailnet to the tagged app connectors before egressing over the internet to the target domains, even when the device is using an exit node. The source IP address of traffic from your tailnet will be one of the public IP addresses of the devices running as an app connector.

Add an app connector to an IP allowlist

Many SaaS (software as a service) applications let you restrict access to only trusted IP addresses. Using an app connector lets you always egress from a single or small set of known IP addresses, ensuring traffic to the SaaS application is coming from users and devices in your tailnet. To configure the IP allowlist, locate your SaaS provider's IP allowlist configuration page and add the public IP addresses of every device running as an app connector. If you use multiple app connectors in high availability mode, add all app connector public IP addresses. You can often find the public IP address in your infrastructure provider's administrative console.

For ease of use, Tailscale automatically discovers egress IP addresses. For any app, navigate to the Apps page in the admin console, select the app you'd like to configure, and copy the Egress IPs listed. This includes all IP addresses of all connectors configured on the associated tags. Remember to update your IP allowlist if you add new app connectors.

The Tailscale IP addresses of app connectors are private to the tailnet and do not represent the public IP address from which an app connector will egress internet-bound traffic.

Remove an app from an app connector

You must be an Owner, Admin, or Network admin of a tailnet in order to remove an app from an app connector.

1. Open the Apps page of the admin console.
2. Select the menu next to the relevant app, and select Remove.

After you remove an app, the app traffic will no longer route through an app connector. Traffic to domain will route directly from the client device or through an exit node (if the device is using an exit node).

Remove an app connector

You must be an Owner, Admin, or Network admin of a tailnet in order to remove an app connector.

1. Open the Machines page of the admin console and locate the app connector machine.
2. Select the menu next to the app connector machine.
3. Select Remove, then confirm the removal.

Considerations

• App connectors support Tailscale high availability options.
• When configuring a SaaS provider using this method, the provider often uses multiple domains. You must add all of these domains to your app configuration. A helpful resource for this is the v2fly project, which curates a list of known domains used by various services.
• If a user disables accept routes on their Tailscale client, they won't route through the app connectors. You can use a system policy to prevent users from disabling the accept routes setting.
• If the user disables accept dns, they will still route through the app connectors if accept routes is enabled and the routes are already established on that app connector.
• If an app connector becomes unavailable while in use, and no other app connectors are available, resolution to the domain will begin to fail until the app connector is again online.
• To view all routes configured for use with app connectors, go to the Apps page of the admin console.

"nodeAttrs": [
  {
    "target": ["*"],
    "app": {
      "tailscale.com/app-connectors": [
        {
          "name": "example",
          "connectors": ["*"],
          "domains": [
            "example.com",
            "*.example.com"
          ]
        }
      ]
    }
  }
]

"nodeAttrs": [
  {
    "target": ["*"],
    "app": {
      "tailscale.com/app-connectors": [
        {
          "name": "example",
          "connectors": ["tag:connector"],
          "domains": [
            "example.com",
            "*.example.com"
          ]
        }
      ]
    }
  }
]