Skip to content

Add CLI sign-in and JWT credential management #1562

Open

Description

@duffney

Problem or use case

The Scope CLI can send a bearer supplied through SCOPE_TOKEN, but users cannot
yet sign in through the CLI or have it acquire, securely persist, and refresh
their credentials. Manually sourcing access tokens is not a complete interactive
authentication experience.

This is the human CLI authentication delivery under parent #17. RBAC policy and
administration belong to #1300; internal service/job JWT authentication belongs
to #1557.

Proposed change

Implement human sign-in and the credential lifecycle for the CLI:

  • scope auth login: authenticate through the existing IdP, acquire an access
    token for the Scope API, and explicitly enroll through POST /api/v1/users/me.
  • scope auth logout: clear the selected locally cached credentials/account
    context. Do not imply that local logout revokes already-issued bearer tokens.
  • scope auth status / scope auth whoami: show the selected API/account and
    Scope identity/role without exposing credentials; use read-only user lookup.
  • Persist the authentication SDK's cache through secure storage and silently
    acquire/refresh access tokens for ordinary commands.
  • Reuse the centralized API client's token-provider and reauthentication hooks.
    Preserve SCOPE_TOKEN supplied-bearer support, public/offline commands, and
    separation from external HTTP requests such as update checks.
  • Provide actionable credential errors and deterministic non-interactive
    behavior. Do not unexpectedly launch login or open a browser in automation.

Authentication boundary

The CLI uses a human IdP access JWT for the Scope API, not a worker
service/job token. JWT is the format, not a shared identity or signing key.
Preserve the API's unchanged-IdP-bearer and explicit-enrollment contract:
ordinary commands, status reads, and token refresh must never implicitly enroll.
Do not forward human bearer tokens into jobs or place client secrets/signing
private keys in the CLI.

JWT infrastructure and public-client/API configuration are assumed supplied.
This issue consumes the configured authority, API audience/scopes, client
registration, consent, and redirect/local-development settings; infrastructure
research and provisioning are not part of this implementation.

Application decisions to settle

  • Adopt or explicitly amend the existing device-code/MSAL/SecretStore design in
    docs/architecture/auth-rbac.md section 7. The Azure CLI-style browser-first
    flow with a device-code option is a proposal, not a selected default.
  • Define account/API-origin binding, account selection, and SCOPE_TOKEN
    precedence and failure behavior.
  • Select secure persistence and its failure/fallback policy, including
    headless environments. Do not silently downgrade storage security.
  • Define refresh concurrency, bounded reauthentication/retry, logout, and
    rejected/expired-session behavior.
  • Resolve secure-storage dependencies against the standalone CLI distribution
    contract, not just source-mode execution.

Acceptance criteria

  • A user can sign in without manually sourcing a bearer and intentionally
    enroll through the existing API contract.
  • Ordinary commands authenticate with the human API access token; refresh
    and read-only identity/status calls never implicitly enroll.
  • Secure cache persistence, access-token expiry/refresh, local logout,
    account/API isolation, and storage failures are covered.
  • Existing SCOPE_TOKEN usage remains compatible under documented
    precedence; non-interactive failures are actionable and do not prompt.
  • Concurrent token acquisition/refresh is bounded and deduplicated; invalid
    credentials do not cause unbounded retries or anonymous fallback.
  • Tokens are redacted from diagnostics and never attached to external
    destinations, queues, agent environments, or AI-visible tools.
  • The actual standalone installed bundle supports the chosen authentication
    and storage implementation, including supported headless behavior.
  • CLI help, command snapshots, environment guidance, and authentication/
    distribution documentation describe the delivered behavior.

Alternatives

Continue requiring users to provide SCOPE_TOKEN manually. Keep that option for
supplied-bearer automation, but it does not replace interactive login, secure
cache persistence, and silent renewal.

Reuse internal service/job credentials for human CLI calls. Reject this because
it would conflate human identity with service authority.

Introduce a human Scope-token exchange or Scope PAT issuance. Neither is needed
for the existing human IdP-token contract; both remain outside this issue.

Additional context

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