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=localand Go 1.26 or older the build fails; with the defaultGOTOOLCHAIN=autothe go command fetches 1.27.encoding/jsonnow runs on the v2 engine, so error messages for invalid JSON can read differently.GOEXPERIMENT=nojsonv2switches 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().SetRedirectPolicyoverrides it. ValidateAccessTokenrejects tokens whoseissbelongs to another realm or is missing.- Response bodies are limited to 100 MiB (
RestyClient().SetResponseBodyLimit). - Idle connections:
NewClientkeeps 100 idle connections per host instead of resty'sGOMAXPROCS+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.OnAfterResponsehooks onRestyClient()do not run for these calls andSetDebugdoes 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.
ValidateAccessTokennow checks thatissends 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
emailorusername. The query is now replaced with?REDACTED. GetCertsreturnedX5candKeyOpsslices shared with the cache; they are now copied.EnforcedString.UnmarshalJSONpanicked 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