Issue tracking integration for Jira

This page describes the issue tracking integration for Jira, and what you need to do to connect Polaris to Jira. Once configured, the issue tracking integration allows Polaris to create tickets in Jira for issues captured in Polaris.

Prerequisites and technical requirements

The issue tracking integration for Jira requires:

  • A classic Jira Cloud instance running the latest long term support release.
    Important: The Jira instance must be routable over the Internet. Closed networks are not supported at this time. Jira Next-Gen is not supported.
  • Only organization administrators can connect Polaris to Jira. The organization administrator who configures the integration must also be a Jira administrator (with permissions to link external applications to Jira).
  • Authentication between Jira and Polaris is through OAuth. You will need to create public and private OAuth keys, as described in this article.

Issue fields and attributes

Each ticket Polaris creates in Jira includes the following fields:

  • Summary: the format of summaries vary, depending on how the ticket was created:
    • Tickets for issues you export manually: 
      Polaris - Project '<Polaris project name>' contains issue '<Issue Type>'
    • Tickets created for policy violations: 
      Polaris - Project '<Polaris project name>' contains issues violating policy '<Policy name>'
  • Description: the format of descriptions vary, depending on how the ticket was created:
    • Tickets for issues you export manually: detailed information about the issue, remediation guidance, and helpful links.
    • Tickets created for policy violations: the name of the violated policy, the names of any violate rules, and links you can use to view violating issues in Polaris.
  • Reporter: The name of the user who configured the integration.
Important: If other fields are required by your Jira project, exports will fail.

Connect Polaris to a Jira instance

Complete the following tasks to connect Polaris to a Jira instance:
  1. Create public and private RSA Keys
  2. Link Polaris to Jira with a public key
  3. Add a Jira instance to Polaris
Important: These tasks can only be completed by an organization administrator who is also a Jira administrator. The same person must complete all of the tasks in this section.

Each one of these tasks is explained in more detail below.

Create public and private RSA Keys

To link Jira to Polaris, you need to create a pair of public and private OAuth keys. If you already have these keys, go to the next section. If not, follow these steps:
  1. Open a terminal and run the following openssl commands.
  2. Generate a new RSA private key: 
    openssl genrsa -out jira_privatekey.pem 1024

    This command assigns the key name jira_privatekey.pem and a length of 1024 bits. The .pem file is written to your working directory; you'll need it in the next step.

  3. Create a certificate: 
    openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365

    You are prompted to answer a series of questions that are necessary for the certificate creation.

    If successful, the command generates an X509 certificate.

    The certificate will expire in 365 days – you can change the final value to a different number. A new certificate will be needed after the interval has passed.

    CAUTION: Certificates expire after a set period of time. Schedule periodic rotation of certificates. When updating the certificates, you must repeat this procedure, except that you will update the record rather than creating it.
  4. Extract a PCKS8 private key: 
    openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8

    This command reads the unencrypted private key and outputs a new key in PKCS8 format with the name specified (jira_privatekey.pcks8). This is the private key that you will provide to Polaris later.

  5. Extract the public key: 
    openssl x509 -pubkey -noout -in jira_publickey.cer > jira_publickey.pem

    This command uses the certificate you created to extract the public key file, jira_publickey.pem. This is the public key that you will provide to Jira in the next task.

Link Polaris to Jira with a public key

Now, add Polaris to Jira as a linked application with the public OAuth key.
  1. In Jira, go to Settings > Products.
    Settings is the cog icon at the top right.
  2. Under Integrations, select Application Links.

    A screenshot of the left-hand navigation in Jira.
  3. Select Create Link.
    The Create an application link window opens.
  4. Select Direct application link, enter the URL of your Polaris instance in the Application URL field, and select Next.

    A screenshot of the Create an application link window in Jira.
    Note: If a warning appears, select Continue.

    The Review Link window opens.

  5. On the Review link form, complete three required fields:
    • Enter an Application Name (for example, Polaris).
    • Select Generic Application from the Application Type dropdown menu.
    • Select the Create incoming link checkbox.
    Important: If you enter text or place the cursor in the other fields, the form will not be accepted.
  6. Select Continue.
    The link you created for Polaris appears on the Application Links page.
  7. Select the options icon next to the application link you created for Polaris and then select Edit.
    The Configure window opens.
  8. Open the Incoming Authentication tab, and complete the required fields:

    A screenshot of the Incoming Authentication tab.
    • Consumer Key: Enter OauthKey.
    • Consumer Name: Enter Polaris.
    • Public Key: Copy and paste the public key you created into this field.

    Select Save (near the bottom of the form).

Add a Jira instance to Polaris

Configure your Polaris instance with the private OAuth key and verify the connection.
Important: These steps can only be completed by the user who connects Polaris to Jira (described in the previous task).
  1. In Polaris, go to My Organization > Integrations.
  2. Select + Add Integration > Jira Cloud.


  3. On the Jira Integration Set Up page, complete the form as follows:
    • Enter your Jira instance's URL in the Enter Jira URL field.
    • Enter OauthKey in the Enter Consumer Key field.
    • Copy and paste your private key (from the .pcks8 file) into the Enter Private Key field.
    Note: Before you proceed, turn off any pop-up blockers or ad blockers to ensure that you receive the verification code.
  4. Click Next.
    Jira opens in a new tab.
  5. Under Welcome to JIRA, select Allow.
  6. Copy the verification code that appears on the Access Approved page and go back to Polaris.
  7. Paste the code into the Enter Verification Code field and select Validate.
  8. Click Next.
  9. Review the information and then click Finish.
  10. When the Integrations page opens, select Test next to your Jira URL to verify the connection is working as expected.
    If the test is successful, a green check mark appears next to the Test button.

Connect a Polaris project to Jira

After an organization administrator establishes the connection between Polaris and Jira, follow these steps to connect a project to Jira.
  1. In Polaris, go to Portfolio.
  2. Open an application and then open a project.
  3. Go to Settings > Integrations.
  4. Under Issue Tracker, select a Jira instance from the Instance dropdown menu.


    Note: Each Polaris project supports one issue tracking integration. You cannot add an issue tracking integration to a project that already has one configured.
  5. Select the Jira Project exported issues will be sent to.
  6. Select the Jira Issue Type used when exporting issues.
  7. Select Save.