Administering the Atlassian Companion App
This page applies to Confluence Server and Data Center
The Companion app will be removed from Confluence Cloud at the end of March 2022. Read announcement
We have no plans to end support for the Companion app in Confluence Data Center and Server.
The Atlassian Companion app enables users to edit Confluence files in their preferred desktop application, then save the file back to Confluence automatically.
The download and re-upload of files is managed by the Atlassian Companion app, which needs to be installed on each user's machine (not in the Confluence installation directory) to enable file editing.
On this page:
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)
If the link above downloads an .exe file instead of the MSI, copy the URL below into your browser to download the file.
https://update-nucleus.atlassian.com/Atlassian-Companion/291cb34fe2296e5fb82b83a04704c9b4/latest/win32/ia32/Atlassian%20Companion.msiUse 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.
Go to
> General Configuration > Office Connector.- Choose Enable Edit in Office for all users and save your changes.
This will disable Companion app functionality for all users in the site.