Administering the Atlassian Companion App

Download and install the Atlassian Companion app

To edit files, users need to install the Atlassian Companion app and have it running in the background. The first time a user clicks the Edit button in file preview, we prompt them to download and install the app. See Edit Files for details.

If your users aren't able to install applications themselves, you may want to distribute the app to them or deploy using the Microsoft Installer.

Single sign-on considerations

If you've configured single sign-on (SSO) in such a way that your reverse proxy redirects the requests to your SSO gateway, and only successfully authenticated requests ever reach Confluence, your users won't be able to edit files using the Atlassian Companion app. This is because the Atlassian Companion app uses JWT tokens to authenticate requests, and only Confluence can authenticate these requests, not your SSO authenticator. 

To make sure requests from the Atlassian Companion app can be authenticated, you should configure your reverse proxy to always allow requests from the following URLs: 

• <base-url>/rest/token-auth/api/* 
• <base-url>/download/token-auth/attachments/*
• <base-url>/plugins/servlet/imgFilter*   
• <base-url>/rest/analytics/1.0/publish/bulk     (only necessary if you have opted in to data collection)

If an unauthenticated user tries to access these URLs directly, they would be redirected to the Confluence login screen. The wouldn't be able to access any content or download files while unauthenticated.

There's a known issue where the token-auth path is not included in the download URL that Confluence provides Companion. See  CONFSERVER-63189 - Getting issue details... STATUS

Content security policy (CSP) considerations

If you have a restrictive content security policy, your browser will refuse to launch companion, and you'll see a content security policy error in the browser console. This error occurs because Confluence 7.3 and later uses a hidden iframe to attempt to launch Companion's custom protocol (atlassian-companion). To resolve this problem you will need to add atlassian-companion: to the default-src or frame-src  list. For example:

frame-src atlassian-companion:;

The content security policy is most commonly configured in your reverse proxy.

Install the Companion app via Microsoft Installer (MSI)

We also provide a Microsoft Installer package (.msi file) to deploy the Atlassian Companion app for Windows across multiple users or machines. By default, the Companion app installs to the Program Files directory, but you can customize this.

Download the Atlassian Companion MSI (69 MB)

https://update-nucleus.atlassian.com/Atlassian-Companion/291cb34fe2296e5fb82b83a04704c9b4/latest/win32/ia32/Atlassian%20Companion.msi

Use the Microsoft Installer to install the Companion app for all users on a given computer:

msiexec /i “Atlassian Companion.msi” COMPANION_TRUSTED_DOMAINS=“https://confluence.atlassian.com;https://support.atlassian.com;” /qb ALLUSERS=“1"

If you deploy using the Microsoft Installer, the Companion app won’t automatically get the latest updates, including security and bug fixes, so some maintenance is required.

We may update the Companion app before or after we release a new version of Confluence. Check the Atlassian Companion app release notes to make sure you're on the latest version.

Standard install switches

The Microsoft Installer supports standard install switches. For example, install with the TARGETDIR and APPLICATIONROOTDIRECTORY parameters to change the installation directory:

msiexec /i "Atlassian Companion.msi" TARGETDIR="C:\Users\Emma\AppData\Local\Companion" APPLICATIONROOTDIRECTORY="C:\Users\Emma\AppData\Local\Companion" /qb

Set trusted domains

In Companion 1.2.0 and later, set your Confluence URL as a trusted domain so users don’t have to select 'Trust this domain' when they edit a file for the first time. 

System administrators have two options for setting trusted domains/sites before rolling out the Companion app to all users. Either set an environment variable called COMPANION_TRUSTED_DOMAINS on each user's computer, or pass the parameter COMPANION_TRUSTED_DOMAINS to the Microsoft Installer (MSI). Set multiple trusted domains by using semicolons (;) as separators.

To set trusted domains when installing using the MSI:

msiexec /i "Atlassian Companion-1.1.0.msi" COMPANION_TRUSTED_DOMAINS=“https://confluence.atlassian.com;https://support.atlassian.com;"

Compatibility with virtual desktop environments

From Confluence 7.3 onwards, Atlassian Companion app should work in most session-based virtual desktops. 

Recover edited files

When a user edits a file, that file is also downloaded and saved to the Atlassian Companion folder on their computer. Files modified more than 60 days ago are automatically cleared when the Companion app restarts.

Follow our guide to accessing Confluence files edited with the Atlassian Companion app.

How to delete the Cache folder

If you’d like to free up disk space, it’s safe to manually delete the cache folder. Deleting individual files in the cache folder may cause errors, so you should delete the entire Cache folder. If the cache folder is locked while Companion App is running, quit Companion, delete the cache folder, then open Companion.

Disable file editing

From Confluence 7.3 onwards, it is not possible to disable file editing completely.  However, you can choose to revert to the previous Edit in Office functionality, which disables the Companion app integration.  

Alternatives to the Atlassian Companion app

In some versions of Confluence, you can revert to the previous Edit in Office functionality. This is a workaround for customers who are unable to use the Companion app in their environment.