OpenID AuthZEN 1.0
went Final on 2026-01-11. It’s a small, focused spec: the wire protocol
between a Policy Enforcement Point (the bit of your app that asks “can
this user do this?”) and a Policy Decision Point (the bit that answers).
Four endpoint families — a single evaluation, a batch evaluations call,
and three “search” variants (which subjects can do this? which resources
can this subject touch? which actions can this subject perform?) — plus
a /.well-known/authzen-configuration metadata document. That’s the
whole surface.
If you write Go and you want to participate in AuthZEN today, your options are surprisingly thin. The WG’s reference implementations are in Node.js and Python. The existing Go prior art on pkg.go.dev is coupled to specific PDP backends — useful if you already run that backend, useless as a starting point if you don’t. There has been no widely-used, backend-neutral Go library for the wire protocol itself.
So I wrote one. v0.1.0 shipped today.
Repo: github.com/hstern/go-authzen — Apache 2.0, Go 1.26+, zero non-test runtime dependencies.
What it does
go-authzen is the wire protocol, nothing more:
- A typed HTTP client for calling AuthZEN PDPs (the PEP role).
http.Handlerconstructors over a five-methodDeciderinterface (the PDP role).- The full type surface for every spec message — single evaluation, batch, the three search variants — with godoc on every exported symbol naming the spec section it implements.
- The
/.well-known/authzen-configurationmetadata document on both sides, including the mix-up protection that §9.1.1 requires of clients. - An interop fixture set covering both PEP and PDP roles against the OpenID AuthZEN Todo conformance scenario.
What it deliberately doesn’t include: a policy engine, an opinion about how PEPs and PDPs authenticate to each other, or a vendor-specific adapter. Those belong in downstream consumers. The library is library-vendor-neutral by design — you can wire it to Cedar, OPA, Cerbos, a hand-rolled rule set, or a SaaS PDP, and the library doesn’t care which.
The PEP side, in one screen
c, err := client.NewClient("https://pdp.example.com")
if err != nil {
log.Fatal(err)
}
resp, err := c.Evaluate(ctx, &authzen.EvaluationRequest{
Subject: authzen.Subject{Type: "user", ID: "[email protected]"},
Action: authzen.Action{Name: "read"},
Resource: authzen.Resource{Type: "document", ID: "doc-42"},
})
if err != nil {
log.Fatal(err) // transport / 4xx / 5xx — NOT policy-deny
}
log.Printf("decision: %v", resp.Decision) // false = legal policy deny
That last line is load-bearing. A false decision is a successful
HTTP 200 response, never a Go error. The spec is explicit about this
(§10.1.2) and it matters: if you conflate “the PDP said no” with
“something went wrong”, a temporary PDP outage looks identical to a
denied request, and the easy mistake is to fail-open during the outage.
The library reserves the error return for transport failures, authn
rejections, and malformed bodies — the things that mean we don’t know
the answer. Policy denials ride on a false boolean, the way they’re
supposed to.
The PDP side
type myPDP struct{ server.NotImplementedDecider }
func (p *myPDP) Evaluate(_ context.Context, req *authzen.EvaluationRequest) (*authzen.EvaluationResponse, error) {
allow := req.Subject.ID == "[email protected]" && req.Action.Name == "read"
return &authzen.EvaluationResponse{Decision: allow}, nil
}
func main() {
h := server.NewHandler(&myPDP{})
http.ListenAndServe(":8080", h)
}
The Decider interface has five methods, one per endpoint family.
Embedding NotImplementedDecider and overriding only the methods you
serve mirrors the spec’s capability model exactly: AuthZEN says that
the absence of an endpoint URL from the metadata document is how a
PDP advertises “I don’t implement this.” So server.BuildMetadata
introspects your Decider by probing each method with a sentinel
request, and the published metadata document advertises only the
endpoints you actually implement. Unimplemented methods map to HTTP
501. There’s exactly one source of truth for “what does this PDP
support” — the method set on your Decider — and it propagates to
the wire automatically.
Where I spent the design budget
The eight design questions that gated the build are written up in
DESIGN.md.
The three that took the most thinking:
Properties and Context are json.RawMessage, not map[string]any.
The spec’s “open” extension fields — Subject.Properties,
Resource.Properties, Action.Properties, and the request/response
Context — are arbitrary JSON. The obvious Go shape is
map[string]any. The interop scenario rules it out: the conformance
fixtures pin exact JSON bytes, and Go’s encoding/json reorders map
keys on marshal. If you decode {"a":1,"b":2} into a map and re-encode
it, you might get {"b":2,"a":1} back, which the fixture comparison
treats as a different document. json.RawMessage round-trips byte-for-byte
regardless of key order, which is what the spec actually requires. The
ergonomic cost — you have to call authzen.DecodeJSON /
EncodeJSON to bridge to typed Go values — is small and explicit, and
the helpers treat absent/empty RawMessage as “no extension present”
so the common path is one line.
Lenient unmarshal, strict marshal. Postel’s law, applied to a
spec that’s settled but young. Decode whatever the wire gave us;
validate at the marshal boundary only; offer opt-in Validate(...)
for consumers who want stricter inbound checking. The library will
decode a response with an unknown capability URN in the metadata
document, because the IANA urn:ietf:params:authzen:* registry has
no entries yet and we don’t know what will appear there. Branching
on specific URN values now would lock the library to a particular
historical reading of the spec. Treat unknown URNs as
forward-compatible data, not as errors.
Mix-up protection on by default. The spec’s metadata-document
mix-up defense (§9.1.1) is the kind of check that’s trivially correct
when on and silently dangerous when off — a swapped metadata document
is an authorization-bypass class vulnerability, not a configuration
nit. So Client.FetchMetadata hard-fails with a typed
*client.MixUpError when the response’s policy_decision_point
doesn’t match the base URL the client was configured with, and the
escape hatch is client.WithRelaxedMetadataValidation() — explicit,
named, opt-in. The named option is itself a documentation surface:
anyone reading code that uses it knows exactly what they’re trading.
Why the dependency count is zero
v0.1.0 ships with no non-test runtime dependencies. Standard
library only — no jsoniter, no go-json, no JOSE library, nothing.
That’s a real constraint, not a vanity. The library is meant to be used inside other people’s services, including services where dragging in a transitive dependency graph for a wire-protocol library is the wrong trade. Every dep you add forces a decision on every consumer: upgrade pin conflicts, supply-chain audit surface, build size.
The one thing that would pull in a dependency — verifying the
signed_metadata JWS on a metadata document — is round-tripped as
opaque bytes in v0.x. Existing data survives upgrades without churn,
and the JOSE dependency lands in v0.2.0 along with the verification
code, where consumers who don’t need signed metadata can stay on the
v0.1.x branch and consumers who do can opt in.
What ships today
- Full wire surface: single evaluation, batch evaluations, the three search variants.
/.well-known/authzen-configurationon both sides, with mix-up protection on the client and capability-introspection on the server.- Interop fixtures driving the library in both PEP and PDP roles against Topaz at the OpenID AuthZEN Todo conformance scenario URL.
- CI gates on the published surface:
build,static(gofmt+go vet+staticcheck),test,lint, plus a separate dailyvulnworkflow runninggovulncheckagainstmain. - godoc on every exported symbol, with
Exampletests for the load-bearing surfaces.
What’s next
v0.2.0addssigned_metadataproduce and verify, with the JOSE dependency it pulls in. Defaults won’t change.- An end-to-end example PDP demonstrating the server surface with
a real-ish policy engine plugged in behind the
Decider. Theinterop/package has an in-memoryDecidertoday, but an explicitexamples/walkthrough is the missing piece for someone landing on the README cold.
Where I’d love help
If you write a service in Go and you want to interoperate with an
AuthZEN PDP — or implement one yourself — try go-authzen and tell me
what’s broken. The interop scenario in interop/ is currently pinned
to the Todo conformance scenario; if you have access to another
production PDP (a vendor one, your own, anything), running the library
against it and reporting back is the single highest-leverage
contribution right now.
The OpenID AuthZEN WG is the place to be if you care about the wire itself. The Go ecosystem now has a library that participates on its terms.