Repository navigation
ProxyAuthK8s v0.5.0 - v0.6.0
Release Date: 2026-11-02T11:36:24Z
Overview
Token exchange release: one SSO login to the proxy now serves every cluster that asks for it. The default behaviour is unchanged; nothing moves without the proxy admin opening the mode.
✨ Highlights
- Token exchange (RFC 0010, #332): a
ProxyKubeApiinupstream_auth.mode: TokenExchangehas the proxy exchange the user's proxy token for a cluster token at the cluster's own IdP (RFC 8693), so a federation of IdPs needs a single login. Tokens are cached per user and cluster in memory, with a TTL bounded by the proxy token, the cluster token and the configured cap.kubectl-proxyauth login clusterssigns in to the proxy once (SSO, PKCE) and writes one context per exchange cluster;login --server-url --tokenstays.- Keycloak, Authentik and Dex covered in the guide, each proven on the integration bench (Dex) or the heavy suite (Authentik).
- Opening the mode is the proxy admin's call through
upstreamAuth.allowedModes, as for RFC 0014.
🛡️ Security and fixes
- A user without
preferred_usernameis named by theiremailinstead of sharing an empty name (audit, per-user rate limit). - A refresh token the IdP rejects as
invalid_requestis treated asinvalid_grant: the CLI asks for a new login instead of failing. - An IdP token response past 16 KiB is refused as
502. - The chart quotes the back and front
extraEnvvalues. - Dependencies bumped in range (#334); the
crypto-bigintadvisory RUSTSEC-2026-0387 left every lockfile with openidconnect 4.1, so its exception is retired. ThersaMarvin exception (RUSTSEC-2023-0071) remains, documented with its expiry.
🧪 Tests and tooling
- Heavy suite (upstream echo, previous release side by side) and k6 HTTP load (RFC 0016, #331).
- The bench proves the exchange end to end against a second Dex (
rfc0010), and counts its exchanges by delta instead of a time window (#333). kubestays on 4 until the operator kit moves;kubectlwithin one minor of the bench's k3s.
📚 Docs
- Token exchange guide and migration to 0.6.0.
- Full changelog in CHANGELOG.md.
⚠️ Upgrade notes
chart-crdbefore the chart, as always. On a 0.5.x CRD the apiserver refusesmode: TokenExchangeat write time.- Enabling the exchange on a cluster invalidates the cluster tokens already handed out for it: its users run
kubectl-proxyauth login clustersagain. - Rolling back to 0.5.x: put every cluster back in
Passthroughfirst, a 0.5.x binary does not knowTokenExchange. - The Dex image of the bench is held at v2.45.1 (dexidp/dex#5017, newer Dex wedges
/tokenafter one refresh grant); this only concerns the integration bench, not your IdP, but if you run Dex ≥ 2.46 as the proxy's IdP, check that issue.
📦 Installation
Prerequisites
- Kubernetes 1.30+
- Helm 3.8+ (OCI registries)
- An OIDC provider
- Redis (single node or cluster)
See the Quick Started guide and the
chart values reference.
Using Helm (Recommended)
# CRDs first
helm upgrade --install proxyauthk8s-crd oci://ghcr.io/batleforc/proxyauthk8s/chart-crd \
--version 0.6.0 \
--namespace proxyauthk8s --create-namespace
# Then the application
helm upgrade --install proxyauthk8s oci://ghcr.io/batleforc/proxyauthk8s/chart \
--version 0.6.0 \
--namespace proxyauthk8s \
--values values.yamlThe chart ships a values.schema.json: Helm rejects unknown or mistyped values.
Container images
Multi-arch (linux/amd64, linux/arm64), signed with cosign (keyless) and carrying
provenance and SBOM attestations:
docker pull ghcr.io/batleforc/proxyauthk8s/server:v0.6.0
docker pull ghcr.io/batleforc/proxyauthk8s/front:v0.6.0
# Verify a signature (images and charts)
cosign verify ghcr.io/batleforc/proxyauthk8s/server:v0.6.0 \
--certificate-identity-regexp 'https://github.com/batleforc/.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
cosign verify ghcr.io/batleforc/proxyauthk8s/chart:0.6.0 \
--certificate-identity-regexp 'https://github.com/batleforc/.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comThe CycloneDX SBOMs (server-sbom.json, front-sbom.json) are attached to this release.
kubectl plugin
With mise: mise use -g github:batleforc/ProxyAuthK8S@v0.6.0. With
krew: use the proxyauth.yaml manifest attached to this release
(kubectl krew install --manifest=proxyauth.yaml). Or download the archive for your platform:
# linux_amd64, darwin_amd64, darwin_arm64 or windows_amd64
curl -LO https://github.com/batleforc/ProxyAuthK8S/releases/download/v0.6.0/kubectl-proxyauth_v0.6.0_linux_amd64.tar.gz
tar -xzf kubectl-proxyauth_v0.6.0_linux_amd64.tar.gz
sudo install kubectl-proxyauth /usr/local/bin/
kubectl proxyauth --helpEach archive has a .sha256 next to it.
🔄 Update Instructions
helm upgrade proxyauthk8s-crd oci://ghcr.io/batleforc/proxyauthk8s/chart-crd \
--version 0.6.0 --namespace proxyauthk8s
helm upgrade proxyauthk8s oci://ghcr.io/batleforc/proxyauthk8s/chart \
--version 0.6.0 --namespace proxyauthk8s --values values.yamlFor the plugin: mise upgrade github:batleforc/ProxyAuthK8S, kubectl krew upgrade proxyauth, or replace
the binary as above.
🔗 Related Resources
📞 Support & Feedback
- Report bugs: GitHub Issues
- Security concerns: report privately, never in a public issue
- Discussions: GitHub Discussions
🙏 Contributors
Thank you to all contributors who made this release possible:
Max Batleforc,Maxime StepSecurity Bot
What's Changed
- build(deps): bump taiki-e/install-action from 2.87.29 to 2.87.31 by @dependabot[bot] in #325
- build(deps): bump github/codeql-action/upload-sarif from 4.39.0 to 4.39.1 by @dependabot[bot] in #315
- build(deps): bump mlab-sh/postmortem from 2.9.0 to 2.9.2 by @dependabot[bot] in #311
- chore(version): v0.5.0 by @batleforc in #330
- build(deps): bump docker/login-action from 4.6.0 to 4.7.0 by @dependabot[bot] in #326
- RFC 0016: heavy suite and HTTP load by @batleforc in #331
- RFC 0010: token exchange by @batleforc in #332
- fix(deps): November pass, closing RUSTSEC-2026-0387 by @batleforc in #334
- test(integration): count Dex B's exchanges by delta, not by time window by @batleforc in #333
Full Changelog: v0.5.0...v0.6.0