github Nerzal/gocloak v15.1.0

one hour ago

No API changes. gocloak now needs Go 1.27 and behaves stricter in a few places (see below).

The new minimum Go version is: Go 1.27
Tested against Keycloak: 26.8.2

Behavior changes to be aware of

  • Go 1.27 required. With GOTOOLCHAIN=local and Go 1.26 or older the build fails; with the default GOTOOLCHAIN=auto the go command fetches 1.27. encoding/json now runs on the v2 engine, so error messages for invalid JSON can read differently. GOEXPERIMENT=nojsonv2 switches back to the old engine.
  • Redirects are only followed to the same scheme, host and port (max 10). A cross-origin redirect now fails instead of being followed. RestyClient().SetRedirectPolicy overrides it.
  • ValidateAccessToken rejects tokens whose iss belongs to another realm or is missing.
  • Response bodies are limited to 100 MiB (RestyClient().SetResponseBodyLimit).
  • Idle connections: NewClient keeps 100 idle connections per host instead of resty's GOMAXPROCS+1. RestyClient().Transport() changes it.

Performance

gocloak is the base of gocloak-mcp and gocloak-auth-proxy, which send a lot of concurrent traffic through one client.

  • On Go 1.27, decoding Keycloak responses is 28 to 70 % faster with 40 % fewer allocations, without code changes.
  • With the larger idle pool, 16 concurrent callers over TLS need 57 % less time per call and open 98 % fewer connections. A pod limited to 1 CPU used to keep only 2 connections to Keycloak and did a TLS handshake for almost every further request.
  • New opt-in option SetDirectBodyRead(): gocloak reads response bodies itself into a buffer sized from Content-Length. GetUsers(max=1000) allocates 39 % fewer bytes and runs 22 % faster. OnAfterResponse hooks on RestyClient() do not run for these calls and SetDebug does not log response bodies, which is why it is off by default.
  • From v15.0 on Go 1.26 to v15.1 on Go 1.27, offline benchmarks show 21 % less time and 27 % fewer allocations (geomean). Against a real Keycloak the latency of a single call stays the same, because Keycloak takes milliseconds and gocloak microseconds.

The measurements, profiles and what was left out (fasthttp, the direct encoding/json/v2 API, value fields in User) are in benchmarks/PERFORMANCE.md. The README has a new Performance section.

Security fixes

From a review of v15.0.0 against the OWASP Top 10 2025:

  • A 307 redirect to another host re-sent the form body (password, refresh token, client assertion), and a redirect to another port kept Authorization. Fixed by the redirect policy above.
  • Realms sharing a signing key accepted each other's tokens. ValidateAccessToken now checks that iss ends with /realms/{realm}; only the path is compared, so a public hostname that differs from the base URL still works.
  • Every unknown realm left an entry in the certs cache forever. Entries without a successful fetch are now removed.
  • Transport errors contained the full URL including query parameters such as email or username. The query is now replaced with ?REDACTED.
  • GetCerts returned X5c and KeyOps slices shared with the cache; they are now copied.
  • EnforcedString.UnmarshalJSON panicked on empty input (found by fuzzing).

What's Changed

  • Harden redirects, issuer check, certs cache and error messages by @Nerzal in #541
  • Bump golang.org/x/crypto from 0.58.0 to 0.59.0 by @dependabot in #540
  • Pin GitHub Actions to commit SHAs by @Nerzal in #542
  • v15.1.0: require Go 1.27, reuse connections, opt-in direct body read by @Nerzal in #543

Full Changelog: v15.0.0...v15.1.0

Don't miss a new gocloak release

NewReleases is sending notifications on new releases.