Skip to content

Add device code flow support #3225

Description

@yuito-it

Is your feature request related to a problem? Please describe.

When using pinniped CLI on headless environments or jump hosts (e.g., SSH bastion servers without a local web browser), authenticating via OIDC requires either manual SSH port forwarding or copying long callback URLs via --oidc-skip-browser. This introduces unnecessary friction for developers working in remote or terminal-only environments.

Describe the solution you'd like

Add support for the OAuth 2.0 Device Authorization Grant (Device Code Flow - RFC 8628) in the Pinniped CLI / pinniped get kubeconfig.

When connecting from a jump host, Pinniped CLI could initiate the device authorization flow, outputting a verification URL and a user code (e.g., ABCD-1234), and poll the token endpoint until the user completes authentication on any device with a browser.

Describe alternatives you've considered

  • --oidc-skip-browser (Issue Support for OIDC logins on hosts without a local web browser ("jump host") #668): Requires the user to attempt a login in their browser, fail the localhost redirect, and manually copy/paste the full callback URL back into the terminal.
  • SSH Port Forwarding (ssh -L): Requires extra local client configuration and port coordination.
  • Custom exec Credential Plugins: Bypasses Pinniped CLI authentication entirely, losing the benefits of standard Pinniped configuration management.

Are you considering submitting a PR for this feature?

Yes, I am considering submitting a PR to implement this functionality.

  • How will this project improvement be tested?
    • Unit tests covering the device code flow initiation, user code rendering, polling logic, and error/timeout handling.
    • Integration/mock tests verifying interaction with OIDC discovery documents (device_authorization_endpoint) and RFC 8628 token endpoints.
  • How does this change the current architecture?
    • Expands the CLI authentication handlers to support RFC 8628 alongside the existing Authorization Code Grant with PKCE flow.
    • No breaking changes to the Concierge or Supervisor core architectures.
  • How will this change be backwards compatible?
    • Fully backwards compatible. The existing Authorization Code flow remains default unless --oidc-use-device-code (or similar flag) is specified, or if configured via kubeconfig options.
  • How will this feature be documented?
    • CLI help documentation for pinniped get kubeconfig will be updated.
    • User documentation regarding authentication on headless/jump hosts will be updated to highlight Device Code Flow support.

Additional context

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions