How to run JIRA over HTTPS with a Personal Information Exchange (PFX) Certificate

Still need help?

The Atlassian Community is here for you.

Ask the community

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

Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles 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

Atlassian applications allow the use of SSL within our products, however Atlassian Support does not provide assistance for configuring it. Consequently, Atlassian cannot guarantee providing any support for it.

  • If assistance with conversions of certificates is required, please consult with the vendor who provided the certificate.
  • If assistance with configuration is required, please raise a question on Atlassian Answers.

Description

Certificates with the extension .pfx or .p12 usually use PKCS12 as its encryption mechanism and this type of certificate is possible to be used in JIRA/Tomcat without any conversion.

(info) Usually, certificates generated by Microsoft's Certification Authority console use PKCS12.

Symptoms

The stack trace is shown in atlassian-jira.log:

14-Sep-2016 14:30:34.884 SEVERE [main] org.apache.coyote.AbstractProtocol.init Failed to initialize end point associated with ProtocolHandler ["http-bio-xxxx"]
java.io.IOException: Failed to load keystore type JKS with path \\xxx\xxx\xxx\xxx.pfx<file://xxx/xxx/xx/xx.pfx> due to Illegal character in path at index 0: \\xx\xx\xx\xx.pfx<file://xx/xx/xx/xx.pfx>

(info) Improvement on the stack trace part to avoid any misleading information -  JRA-62540 - Getting issue details... STATUS

Diagnosis

You can check the Keystore type of your certificate using the following keytool command "keytool -list -keystore path_to_certificate.pfx -storetype PKCS12"   and in case it's indeed PKCS12 you'll see the following output:

$ keytool -list -keystore cert.pfx -storetype PKCS12
Enter keystore password:  

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry

Resolution

  1. Shutdown JIRA;
  2. Adjust your SSL connector into the server.xml file (located $JIRA_Install/conf). This is an example of SSL connector using keystoreType="PKCS12":

    JIRA 6.x - 7.11.x:

    <Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
    			maxHttpHeaderSize="8192" SSLEnabled="true"
    			maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    			enableLookups="false" disableUploadTimeout="true"
    			acceptCount="100" scheme="https" secure="true"
    			keystoreFile="C:\path_to_cert\certificate.pfx" keystorePass="certificate_password" keyAlias="1" keystoreType="PKCS12"
    			clientAuth="false" connectionTimeout="20000"  sslProtocol="TLS" useBodyEncodingForURI="true"/>
    

    JIRA 7.12.1+:

    <Connector port="443" relaxedPathChars="[]|" relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" protocol="org.apache.coyote.http11.Http11NioProtocol"
    			maxHttpHeaderSize="8192" SSLEnabled="true"
    			maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    			enableLookups="false" disableUploadTimeout="true"
    			acceptCount="100" scheme="https" secure="true"
    			keystoreFile="C:\path_to_cert\certificate.pfx" keystorePass="certificate_password" keyAlias="1" keystoreType="PKCS12"
    			clientAuth="false" connectionTimeout="20000"  sslProtocol="TLS" useBodyEncodingForURI="true"/>
    

    (info) Notice that the keyAlias parameter is not always 1. Every key has a different keyAlias.

  3. Restart JIRA.

    (info) Currently, this is the only way to configure JIRA with a PKCS12 certificate, but there is already an improvement request opened to add it to JIRA Configuration Tool.

Last modified on Nov 15, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.