Configuring UPM app signature check

UPM version differences in configuration 

When app signing was introduced in UPM 7.1, it was disabled by default, allowing Data Center products to run as usual without any configuration changes.

Starting with UPM 8.0, the feature is enabled by default for all new app installations. This means that to keep installing new apps, you must either configure the location of the trust store folder or disable the app signing feature.

The table below lists the UPM version bundled with major Data Center product versions (some of them are not released yet).

Configuration resources

The app signature check requires the following resources to work: 

1. Configuration properties. UPM uses properties to enable or disable the feature, and offers the ability to do this for all apps, or depending on the app’s origin. 
2. The trust store folder that contains trusted certificates. 

Configuration resources location

Location properties

UPM uses system properties to locate its configuration and resources. These properties depend on the version and have default values listed in the following table.

The default values for the file and trust store system properties are set to ensure backward compatibility; if you have a running configuration for UPM 7.1, then UPM 8.0 will pick it up without any change.

The resource locations are displayed on the Manage apps and Trusted Certificates pages in the admin panel. This can be a convenient way to find the default locations when no system property is set.

Location resolution

The actual location of a configuration resource is resolved from the system property value as follows: 

1. If this value is an absolute path, then it is used as is.
2. If the value 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)

Configuration properties

Configuration properties are read from different sources depending on UPM’s version: 

• In UPM 7.1, properties are read from the UPM configuration file. If they exist, the configuration file and the trust store must be located in the same folder. If the configuration file is missing, the default configuration is applied (that is, the feature is disabled).
• In UPM 8.0 and later, the configuration properties can be read from one of the following:
  • configuration file (if present)
  • system properties (if the configuration file is missing) 

If no properties are found, the default configuration is applied (that is, the feature is enabled, using the default trust store location resolved as explained before). The location of the optional configuration file and the trust store can be set separately. 

UPM 8.0 is fully compatible with UPM 7.1 configuration and settings, but it offers more flexible ways of achieving the desired result.

The table below describes the supported configuration properties.

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

• In UPM 7.1, the feature is disabled by default, and the admin has to enable it.

• In UPM 8.0, the feature is enabled by default, and the admin will have to take action to disable it.

Safety check for configuration file and trust store permissions

The configuration file (if it exists) and trust store must meet some permissions and ownership requirements: 

• The user running the product must NOT own the configuration file, the truststore folder, or any file or folder it contains
• The user running the product must NOT have write privileges on the configuration file, the truststore 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.

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

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

Configure app signature check

1. Create an empty directory called upmconfig in the product’s home directory. For example, [jira-home]/upmconfig.
2. Create an empty directory upmconfig/truststore.
3. Download the certificates provided by Atlassian and copy them to the trust store directory you’ve just created.
4. To apply a configuration that differs from the default settings:
   1. Create an upm.properties text file in the upmconfig directory.
   2. Add the desired configuration properties as described in the table above.

 5. Apply the required file permissions to the configuration folder.

chmod 755 upmconfig upmconfig/truststore

That’s all! After you restart the service, UPM will detect that its default configuration directory exists and read the properties file, enabling the signature check.

You can add new certificates to the truststore folder at any time, but they must NOT be writable by the user who is running the application. You can customize the location of the configuration folder by setting the atlassian.upm.configuration.directory system property as described previously on this page.

When everything is configured correctly, you’ll see the “Configuration check was successful” message.

If you see an error, refer to App signing troubleshooting. 

Update configuration and certificates

Configuration

You can create or edit the configuration file while the product is running.

In UPM 8.0, the system properties are read-only when the product starts, and the configuration read from the configuration file takes precedence over any other configuration. This means that if the feature is disabled using system properties, it can be enabled later by creating the configuration file with the appropriate values.

Certificates

If the feature is enabled, you can add the certificates at any time while the product is running.

Enable the feature with UPM 7.1

In UPM 7.1, the feature is disabled by default.

We assume the instance is running and no system properties were set.

1. Create the UPM configuration folder at the default location as explained before.
2. Add atlassian.upm.signature.check.enabled=true to the upm.propeties file.
3. Copy Atlassians certificates to the truststore directory.
4. Set the correct file permissions, and make sure the user running the product isn't the owner of any file in the configuration folder.

Add certificates with UPM 8.0

In UPM 8.0, the feature is enabled by default, but there are no certificates.

1. Create the UPM configuration folder at the default location as explained before.
2. Copy Atlassian certificates to the truststore directory.
3. Set the correct file permissions, and make sure the user running the product is not the owner of any file in the configuration folder.

Disable the feature with UPM 8.0

In UPM 8.0, the feature is enabled by default.

We assume the product is running and no system properties were set.

1. Create the UPM configuration folder at the default location as explained before.
2. Add atlassian.upm.signature.check.disabled=true to the upm.properties file.

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.