Skip to content

CLI Browser OIDC PKCE Login v1

Purpose

gpuaas auth login should use the same brokered identity path as the web product. Password grant is useful for local/dev and breakglass testing, but it is not the primary model for a cloud CLI because social and enterprise providers such as Hugging Face, GitHub, and SSO do not fit a username/password prompt.

Command Model

Primary human login:

gpuaas auth login
gpuaas auth login --provider huggingface
gpuaas auth login --provider github
gpuaas auth login --tenant-hint acme --identity-hint user@acme.example
gpuaas auth login --no-browser

Development-only password flows:

gpuaas auth dev-login --username dev-user --password dev123
gpuaas auth keycloak-login --username dev-user --password dev123

Automation flow:

gpuaas auth service-account-token --service-account-id ... --key-id ... --client-secret ...

Browser Login Flow

  1. CLI generates a PKCE verifier and S256 challenge.
  2. CLI starts a localhost callback listener on 127.0.0.1:<ephemeral>/callback.
  3. CLI calls GET /api/v1/auth/oidc/authorize with:
  4. redirect_uri,
  5. code_challenge,
  6. code_challenge_method=S256,
  7. optional provider_hint,
  8. optional tenant_hint,
  9. optional identity_hint.
  10. API returns a server-authoritative authorization URL and opaque state.
  11. CLI opens the browser unless --no-browser is set.
  12. Browser completes the IdP flow and redirects to the localhost callback.
  13. CLI validates callback state before token exchange.
  14. CLI calls POST /api/v1/auth/oidc/exchange with code, verifier, redirect URI, and state in the JSON body.
  15. CLI stores access and refresh tokens in the existing CLI config file.

The CLI never receives or passes access tokens in URL query parameters.

Provider Hints

Provider hints are advisory shortcuts. The server remains authoritative.

Supported first-pass values:

  1. huggingface,
  2. github,
  3. google.

The API maps the validated hint to the brokered IdP hint understood by Keycloak. The CLI does not construct direct provider URLs and does not bypass the GPUaaS API.

Headless Behavior

--no-browser prints the authorization URL and still waits for the localhost callback. This supports SSH sessions where the user can open the URL from another local browser that can reach the callback endpoint through forwarding.

A true device-code flow is a later addition because the current API contract exposes authorization-code exchange, not OAuth device authorization. Until that endpoint exists, service-account auth remains the correct non-interactive automation path.

Security Rules

  1. Use PKCE S256 for every human browser login.
  2. Keep authorization codes, access tokens, refresh tokens, and client secrets out of logs.
  3. Do not pass access or refresh tokens in URL query parameters.
  4. Validate callback state before exchange.
  5. Store tokens using the existing restricted-permission CLI config initially.
  6. Move to OS keychain storage later as a separate hardening task.
  7. Keep service-account auth for CI and automation.
  8. Keep password grant commands clearly labeled as dev/breakglass paths.

UX Implications

The normal help path should point users to:

gpuaas auth login

not to password grant. Brokered identities should work without asking users to know whether the underlying provider is Keycloak, Hugging Face, GitHub, or enterprise SSO.

Implementation Notes

The first implementation keeps token persistence compatible with the existing SDK config file:

~/.gpuaas-cli/config.json

That preserves current CLI behavior while changing the default login path. Future hardening can move refresh-token storage to an OS keychain without changing the CLI command contract.