Feat: implement OIDC flow by NishchayRajput · Pull Request #1007 · goharbor/harbor-cli

NishchayRajput · 2026-06-17T18:32:54Z

Description

This pull request adds work-in-progress OIDC login support for harbor-cli together with the Harbor Core changes needed to support that flow.

The current implementation allows harbor-cli to start an OIDC login through Harbor Core, return a browser login URL plus a CLI-only polling token, poll Harbor Core for completion, store the returned credential locally, and use bearer authentication for later API requests.

This change is needed because Harbor currently supports browser-based OIDC login, but harbor-cli does not yet have a native OIDC login flow. The current implementation is still being actively worked on and is not final yet.

Fixes [feature]: Harbor CLI OIDC auth (LFX Term-2, June-Augut 2026) #1006

Type of Change

Please select the relevant type.

Changes

Added harbor login <server> --oidc
Added Harbor Core support for GET /c/oidc/login?mode=cli
Added Harbor Core polling endpoint for CLI login completion:
GET /c/oidc/cli-token?poll_token=...
Added cache-backed CLI OIDC login state handling in Harbor Core
Added local OIDC credential storage support in harbor-cli:
- auth-type
- id-token
- refresh-token
- expires-at
Added bearer-token client path for OIDC credentials
Added CLI and Harbor test coverage for the OIDC polling flow
Updated the design/plan documentation to reflect the current polling-token-based flow

Flow Diagram

Video

Screencast.from.21-06-26.04.07.57.PM.IST.webm

In case of token expiry cli gives output as

NishchayRajput · 2026-06-17T18:36:35Z

@bupd Please have look at the idea. We may also required changes on harbore-core using existing oidc flow still required still needed few changes like polling state to get the id_token and other details. It's not completed yet but wanted you to have a look and design level decisions.

PS: ignore lint for now :)

codecov · 2026-06-20T10:46:25Z

Codecov Report

❌ Patch coverage is 50.49702% with 249 lines in your changes missing coverage. Please review.
✅ Project coverage is 10.95%. Comparing base (60ad0bd) to head (090f676).
⚠️ Report is 209 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/utils/client.go	36.36%	68 Missing and 16 partials ⚠️
pkg/utils/oidc.go	53.33%	48 Missing and 29 partials ⚠️
cmd/harbor/root/login.go	58.20%	36 Missing and 20 partials ⚠️
pkg/utils/config.go	55.55%	16 Missing and 16 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1007      +/-   ##
==========================================
- Coverage   10.99%   10.95%   -0.04%     
==========================================
  Files         173      323     +150     
  Lines        8671    16836    +8165     
==========================================
+ Hits          953     1845     +892     
- Misses       7612    14764    +7152     
- Partials      106      227     +121

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

NishchayRajput · 2026-06-21T10:49:52Z

Suggestion:

We can use URL shortener or copy support for the link in the terminal itself.
Also should display the QR code for the url incase user can scan via phone.

Please let me know if you have more suggestion.

qcserestipy · 2026-06-30T12:13:54Z

@NishchayRajput Had a brief look through this. It looks really really cool!
Just one question out of interest. After the oidc login the id_token is retrieved for identity info.
The refresh_token is also stored for refreshing which is really nice. Is there already functionality included to make use of the refresh_token anyhow or is this just added for completenes currently?
Should we also store the access_token?

Lastly, which party is validating the trust relationship to the oidc source. Just to confirm: this is governed through OIDC providers that are configured in harbor itself and we just make use of the trusted identity provider from Harbor itself.

NishchayRajput · 2026-07-02T03:12:37Z

@NishchayRajput Had a brief look through this. It looks really really cool! Just one question out of interest. After the oidc login the id_token is retrieved for identity info. The refresh_token is also stored for refreshing which is really nice. Is there already functionality included to make use of the refresh_token anyhow or is this just added for completenes currently? Should we also store the access_token?

Lastly, which party is validating the trust relationship to the oidc source. Just to confirm: this is governed through OIDC providers that are configured in harbor itself and we just make use of the trusted identity provider from Harbor itself.

Hey, Thanks @qcserestipy for review.
Below is how flow would look like

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

NishchayRajput · 2026-07-05T05:19:05Z

Untitled.design.1.mp4

Added Refresh Token support.

Copilot

Pull request overview

This PR introduces work-in-progress OIDC login support to harbor-cli, enabling a browser-based authentication flow via Harbor Core, persisting OIDC credentials locally, and using bearer-token auth for subsequent API requests.

Changes:

Added OIDC login helpers (initiate login, poll for completion, refresh tokens) and corresponding unit tests.
Extended credential/config model to store OIDC auth metadata (auth-type, id/refresh tokens, expiry) and added token refresh + retry-on-401 support in the Harbor API client.
Updated harbor login command/docs to add --oidc and tests for the new flag/flow.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
pkg/utils/oidc.go	Implements OIDC login initiation, polling, refresh, and URL construction helpers.
pkg/utils/oidc_test.go	Adds unit tests covering OIDC login, polling, and refresh behaviors.
pkg/utils/config.go	Extends stored credentials for OIDC fields and adds helpers to store/decrypt/update OIDC tokens.
pkg/utils/config_test.go	Adds tests for OIDC credential storage + token update/decryption.
pkg/utils/client.go	Adds OIDC bearer auth client path, token refresh logic, and retry transport for 401 responses.
pkg/utils/client_oidc_internal_test.go	Adds internal tests for JWT expiry parsing and retry transport behavior.
cmd/harbor/root/login.go	Adds `--oidc` flag and `RunOIDCLogin` flow.
cmd/harbor/root/login_test.go	Adds tests for OIDC flag mutual exclusivity and successful OIDC login.
doc/man-docs/man1/harbor-login.1	Documents the new `--oidc` flag in man pages.
doc/cli-docs/harbor-login.md	Documents the new `--oidc` flag in CLI docs.

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

Vad1mo · 2026-07-08T20:42:16Z

not a big fan of

added harbor login --oidc

is that the only option to have attach --oidc?
Can this not be derived automatically?
In what situations would you not want to have it automatically and manually specify it?

NishchayRajput · 2026-07-09T17:22:52Z

not a big fan of

added harbor login --oidc

is that the only option to have attach --oidc? Can this not be derived automatically? In what situations would you not want to have it automatically and manually specify it?

Yes this can be derived automatically via /api/v2.0/systeminfo endpoint, this would allow harbor login to automatically initiate the OIDC flow when the target Harbor instance is configured for OIDC, without requiring the user to explicitly specify --oidc.

But besides the oidc flow we also support auth via cli_secret, so in those cases simply knowing auth_mode doesn't necessarily indicate the authentication flow the user intends to use.

Best way can be interactive solution which was discussed in this weekly meet that we can have over harbor login, user can choose the auth method.

cc: @Vad1mo

Vad1mo · 2026-07-09T17:31:53Z

But besides the oidc flow we also support auth via cli_secret, so in those cases simply knowing auth_mode doesn't necessarily indicate the authentication flow the user intends to use.

Best way can be interactive solution which was discussed in this weekly meet that we can have over harbor login, user can choose the auth method.

can we have this flow.

keep --oidc etc.

if no value provided try to determin automatically
if arg provided use that explicitly

One important not on interactive solution. Make sure interactive is only one of the option, it should work across CI/CD and AI agents using the CLI...

NishchayRajput · 2026-07-09T18:01:19Z

can we have this flow.

keep --oidc etc.

if no value provided try to determin automatically

if arg provided use that explicitly

One important not on interactive solution. Make sure interactive is only one of the option, it should work across CI/CD and AI agents using the CLI...

Yes indeed. Just to summarize the proposed flow:

If authentication flags are provided (e.g. --oidc, -u -p , etc.), use the explicitly requested authentication flow.
If no authentication flags are provided:

Query the /api/v2.0/systeminfo endpoint to determine the configured auth_mode.
If auth_mode is oidc_auth, the CLI can offer an interactive choice between the supported OIDC authentication methods (e.g. browser-based OAuth or CLI secret-based authentication, if supported).
If auth_mode is db_auth, continue with the existing interactive username/password login flow.

For AI Agents and CI/CD path flags paths remains covered.
cc : @Vad1mo @bupd

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

qcserestipy

Thank you for your contribution! nice work, the polling flow looks solid and the recent fixes (mutex guarding, the 202/timeout test) look good. just two small things left below.

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

bupd

--auth-mode this Should be the flag instead of OIDC.
flag options

oidc
ldap
db (usually used in the case of username: admin- sole system admin)

without giving this flag should fallback first to oidc > db.

NishchayRajput · 2026-08-05T19:12:25Z

Error: failed to decode OIDC login response: invalid character '<' looking for beginning of value
exit status 1

Above error is expected as currently you don't use the corresponding changes made in HARBOR-PR#23421. Since while triggering Harbor OIDC mode from CLI, without those changes would trigger oidc auth flow and return redirect html output instead of JSON format output as expected by CLI. (Will add a check for json response and will give proper error output on CLI side)
Also for the second thing
go run ./cmd/harbor/main.go login registry.goharbor.io -u bupdprasanth@gmail.com
This is shouldn't ideally go to oidc mode as user may user cli_secret so we have to support that as well. Also it may be possible that admin may login via idp.

@bupd

…compatible harbor platform version. Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

NishchayRajput · 2026-08-06T17:48:43Z

This image shows output for --auth-mode oidc
command: harbor login --auth-mode oidc http://localhost:4200 -v

When user tries to login when auth mode is db
command: harbor login --auth-mode oidc http://localhost:4200 -v

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

bupd

@NishchayRajput not working yet,

please check and verify against https://registry.goharbor.io

NishchayRajput · 2026-08-07T02:38:02Z

@NishchayRajput not working yet,

please check and verify against https://registry.goharbor.io

To login via oidc there's need of harbor changes, which are present in pr #23421 on harbor

bupd · 2026-08-07T03:35:49Z

why shouldnt this work out of the box in harbor-cli ??

bupd · 2026-08-07T03:50:48Z

I dont think we need change from the harbor core side.

NishchayRajput · 2026-08-07T04:34:21Z

Using the existing OIDC flow as-is is not straightforward here. When Harbor CLI opens the browser, it has no visibility into the browser's auth state. The browser communicates directly with the IdP, and the IdP then communicates with harbor-core. Harbor CLI is completely out of that loop and has no way to know when authentication has completed.

To support this flow, Harbor CLI would need to poll Harbor to retrieve the auth state. That is the minimum change required if we want to reuse the existing OIDC flow in Harbor.

and This is exactly what I have done.

NishchayRajput · 2026-08-07T04:34:42Z

Using the existing OIDC flow as-is is not straightforward here. When Harbor CLI opens the browser, it has no visibility into the browser's auth state. The browser communicates directly with the IdP, and the IdP then communicates with harbor-core. Harbor CLI is completely out of that loop and has no way to know when authentication has completed.

To support this flow, Harbor CLI would need to poll Harbor to retrieve the auth state. That is the minimum change required if we want to reuse the existing OIDC flow in Harbor.

and This is exactly what I have done.

If you have any other idea/opinion please let me know.

bupd · 2026-08-07T07:37:55Z

okay cool, can you check and add some tests to ensure that is backward compatible and does it needs update in the ui of harbor.

NishchayRajput · 2026-08-08T16:59:37Z

okay cool, can you check and add some tests to ensure that is backward compatible and does it needs update in the ui of harbor.

Sure. Also we don't require any UI changes.

NishchayRajput changed the title ~~Feat/implement OIDC flow~~ Feat: implement OIDC flow Jun 17, 2026

NishchayRajput mentioned this pull request Jun 23, 2026

[feature]: Harbor CLI OIDC auth (LFX Term-2, June-Augut 2026) #1006

Open

NishchayRajput added 8 commits July 4, 2026 23:25

basic implementation

e5c2d8a

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

moved to state based login with existing endopoint

261a1bd

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

fix client error

2423ed7

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

basic refresh token support

6032e10

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

basic implementation

1aa8534

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

moved to state based login with existing endopoint

96eff11

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

added polling-token support

2fafc55

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

added test

a469bf0

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

NishchayRajput force-pushed the feat/implement-oidc-flow branch from d532c48 to a469bf0 Compare July 4, 2026 17:56

NishchayRajput added 10 commits July 5, 2026 00:33

fix: lint and genrate docs

7d57d58

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

basic implementation

54fe507

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

moved to state based login with existing endopoint

6d56600

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

fix client error

e7541a0

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

basic refresh token support

d7259e8

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

basic implementation

d94bf4f

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

moved to state based login with existing endopoint

9470b1c

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

added polling-token support

6f59953

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

added test

a0fa532

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

fix: lint and genrate docs

1a370a5

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

qcserestipy requested review from Copilot and qcserestipy July 6, 2026 07:22

Copilot started reviewing on behalf of qcserestipy July 6, 2026 07:23 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

fix: reviewed changes

ebb3f9d

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

qcserestipy requested changes Jul 20, 2026

View reviewed changes

Comment thread pkg/utils/client.go

Comment thread pkg/utils/client.go

Comment thread pkg/utils/oidc.go

fix: reviewed changes, added test and debug log

b50513f

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

bupd requested changes Aug 4, 2026

View reviewed changes

NishchayRajput added 4 commits August 6, 2026 13:49

fix: reviewed changes added logs for verbose mode and check agains in…

3aec5de

…compatible harbor platform version. Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

fix: lint

b0728ac

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

fix: tests

6c87765

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

fix

bc6600c

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

NishchayRajput and others added 2 commits August 7, 2026 01:01

fix lint

8e59df4

Signed-off-by: Nishchay Rajput <nishchayr@iitbhilai.ac.in>

Merge branch 'main' into feat/implement-oidc-flow

090f676

bupd requested changes Aug 7, 2026

View reviewed changes

bupd removed the deps/harbor Issues related to upstream Harbor behavior, API quirks, configuration requirements, or Harbor bugs. label Aug 7, 2026

Uh oh!

Conversation

NishchayRajput commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of Change

Changes

Flow Diagram

Video

In case of token expiry cli gives output as

Uh oh!

NishchayRajput commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

NishchayRajput commented Jun 21, 2026

Uh oh!

qcserestipy commented Jun 30, 2026

Uh oh!

NishchayRajput commented Jul 2, 2026

Uh oh!

NishchayRajput commented Jul 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Vad1mo commented Jul 8, 2026

Uh oh!

NishchayRajput commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Vad1mo commented Jul 9, 2026

Uh oh!

NishchayRajput commented Jul 9, 2026

Uh oh!

qcserestipy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bupd left a comment

Choose a reason for hiding this comment

Uh oh!

NishchayRajput commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NishchayRajput commented Aug 6, 2026

Uh oh!

bupd left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NishchayRajput commented Aug 7, 2026

Uh oh!

bupd commented Aug 7, 2026

Uh oh!

bupd commented Aug 7, 2026

Uh oh!

NishchayRajput commented Aug 7, 2026

Uh oh!

NishchayRajput commented Aug 7, 2026

Uh oh!

bupd commented Aug 7, 2026

Uh oh!

NishchayRajput commented Jun 17, 2026 •

edited

Loading

NishchayRajput commented Jun 17, 2026 •

edited

Loading

codecov Bot commented Jun 20, 2026 •

edited

Loading

NishchayRajput commented Jul 9, 2026 •

edited

Loading

NishchayRajput commented Aug 5, 2026 •

edited

Loading

bupd left a comment •

edited

Loading