Limiting Jira project access

Due to the way that Jira integrations work (both Forge and Connect apps), when you install Swarmia on your Jira instance, we automatically get access to all of the Jira projects in that instance.

There are two ways to limit this access: using Atlassian Guard or by using a user level API token instead of our Connect app.

Recommended: limiting the Swarmia app's access with Atlassian Guard

You can limit what Jira data third party apps have access to using Data Security policies provided by Atlassian Guard. This is a paid feature (the free one is not granular enough), although it is included in their Cloud Enterprise plans. Here are Atlassian's docs for it.

To add a rule, navigate to Data Security Policies under https://admin.atlassian.com/ and click on "Create policy"

Depending on your needs, you might either block Swarmia from all projects by default, and allowlist the ones you need, or block a few specific projects that you don't want to give access to.

After you are done defining your policy, remember to click "Activate policy" for it to take effect!

Some data is still available

Due to the way the Data Security policies work, we still have access to some metadata of the blocked projects. Namely, we are able to see that the projects exist, but we cannot fetch their issues. Please ensure that you don't have sensitive information in the project names.

This also means that you'll still see the blocked projects in Swarmia's project sync settings, but in reality we are not able to sync issues from those projects.

To see what data exactly we still have access to, you can consult the API docs. Any endpoint marked with Data Security Policy: Exempt from app access rules is still accessible by us regardless of any rules you added.

Using a user level API token to authorize Swarmia

Instead of installing the Connect app, it is also possible to integrate Jira to Swarmia by using a user level API token. That way, you can limit Swarmia's access by limiting which projects the user has access to.

Swarmia needs access to the emails of Jira users, which is essential to correctly map authors across different tools like Github. This is not possible to do with personal API tokens, so you'll also need to install our minimal Forge application that allows Swarmia to access just the user emails on your Jira instance.

First, install the Swarmia author identity mapper application on your Jira instance. The application can be found here.

Note that it might take few minutes after the application is installed for us to receive the installation event.

Once the application is installed, log in to your Swarmia account and go to Settings - Jira, then select the "Use API token" installation:

The next steps will guide you through linking Swarmia to your Jira instance.

Step 1: Install the Jira email app

Navigate to the application settings in your Jira instance.

Then click on the "Configure" button. This will bring you on the app's configuration page. If the app is recognized on our side as installed (this might take a few minutes after the installation on your instance), a secret token will be displayed. Copy this token and paste it in the field of the Step 1, then click "Connect".

This will bring you to the second step.

Step 2: Provide an API token

Provide the credentials (user email and API token) of the user Swarmia will use to access your Jira instance.

After clicking "Confirm", Swarmia will immediately use these credentials to retrieve the list of projects that are visible to the given user.

Step 3: Create a webhook

The last step is to create a webhook in your Jira installation to keep your Jira data in sync with Swarmia. This step needs to be done manually as API tokens are not authorize to register webhooks automatically. The last panel will provide you the information needed to create the webhook in your Jira UI:

• The webhook url and the webhook token

• The JQL filters matching the visible projects for the given API token

• The list of events that we need to receive through webhooks

After checking the "I have created the webhook in Jira or saved the information" box, you can click the "Finish setup" button. Swarmia will then start automatically syncing your data using the API token you provided.

Important note on API token expiry

The Jira API token will expire after maximum a year. After that, you will need to refresh the credentials in Swarmia in order to continue to get up-to-date data.

You can update the Jira credentials in the "Configuration" tab, in the Jira settings page.