Skip to main content

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​

FieldValue
System TypeApplication
Default Scan Priority500

Version Support​

OrbisID EditionSupported
CommunityNo
ProYes
EnterpriseYes

Supported Protocol​

ProtocolPortNotes
REST API (HTTPS)443 TCPHTTP Basic: Atlassian account email and API token

What OrbisID Discovers​

DataSource
Users and app accountsGET /rest/api/3/users/search
GroupsGET /rest/api/3/group/bulk
Group membershipsGET /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 FieldValue
credential.usernameThe Atlassian account email address
credential.passwordAn API token for that account
system.hostnameThe 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​

  1. At id.atlassian.com, sign in as the account OrbisID will use and choose Create API token
  2. Create a Credential in OrbisID:
    • Username: the account's email address
    • Password: the API token
  3. Navigate to Systems → Add System
  4. Fill in the fields:
FieldValue
NameDescriptive name (for example Jira Cloud - Engineering)
OS TypeJira Cloud
System TypeApplication
HostnameYour site, for example acme.atlassian.net
CredentialThe API token credential
  1. Click Test Connection
  2. 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:

SettingDescription
Raise tickets for findingsThe switch. Nothing is raised until it is on
CredentialA credential that can create and transition issues in the project. Leave empty to use the system's scan credential
Project keyThe project issues are created in, in capitals (for example SEC)
Issue typeThe issue type, such as Task or Bug
Raise tickets forSeverities that raise an issue. Critical and High by default
Jira priority per severityOptional. A severity with no priority uses the project's default
Done transitionThe 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 runStops 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​

SymptomLikely CauseResolution
401 UnauthorizedWrong email or an expired or revoked API tokenCreate a new API token and update the credential
403 Forbidden on scanMissing Browse users and groupsGrant the permission to the account
Accounts named like 5b10a...Users hide their email addressExpected; the account ID is used instead
Issue not moved to DoneNo transition into a Done status, or one needs a required fieldAllow a simple transition to Done, or set Done transition
Issue created unassignedThe owner has no matching email in Jira, or is inactiveCheck the owner's email in OrbisID matches their Jira account