Feature Proposal: OAuth Integration #525
Description
1. Summary
The purpose of this proposal is to enhance harbor-cli with OAuth 2.0 authentication support, enabling passwordless, token-based logins. By integrating with standards-based identity providers such as OIDC, GitHub, or GitLab, the CLI will offer a seamless experience for both interactive users and automated pipelines, eliminating the need for static credentials and improving overall security.
2. Motivation
Developers and CI/CD environments currently rely on database-stored usernames and passwords, which can lead to secrets management challenges and increased risk of credential leakage. Introducing OAuth support will allow users to leverage short-lived tokens and refresh flows, align with enterprise identity policies, and remove the burden of embedding passwords in scripts or pipeline definitions. Moreover, by adopting widely supported OAuth grant types, harbor-cli will interoperate smoothly with popular identity solutions such as Azure AD, Keycloak, and GitLab.
3. Goals
Our objectives are threefold: first, to implement the OAuth Device Code Flow for interactive terminal sessions, guiding users through a browser-based authorization step; second, to support non-interactive scenarios via JWT Bearer or Client Credentials flows, enabling automated tokens to be provided in CI environments; and third, to securely cache and transparently refresh tokens in the user’s configuration directory (~/.config/harbor-cli), falling back to traditional username/password behavior only when OAuth is not configured.
4. Scope and Non-Goals
This enhancement will rely on Harbor’s existing OIDC endpoints and does not aim to build a dedicated OAuth server or introduce graphical login interfaces. SAML-based or other proprietary federation mechanisms remain outside the scope of this project, and we will focus on standards-compliant, CLI-friendly grant types.
5. User Scenarios
In an interactive setting, a developer might type harbor-cli login --sso and follow the displayed device code and URL to authorize access. On the CI side, a pipeline can invoke harbor-cli login --sso --token-file /path/to/jwt to authenticate without requiring human intervention. Once authenticated, the CLI will automatically detect expired tokens and invoke the configured refresh flow, ensuring uninterrupted access during long-running operations.
6. Configuration Format
Users will define OAuth settings in ~/.config/harbor-cli/config.yaml under each registry, specifying the issuer URL, client ID, client secret, required scopes, and token endpoint. While sensible defaults can be provided, CLI flags such as --issuer-url, --client-id, --client-secret, and --scopes will allow users to override configuration on a per-command basis.
7. Security Considerations
All token storage will default to restrictive file permissions (600), and token encryption at rest can be offered as an opt-in enhancement. HTTPS connections to the issuer and token endpoints will validate TLS certificates, and users will be encouraged to trust only well-known certificate authorities to prevent man-in-the-middle attacks.