Edit

Set up the Jira Cloud service for Jira Cloud Copilot connector ingestion

The Jira Cloud connector for Microsoft 365 Copilot and Microsoft Search enables your organization to index and search Jira Cloud content directly within Microsoft 365 experiences. By integrating Jira Cloud with Microsoft 365, users can discover issues, projects, and other Jira data through Copilot and Microsoft Search, improving productivity and collaboration.

This article describes the Jira Cloud configuration that you must complete before you deploy the Jira Cloud Copilot connector in the Microsoft 365 admin center.

For information about how to deploy the connector, see Deploy the Jira Cloud connector.

Prerequisites

Before you begin, make sure that you meet the following prerequisites:

  • You must be a Jira Cloud site admin. Coordinate with an organization admin to manage account access and grant the Jira app admin role in centralized user management. The administrator changing global permissions or company-managed permission and security schemes must also have Administer Jira permission.
  • Confirm that Jira REST APIs are enabled and accessible.
  • Make sure that your organization allows outbound connections to Microsoft Graph connector IPs if network restrictions apply.
  • Make sure that you have access to the Atlassian Developer Console.

Setup checklist

Task Role
Identify the Jira Cloud instance URL Jira admin
Enable API access Jira admin
Create an account and grant permissions Jira admin, with an organization admin for account access and Jira app admin role assignment
Choose an authentication method Jira admin
Review profile visibility for identity mapping Jira admin
Estimate content scope Jira admin

Identify the Jira Cloud instance URL

The Jira Cloud instance URL is required when you deploy the connector in the Microsoft 365 admin center. To identify the Jira Cloud instance URL:

  • Sign in to your Jira Cloud account at https://<yourcompany>.atlassian.net.
  • From the dashboard, note the base URL in the browser address bar. For example: https://<yourcompany>.atlassian.net.

Note

  • Don't use a project-specific URL (such as /browse/PROJ-123).
  • Test the URL in a browser to confirm that it resolves to your Jira dashboard.

Enable API access

Verify that Jira Cloud REST APIs are enabled by default and that no API restrictions or app allowlists prevent access.

If your organization uses network-level restrictions, add the Microsoft Graph connector IPs to the allowlist.

Create an account and grant permissions

Create a dedicated Jira Cloud account for the connector instead of using a personal account.

To create the account:

  • Sign in to the Atlassian Admin Console as an organization or site admin.
  • Go to Directory > Users.
  • Choose Invite users and enter a dedicated email address, such as jira-connector@contoso.com.
  • Under Products, select Jira Software.
  • Grant the account only the permissions required for indexing and security trimming.

Grant these permissions to the account used to authenticate the connector:

Note

Atlassian's current documentation uses spaces for projects and work items for issues. Depending on your Jira interface, you might see Space settings, Browse spaces, and Work items instead of Project settings, Browse projects, and Issues.

Permission Type Required when Setup steps
Administer Jira Global permission Search permissions are set to Only people with access to this data source. Organization admin: Atlassian Administration > Directory > Users > account > Grant access > Jira Administration > App admin. Select Grant access and keep Jira user access. In Jira, open Settings > System > Global permissions and confirm the account's group has Administer Jira.
Browse users and groups Global permission Search permissions are set to Only people with access to this data source. Settings > System > Global permissions > Grant Permission. Choose Browse users and groups and a group containing the account, then select Add.
Browse projects Project permission All projects to index. Company-managed: Space settings > Permissions > Edit permissions > Browse projects > Update. Include the account or its group in the grants.
Team-managed: Space settings > Access > Add people. Add the account as Viewer or another role that can view issues.
Issue-level security access Issue-level access Restricted issues to index. Company-managed: Settings > Work items > Work item security schemes > your scheme > Security Levels > Add. Include the account or its group in each required level.
Team-managed: Space settings > Access. Assign the account a role allowed to view the restricted issues. Check existing issues separately.

To verify access, sign in as the connector account. Open an unrestricted issue in each target project and a restricted issue for each security level or restriction in scope. Confirm that each intended issue is visible before configuring ingestion.

Choose an authentication method

To authenticate and sync issues from Jira, choose one of the following supported authentication methods:

  • OAuth (recommended) - Use the standard OAuth option in the connector. The Jira admin doesn't need to register an Atlassian app or set up an OAuth app manually.
  • Customized Atlassian Jira OAuth 2.0 - Use your own Atlassian OAuth 2.0 app registration and provide the client ID and secret during connector setup.

To use Customized Atlassian Jira OAuth 2.0 for authentication:

  1. Register an app in Atlassian Jira so Microsoft Search and Microsoft 365 Copilot can access the instance. For more information, see Enable OAuth 2.0.

  2. Sign in to the Atlassian Developer console with your Atlassian Jira admin account.

  3. Choose Create and select OAuth 2.0 integration.

  4. Provide an appropriate name for the application and create the new app.

  5. On the left navigation pane, go to Permissions. Select Add for Jira API and select Configure. Under Granular Permissions, add the required scopes.

    # Scope name Code
    1 View fields read:field:jira
    2 View avatars read:avatar:jira
    3 View project categories read:project-category:jira
    4 View projects read:project:jira
    5 Read field configurations read:field-configuration:jira
    6 View issue types read:issue-type:jira
    7 View project properties read:project.property:jira
    8 View users read:user:jira
    9 View application roles read:application-role:jira
    10 View groups read:group:jira
    11 Read issue type hierarchies read:issue-type-hierarchy:jira
    12 View project versions read:project-version:jira
    13 View project components read:project.component:jira
    14 View issue details read:issue-details:jira
    15 View audit logs read:audit-log:jira
    16 View issue meta read:issue-meta:jira
    17 View project roles read:project-role:jira
    18 View issue security levels read:issue-security-level:jira
    19 View issue security schemes read:issue-security-scheme:jira
    20 View permission schemes read:permission-scheme:jira
    21 View permissions read:permission:jira
    22 View attachments read:attachment:jira
    23 View comments read:comment:jira
    24 View comment properties read:comment.property:jira
    25 View webhooks read:webhook:jira
    26 View JQL read:jql:jira
    27 Create and update webhooks write:webhook:jira
    28 Delete webhooks delete:webhook:jira
    29 View epics and related issues read:epic:jira-software
  6. On the left navigation pane, go to Authorization to add the callback URL:

    • For Microsoft 365 Enterprise: https://gcs.office.com/v1.0/admin/oauth/callback
    • For Microsoft 365 Government: https://gcsgcc.office.com/v1.0/admin/oauth/callback
    • For Microsoft 365 GCC High (Government Community Cloud High): https://gcs.office365.us/v1.0/admin/oauth/callback
    • For Microsoft 365 DoD (Department of Defense): https://gcs-dod.office365.us/v1.0/admin/oauth/callback
  7. Select Save.

  8. In the left pane, go to Settings to get the client ID and secret. Complete the connection settings step by using the Client ID and Secret.

    Note

Review profile visibility for identity mapping

The Jira Cloud Copilot connector supports search permissions visible to Everyone or Only people with access to this data source. If you choose Everyone, indexed data appears in the search results for all users. If you choose Only people with access to this data source, indexed data appears in the search results for users who have access to them.

Important

If you plan to configure the connector with Only people with access to this data source, the Jira Cloud Copilot connector must be able to read a user's email ID in Jira to appropriately assign security permissions in Microsoft Search and Microsoft 365 Copilot. This requirement means you need to ensure one of the following conditions:

  • All users select the Anyone option for their profile visibility settings. To learn more about profile visibility settings, see Update your profile and visibility settings.
  • For organizations that use managed accounts:
    • All users select the managed account setting in profile visibility settings.
    • Users who aren't part of the managed account (same as crawling account) select Anyone in their profile visibility settings.
    • The crawling account used during connection configuration has the managed account domain.

Estimate content scope

Determine the number of projects and issues to index. For instances with more than 10,000 issues:

  • Enable incremental sync.
  • Plan for throttling.
  • Full indexing can take several hours. Schedule the initial sync during off-business hours.

Next step