JIRA Fails to connect to the Azure SQL database after updating the Minimum TLS version to TLSv1.3

Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Summary

When Jira is connected to Azure SQL database server and Minimum TLS version is set to “TLS 1.3”, Jira startup fails.

Restarting Jira leads to the below error. The error can be observed in “catalina.out” file.

1 2 3 4 5 6 7 8 2024-08-09 07:29:55,936-0500 JIRA-Bootstrap ERROR [c.a.jira.health.HealthChecks] JIRA couldn't connect to your database 2024-08-09 07:29:55,936-0500 JIRA-Bootstrap ERROR [c.a.jira.health.HealthChecks] JIRA failed to establish a connection to your database. This could be because: - Your database isn't running - The configuration of your dbconfig.xml file is incorrect (user, password, or database URL etc.) - There is a network issue between JIRA and your database (e.g. firewall, database doesn't allow remote access etc.) There are several other solutions you can try, please review our documentation and see what works best for you.

Environment

Jira Data Center on any version from 9.4.0.

Diagnosis

Since Azure SQL database only accept TLSV1.3 protocol, it's important to restrict the TLS versions used by Jira when connecting as a client. We can achieve this by setting the lower protocol values in the jdk.tls.disabledAlgorithms parameter in <JAVA_HOME>/lib/security/java.security. Another approach is to add the following startup properties to configure these settings:

1 -Djdk.tls.client.protocols=TLSv1.3

By implementing these adjustments, Jira will initiate the SSL handshake using the TLSv1.3 protocol when acting as a client. Enable the below debug parameter as outlined in the documentation, restart Jira to replicate the issue, and examine the SSL handshake debug logs.

1 -Djavax.net.debug=all

As evidenced by the debug logs below, the Supported_versions field indicates TLSv1.3, and the handshake process includes the transmission of key_share, both integral components of the TLSv1.3 handshake process as outlined in the article provided. This confirms that Jira effectively utilises the TLSv1.3 protocol, while Azure SQL has rejected the connection.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 "ClientHello": { "client version" : "TLSv1.2", "random" : "FB54B80D226ECB51D25ECC5A2F9BC28E540C4AEDE0B62598CD0699481AF8707C", "session id" : "9580F42696CB4A648B4C4EB73CC5BFF6FD8155A314E4DDE9166094CE6DB79EAF", "cipher suites" : "[TLS_AES_256_GCM_SHA384(0x1302), TLS_AES_128_GCM_SHA256(0x1301), TLS_CHACHA20_POLY1305_SHA256(0x1303)]", "compression methods" : "00", "supported_versions (43)": { "versions": [TLSv1.3] }, "key_share (51)": { "client_shares": [ { "named group": x25519 "key_exchange": { 0000: 2D 88 77 D8 18 3D 76 80 9D 83 49 B7 B9 E3 0F 94 -.w..=v...I..... 0010: B3 13 30 25 9A A0 C1 FD E6 23 55 7E CC B3 AF 24 ..0%.....#U....$ } }, javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.207 GMT|null:-1|WRITE: TLSv1.3 handshake, length = 364 javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.207 GMT|null:-1|Raw write ( 0000: 16 03 03 01 6C 01 00 01 68 03 03 FB 54 B8 0D 22 ....l...h...T.." 0010: 6E CB 51 D2 5E CC 5A 2F 9B C2 8E 54 0C 4A ED E0 n.Q.^.Z/...T.J.. 0020: B6 25 98 CD 06 99 48 1A F8 70 7C 20 95 80 F4 26 .%....H..p. ...& 0030: 96 CB 4A 64 8B 4C 4E B7 3C C5 BF F6 FD 81 55 A3 ..Jd.LN.<.....U. 0040: 14 E4 DD E9 16 60 94 CE 6D B7 9E AF 00 06 13 02 .....`..m....... 0050: 13 01 13 03 01 00 01 19 00 00 00 2A 00 28 00 00 ...........*.(.. 0060: 25 6E 61 76 6E 65 65 74 68 61 7A 75 72 65 73 71 %navneethazuresq 0070: 6C 2E 64 61 74 61 62 61 73 65 2E 77 69 6E 64 6F l.database.windo javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.268 GMT|null:-1|duplex close of SSLSocket javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.269 GMT|null:-1|WRITE: TLSv1.3 alert(user_canceled), length = 2 javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.269 GMT|null:-1|Raw write ( 0000: 15 03 03 00 02 01 5A ......Z ) javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.269 GMT|null:-1|WRITE: TLSv1.3 alert(close_notify), length = 2 javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.269 GMT|null:-1|Raw write ( 0000: 15 03 03 00 02 01 00 ....... ) javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.269 GMT|null:-1|close the underlying socket javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.270 GMT|null:-1|close the SSL connection (passive) javax.net.ssl|DEBUG|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.270 GMT|null:-1|close inbound of SSLSocket javax.net.ssl|ERROR|F1|http-nio-8081-exec-1|2024-08-27 14:34:43.272 GMT|null:-1|Fatal (UNEXPECTED_MESSAGE): SQL Server did not return a response. The connection has been closed. ClientConnectionId:3e59ada5-94b0-4bf6-8fa8-228e67be7f41 ( "throwable" : { java.io.IOException: SQL Server did not return a response. The connection has been closed. ClientConnectionId:3e59ada5-94b0-4bf6-8fa8-228e67be7f41 at com.microsoft.sqlserver.jdbc.TDSChannel$SSLHandshakeInputStream.ensureSSLPayload(IOBuffer.java:895) at com.microsoft.sqlserver.jdbc.TDSChannel$SSLHandshakeInputStream.readInternal(IOBuffer.java:949) at com.microsoft.sqlserver.jdbc.TDSChannel$SSLHandshakeInputStream.read(IOBuffer.java:942) at com.microsoft.sqlserver.jdbc.TDSChannel$ProxyInputStream.readInternal(IOBuffer.java:1206) at com.microsoft.sqlserver.jdbc.TDSChannel$ProxyInputStream.read(IOBuffer.java:1192) at java.base/sun.security.ssl.SSLSocketInputRecord.read(Unknown Source) at java.base/sun.security.ssl.SSLSocketInputRecord.readHeader(Unknown Source) at java.base/sun.security.ssl.SSLSocketInputRecord.decode(Unknown Source) at java.base/sun.security.ssl.SSLTransport.decode(Unknown Source) at java.base/sun.security.ssl.SSLSocketImpl.decode(Unknown Source) at java.base/sun.security.ssl.SSLSocketImpl.readHandshakeRecord(Unknown Source) at java.base/sun.security.ssl.SSLSocketImpl.startHandshake(Unknown Source) at java.base/sun.security.ssl.SSLSocketImpl.startHandshake(Unknown Source) at com.microsoft.sqlserver.jdbc.TDSChannel.enableSSL(IOBuffer.java:1854) at com.microsoft.sqlserver.jdbc.SQLServerConnection.connectHelper(SQLServerConnection.java:3797) at com.microsoft.sqlserver.jdbc.SQLServerConnection.login(SQLServerConnection.java:3385) at com.microsoft.sqlserver.jdbc.SQLServerConnection.connectInternal(SQLServerConnection.java:3194) at com.microsoft.sqlserver.jdbc.SQLServerConnection.connect(SQLServerConnection.java:1971) at com.microsoft.sqlserver.jdbc.SQLServerDriver.connect(SQLServerDriver.java:1263) at java.sql/java.sql.DriverManager.getConnection(Unknown Source) at java.sql/java.sql.DriverManager.getConnection(Unknown Source)

Cause

  • Azure SQL Database supports Transport Layer Security TLS v1.3 when TDS 8.0 is utilized.

  • The Tabular Data Stream (TDS) protocol serves as an application layer protocol enabling clients to establish connections with SQL Server. For further insights on TLS 1.3 and TDS prerequisites, kindly consult the Microsoft documentation available here.

  • In order to leverage TDS 8.0, Azure SQL has introduced "strict" as an additional connection encryption type to SQL Server drivers (Encrypt=strict).

  • Database URL configured in dbconfig.xml does not incorporate this string, consequently leading to the encountered issue.

Solution

  1. Stop Jira

  2. TDS 8.0 is supported for driver version 11.2.0 and higher. Please ensure that the Microsoft drivers in the Jira installation library directory contain the latest JAR for version 11.2.0 or higher.

  3. If necessary, download the Microsoft JDBC Driver for SQL Server version 11.2.0 or higher and copy the JAR files to the <jira-installation>/lib folder.

  4. Modify the dbconfig.xml file. 

    1. Locate the dbconfig.xml file at the root of your JIRA home directory, the default locations are:

      1. C:\Program Files\Atlassian\Application Data\JIRA (on Windows) or

      2. /var/atlassian/application-data/jira (on Linux)

    2. Open the file in a text editing program.

    3. Modify the URL to include "encrypt=strict" as demonstrated below.

      1 url>jdbc:sqlserver://;serverName=example.database.windows.net;portNumber=1433;databaseName=exampleAzureSQL;encrypt=strict;hostNameInCertificate=*.database.windows.net</url>

    4. Save the file.

  5. Start Jira and verify that Jira can connect to the Azure SQL database using TLS v1.3 protocol.

Updated on March 12, 2025
Platform
Data Center only
Product
Jira Software Data Center
On this pageSummaryDiagnosisCauseSolution

Still need help?

The Atlassian Community is here for you.
Ask the Community