How Does it Work?
Prerequisites
As a Jira admin, you must have the following information:
- The supported authentication type should be one of OAuth1, OAuth2, or Basic Authentication.
- User credentials depend on the authentication type.
- Jira Project Name.
- Issue type (bug, security, escalation, etc).
- Jira labels (optional).
- Custom Field Mapping (optional).
Step 1 Creating a Jira Connection Profile
Connect Jira to Xray through the Xray interface using one of the supported authentication methods. Navigate to Administration > Xray Security & Compliance > Integrations > Jira Integration and select New Jira Integration.JFrog Cloud New Interface (Beta)
On the taskbar, click
(Platform Configurations) , and select Xray Settings > Integrations. To l earn more, click here .
Xray supports three authentication methods:
- OAuth1
- OAuth2
- Basic Auth
| Xray Self Hosted | Xray Cloud | |
|---|---|---|
Jira On-Prem |
|
Note: This configuration is not recommended, as it would require allowing inbound connections to your local Jira instance. |
Jira Cloud |
|
|
Connecting Jira to Xray Using OAuth1
In Xray:
Define the following fields in the Xray Jira Integration:
Field
Description
Consumer Key
The consumer key that is provided in Jira when linking applications.
Jira server URL
The URL of your Jira deployment.
Generate a public key that you will define in your Jira.
In Jira:
Paste the generated Public Key you copied from the Xray interface.
Connecting Jira to Xray Using OAuth2
In Atlassian:
Required scope permissions
read:issue-type:jira read:issue-type.property:jira read:project:jira read:project.property:jira read:user:jira read:application-role:jira read:avatar:jira read:group:jira read:issue-type-hierarchy:jira read:project-category:jira read:project-version:jira read:project.component:jira read:field:jira read:field-configuration:jira read:issue-meta:jira write:issue:jira write:comment:jira write:comment.property:jira write:attachment:jira read:issue:jira read:label:jira offline_access read:issue-security-level:jira read:issue.vote:jira read:issue.changelog:jira read:status:jira read:comment:jira read:comment.property:jira read:project-role:jira
From the Developer Console of Atlassian, create an OAUTH2 Integration. Specify the callback URL as the JFrog server URL, such as:
https://artifactory:8082/xray/api/v1/ticketing/integrations/callback
In the Authentication details section, copy the Client ID and secret. You will use these in the Xray interface.
In Xray:
Define the following fields in the Xray Jira Integration:
Field | Description |
|---|---|
Client ID | The client ID you obtained from the Atlassian OAUTH2 integration. |
Client Secret | The client secret you obtained from the Atlassian OAUTH2 integration. |
Connecting Jira to Xray Using Basic Authentication
Define the following fields in the Xray Jira Integration:
Field | Description |
|---|---|
Username | The username you use for Jira authentication. |
Password | The password you use for Jira authentication. |
Installation Type | Type of installation of your Jira instance, Cloud or On-Prem |
Jira Server URL | URL of the Jira deployment. |
Ensure to test connectivity between Xray and Jira by clicking the Test Jira Connectivity button before proceeding to the next step.
Step 2 Creating a Jira Configuration Profile
After successfully completing the connection between Jira and Xray, you need to create a Jira Configuration profile. As there are different Jira projects for different teams, the configuration profile enables you to define specific criteria for the issued Jira ticket per Jira project, such as labels and custom mappings defined in the Jira project.
Notes
Note the following:
- Tag Labels should be created in Jira before configuring them in the profile.
- If an issue type has mandatory fields in Jira, these issue types will not appear in the issue type list for selection. The following fields are an exception:
- summary
- description
- project
- issuetype
- labels
- reporter
As each violation creates a new Jira ticket, you might have multiple Jira tickets for the same violation in different versions of the Build, Release Bundle, or package. You can choose to only have one Jira ticket for the violation, by eliminating duplicate Jira tickets. If unchecked, multiple Jira tickets will be created for the same violation in all Builds, Release Bundles, and Packages.
List of Available Custom Fields
| Custom Field | Type |
|---|---|
| Xray_Impacted_Artifact | Text |
| Xray_Package_Type | Text |
| Xray_Vulnerability_Id | Text |
| Xray_Violation_Type | Text |
| Xray_Severity | Text |
| Xray_Severity_Source | Text |
| Xray_JFrog_Research_Severity | Text |
| Xray_CVEs | Text |
| Xray_CVSS_V2_Vector | Text |
| Xray_CVSS_V3_Vector | Text |
| Xray_CVSS_V2_Score | Text |
| Xray_CVSS_V3_Score | Text |
| Xray_Fix_Version | Text |
| Xray_Watch_Name | Text |
| Xray_Policy_Name | Text |
| Xray_Triggered_Rule | Text |
| Xray_Component_License_Id | Text |
| Xray_Created_Date | Text |
Xray Entities Custom Fields
List of Available Xray Labels
| Label | Type |
|---|---|
| Xray_Impacted_Artifact | Text |
| Xray_Impacted_Component | Text |
| Xray_Package_Type | Text |
| Xray_Vulnerability_Id | Text |
| Xray_Violation_Type | Text |
| Xray_Severity | Text |
| Xray_JFrog_Research_Severity | Text |
| Xray_CVEs | Text |
| Xray_CVSS_V2_Score | Text |
| Xray_CVSS_V3_Score | Text |
| Xray_Watch_Name | Text |
| Xray_Policy_Name | Text |
| Xray_Triggered_Rule | Text |
| Xray_Component_License_Id | Text |
Custom Fields and Labels in the Jira Issue
Step 3 Configuring the Policy Rules
Enable the Jira ticket creation in the Policy rules. In Policy > Policy Rules > Automatic Actions, select the Create Jira Ticket checkbox to trigger the creation of Jira tickets when violations are found that match the rule you defined in the Policy.
Step 4 Configuring the Watch with the Jira Configuration Profile
Attach the Jira Configuration Profile to the Watch that contains all of your Policies. In Watches > Watch settings select the Enable Jira Ticket Creation checkbox and from the drop-down list select the relevant Jira Configuration Profile. The Jira tickets that are triggered will contain the configurations you defined in the selected configuration profile.
Viewing Created Jira Tickets
Violations Report
When generating a Violations Report, the created Jira tickets appear in the details of each violation.
Jira Ticket
These are examples of the generated Jira tickets:
Security Violation
License Violation 
REST API Support
You can enable Jira ticket creation using the following REST APIs:
Manual Creation of Jira Tickets
In addition to automatic creation of Jira ticket, Xray enables you to manually create a Jira ticket for the following issue types:
- Violations (all types)
- Operational risk
- License violation
- Security
Manually Creating a Jira Ticket
More Permissions for OAuth2
If you have set up Jira integration with Xray using OAuth2, manual creation of Jira tickets requires some extra permissions. Ensure that the permissions are updated before manually creating Jira tickets. For more information, see Connecting Jira to Xray Using OAuth2 .
To manually create a Jira ticket:
- In the Application tab, navigate to a violation on one of the following pages:
- Artifactory > Builds
- Artifactory > Artifacts
- Scans List > Repositories
- Scans List > Builds
- Scans List > Release Bundles
- Watch Violations
- Click the vulnerability ID, and in the window that appears on the right, click the action button (three dots) and click Create a Jira.
In the Create a Jira Ticket window, update the following fields:
Field
Description
Profile Name
This dropdown lists all the Jira configuration profiles that were defined when creating the Jira integration.
Click to select the relevant profile.
Issue Type This is auto-filled according to the profile selection.
Labels This is auto-filled with all the labels. The drop-down displays the labels on the profile integration page. While you can remove the label from the field, it will not delete it from the main profile integration.
Component
This is auto-filled. The drop-down lists all the components affected by the vulnerability and all components are selected by default. You have the option of selecting a subset of the listed components.
Title The is auto-filled based on the type of violation.
Description
This is auto-filled and cannot be edited.
Description is auto-filled based on the violation's current state and the selected components. If the components are changed, the description is updated accordingly.
User comment
Add relevant comments for the ticket.
Click Create.
If a ticket has already been created for the issue, you have the option of updating it.
Jira Ticket Indicator
Whenever a Jira ticket is manually created for a violation, it is indicated with an icon 
. Hover over the icon to see the list of Jira tickets that have already been created for the violation. If there are multiple tickets, the last created ticket will be the leading ticket.
The Jira indicator along with the Jira Id is also shown on the Details screen. Clicking on a Jira Id redirects you to the Jira page for that ticket.
Manually Updating a Jira Ticket
To manually update a Jira ticket:
- In the Application tab, navigate to a violation on one of the following pages:
- Artifactory > Builds
- Artifactory > Artifacts
- Scans List > Repositories
- Scans List > Builds
- Scans List > Release Bundles
- Watch Violations
- Click the vulnerability ID that already has a Jira indication, and in the window that appears on the right, click the action button (three dots) and click Update a Jira.
In the Update a Jira Ticket window:
- If there are multiple tickets, click the Jira Ticket Number drop-down to select the ticket to be updated.
Scroll down to the Add Comments field and add relevant comments for the ticket.
All the other fields are grayed out and cannot be updated.
- Click Update.
The Title and Description are automatically updated based on the current state of the violation.
If you try to update a ticket that has already been deleted, a message is displayed to that effect and you will have the option of creating a new ticket.
