• Products
  • Documentation
  • Resources

Security overview of application tunnels

This page explains the main concepts related to the security of Cloud and Data Center connectivity when using application tunnels, including authentication and authorization mechanisms used when making requests and example request flows.

What are application tunnels?

Application tunnels are a communication layer that allows you to make requests from Atlassian cloud products, such as Jira or Confluence, to the self-managed ones that live in your network – Jira, Confluence, Bitbucket, and Bamboo. In short, they’re responsible for routing the HTTP requests from cloud to server.

Traffic encryption

The traffic that goes through the tunnels is encrypted using TLS v1.3. While you might have noticed that the tunneled app links (a type of app links used exclusively by the tunnels) are configured with HTTP inside the product, it doesn’t mean the traffic itself isn’t secure.

Traffic routing

App tunnels are implemented using secure WebSocket protocols, established from your self-managed product by an Atlassian Cloud service called Tunnel server.

You could view every app tunnel as an uninterrupted line from Atlassian Cloud to your self-managed product through the public internet.

The tunnels are only responsible for routing the requests to your network. They don’t verify or alter any application-level authentication or authorization mechanisms. This means that just creating a tunnel isn’t enough for the cloud requests to be processed in your self-managed product.

High-level request flow

The following diagram shows an example tunnel that goes from cloud to your network through the firewall, until it reaches the Tunnel client and Tunnel connector in the application server (it doesn’t illustrate the entire request flow):

High-level architecture view of app tunnels between cloud and server.

Once the request from cloud passes through the tunnel, it goes to the Tunnel connector configured in the application server for your product. At this point, your Atlassian self-managed product validates the request, checking for authentication:

  • If the requests is for a resource that doesn’t require authenticating, it will be allowed and the results will be returned to the caller.

  • If the resource is restricted, the request will be blocked by your self-managed product.

The authentication and authorization methods are defined by the caller – Atlassian Cloud products. Currently, the only supported way for making requests is by using app links, which use OAuth 1.0a.

While all the communication that goes through the tunnels is using Atlassian app links, it’s technically possible to make requests with other authentication types. However, right now, we’re only using app links.

App tunnel and connection security

When you create an app tunnel, we generate a security key and pass it to you. You then add it to your self-managed instance, which allows that instance to establish the connection.

The security key is a random byte array:

  • Cloud side: It’s stored at rest and encrypted with AES using a 256-bit key.

  • Self-managed side: It’s stored at rest in the database, by default encrypted with the AES mechanism. You can change that algorithm if you’d like.

When added to your self-managed instance when configuring the tunnel, the security key is passed to a separate client process that’s started by the Tunnel client app in each of your Data Center nodes. This client process will use the key to authenticate itself with Atlassian Cloud.

To make sure the client process is actually connecting to Atlassian Cloud, it verifies the certificate of the tunnel.services.atlassian.com hostname, using the Certificate Authority (CA) chain on the instance.

Authentication and authorization by self-managed products

App tunnels don’t provide authentication or authorization for the requests that go through them. The tunnels only verify:

  • the client (by the security key)

  • the cloud organization where the request originated, to make sure it’s the same as the one the tunnel belongs to

This is to prevent hijacking the tunnel by a malicious actor.

When a request goes through the tunnel, your self-managed product is responsible for authenticating and authorizing it. Since all the features that require cross-deployment (cloud and server) connectivity rely on tunneled app links, the authentication and authorization methods are based on OAuth 1.0a.

In this flow, OAuth 1.0a is used to:

  • get the user consent and authorization of the link

  • make requests on user’s behalf

All requests are made in user context and not by using service to service authentication methods. This means that your self-managed product, as well as your admins and users, can control access and permissions for certain resources. Permissions and restrictions in your self-managed products are respected.

Example request flow with details on authentication

Let’s look at an example of cloud to server request flow to see how authentication and authorization works.

To make it more specific, this example assumes that:

  • An admin created an app tunnel and a tunneled app link between Confluence Cloud and Jira Data Center.

  • A user opens a Confluence Cloud page that has an issue link to an issue in Jira Data Center.

  • The user didn’t use the functionality related to this app link before, i.e. they’re trying to view the resources for the first time.

Request flow from user perspective, explained below the diagram.

Here’s an explanation of the diagram above:

  1. A user opens a page in Confluence Cloud that contains a Jira issue macro with a link to an issue in Jira Data Center.

  2. Confluence Cloud makes a back-end request to Jira Data Center via the tunnel. The request is blocked, because Confluence isn’t allowed to make requests on behalf of that user. The Jira issue macro that they’re trying to view displays a message saying they don’t have permission to view the linked issue and must authenticate.

  3. The user selects Authenticate in the message and is redirected to Jira Data Center where they can authorize the link.

  4. If they’re not already logged in to Jira Data Center, they will need to log in using one of your authentication methods, such as login form or single sign-on.

  5. Once logged in, the user is asked to allow Confluence Cloud to access Jira Data Center on their behalf.

  6. If they accept, they’ll be redirected back to Confluence Cloud. At this point, Confluence Cloud exchanges the request token with an access token via the tunnel.

  7. Confluence Cloud makes another request to Jira Data Center via the tunnel, this time using the access token as the authorization method, to get the issue details on behalf of the user. The Jira issue macro is displayed correctly.

Accessing the resources on user’s behalf and revoking access

As explained earlier, Atlassian cloud products access the resources in your self-managed instance on behalf of the users that authorized the link.

Every user needs to authorize the link individually, usually when they try to view a linked entity for the first time. Admins can’t pre-authorize such links. Every user can also revoke access to the link at any time.

Requests made using such authorized links are made in user context, taking into account all of their current permissions. This means the cloud product won’t be able to access the resources the users themselves don’t have access to.

Additional information on security

Can you make requests using an app tunnel that belongs to a different organization?

No, even if both organizations belong to the same user. We have a dedicated authorization mechanism inside the Tunnel server that prevents such calls.

Other security questions

Application tunnel security

Still need help?

The Atlassian Community is here for you.