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 on 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.
- Routing traffic to pods and services within distributed Kubernetes clusters.
How app connectors work
Learn how app connectors function.
Requirements
Before you tell a device to function as an app connector, you must:
- Have a specific application in mind. For example, GitHub or Heroku.
- Configure your tailnet policy file to meet the requirements.
- Ensure the device meets all the requirements for running as an app connector.
Requirements for the tailnet policy file
Requirement | Description |
---|---|
A tag for the app connector | You have 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. |
An auto-approval policy | You have an auto-approval policy to approve routes for the app connectors automatically. You can do this by adding a rule to the autoApprovers section to automatically approve specific routes for the app connector tag. |
An access control policy | You must have an access control policy to route application-specific traffic through the app connector tag. |
A node attribute for the app connector | You have a node attribute that maps the app connector tag to the application-specific domains. |
Device requirements
Requirement | Description |
---|---|
Linux server operating system | Only devices using a Linux server operating system can be an app connector. |
Tailscale v1.54 or later | Only Tailscale versions v1.54 or later support app connectors. |
A public IP address | The device must have a publicly accessible IP address. |
IP forwarding enabled | The device must have IP forwarding enabled. |
A tag-based identity | The device must be authenticated with the tag you created to route the application traffic. The device cannot have a user-based identity. |
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
.
-
Go to the Access Control page of the admin console.
-
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 thegithub-app-connector
tag."tagOwners": { [ "group:github-admins", "tag:github-app-connector", ], },
-
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"], }, },
-
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 on the tailnet)."acls": [ { "action": "accept", "src": ["autogroup:member"], "dst": ["autogroup:internet:*"], }, ],
-
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.
- Open the Apps page of the admin console.
- Select Add app.
- In the Name section, input a memorable name for the app.
- In the Domains section, add a comma-separated list of all the domains relevant to the app.
- In the Connectors section, select a tag or set of tags referencing the app connectors to use for the app.
- Select Save.
These setting 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 on 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.
- Open the Apps page of the admin console.
- 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.
- Open the Machines page of the admin console and locate the app connector machine.
- Select the
menu next to the app connector machine.
- 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 Tailsclae 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.
Deprecation notices:
Tailscale's SNI Proxy is no longer supported as of March 1st, 2024. Use app connectors instead. To migrate, follow the steps above to set up your new app connectors, configure apps, and then remove your legacy connectors and associated configuration.
Tailscale no longer supports app connector configurations using all available connectors (wildcards). Users with app connector configurations that contain connectors: ["*"]
need to update their tailnet policy file in the Access Controls page of the admin console to use tags instead.
Wildcard workaround
If you experience the following error when attempting to update an app connector configuration, update all app connector configurations that use connectors: ["*"]
directly in your tailnet policy file.
Failed to update app connector configuration: tailscale.com/app-connectors: connector ("*") must be a tag
Here's an example of a configuration that contains connectors: ["*"]
:
"nodeAttrs": [
{
"target": ["*"],
"app": {
"tailscale.com/app-connectors": [
{
"name": "example",
"connectors": ["*"],
"domains": [
"example.com",
"*.example.com"
]
}
]
}
}
]
To replace the deprecated connectors: ["*"]
statement, define a tag (such as tag:connector
), and use it in the app configuration:
"nodeAttrs": [
{
"target": ["*"],
"app": {
"tailscale.com/app-connectors": [
{
"name": "example",
"connectors": ["tag:connector"],
"domains": [
"example.com",
"*.example.com"
]
}
]
}
}
]