Jira
- 02 Sep 2024
- 3 Minutes to read
- Contributors
- Print
- DarkLight
Jira
- Updated on 02 Sep 2024
- 3 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Connection
A connection to Jira can be established via an API Token or an OAuth2 (SSO) connection.
The primary distinction between an API Token and an SSO connection lies in their scope and longevity. The API Token does not offer scoping options (permission granularity), whereas the SSO connection does. Conversely, an API Token is perpetual and requires no renewal, whereas an SSO connection may necessitate periodic reconnection per Atlassian's token policy.
API Token
An API Token can be generated through the Atlassian User Interface. This is accessible on the security page of the user's profile. For more information, please visit: https://id.atlassian.com/manage-profile/security/api-tokens.
SSO Connection
For SSO the connection will use the connecting user credentials requesting the following read scopes. For an SSO connection, the connecting user's credentials will be utilized. This process involves requesting the following read scopes:
read:user:jira
read:application-role:jira
read:avatar:jira
read:group:jira
read:project-role:jira
read:issue-type-hierarchy:jira
read:issue-type:jira
read:project-category:jira
read:dashboard:jira
read:project.component:jira
read:project-version:jira
read:project.property:jira
read:project:jira
read:workflow:jira
read:attachment:jira
read:issue:jira
read:issue-worklog:jira
read:status:jira
read:issue-status:jira
read:issue-details:jira
read:issue-meta:jira
read:audit-log:jira
read:field-configuration:jira
read:field:jira
read:jql:jira
read:webhook:jira
write:webhook:jira
delete:webhook:jira
read:issue-security-level:jira
read:issue.changelog:jira
read:issue.vote:jira
read:me
offline_access
A full list of scopes and descriptions can be found here: https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/
Supported Resources
Issues
Filtering and Selection
When establishing a connection, it is feasible to refine the index scope of the connected account by selecting specific projects. This feature allows for more targeted indexing based on the user's requirements.
It is crucial to note that narrowing down the indexing scope does not impact the scope of the token (credentials). This means the token retains access to all available projects, regardless of the selected indexing scope.
Sync
The integration retrieves all issues from the selected projects during the connection process.
Following the initial synchronization, the integration updates with any changes in each project every 15 minutes.
API Calls
The table below outlines the primary endpoints utilized by the integration -
Endpoint | Docs | Purpose |
|---|---|---|
/rest/api/3/project/search | List and filter for selected projects | |
/rest/api/3/search | List issues of a project | |
/rest/api/3/issuetype | Get information of custom issue types (icons, names etc) | |
/rest/api/3/issue/{issueIdOrKey} | Get a specific issue in order to list its comments |
Resource Level Permissions (RLP)
RLP is available for Jira, ensuring that any shared link adheres to the permissions set within Jira. Currently, RLP enforces permissions at the project level. Efforts are underway to extend this to the issue level. For more details on RLP Links and other link types, refer to our general RLP documentation.
Prerequisite
To enable RLP mode for Jira, you must first install our Atlassian Connect App. This app facilitates indexing and syncing user and group directories, allowing for permission enforcement based on these parameters.
Installation Guide
Follow these steps to install the app:
Atlassian (JIRA, Confluence) Installation for Permission Based Link
Sign in to your JIRA/Confluence workspace. If you are already signed in and have multiple workspaces, ensure you are signed into the correct account for the intended workspace.
Go to Apps > Manage your apps.
Click on Settings at the bottom of the page.
.png "image-1725174067812(1).png")
Ensure that the Enable private listings and Enable development mode options are checked and hit Apply.
Refresh the page, and click on the Upload app button that appears.
.png "image-1725174279807(2).png")
Fill in the app descriptor URL - the value depends on your installation:
For Jira use -
https://jira.unleashing.app/install/descriptor/
Wait for the app to install successfully. Please let us know if the installation fails.
Scopes
The required scopes for the Connect App are:
ADMIN
ACT_AS_USER
ACCESS_EMAIL_ADDRESSES
READ
A comprehensive list of scopes and their descriptions is available here: Atlassian Connect App Scopes.
Connection
There are two methods to connect the RLP link:
As App User: Accesses resources based on a user created for the installed app (Unleash) in the previous step.
As Impersonated User: Accesses resources based on the credentials of the connecting user.
Additional API Calls
The following table is additional endpoints that are used for enforcing permissions:
Endpoint | Docs | Purpose |
/rest/api/3/user/search | List users connected to Jira | |
/rest/api/3/user/email/bulk | Match Jira accounts with email addresses | |
/rest/api/3/group/bulk | List groups connected to Jira | |
/rest/api/3/group/member | List all members of specific group | |
/rest/api/3/project/{projectKeyOrId}/permissionscheme | Get the assigned project permissions scheme | |
/rest/api/3/project/{projectIdOrKey}/role | Get the roles for specific project | |
/rest/api/3/project/{projectIdOrKey}/role/{id} | Get the role details of a specific role in project |
Was this article helpful?