Feat: implement OIDC flow

[NishchayRajput]

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.

• Bug fix
• New feature
• Refactor
• Documentation update
• Chore / maintenance

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]

@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]

Codecov Report

❌ Patch coverage is 45.47945% with 199 lines in your changes missing coverage. Please review.
✅ Project coverage is 10.53%. Comparing base (60ad0bd) to head (ebb3f9d).
⚠️ Report is 196 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/utils/client.go	35.87%	68 Missing and 16 partials ⚠️
pkg/utils/oidc.go	47.40%	42 Missing and 29 partials ⚠️
pkg/utils/config.go	55.55%	16 Missing and 16 partials ⚠️
cmd/harbor/root/login.go	55.55%	6 Missing and 6 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1007      +/-   ##
==========================================
- Coverage   10.99%   10.53%   -0.46%     
==========================================
  Files         173      322     +149     
  Lines        8671    16454    +7783     
==========================================
+ Hits          953     1733     +780     
- Misses       7612    14509    +6897     
- Partials      106      212     +106     

☔ 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]

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]

@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]

@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

[NishchayRajput]

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.

[NishchayRajput]

Using poll_token instead of state as state is exposed in the url and anyone can get the session via that state.

[Vad1mo]

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]

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]

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.

1. if no value provided try to determin automatically
2. 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]

can we have this flow.

keep --oidc etc.

1. if no value provided try to determin automatically
2. 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:

1. If authentication flags are provided (e.g. --oidc, -u -p , etc.), use the explicitly requested authentication flow.
2. 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