Support Jira Cloud service accounts in the Jira integration (via API tokens)

Ben Kingrequested to merge
benjaminking-jira-service-account into master

What does this MR do and why?

We've had a lot of interest in issue #576326 (closed) from users who want to utilise a designated service account for their integration linking instead of a standard/regular user account.

This approach involves a user defining the Jira API URL as: https://api.atlassian.com/ex/jira/{cloudid}. This is the API 'endpoint' used by service accounts, with applicable REST API calls made against this. It looks like that in two parts of the code used for the Jira issue integration we were manually 'setting' the API path, and not respecting any context path (which would be: /ex/jira/{cloudid}).

While working on this MR, I've also realised that a user's API token will fail if they use scoped tokens, as Atlassian requires scoped tokens to use the new API address. The documentation has been updated to reflect this.

An example of the difference between API paths:

Regular Jira Cloud User Jira Cloud Service Account
https://${SITE_ID}.atlassian.net/rest/api/2/myself https://api.atlassian.com/ex/jira/${CLOUD_ID}/rest/api/2/myself

Because all service account endpoints use the same paths (just with /ex/jira/$cloudid} in the path), we can fix this problem and get service accounts working. I've expanded this approach to include a new authentication type, titled Jira Cloud service account. The fields have also been brought into Vue to be dynamic, and can have their help text changed based on the selected authentication type.

References

Screenshots or screen recordings

Provided below is an example of how it looks for the end-user to provide their service account details:

Before After
image.png image.png

Based on some earlier feedback, this now features:

  • Authentication method has been moved above the field items, to improve the UX (otherwise, fields will disappear when selecting a different authentication method).
  • A new field is presented as Service account token, with new help text.
  • The Jira API URL field has additional help text, directing to Atlassian's knowledge base on getting their Cloud ID for the URL.

Short video going over the options:

How to set up and validate locally

  1. With a Jira Cloud account, configure a service account.
  2. Create an API token for the service account. Use the classic scopes read:jira-user, read:jira-workandwrite:jira-work`.
  3. Copy the API token to a safe place for testing purposes.
  4. In GDK, create a new project and go to Settings > Integrations > Jira issues
  5. Configure the integration with:
    1. Web URL: https://example.com (this is not used when the API URL is set)
    2. Jira API URL: https://api.atlassian.com/ex/jira/{cloudId}. You can confirm your Cloud ID by navigating to this resource: https://<my-site-name>.atlassian.net/_edge/tenant_info, replacing <my-site-info> with your cloud instance name. It should return a value like: "cloudId": "5e2ad8d2-3f1a-4270-8bc6-68735d7f6add"
    3. Select Jira personal access token, then provide the service account API token.
  6. Confirm that you can import issues from Jira successfully with the service account token.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Ben King

Merge request reports