Jira Service Management 10.2.x upgrade notes

Below are some important notes on upgrading to Jira Service Management 10.2.x. For details on the new features and improvements in this release, see:

Jira Service Management 10.2.x release notes

Skip to:

New login experience with two-step verification

To improve the security of the Jira login experience, we’ve added a second authentication layer. If you experience any issues with the new login process, you can switch to the legacy login experience by setting the JVM system property atlassian.authentication.legacy.mode to true.

Keep the database password secure in the secret storage

We're now using the secret storage to secure the database password. After the upgrade, or during the zero-downtime upgrade (ZDU), we'll read the password from the dbconfig.xml file, encrypt it, store it in the secret storage and replace the password in the dbconfig.xml file with the placeholder: {ATL_SECURED}. If the password was previously stored in plaintext, you can expect the following logs:

 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Secret Service is enabled
 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Detected new password in the xml file, that hadn't been encrypted by Secret Service
 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Trying to get password from xml and decrypt it with legacy Secret Store Provider
 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Database password decryption not performed.
 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Getting plaintext password from config, encrypting it and storing in Secret Service.
 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Secret Service is enabled
 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Storing encrypted database password in Secret Service
 main INFO      [c.a.j.config.database.DatabaseConfigHandler] Replacing the password in config with {ATL_SECURED}

The dbconfig.xml file will contain: <password>{ATL_SECURED}</password>.

In case of a ZDU rollback, you need to edit the dbconfig.xml file on every node that was upgraded and change the password back to the plaintext password.

If the password is secured with the Secret Store Provider, the secret will be located in the secret storage, but we won’t replace the password in the dbconfig.xml file and we’ll use the secret store provider to encrypt and decrypt the password.

Starting from Jira 10.2.1:

If the password is encrypted with the Secret Store Provider, the AES encryption, or a custom implementation, we'll decrypt the password, store it in the Secret Storage and replace the password in the dbconfig.xml file with {ATL_SECURED}.
If the password is encrypted with the Secret Store Provider, the AWS Secrets Manager, or HashiCorp Vault, we'll keep it as the encryption method and won’t use the Secret Storage for handling the password.

Ignore warnings from Atlassian Package Scanner

Atlassian Package Scanner verifies if there are no .jar files providing the same package, potentially with a different version. After you upgrade to Jira Software Data Center 10.2 or Jira Service Management Data Center 10.2, Atlassian Package Scanner will notify you about packages with the same content provided by different .jar files.

This is due to Embedded Crowd still migrating to the new version of the platform and still using password-cipher, while Jira has already moved to atlassian-secrets but still has to provide password-cipher for backwards compatibility. atlassian-secrets embeds password-cipher, which is why Atlassian Package Scanner notices them, but since the content is the same, the following warnings may be safely ignored (note the duplicated lines — those appear because the .jar files are placed both in /lib and atlassian-jira/WEB-INF/lib):

Note that the full warning comes with the details about the exact location of the scanned files:

JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.db.config.password' with different versions. Files: atlassian-secrets-api-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.protocol' with different versions. Files: atlassian-secrets-store-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.utils' with different versions. Files: atlassian-secrets-store-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.cipher' with different versions. Files: atlassian-secrets-store-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.protocol' with different versions. Files: password-cipher-base-1.4.0.jar and atlassian-secrets-store-5.0.4.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.utils' with different versions. Files: password-cipher-base-1.4.0.jar and atlassian-secrets-store-5.0.4.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.db.config.password' with different versions. Files: password-cipher-base-1.4.0.jar and atlassian-secrets-api-5.0.4.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.cipher' with different versions. Files: password-cipher-base-1.4.0.jar and atlassian-secrets-store-5.0.4.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.db.config.password' with different versions. Files: atlassian-secrets-api-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.protocol' with different versions. Files: atlassian-secrets-store-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.utils' with different versions. Files: atlassian-secrets-store-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.secrets.tomcat.cipher' with different versions. Files: atlassian-secrets-store-5.0.4.jar and password-cipher-base-1.4.0.jar
JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.db.config.password' with different versions. Files: password-cipher-api-1.4.0.jar and atlassian-secrets-api-5.0.4.jar

Note that the full warning comes with the details about the exact location of the scanned files:

2024-10-17 09:31:28,389+0000 JIRA-Bootstrap WARN      [o.twdata.pkgscanner.ExportPackageListBuilder] Package Scanner found duplicates for package 'com.atlassian.db.config.password' with different versions. Files: atlassian-secrets-api-5.0.4.jar and password-cipher-base-1.4.0.jar
      '/tmp/jira/lib/atlassian-secrets-api-5.0.4.jar'
      '/tmp/jira/lib/password-cipher-base-1.4.0.jar'

End of support announcements

There are no changes to supported platforms in this release.

For the list of supported platforms, see Supported platforms.

For previous announcements, see End of support announcements.

App developers

Check out Preparing for Jira 10.2 for any important changes regarding apps.

Upgrade procedure

To help you upgrade to the latest and greatest:

See Upgrading Jira applications for complete upgrade procedures, including all available upgrade methods and pre-upgrade steps.
For a more tailored upgrade, go to Jira administration, then Applications, and then Plan your upgrade. We’ll recommend a version to upgrade to, run pre-upgrade checks, and provide you with a custom upgrade guide with step-by-step instructions.

Products

Jira Software