Set up an app connector

App connectors let you route Tailscale network (known as a tailnet) traffic to your software as a service (SaaS), cloud, and self-hosted applications, letting users and devices on the tailnet access applications by domain names instead of IP addresses. You can also incorporate monitoring, optimization, security, and reliability into your app connector setup.

For more in-depth information about app connectors, refer to How app connectors work.

Requirements

To set up an app connector, you must have the following:

• An existing tailnet and user account with the Owner, Admin, or Network admin role for editing the tailnet policy file and managing the app connector settings in the admin console.
• The Linux device to use as the app connector with the following:
  • A publicly accessible IP address.
  • IP forwarding is enabled.
  • You can use a physical device or a VM as the app connector device.
• A SaaS or self-hosted application with administrative access.

Get started

To add a preset app type app connector in your tailnet, you must complete the following steps:

1. Add the app connector in the admin console to route traffic to your application. When you add a preset app, the nodeAttrs section of your tailnet policy file will automatically add a new target entry for the app connector. The tagOwners, autoApprovers, and grants entries must be manually added in the tailnet policy file.
2. Update your tailnet policy file with the tagOwners, autoApprovers, and grants entries to let devices in your tailnet use the app connector.
3. Configure a Linux node in your tailnet as an app connector device.
4. (Optional) Restrict application access to only the app connector device by configuring an IP allowlist in your application.

To add a custom app type app connector in your tailnet, you must complete the following steps:

1. Update your tailnet policy file to let devices in your tailnet use the app connector, by adding entries to the nodeAttrs, tagOwners, autoApprovers, and grants sections.
2. Configure a Linux node in your tailnet as an app connector device.
3. Add the app connector settings in the admin console to route traffic to your application.
4. (Optional) Restrict application access to only the app connector device by configuring an IP allowlist in your application.

Update the tailnet policy file

Configure your tailnet policy file with the necessary permissions to let devices use the app connector device.

You need to be an Owner, Admin, or Network admin to edit a tailnet policy file.

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

2. Add a tagOwners rule to define the tag name and the group of users that have the ability to assign other devices with the tag that lets them you connect to the app connector. 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 an autoApprovers rule 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 triggers route discovery. When an app connector discovers routes, it adds the identified routes and CIDR blocks to the tailnet policy file.

   The following auto-approval policy example 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. Add a grants rule 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 access control policy to your tailnet policy file that grants access to autogroup:internet (any port number) for members of the tailnet, which will also grant users access to any exit nodes in the tailnet.

     "grants": [
     {
       "src": ["autogroup:member"],
       "dst": ["autogroup:internet"],
       "ip": ["*"]
     }
   ]
   

5. Add a nodeAttrs rule to map 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 updating the tailnet policy file, configure the device to function as an app connector.

Run the following Tailscale CLI command, making sure to replace the variables in the angle brackets (<>) with the actual app connector tag name.

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

The --advertise-connector flag enables 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.

Add a preset app

Preset apps are the applications we support for automatically adding the necessary domains needed for your application, and can reduce the time needed for app connector configuration. After set up, preset apps periodically fetch domains and routes from the application's authoritative configuration and propagate any changes to the tailnet.

Tailscale supports the following preset apps:

• Confluence
• GitHub
• Google Workspace
• Jira
• Okta
• Salesforce
• Stripe

You need to be an Owner, Admin, or Network admin of a tailnet to configure a preset app.

1. Open the Apps page of the admin console.

2. In the Add an app dialog, enter the following details.

   1. Name: Enter a unique name for identifying the application.
   2. Target: Select a preset app to automatically add the domains for your application.
   3. Connectors: Select a tag or set of tags that you configured for your app connector in your tailnet policy file.

3. Select Save.

A green icon next to the app connector name indicates that it is currently active and working as expected.

Select the app connector you added for additional details you can use to administer settings on both your tailnet and your application.

Traffic to configured domains routes through tagged app connectors before reaching target domains on the internet. This routing occurs even when the originating device uses an exit node. The source IP address for this traffic appears as one of the public IP addresses from the devices running as app connectors.

Add a custom app

If your application is not available as a preset app in the admin console, you can manually configure the settings.

You need to be an Owner, Admin, or Network admin of a tailnet to add and edit app connectors.

1. Open the Apps page of the admin console.

2. In the Add an app dialog, enter the following details.

   1. Name: Enter a unique name for identifying the application.
   2. Target: Select Custom and manually enter the application domain names. If you need to add multiple domain entries, separate each one with a comma. When specifying domains, you can use wildcards for subdomains but not for top-level domains (TLDs). For example, *.example.com, *.example.co.uk, *.example.info are valid while *.com, *.co.uk, *.info are not valid.
   3. Connectors: Select a tag or set of tags that you configured for your app connector in your tailnet policy file.

3. Select Save.

A green icon next to the app connector name indicates that it is currently active and working as expected.

Select the app connector you added for additional details you can use to administer settings on both your tailnet and your application.

Edit preset apps

The Apps page of the admin console is the primary way to set up a preset app and automatically updates the presetAppID when you add an app connector. You can also manually modify the presetAppID for an app in your tailnet policy file.

The following shows an example snippet with GitHub as a preset app.

  "nodeAttrs": [
    {
      "target": ["*"],
      "app": {
        "tailscale.com/app-connectors": [
          {
            "name": "github app",
            "connectors": ["tag:code", "tag:ci-cd"],
            "presetAppID": "github"
          }
        ]
      }
    }
  ]

The following is the list of the supported preset apps as they appear in the tailnet policy file.

Remove an app connector

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

1. Open the Apps page of the admin console.
2. Select the menu next to the app connector you want to remove, and select Remove.

After you remove an app connector, traffic to the application no longer routes through the app connector. Instead, traffic to the application's domain names routes directly from the client device or through an exit node if the device uses one.

If you no longer need the app connector device in your tailnet, you can remove it.

Restrict application access by IP address

Many applications let you control access by specifying which IP addresses can connect to them. When you use an app connector, all traffic from your tailnet to the target application appears to come from the app connector's public egress IP address. This means you can add the app connector's egress IP address to your target application's trusted list of ingress IP addresses (called an IP allowlist). This ensures only users with access to the app connector can access the target application.

To set this up, find your application's IP allowlist settings and add the public IP address of each device running as an app connector. If you use multiple app connectors for redundancy, add all their public IP addresses. You can find these IP addresses in your cloud provider's management interface.

The following is a list of Tailscale's supported preset apps and links for configuring specific IP addresses (IP allowlisting) for providing exclusive access to your app connector devices.

• Confluence
• GitHub
• Google Workspace
• Jira
• Okta
• Salesforce
• Stripe

Tailscale automatically finds the preset app's IP addresses. Go to the Apps page in the admin console, select the app details you'd like to configure, and copy the Egress IPs listed. This list includes all IP addresses of all connectors configured on the associated tags. Remember to update your IP allowlist if you add new app connectors.

Limitations

• Linux is the only operating system that can be used as an app connector device in a tailnet.
• App connectors cannot be shared across multiple tailnets.
• Advertising more than 10K routes on any instance, or across the whole tailnet, will cause significant functionality issues for connecting clients.
• Tailnets are limited to advertising 250 domains across all applications.