feat: Enable OAuth 3LO support #877

christianarty · 2025-07-17T03:30:39Z

Summary

fixes #863

This PR allows for users to have another option (oauth) when generating their JIRA config.yml for the Cloud installation.

Details

This PR implements JIRA's 3LO OAuth solution for users to obtain a JIRA access token.
Each consumer of jira-cli will need to create a JIRA App with the specific scopes in order to connect it properly with their JIRA cloud instance.

The oauth secret will be stored in the .config/.jira directory, where the tokens will be automatically regenerated when it expires and the newly generated tokens will be cached to the oauth secret file.

How to create a JIRA App properly:

See this discussion post here: #879 (comment)

Known Limitations/Issues

Note

This limitation has also been noted in the README under the Known Issues section.

Ideally, for OAuth, we would have one single distributed app that can be installed in multiple different JIRA cloud instances. However, The 3LO doesn't support Proof Key for Code Exchange (PKCE). Without this support, we would have to share the single distrubuted app's client secret with all the consumers. See these links for more info:

As noted in the forum above, a workaround would be that each consumer has to create their own JIRA app and use that app's client ID and secret in the jira-cli client app.

This basically acts like a proxy to funnel requests into your JIRA cloud instance

Testing Done

make deps install => WORKS
~/go/bin/jira issue create -tTask -s"TEST TICKET" -l"testing" --template ~/jira/task.tmpl -a$(~/go/bin/jira me) => WORKS (created a ticket, and proper link)
make test => WORKS
make lint => WORKS
make ci => WORKS

shadyabhi · 2025-07-22T03:57:53Z

cc: @ankitpokhrel for visibility. It'll be great if this can be reviewed/merged soon, so folks that can only authenticate through OAuth 3LO can start using this tool again.

christianarty · 2025-09-06T22:30:47Z

@ankitpokhrel Could you take a look at this PR when you get a chance? I think this is a nice feature add (and personally been using it for months now without hiccup)

ankitpokhrel · 2025-09-07T07:47:41Z

@christianarty Thanks for the PR! I'm currently away, I'll look into this in a few weeks.

christianarty · 2025-10-08T21:01:16Z

@ankitpokhrel Hey! Just wanted to see if you had a moment to take a peek at this PR! Would be appreciated thanks!

christianarty · 2025-10-08T22:33:12Z

Also added a new commit that expanded the default scopes since recently realized, with the oauth, for jira sprint list to work properly needed extra scopes: https://developer.atlassian.com/cloud/jira/software/rest/api-group-board/#api-rest-agile-1-0-board-boardid-sprint-sprintid-issue-get
https://developer.atlassian.com/cloud/jira/software/rest/api-group-sprint/#api-rest-agile-1-0-sprint-sprintid-issue-post

Copilot

Pull Request Overview

This PR adds OAuth 3LO (3-legged OAuth) authentication support to the JIRA CLI, allowing users to authenticate with Atlassian Jira Cloud using OAuth instead of API tokens. The implementation includes a complete OAuth flow with automatic token refresh, secure credential storage, and cloud ID retrieval for proper API access.

Implements OAuth 3LO authentication flow with automatic browser-based authorization
Adds secure file-based storage for OAuth tokens and client credentials
Integrates OAuth authentication into existing JIRA client with automatic token refresh

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/oauth/oauth.go	Core OAuth implementation with flow management and cloud ID retrieval
pkg/oauth/tokens.go	Token management with automatic refresh and persistent storage
pkg/oauth/oauth_test.go	Comprehensive test suite for OAuth functionality
pkg/utils/storage.go	Generic file storage interface with JSON serialization helpers
pkg/utils/storage_test.go	Test coverage for storage functionality
pkg/jira/client.go	Integration of OAuth transport into JIRA client
internal/config/generator.go	Configuration generator updates for OAuth setup
api/client.go	Client factory updates to support OAuth token sources
pkg/jira/types.go	New authentication type constants
pkg/jira/cloud_id.go	Cloud ID retrieval functionality
README.md	Documentation updates for OAuth authentication

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-11T09:07:52Z

pkg/oauth/oauth.go

+		ctx, cancel := context.WithTimeout(context.Background(), serverShutdownTimeout)
+		defer cancel()
+		if err := server.Shutdown(ctx); err != nil {
+			fmt.Printf("Warning: failed to shutdown server: %v\n", err)
+		}


The server shutdown logic is duplicated in three places (lines 283-287, 303-307, 312-316). Consider extracting this into a helper function to reduce code duplication.

Copilot · 2025-10-11T09:07:53Z

pkg/jira/client.go

-		transport.TLSClientConfig.RootCAs = caCertPool
-		transport.TLSClientConfig.Certificates = []tls.Certificate{cert}
-		transport.TLSClientConfig.Renegotiation = tls.RenegotiateFreelyAsClient
+		tlsConfig := transport.(*http.Transport).TLSClientConfig


This type assertion will panic if the transport is not an *http.Transport. After adding OAuth support, the transport could be an *oauth2.Transport, making this assertion unsafe. Add a type check before the assertion.

Suggested change

tlsConfig := transport.(*http.Transport).TLSClientConfig

httpTransport, ok := transport.(*http.Transport)

if !ok {

log.Fatal("transport is not an *http.Transport; cannot configure mTLS")

}

tlsConfig := httpTransport.TLSClientConfig

internal/config/generator.go

README.md

ankitpokhrel

Hi @christianarty, first of all, amazing work and sorry for jumping in a bit late!

I ran some tests, and most things are working great. I noticed a few things tho:

Listing epic items returns 401. Perhaps we are missing some permissions?

➔ jira epic list ABC-3

jira: Received unexpected response '401 Unauthorized'.
Please check the parameters you supplied and try again.

The warning is shown every time when oAuth is not used. I think we only want to show warning if the type is oAuth and api_server is not set.

Using jira init with Authentication type: cloud is failing with authentication err.

Could you please help check?

(Feel free to ignore any copilot comment if that doesn't make sense)

Thank you again for great work! 🎉

pkg/jira/cloudid.go

internal/config/generator.go

pkg/oauth/oauth.go

christianarty

Hi @christianarty, first of all, amazing work and sorry for jumping in a bit late!

I ran some tests, and most things are working great. I noticed a few things tho:

Listing epic items returns 401. Perhaps we are missing some permissions?
➔ jira epic list ABC-3

jira: Received unexpected response '401 Unauthorized'.
Please check the parameters you supplied and try again.
The warning is shown every time when oAuth is not used. I think we only want to show warning if the type is oAuth and api_server is not set.

Using jira init with Authentication type: cloud is failing with authentication err.

Could you please help check?

(Feel free to ignore any copilot comment if that doesn't make sense)

Thank you again for great work! 🎉

Thanks for the information! Will address them.

Listing epic items returns 401. Perhaps we are missing some permissions?
After checking this url here for the endpoint we are hitting: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-jql-get

from my own mental model, the Classic scope should be sufficient, but then again the JIRA API is okay at best, so i added in all the other granular scopes that is stated there in the defaultScopes field, and will update the discussion post regarding it. With adding in all those scopes, it works as intended.

The warning is shown every time when oAuth is not used. I think we only want to show warning if the type is oAuth and api_server is not set.

I'll take a look at this in a bit to see what small thing is off

Using jira init with Authentication type: cloud is failing with authentication err.

I just fixed the logic error for when we checkJiraAPIToken basically if you already did oauth, it thinks it should use the oauth token. However i think the JIRA api has changed and tbh, i think we should migrate to use the v3 of the myself API: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-myself/#api-rest-api-3-myself-get

I am going to address these comments over the next couple days and when its ready to re-review i'll re-request a review.

…figureServerMeta`

… transport in the client

…er, rather than their own JIRA server

ccoVeille · 2025-11-16T19:43:43Z

Also, I'm unsure if you can report the scope the app was created with without being authenticated, but it would be great to double check what us expected and what is currently on the created oauth app

Great suggestion! I am not sure about the scope when unauthorized and I think that should be a separate PR (this PR is already big enough tbh)

Yes, it does. And as we both said, we are not sure it can be done.

Copilot

Pull Request Overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pkg/utils/keyring_storage.go

pkg/oauth/oauth.go

internal/config/generator.go

README.md

api/client.go

Co-authored-by: Copilot <[email protected]>

christianarty · 2025-11-19T00:48:41Z

Thanks @ccoVeille for the comments! Appreciate the extra look! I've addressed them all and tested it with the new revisions and things work as intended. @ankitpokhrel it now defaults to the keyring and fallsback to the filesystem storage. Please let me know if there is anything else we need to do in this PR otherwise i think its ready to 🚢

christianarty · 2025-11-19T00:50:38Z

Also, @ccoVeille these are what the new order of expected scopes, alphabetically sorted and grouped by scope type.

internal/config/generator.go

pkg/oauth/oauth.go

pkg/oauth/tokens.go

pkg/utils/fsstorage.go

pkg/jira/cloudid.go

…ctedScopes

vibbix · 2025-11-21T15:41:40Z

Hoping to see this merged soon, looks great!

christianarty · 2025-11-26T20:26:27Z

@ankitpokhrel, whenever you get a chance could you drop a 🚢 . Would be greatly appreciated thanks!

christianarty marked this pull request as ready for review July 17, 2025 12:45

christianarty force-pushed the add-oauth-type branch from ec9c285 to 323089d Compare July 17, 2025 13:54

christianarty force-pushed the add-oauth-type branch from fa19335 to 0ebaa17 Compare September 6, 2025 22:25

ankitpokhrel requested a review from Copilot October 11, 2025 09:06

Copilot AI reviewed Oct 11, 2025

View reviewed changes

ankitpokhrel reviewed Oct 11, 2025

View reviewed changes

pkg/jira/cloudid.go Show resolved Hide resolved

internal/config/generator.go Show resolved Hide resolved

ankitpokhrel reviewed Oct 11, 2025

View reviewed changes

pkg/oauth/oauth.go Outdated Show resolved Hide resolved

christianarty commented Oct 13, 2025

View reviewed changes

christianarty added 17 commits November 16, 2025 12:16

(build) Update Golang OAuth2 Library to latest

40b055a

(feat) Implement OAuth2 func. into jira-cli

b615be3

feat:(oauth) - Ability to get cloud id for clients

23a3c5d

(docs) Add note about OAuth weirdness

eb98589

(refactor) Move oauth to separate module

722e4d9

(refactor) Remove unnecessary args from verifyLoginDetails and `con…

007f761

…figureServerMeta`

(tests): Add tests for oauth

e4cc1c2

(nit) Move getToken logic into separate func

691edbb

(refactor) Organizing the oauth to break up the logic to other files

f57474b

(feat) Add the ability to load the persisted oauth token from filesystem

40402e6

(test) More tests for oauth

ca6a100

(feat) Enable auto refreshing access tokens through the oauth2 custom…

00d31d5

… transport in the client

(nit) remove dead code

c5533a8

(fix) The constructed server urls were pointing to authorization serv…

d7917e9

…er, rather than their own JIRA server

(docs) update README with more instructions.

2af8279

(fix/cleanup) Remove old/redundant code and fix the oauth tests

605d9f0

(nit) Remove old TODO

7264fa9

ankitpokhrel requested a review from Copilot November 17, 2025 08:29

Copilot AI reviewed Nov 17, 2025

View reviewed changes

pkg/utils/keyring_storage.go Outdated Show resolved Hide resolved

pkg/oauth/oauth.go Show resolved Hide resolved

internal/config/generator.go Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

api/client.go Show resolved Hide resolved

christianarty and others added 13 commits November 17, 2025 09:09

(pr) rename cloudId to be consistent

6680e93

(pr-nit) oauth canonical

f49ce94

(pr) use Jira AuthType for options

3006834

(pr) path escape cloudid

a1c1617

(pr-fix) c.JiraClient was checking if !nil, when it should be

38c5fc4

(pr) move and use accessibleURL to cloud_id

a1b4bcc

(pr) rename cloudid file

858d625

(pr) fix the way we set the clientID and ClientSecret from env

4be38c9

(pr) refactor the scopes to be a struct to properly print and use

62878e2

(nit) remove a useless test

3362e6e

(nit) this should be before setting the apiServer not after

a7270c6

Update README.md

bdabb55

Co-authored-by: Copilot <[email protected]>

Update pkg/utils/keyring_storage.go

69a45c3

Co-authored-by: Copilot <[email protected]>

christianarty requested review from ankitpokhrel and ccoVeille November 19, 2025 00:47

ccoVeille reviewed Nov 19, 2025

View reviewed changes

christianarty added 5 commits November 18, 2025 22:04

(pr-nit) oauth name

00a3792

(pr-nit) add AccessibleURL

3b2414c

(pr-nit) godoc comments

fb011af

(pr-nit) rename to follow conventions

8eed942

(pr-improv) use slices.SortFunc for a simpler sort when printing expe…

8fe3460

…ctedScopes

christianarty requested a review from ccoVeille November 19, 2025 03:18

ccoVeille approved these changes Nov 19, 2025

View reviewed changes

-		tlsConfig := transport.(*http.Transport).TLSClientConfig
+		httpTransport, ok := transport.(*http.Transport)
+		if !ok {
+			log.Fatal("transport is not an *http.Transport; cannot configure mTLS")
+		}
+		tlsConfig := httpTransport.TLSClientConfig

Uh oh!

feat: Enable OAuth 3LO support #877

Are you sure you want to change the base?

feat: Enable OAuth 3LO support #877

Uh oh!

Conversation

christianarty commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

How to create a JIRA App properly:

Known Limitations/Issues

Testing Done

Uh oh!

shadyabhi commented Jul 22, 2025

Uh oh!

christianarty commented Sep 6, 2025

Uh oh!

ankitpokhrel commented Sep 7, 2025

Uh oh!

christianarty commented Oct 8, 2025

Uh oh!

christianarty commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ankitpokhrel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

christianarty left a comment

Choose a reason for hiding this comment

Uh oh!

ccoVeille commented Nov 16, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

christianarty commented Nov 19, 2025

Uh oh!

christianarty commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vibbix commented Nov 21, 2025

Uh oh!

christianarty commented Nov 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

christianarty commented Jul 17, 2025 •

edited

Loading

christianarty commented Oct 8, 2025 •

edited

Loading

christianarty commented Nov 19, 2025 •

edited

Loading