Azure App Service Hybrid Connections

Hybrid Connections is both a service in Azure and a feature in Azure App Service. As a service, it has uses and capabilities beyond those that are used in App Service. To learn more about Hybrid Connections and their usage outside App Service, see Azure Relay Hybrid Connections.

Within App Service, Hybrid Connections can be used to access application resources in any network that can make outbound calls to Azure over port 443. Hybrid Connections provides access from your app to a TCP endpoint and doesn't enable a new way to access your app. As used in App Service, each Hybrid Connection correlates to a single TCP host and port combination. This feature enables your apps to access resources on any OS, provided it's a TCP endpoint. The Hybrid Connections feature doesn't know or care what the application protocol is, or what you are accessing. It simply provides network access.

How it works

Hybrid Connections requires a relay agent to be deployed where it can reach both the desired endpoint and Azure. The relay agent, Hybrid Connection Manager (HCM), calls out to Azure Relay over port 443. From the web app site, the App Service infrastructure also connects to Azure Relay on your application's behalf. Through the joined connections, your app is able to access the desired endpoint. The connection uses TLS 1.2 for security and shared access signature (SAS) keys for authentication and authorization.

Diagram of Hybrid Connection high-level flow.

When your app makes a DNS request that matches a configured Hybrid Connection endpoint, the outbound TCP traffic is redirected through the Hybrid Connection.

Note

This means that you should try to always use a DNS name for your Hybrid Connection. Some client software does not do a DNS lookup if the endpoint uses an IP address instead.

App Service Hybrid Connection benefits

There are many benefits to the Hybrid Connections capability, including:

  • Apps can access on-premises systems and services securely.
  • The feature doesn't require an internet-accessible endpoint.
  • It's quick and easy to set up. No gateways required.
  • Each Hybrid Connection matches to a single host:port combination, helpful for security.
  • It normally doesn't require firewall holes. The connections are all outbound over standard web ports.
  • Because the feature is network level, it's agnostic to the language used by your app and the technology used by the endpoint.
  • It can be used to provide access in multiple networks from a single app.
  • Supported in GA for Windows apps and Linux apps. It isn't supported for Windows custom containers.

Things you can't do with Hybrid Connections

Things you can't do with Hybrid Connections include:

  • Mount a drive.
  • Use UDP.
  • Access TCP-based services that use dynamic ports, such as FTP Passive Mode or Extended Passive Mode.
  • Support LDAP, because it can require UDP.
  • Support Active Directory, because you can't domain join an App Service worker.

Add and Create Hybrid Connections in your app

To create a Hybrid Connection, go to the Azure portal and select your app. Select Networking > Configure your Hybrid Connection endpoints. Here you can see the Hybrid Connections that are configured for your app.

Screenshot of Hybrid Connection list.

To add a new Hybrid Connection, select [+] Add hybrid connection. You see a list of the Hybrid Connections that you already created. To add one or more of them to your app, select the ones you want, and then select Add selected Hybrid Connection.

Screenshot of Hybrid Connection portal.

If you want to create a new Hybrid Connection, select Create new hybrid connection. Specify the:

  • Hybrid Connection name.
  • Endpoint hostname.
  • Endpoint port.
  • Service Bus namespace you want to use.

Screenshot of Create new hybrid connection dialog box.

Every Hybrid Connection is tied to a Service Bus namespace, and each Service Bus namespace is in an Azure region. It's important to try to use a Service Bus namespace in the same region as your app, to avoid network induced latency.

If you want to remove your Hybrid Connection from your app, right-click it and select Disconnect.

When a Hybrid Connection is added to your app, you can see details on it simply by selecting it.

Screenshot of Hybrid connections details.

Create a Hybrid Connection in the Azure Relay portal

In addition to the portal experience from within your app, you can create Hybrid Connections from within the Azure Relay portal. For a Hybrid Connection to be used by App Service, it must:

  • Require client authorization.
  • Have a metadata item and named endpoint that contains a host:port combination as the value.

Hybrid Connections and App Service plans

App Service Hybrid Connections are only available in Basic, Standard, Premium, and Isolated pricing SKUs. Hybrid Connections aren't available for function apps in Consumption plans. There are limits tied to the pricing plan.

Pricing plan Number of Hybrid Connections usable in the plan
Basic 5 per plan
Standard 25 per plan
Premium (v1-v3) 220 per app
Isolated (v1-v2) 220 per app

The App Service plan UI shows you how many Hybrid Connections are being used and by what apps.

Screenshot of App Service plan properties.

Select the Hybrid Connection to see details. You can see all the information that you saw at the app view. You can also see how many other apps in the same plan are using that Hybrid Connection.

There's a limit on the number of Hybrid Connection endpoints that can be used in an App Service plan. Each Hybrid Connection used, however, can be used across any number of apps in that plan. For example, a single Hybrid Connection that is used in five separate apps in an App Service plan counts as one Hybrid Connection.

Pricing

In addition to there being an App Service plan SKU requirement, there's an extra cost to using Hybrid Connections. There's a charge for each listener used by a Hybrid Connection. The listener is the Hybrid Connection Manager. If you had five Hybrid Connections supported by two Hybrid Connection Managers, that would be 10 listeners. For more information, see Service Bus pricing.

Adding a Hybrid Connection to your app programmatically

There's Azure CLI support for Hybrid Connections. The commands provided operate at both the app and the App Service plan level. The app level commands are:

az webapp hybrid-connection

Group
    az webapp hybrid-connection : Methods that list, add and remove hybrid-connections from webapps.
        This command group is in preview. It may be changed/removed in a future release.
Commands:
    add    : Add a hybrid-connection to a webapp.
    list   : List the hybrid-connections on a webapp.
    remove : Remove a hybrid-connection from a webapp.

The App Service plan commands enable you to set which key a given hybrid-connection uses. There are two keys set on each Hybrid Connection, a primary and a secondary. You can choose to use the primary or secondary key with the below commands. This option enables you to switch keys for when you want to periodically regenerate your keys.

az appservice hybrid-connection --help

Group
    az appservice hybrid-connection : A method that sets the key a hybrid-connection uses.
        This command group is in preview. It may be changed/removed in a future release.
Commands:
    set-key : Set the key that all apps in an appservice plan use to connect to the hybrid-
                connections in that appservice plan.

Secure your Hybrid Connections

An existing Hybrid Connection can be added to other App Service Web Apps by any user who has sufficient permissions on the underlying Azure Service Bus Relay. This means if you must prevent others from reusing that same Hybrid Connection (for example when the target resource is a service that doesn't have any other security measures in place to prevent unauthorized access), you must lock down access to the Azure Service Bus Relay.

Anyone with Reader access to the Relay is able to see the Hybrid Connection when attempting to add it to their Web App in the Azure portal, but they can't add it as they lack the permissions to retrieve the connection string that is used to establish the relay connection. In order to successfully add the Hybrid Connection, they must have the listKeys permission (Microsoft.Relay/namespaces/hybridConnections/authorizationRules/listKeys/action). The Contributor role or any other role that includes this permission on the Relay allows users to use the Hybrid Connection and add it to their own Web Apps.