Configuring UPM plugin signature check

Using the Universal Plugin Manager

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Starting with version 7.1, Atlassian Universal Plugin Manager (UPM) is rolling out a useful feature that lets you verify the integrity and origin of plugin and application files using a digital signature. This enhancement not only aims to securely re-enable the app upload feature but also improves security overall, as Marketplace apps will now need to come with a signature too.

On this page:

Configuration

This document explains how to configure the app signing feature and how its enablement can change UPM's behavior.

The app signing feature is disabled by default, but it will be enabled by default in a future version of UPM.

Configuration elements

The configuration lives in a folder that we will refer to as upm configuration folder in this document. 

In the upm configuration folder, UPM will look for:

  • an optional properties file called upm.properties
  • a folder called truststore that must contain the certificates issued from Atlassian and app vendors

To ease adoption, this feature can live without any changes to the current product configuration.

Configuration folder location

Apart from the configuration folder location, which requires a restart if you don’t want to use the default location, the configuration folder can be created or updated while the product is running.

The Manage apps page displays the location and safety status of the configuration folder.

The upm configuration folder location is resolved in the following order: 

  1. Get the value of atlassian.upm.configuration.directory system property, which defaults to upmconfig.
  2. If this value is an absolute path, then it is used as a configuration folder.
  3. If it is a relative path, then it is resolved relatively from:
    • the product’s Shared home directory if it is defined
    • the product’s home directory if it is defined
    • the current directory (depends on the running process)

If the configuration folder does not exist, UPM will use the default configuration with an empty truststore. If the feature is enabled with an empty truststore, all signature checks will fail.

Resolving the upm configuration folder location

atlassian.upm.configuration.directory system property

Shared home

Home

Resulting location

not specified

not specified

not specified

[current folder]/upmconfig

custom_loc

not specified

not specified

[current folder]/custom_loc

not specified

/var/atlassian/shared

/var/atlassian/home

/var/atlassian/shared/upmconfig

not specified

not specified

/var/atlassian/home

/var/atlassian/home/upmconfig

custom_loc

/var/atlassian/shared

/var/atlassian/home

/var/atlassian/shared/custom_loc

custom_loc

not specified

/var/atlassian/home

/var/atlassian/home/custom_loc

/var/atlassian/custom_loc

/var/atlassian/shared

/var/atlassian/home

/var/atlassian/custom_loc


Configuration folder permissions and safety check

The configuration and truststore folders must meet some permissions and ownership requirements:

  • prohibited The user running the product must NOT own the configuration folder or any file or folder it contains.
  • prohibited The user running the product must NOT have write privileges on the configuration folder or any file or folder it contains.

If UPM’s Safety Check detects that these conditions are not met when installing an app, the installation will fail, a warning message will be logged, and an audit log entry will be added.

Examples

We assume the product is run by the user product, a member of the users group on a Linux system.

The following folder would pass the safety check:

  • all files have 644 / rw-r--r-- permissions, they are only writable by the config user
  • all folders have 755 / rwxr-xr-x permissions (x is required for the folder content to be readable by the group members)
ls -Rl 
total 0
drwxr-xr-x@ 4 config users  128 Oct 18 11:27 upmconfig

upmconfig
total 8
drwxr-xr-x@ 8 config  users  256 Oct 18 11:27 truststore
-rw-r--r--@ 1 config  users   70 Oct 21 15:58 upm.properties

upmconfig/truststore:
total 48
-rw-r--r--@ 1 config  users  664 Oct 18 11:27 atl_intermediate_g1.crt
-rw-r--r--@ 1 config  users  652 Oct 18 11:27 atl_root_g1.crt
-rw-r--r--@ 1 config  users  519 Oct 18 11:27 fake_vendor_certificate.crt
-rw-r--r--@ 1 config  users  519 Oct 18 11:27 fake_vendor_expired_certificate.crt


This folder would fail the safety check:

  • the upm.properties file belongs to the product user
  • the product user has write privileges on the file atl_intrermediate_g1.crt as a member of the users group
ls -Rl 
total 0
drwxr-xr-x@ 4 config users  128 Oct 18 11:27 upmconfig

upmconfig
total 8
drwxr-xr-x@ 8 config  users  256 Oct 18 11:27 truststore
-r--r--r--@ 1 product users   70 Oct 21 15:58 upm.properties

upmconfig/truststore:
total 48
-rw-rw-r--@ 1 config  users  664 Oct 18 11:27 atl_intermediate_g1.crt
-rw-r--r--@ 1 config  users  652 Oct 18 11:27 atl_root_g1.crt
-rw-r--r--@ 1 config  users  519 Oct 18 11:27 fake_vendor_certificate.crt
-rw-r--r--@ 1 config  users  519 Oct 18 11:27 fake_vendor_expired_certificate.crt



Configuration properties

Configuration properties must be added in a file called upm.properties located in the configuration folder.

The table below describes the supported configuration properties.

KeyDescription

atlassian.upm.signature.check.enabled

This property will be deprecated after the grace period.


Enables the feature

  • if defined and equals to true, the feature is enabled
  • if defined and not equal to true, the feature is disabled
  • if not defined, UPM will look for atlassian.upm.signature.check.disabled property

atlassian.upm.signature.check.disabled

Disables the feature

The default value will change at the end of the grace period.

  •  if defined and equals to true, the feature is disabled
  • if defined and not equal to true, the feature is enabled
  • defaults to true if it is not defined, disabling the feature 

atlassian.upm.signature.check.upload.disabled

Disables app signature check for uploaded apps

This applies if the feature is globally enabled:

  • if defined and equals to true, the feature is disabled for uploaded plugins
  • if defined and not equal to true, the feature is enabled for uploaded plugins
  • if not defined, defaults to false

atlassian.upm.signature.check.marketplace.disabled

Disables app signature check for apps installed from the Marketplace

This applies if the feature is globally enabled:

  • if defined and equals to true, the feature is disabled for Marketplace plugins
  • if defined and not equal to true, the feature is enabled for Marketplace plugins
  • if not defined, defaults to false

atlassian.upm.signature.check.directory_scanner.disabled

Disables app signature check for apps installed by the PIP directory scanner

This applies if the feature is globally enabled:

  • if defined and equals to true, the feature is disabled for scanned apps
  • if defined and not equal to true, the feature is enabled for scanned apps
  • if not defined, defaults to true (the file system is considered safe)

atlassian.upm.signature.check.self_update.disabled

Disables app signature check for UPM self-installation.

This applies if the feature is globally enabled:

  • if defined and equals to true, the feature is disabled for UPM self-update
  • if defined and not equal to true, the feature is enabled for UPM self update
  • if not defined, defaults to false

This might look a bit complex, but the intent is to minimize the configuration effort and make it explicit:

  • before the end of the grace period, the feature is disabled and the admin has to enable it
  • after the grace period, the feature will be enabled by default and the admin will have to edit the configuration to disable it

Consequences on other UPM configuration

The app signing feature has been added to re-enable app installation by uploading files to the platform.

By default, the Upload app button was disabled in recent product versions, and administrators could re-enable it by setting the upm.plugin.upload.enabled system property to true.

The app signature check feature has an impact on this as shown in the following table.

upm.plugin.upload.enabled

system property value

plugin signature check feature

plugin upload feature

true

enabled

enabled

true

disabled

enabled with warnings

false

disabled

disabled

false

enabled

disabled

unspecified

enabled

enabled

unspecified

disabled

disabled

Last modified on Jan 15, 2025

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.