Jira Cloud
Connector maturity: Beta. See Connector maturity.
Description
The Jira Cloud connector uses the Jira Cloud REST API v3 to discover the users, integration (app) accounts and groups of an Atlassian cloud site, and which users are in which groups. It authenticates with an Atlassian account email address and an API token. The same system can also raise Jira issues for findings.
System Type Classification
| Field | Value |
|---|---|
| System Type | Application |
| Default Scan Priority | 500 |
Version Support
| OrbisID Edition | Supported |
|---|---|
| Community | No |
| Pro | Yes |
| Enterprise | Yes |
Supported Protocol
| Protocol | Port | Notes |
|---|---|---|
| REST API (HTTPS) | 443 TCP | HTTP Basic: Atlassian account email and API token |
What OrbisID Discovers
| Data | Source |
|---|---|
| Users and app accounts | GET /rest/api/3/users/search |
| Groups | GET /rest/api/3/group/bulk |
| Group memberships | GET /rest/api/3/group/member |
An account is named by its email address, or by its Atlassian account ID when the user hides their email address. App accounts (integrations such as the Slack or GitHub apps) are Non-Human accounts of subtype Application. Service desk customers are not Jira users and are not scanned. A group whose name contains admin (for example site-admins or jira-administrators) is treated as privileged.
Connection Requirements
Required Permissions
Create an Atlassian account for OrbisID (a dedicated service account is best) and give it:
- Browse users and groups global permission, so it can list users and groups
- Site administration if you want group members that the account cannot otherwise see
Atlassian only returns a user's email address if the user's profile visibility allows it. Where it is hidden, OrbisID names the account by its account ID instead.
Credential Mapping
| OrbisID Field | Value |
|---|---|
credential.username | The Atlassian account email address |
credential.password | An API token for that account |
system.hostname | The Jira Cloud site (for example acme.atlassian.net) |
Network Requirements
The OrbisID server must have HTTPS access to your *.atlassian.net site on port 443.
Configuration Steps
- At id.atlassian.com, sign in as the account OrbisID will use and choose Create API token
- Create a Credential in OrbisID:
- Username: the account's email address
- Password: the API token
- Navigate to Systems → Add System
- Fill in the fields:
| Field | Value |
|---|---|
| Name | Descriptive name (for example Jira Cloud - Engineering) |
| OS Type | Jira Cloud |
| System Type | Application |
| Hostname | Your site, for example acme.atlassian.net |
| Credential | The API token credential |
- Click Test Connection
- Click Save
Ticketing for findings
Requires Pro or Enterprise edition.
Besides scanning, OrbisID can raise Jira issues for findings, assigned to the finding's owner, and keep them in sync. Only one system can have ticketing turned on. Open Systems, choose Ticketing on the Jira system and set:
| Setting | Description |
|---|---|
| Raise tickets for findings | The switch. Nothing is raised until it is on |
| Credential | A credential that can create and transition issues in the project. Leave empty to use the system's scan credential |
| Project key | The project issues are created in, in capitals (for example SEC) |
| Issue type | The issue type, such as Task or Bug |
| Raise tickets for | Severities that raise an issue. Critical and High by default |
| Jira priority per severity | Optional. A severity with no priority uses the project's default |
| Done transition | The transition used to finish an issue. If the workflow has none with this name, any transition into a Done status is used |
| Most tickets per run | Stops a large backlog flooding Jira when you first turn this on. Default 50 |
The credential's user needs Create issues, Add comments, Transition issues and Assign issues in the project, and Browse users so the owner (found by email address) can be looked up. An owner who is not found is left unassigned and the issue is still created. Use Test connection to check the saved credential and project, and Sync now to run immediately.
Each issue carries the finding's KRI, the affected item, system, severity, due date and a link back to the Findings page, and the labels orbisid and one that identifies the finding. When the finding is resolved by a scan, OrbisID comments on the issue and moves it to Done. If the issue's workflow needs a resolution or another field to reach Done, add a transition that does not, or the move fails and the issue shows the error.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
401 Unauthorized | Wrong email or an expired or revoked API token | Create a new API token and update the credential |
403 Forbidden on scan | Missing Browse users and groups | Grant the permission to the account |
Accounts named like 5b10a... | Users hide their email address | Expected; the account ID is used instead |
| Issue not moved to Done | No transition into a Done status, or one needs a required field | Allow a simple transition to Done, or set Done transition |
| Issue created unassigned | The owner has no matching email in Jira, or is inactive | Check the owner's email in OrbisID matches their Jira account |