Skip to content

feat: support enterprise API path prefix in Vault credential driver URLs #5818

Open

Description

@laik

User Story

I use OpenShell's Vault credential driver (openshell-driver-vault) against an enterprise Vault deployment that routes API requests through an additional line-of-business path prefix. I directly encountered the driver being unable to reach this deployment, so that OpenShell can store and resolve credentials in our enterprise Vault.

Problem Statement

The Vault credential driver builds every API URL through a single shared function that hardcodes the v1/ prefix:

// crates/openshell-driver-vault/src/lib.rs
fn url_for_path(&self, path: &str) -> Result<Url, Status> {
    self.settings
        .address
        .join(&format!("v1/{path}"))
        ...
}

Some enterprise Vault deployments require an extra routing segment immediately after /v1/:

/v1/<lob>/auth/<kubernetes-auth-mount>/login
/v1/<lob>/<kv-mount>/data/<secret-path>

There is no configuration field for this prefix today. Putting it into address does not work: URL joining produces incorrect path ordering or a duplicated /v1/ segment. This limitation was verified in v0.1.7–v0.1.9, v0.1.10-pre.3, and the inspected main revision.

Impact / Why This Matters

Users on enterprise Vault deployments with path-prefix routing cannot use the Vault credential driver at all — both Kubernetes auth login and every KV operation fail. The available workarounds are insufficient:

  • Embedding the prefix in address breaks URL construction (wrong ordering / duplicate /v1/).
  • Fronting Vault with a path-rewriting reverse proxy adds an extra network hop and operational component, and sits awkwardly with the driver's deliberate no-proxy / no-redirect / certificate-verification posture.

This is an adoption blocker for enterprises whose Vault platform teams mandate the prefix.

Proposed Design

Add an optional path-prefix field to the Vault credential driver configuration. When set, the driver inserts it immediately after /v1/ in every API URL, applied consistently through the shared URL-building function:

Configuration Generated API path
prefix omitted /v1/{path}
prefix = business-unit /v1/business-unit/{path}

Scope of the prefix:

  • Kubernetes authentication login;
  • KV reads and writes (v1 and v2);
  • KV metadata deletion;
  • any future token renewal or revocation requests;
  • token_file authentication: KV operations also use the prefix.

The prefix must not be added to logical secret paths or persisted credential handles, so stored handles remain resolvable across restarts with the same configuration.

Validation and compatibility:

  • Behavior is unchanged when the field is omitted.
  • Empty values and unsafe path segments (e.g. .., embedded /, query/fragment characters) are rejected at configuration validation time.
  • Existing HTTPS enforcement, certificate verification, no-proxy, and no-redirect protections are preserved.
  • The field is configurable through the supported Helm gateway configuration interface.

Naming (open question): lob matches the enterprise terminology but is deployment-specific; api_path_prefix is more general and describes the mechanism. Either name satisfies the use case — maintainer preference welcome. This request concerns URL path-prefix routing only, not implicit support for the X-Vault-Namespace header.

Suggested UX (if applicable)

[openshell.credential_drivers.vault]
address = "https://vault.example.com:8200"
api_path_prefix = "business-unit"   # or `lob = "business-unit"` — naming TBD
auth_method = "kubernetes"
kubernetes_auth_mount = "kubernetes"
role = "openshell-gateway"
service_account_token_path = "/var/run/secrets/kubernetes.io/serviceaccount/token"
mount = "secret"
kv_version = "2"

With this configuration the driver issues:

POST https://vault.example.com:8200/v1/business-unit/auth/kubernetes/login
GET  https://vault.example.com:8200/v1/business-unit/secret/data/<secret-path>

Acceptance Criteria

  • Existing URLs remain unchanged when the prefix field is omitted.
  • Configuring the prefix inserts it immediately after /v1/ for all driver API requests.
  • Tests cover Kubernetes and token_file authentication, plus KV v1 and v2 reads/writes and metadata deletion.
  • Invalid prefix values (empty, unsafe path segments) fail configuration validation.
  • Stored credential handles remain resolvable after restarting with the same configuration.
  • The field is settable through the Helm gateway configuration interface, with the configuration docs updated.

Alternatives Considered

  • Prefix inside address: fails — Url::join semantics produce wrong path ordering or duplicate /v1/; also conflates the server origin with a routing concern.
  • Path-rewriting reverse proxy in front of Vault: works around the limitation but adds an extra hop, another component to operate and secure, and undermines the driver's intentional no-proxy/no-redirect design.
  • X-Vault-Namespace header support: a different mechanism (Vault Enterprise namespaces). It does not satisfy deployments that route by URL path prefix, and is out of scope for this request.
  • Gateway interceptors / supervisor middleware: these operate at the gRPC routing and sandbox egress boundaries, not on the credential driver's own Vault HTTP client, so they cannot rewrite these URLs.

A single optional driver configuration field applied in the shared URL builder is the smallest change that unblocks the use case without new infrastructure.

Agent Investigation

Verified on the current main checkout:

  • crates/openshell-driver-vault/src/lib.rs:474-479 — url_for_path hardcodes address.join(&format!("v1/{path}")).
  • All four request sites route through it: Kubernetes login (lib.rs:355), KV read (lib.rs:394), KV write (lib.rs:427), KV metadata delete (lib.rs:454). A prefix applied in this one function covers every current API call.
  • Settings parsing rejects unknown fields (settings_reject_unknown_fields test), so today there is no way to pass a prefix through configuration.

Activity

  1. added
    state:acceptedA maintainer decided OpenShell should pursue this issue
    and removed
    state:triage-neededOpened without agent diagnostics and needs triage
    on Nov 20, 2026
  2. johntmyers commented on Nov 20, 2026

    @johntmyers
    Contributor

    Path prefix is fine I think.

  3. laik commented on Nov 20, 2026

    @laik
    Author

    Path prefix is fine I think.
    I have prepared the code. Can I PR?

  4. TaylorMutch commented on Nov 20, 2026

    @TaylorMutch
    Contributor

    @laik a PR would be great, thanks!

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

    state:acceptedA maintainer decided OpenShell should pursue this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions