feat(cli): import externally issued OIDC tokens non-interactively
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 8.7k
- Forks
- 1.3k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 253
Description
Problem Statement
Headless workloads can obtain a valid OIDC access token from an external identity broker, but OpenShell has no supported non-interactive command for importing that token into an existing OIDC gateway registration. gateway add --oidc-issuer and gateway login initiate login flows, so automation must either invoke an unsuitable interactive flow or write OpenShell's private token-storage format directly.
A supported import boundary would let CI systems and workload-identity brokers authenticate without exposing tokens on command lines or depending on an internal JSON schema.
Proposed Design
Add a non-interactive token-import command for an already registered OIDC gateway, for example:
openshell gateway token import --name <gateway> --file <token-bundle>
The command should:
- accept a bounded file or standard input, never require the access token as a command-line argument;
- require an existing gateway whose metadata declares OIDC authentication;
- accept an explicit, documented token-bundle schema containing the access token, absolute expiry, issuer, and client ID, with an optional refresh token;
- validate required metadata against the selected gateway registration and reject expired or near-expiry credentials;
- store credentials through
openshell-bootstrapusing its restricted-directory and owner-only file handling; - avoid printing token values in normal output or errors;
- fail rather than opening a browser when invoked non-interactively; and
- leave refresh behavior explicit: use a supplied refresh token when supported, otherwise require the imported access token to cover the intended operation.
The storage schema should become a supported CLI input contract without making its on-disk path part of the public interface.
Alternatives Considered
- Write
oidc_token.jsondirectly. This works with current releases but depends on a private path and serialization format, duplicates permission handling, and can race other CLI invocations. - Use browser login. This is appropriate for people but not for projected workload identity or unattended jobs.
- Add a client-credentials mode to every broker. That excludes brokers designed around projected assertions and still leaves token persistence to each integration.
- Pass a token through an environment variable. Environment inheritance and diagnostics make this easier to expose than a bounded file or standard input.
Agent Investigation
- Inspected OpenShell
mainat736e431dand latest release v0.0.96. - Reviewed
GatewayCommandsincrates/openshell-cli/src/main.rs: gateway registration supports OIDC metadata, while login remains a separate authentication flow and no token-import command exists. - Reviewed
crates/openshell-bootstrap/src/oidc_token.rs:OidcTokenBundleand safe storage helpers already provide the underlying persistence primitive. - Reviewed current OIDC login and refresh code in
crates/openshell-cli/src/oidc_auth.rsand gateway command handling. - Searched open and closed issues for OIDC token import, non-interactive OIDC, and externally issued token support; no matching issue was found.
Checklist
- I've reviewed existing issues and the architecture docs
- This is a design proposal, not a "please build this" request
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with GatewayCommands in crates/openshell-cli/src/main.rs, then read crates/openshell-bootstrap/src/oidc_token.rs and the OIDC flow in crates/openshell-cli/src/oidc_auth.rs. Define the command and token-bundle contract for an existing OIDC gateway, including validation and non-interactive behavior. Done means credentials are safely stored through openshell-bootstrap without exposing token values or relying on the private on-disk format.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- authentication, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100