Vault proxy

Vault proxy is the public request boundary for the LibOps Vault service. Vault continues to authorize every Vault token and policy; the proxy adds a Google administrator check to routes that are not explicitly required by customer authentication or secret access flows. Production runs the proxy and Vault as separate Cloud Run services and service identities so this public process does not inherit Vault's storage or KMS authority.

Request policy

• GET /healthz checks only that the proxy process can serve requests.
• A configured public route is forwarded without a Google administrator token.
• Every other route requires a valid Google access token in X-Admin-Token whose verified email is in admin_emails.
• X-Admin-Token is always removed before forwarding. Vault credentials such as X-Vault-Token and Authorization are preserved.
• Authentication failures return a generic 401; logs record the denied path without the Google credential or token-validation details.

Version 2 replaces unsafe implicit prefixes with explicit path patterns. A literal path matches exactly, * matches one complete segment, and a final /** matches a subtree. For example, /v1/auth/userpass/login/** permits login requests but does not expose /v1/auth/userpass/users/**. Legacy routes ending in / are rejected so an upgrade cannot silently retain the broader policy.

Configuration

Set VAULT_PROXY_YAML or pass -config /path/to/config.yaml. Environment configuration takes precedence. Unknown YAML fields, multiple YAML documents, invalid ports, non-HTTP(S) upstreams, malformed emails, and invalid route patterns fail startup.

vault_addr: http://127.0.0.1:8200
port: 8080
admin_emails:
  - admin@example.com
public_routes:
  - /.well-known/**
  - /v1/identity/oidc/provider/*/.well-known/**
  - /v1/identity/oidc/provider/*/authorize
  - /v1/identity/oidc/provider/*/token
  - /v1/identity/oidc/provider/*/userinfo
  - /ui/vault/identity/oidc/provider/*/authorize
  - /v1/auth/oidc/oidc/auth_url
  - /v1/auth/oidc/oidc/callback
  - /ui/vault/auth/*/oidc/callback
  - /v1/auth/userpass/login/**
  - /v1/sys/health

The localhost form is useful only for development or legacy sidecar use. For a separate IAM-protected Cloud Run upstream, configure both fields with the runtime service's default HTTPS URL:

vault_addr: https://vault-runtime-example.run.app
vault_audience: https://vault-runtime-example.run.app

When vault_audience is set, the upstream must use HTTPS. The proxy fetches a short-lived Google-signed ID token from the Cloud Run metadata server, caches it only until shortly before expiration, and sends it in X-Serverless-Authorization. That header lets Cloud Run authenticate the proxy identity while preserving a client's separate Authorization or X-Vault-Token credential for Vault. Caller-supplied forwarding and X-Serverless-Authorization headers are stripped before the proxy creates its own upstream request. The proxy identity needs only roles/run.invoker on the Vault runtime; it needs no Vault data-bucket or KMS role.

The example patterns permit OIDC discovery/exchange and user login while leaving role, provider, user, policy, and system management protected. Add secret-engine subtrees only when downstream Vault policies are intended to be the authorization boundary for those paths.

The provider paths follow Vault's OIDC provider API, and the auth-method callback paths follow the JWT/OIDC auth API.

An administrator can supply a Google access token while independently passing a Vault token:

curl \
  -H "X-Admin-Token: $(gcloud auth print-access-token)" \
  -H "X-Vault-Token: ${VAULT_TOKEN}" \
  https://vault.example.com/v1/sys/policies/acl

Service-account access tokens must include the https://www.googleapis.com/auth/userinfo.email scope so Google's tokeninfo response contains the verified service-account email. Tokens without that identity claim fail closed.

Images and releases

Pull requests build, test, lint, build both native image architectures, and scan them without registry credentials. Protected main and release tags use the LibOps shared publisher to publish and keylessly sign the same manifest in:

• ghcr.io/libops/vault-proxy
• us-docker.pkg.dev/libops-images/public/vault-proxy

Cloud Run deployments must use the GAR image pinned by digest. Other consumers should use GHCR and may also pin the signed digest. Repository releases use PR title markers ([major], [minor], or the default patch increment).