> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/integrations/tracker-integrations/jira-tracker.md).

# Jira findings

Install P0's Jira findings tracker for a Jira Cloud site, so P0 files findings as Jira issues as an Atlassian service account.

This page documents how to install P0's findings tracker for a Jira Cloud site. P0 files each finding as an issue in the Jira project you choose, groups a monitor's issues under one parent issue, and says in each issue who it's assigned to and why. In the P0 app, this integration is called **Jira findings**.

It does what the [Jira](https://docs.p0.dev/integrations/tracker-integrations/jira.md) tracker does, without the P0 app from the Atlassian Marketplace: P0 signs in to Jira as a service account you control, with an OAuth credential you create. Choose it when you can't, or would rather not, install a Marketplace app on your site. Your organization uses one of the two.

{% hint style="info" %}
The Jira findings integration is in preview.
{% endhint %}

## How it works

* **P0 acts as an Atlassian service account.** You create a service account in Atlassian Administration, give it permission to work on one project, and give it an OAuth 2.0 credential. P0 files and labels issues as that account.
* **P0 stores the client secret encrypted.** You enter the credential's client ID and client secret in P0. P0 encrypts the client secret, and never shows it again.
* **P0 calls Jira, and Jira never calls P0.** P0 reaches Jira through Atlassian's API at `api.atlassian.com`. Nothing on your site needs to reach P0.
* **One site and one project.** P0 files every finding in the project you choose on one site.
* **It replaces the Jira tracker.** You can set up the site here while the [Jira](https://docs.p0.dev/integrations/tracker-integrations/jira.md) tracker still files your findings. Once you save a project here, P0 files your findings here, even while the Jira tracker is still installed. See [#move-from-the-jira-tracker](#move-from-the-jira-tracker "mention").

## Before you begin

You need:

* **A Jira Cloud site**, at `<name>.atlassian.net`.
* **An admin of the Atlassian organization that owns the site**, to create the service account and its OAuth credential.
* **A Jira admin for the project P0 files findings in**, to give the service account its permissions.

## Install Jira findings

1. Open the P0 dashboard at [p0.app](https://p0.app) and log in to your organization.
2. In the sidebar, click **Integrations**. Under **Trackers**, click **Jira findings**.
3. Select the **Jira site** component, and click **Add Site**.

The installer then takes you through three pages: the form for a new site, the site's setup page in steps 1 to 4, and its configure page in steps 5 and 6. The setup page lists the six steps with the same titles as below. Once the site is installed, you choose the project on the integration's page.

### Add the site

The form is titled **Installing a new Site**.

1. In **Site host**, enter the site's host in lowercase, such as `acme.atlassian.net`. Leave out `https://` and anything after the host.
2. Click **Next**. P0 saves the site and opens its setup page, titled **Configuring Site**, followed by the site's host.

If P0 can't save the site, it shows why at the top of the form. See [#when-you-add-the-site](#when-you-add-the-site "mention") for each message.

### Step 1: Create the service account

In [Atlassian Administration](https://admin.atlassian.com), in the organization that owns the site, create a service account for P0. Service accounts are under **Directory**, then **Service accounts**. P0 acts in Jira as this account, so use it for nothing else.

### Step 2: Give it access to Jira

Give the service account access to Jira on the site.

### Step 3: Give it the tracker's permissions

In the permission scheme of the project P0 files findings in, give the service account these project permissions:

* **Browse projects**
* **Create issues**
* **Edit issues**
* **Assign issues**

Then add it to a group that holds the global permission **Browse users and groups**, which P0 needs to find each issue's assignee by email. The service account needs nothing else: P0 files and labels issues, and changes no Jira settings.

### Step 4: Create its OAuth credential

On the service account's page in Atlassian Administration, [create an OAuth 2.0 credential](https://support.atlassian.com/user-management/docs/create-oauth-2-0-credential-for-service-accounts/) with these scopes:

* `read:jira-user`
* `read:jira-work`
* `write:jira-work`

Copy its client ID and its client secret. Then click **Next** on the setup page.

### Step 5: Enter the client ID and secret

P0 opens the site's configure page, which lists the steps again with the first four done.

1. In **Client ID**, enter the client ID of the OAuth credential from step 4.
2. In **Client secret**, enter its client secret.

### Step 6: Validate

Click **Finish**. P0 checks the site, in this order:

1. Atlassian issues a token for the OAuth credential.
2. The site answers as a Jira Cloud site.
3. The credential signs in as a service account.
4. The service account holds Browse projects, Create issues, Edit issues and Assign issues on at least one project, and the global permission Browse users and groups.

P0 stops at the first check that fails, and shows what to fix at the top of the page. See [#when-p0-validates-the-site](#when-p0-validates-the-site "mention") for each message. Fix it, then click **Finish** again. When every check passes, P0 stores the client secret encrypted, installs the site and opens the **Jira findings** page, where you choose the project. P0 runs the same checks on the installed site every hour.

### Choose the project

The top of the **Jira findings** page lists the projects the service account can browse. P0 files no findings until you save a project.

The project needs the **Task** issue type, which P0 files each finding as, and the parent issue type, **Epic** unless you enter another. P0 doesn't check the issue types when you save, so a project without them saves, and then every issue P0 files there fails.

1. Select the project where P0 will create issues.
2. Optionally, enter the issue type each finding's issue goes under, if not Epic. Enter it as Jira names it in the project.
3. Click **Save**. P0 checks that the service account holds every permission from [#step-3-give-it-the-trackers-permissions](#step-3-give-it-the-trackers-permissions "mention") on that project, Browse users and groups included, and says when the project is saved.

If the save fails, see [#when-you-choose-the-project](#when-you-choose-the-project "mention").

{% hint style="success" %}
You can now assign P0 findings in Jira. See [Finding details](https://docs.p0.dev/posture/finding-details.md#assign) to learn how.
{% endhint %}

## Move from the Jira tracker

If the [Jira](https://docs.p0.dev/integrations/tracker-integrations/jira.md) tracker files your findings today, it keeps filing them until you cut over.

1. Install Jira findings, through [#step-6-validate](#step-6-validate "mention"), while the Jira tracker runs.
2. On the **Jira findings** page, choose the project and click **Save**, as in [#choose-the-project](#choose-the-project "mention"). From then on, P0 files your findings through Jira findings.
3. Remove the **Jira** tracker integration in P0, when you're ready.

Issues the Jira tracker filed stay in Jira, and on the same site P0 still clears their labels when their findings resolve. Findings filed after the move go under new parent issues.

## What P0 does in Jira

* **One parent issue for each scope in an assessment.** Before it files findings for a scope, P0 files a parent issue named `Remediation - <scope>`, of the parent issue type you chose, and files each finding's issue under it. Later findings for the same scope in the same assessment go under the same parent.
* **One issue for each finding**, of type Task, with the label `P0_finding`. Its description says what P0 found, and who the issue is assigned to and why. P0 sets the issue's assignee in Jira when it can find that person, as in [#limitations](#limitations "mention").
* **Labels cleared when a finding resolves.** P0 removes every label from the finding's issue, `P0_finding` and any you added. P0 doesn't close or transition issues.
* **One issue for each service account key to rotate**, assigned to the key's owner, when P0 manages your keys.

## Error messages

In each message, `<host>` is the site's host. Once you've fixed the cause, retry what failed.

### When you add the site

| Message                                                                                                                                    | What to do                               |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| `The tracker files findings on one Jira site, and <host> is already added. Remove it to add another.`                                      | Remove the other site first, or keep it. |
| `Enter the site's host in lowercase, as <name>.atlassian.net, such as acme.atlassian.net. Leave out https:// and anything after the host.` | Enter the host alone, in lowercase.      |
| `The Jira site <host> is already installed, and there's nothing to change.`                                                                | Open the site from the list instead.     |

### When P0 validates the site

P0 validates the site when you click **Finish** in [#step-6-validate](#step-6-validate "mention"), and when you click **Update** after you change the client ID or the client secret. It runs the same checks on the installed site every hour. A failed check reads `The Jira site <host> failed its install check while <check>: <what to fix>`. The part after `while` names the check:

| The message says                                              | What to do                                                                                                                                                                                                                                             |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `while getting an access token from Atlassian`                | If the message says `Atlassian refused the OAuth credential`, check that **Client ID** and **Client secret** are the same credential's, and that the client secret is its current one. If it says P0 couldn't reach Atlassian, try again later.        |
| `while looking up the site's cloud ID`                        | The host doesn't resolve, or doesn't answer as a Jira Cloud site. Check the host. If it's wrong, remove the site and add it again with the right host.                                                                                                 |
| `while checking the account the OAuth credential signs in as` | The credential belongs to an account that isn't a service account. Create the OAuth credential on the service account, as in [#step-4-create-its-oauth-credential](#step-4-create-its-oauth-credential "mention"), and enter its client ID and secret. |
| `while checking the service account's Jira permissions`       | The message names each missing permission, such as `Create issues`. Grant it as in [#step-3-give-it-the-trackers-permissions](#step-3-give-it-the-trackers-permissions "mention").                                                                     |

P0 can also show these messages:

| Message                                                                                                                                                   | What to do                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `Enter the client ID of the service account's OAuth credential.`                                                                                          | Fill in **Client ID**.                                                                                                               |
| `That doesn't look like an OAuth client ID. Enter the client ID from the service account's OAuth credential in Atlassian Administration, not its secret.` | Enter the client ID. If you pasted the client secret into **Client ID**, create a new credential and enter its client ID and secret. |
| `Enter the client secret of the service account's OAuth credential.`                                                                                      | Fill in **Client secret**.                                                                                                           |
| `The client secret starts or ends with whitespace. Paste it again without it.`                                                                            | Paste the client secret again, with nothing before or after it.                                                                      |
| `The Jira site <host> now answers with another cloud ID than when it was added, so it may be another site. Remove the site and add it again.`             | Check that the host still belongs to your site. Then remove the site and add it again.                                               |

### When you choose the project

| Message                                                                                                                                              | What to do                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `The service account can't browse that project. Choose another, or give the account Browse projects on it.`                                          | Give the service account Browse projects on the project, as in [#step-3-give-it-the-trackers-permissions](#step-3-give-it-the-trackers-permissions "mention"), or choose another project. |
| `The service account lacks these permissions on <KEY>: <permissions>. Grant them in the project's permission scheme, then choose the project again.` | Grant the permissions it names, as in [#step-3-give-it-the-trackers-permissions](#step-3-give-it-the-trackers-permissions "mention"), then click **Save** again.                          |
| `The service account can't browse any project. Give it the permissions below on the project P0 files findings in.`                                   | Give the service account its project permissions, as in [#step-3-give-it-the-trackers-permissions](#step-3-give-it-the-trackers-permissions "mention").                                   |

### When P0 files findings

| Message                                                                                          | What to do                                                                        |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `The Jira findings tracker has no installed Jira site. Ask your P0 admin to finish its install.` | Finish installing the site, as in [#step-6-validate](#step-6-validate "mention"). |
| `No Jira project selected in Jira configuration`                                                 | Choose the project, as in [#choose-the-project](#choose-the-project "mention").   |

## Change the install later

* **Choose another project.** On the **Jira findings** page, select the project and click **Save**. P0 checks the service account's permissions on it again.
* **Rotate the client secret.** Generate a new client secret for the OAuth credential. On the site's page in P0, enter it in **Client secret**, and click **Update**. P0 validates the site with it, as in [#step-6-validate](#step-6-validate "mention"), and uses it from then on.
* **Use another OAuth credential.** Create the credential, as in [#step-4-create-its-oauth-credential](#step-4-create-its-oauth-credential "mention"). On the site's page in P0, enter its client ID and client secret, and click **Update**.
* **Use another site.** Remove the site, and add the new one. Adding a site again starts the tracker over, so choose the project again too. P0 files no findings in between.
* **Go back to the Jira tracker.** Remove the whole **Jira findings** integration, not only its site. While Jira findings is installed, P0 files findings through it, not the Jira tracker.

## Limitations

* **One site and one project.** P0 files every finding in one project on one site.
* **Assignees are found by email.** P0 sets an issue's assignee in Jira only when the assignee's email belongs to exactly one active Atlassian account that the service account can see. If someone hides their email in their Atlassian profile's visibility settings, the issue has no assignee in Jira, and its description still names them.
