Breaking Change
This release contains breaking changes. The module path is now github.com/Nerzal/gocloak/v15.
The new minimum Go version is: Go 1.26
Tested against Keycloak: 26.8.2
See Upgrading from v14 in the README. In short:
- IDs, names and realms are path-escaped by gocloak; do not escape them yourself.
- Response-only structs use plain values instead of pointers; representation structs and query params keep pointers.
UpdateAuthenticationFlowreturns only anerror.ValidateAccessTokenrejects tokens withoutexp.- Tracing uses OpenTelemetry propagation instead of opentracing.
Highlights
ValidateAccessToken/ValidateAccessTokenCustomClaimsverify the signature and checktyp,aud,azpandexp, with optional clock skew leeway.- PKCE support:
TokenOptions.CodeVerifier,NewPKCE()andPKCEChallenge(). - Key rotation: an unknown
kidtriggers a rate-limited cert refetch; concurrent callers share one fetch per realm; stale keys are served while Keycloak is unreachable. APIError.Typeis set from the error body (invalid_grant), andAPIErrorunwraps transport errors (errors.Is(err, context.Canceled)).- Requests time out after 30s by default.
- Many fixes for panics, wrong query params, token exchange, signed JWT login and version handling; see #539 for the full list.
- Dropped dependencies:
opentracing-go,pkg/errors,ksuid,golang.org/x/mod.
What's Changed
- Fix error typing, key rotation, version race and URL escaping; slim down API by @Nerzal in #539
- includes "replace opentracing with opentelemetry propagation" (#538) and "add included.custom.audience to ProtocolMappersConfig" (#537) by @rmocanu001
Full Changelog: v14.0.4...v15.0.0