oidc

zitadel/oidc is a Go library implementing both sides of the OpenID Connect protocol: a relying party (RP) client for consuming external identity providers, and a full OpenID Provider (OP) server implementation for building your own IdP. Built and maintained by ZITADEL, it is certified against the OpenID Foundation’s basic and config conformance profiles, so it can serve as the OIDC layer for both consumer apps and identity infrastructure.

The library implements a wide surface of the OAuth2/OIDC spec — authorization code flow (with PKCE), client credentials, refresh tokens, JWT profile grants, token exchange (RFC 8693), device authorization (RFC 8628), and discovery — split into clean client (pkg/client/rp, pkg/client/rs) and server (pkg/op) packages that can be used independently of each other.

What You Get

• A relying party (RP) client package for authenticating against any OIDC-compliant provider, including PKCE and refresh-token support
• A full OpenID Provider (OP) server package for running your own certified identity server, including discovery, JWKS, and device authorization endpoints
• A resource server (RS) package for verifying and introspecting bearer access tokens in your own APIs
• Working example apps (/example) covering RP, OP, and resource-server integration patterns you can run locally

Common Use Cases

• Standing up an internal OpenID Provider instead of adopting a full IAM product
• Adding SSO / login-with-provider authentication to an existing Go web service
• Validating bearer tokens issued by any OIDC provider in a Go API via token introspection
• Implementing device-flow login for CLIs and headless devices
• Service-to-service auth using JWT profile grants or RFC 8693 token exchange

Under The Hood

Architecture The library separates cleanly into pkg/client (RP and RS consumer-side code, further split into rp, rs, tokenexchange, and profile), pkg/op (the full OpenID Provider/server implementation covering discovery, auth_request, device, keys, error handling, and HTTP routing via server_http.go built on go-chi), and a shared pkg/oidc package holding wire-format types (authorization, introspection, device_authorization, revocation, session) consumed by both sides — a layered, modular split with no circular dependency between the client and server halves. pkg/op/op.go exposes its configuration and storage surface as interfaces (Configuration, Storage) that callers implement rather than concrete structs, so session/token/key persistence is fully pluggable and mockable (pkg/op/mock); pkg/client/rp/relying_party.go mirrors this with a RelyingParty interface built via functional options, keeping OAuth2 config, cookie handling, PKCE state, and the HTTP client swappable per caller. The core abstraction that would ripple through the rest of the codebase if changed is this Storage/RelyingParty contract pairing, not any single concrete struct.

Tech Stack Written in Go 1.25+ using current stdlib idioms (log/slog for logging, slices in the rp package), the library layers go-chi/chi/v5 for HTTP routing in the OP server, go-jose/go-jose/v4 for JWK/JWS handling, golang.org/x/oauth2 (extended, not replaced) for underlying token exchange, zitadel/schema for form/query decoding, gorilla/securecookie for state/PKCE cookie encryption, and rs/cors for CORS on the OP’s HTTP endpoints; tracing comes from go.opentelemetry.io/otel, toggleable off via the no_otel build tag. Testing infrastructure uses stretchr/testify and golang/mock. There is no bundled database or ORM — persistence is entirely delegated to consumer-implemented Storage interfaces, so deployment is just a Go binary/library with no infra dependency of its own.

Code Quality The repo carries 51 _test.go files spanning both client and server packages, including an integration test (client/integration_test.go), runnable example-based doc tests (userinfo_example_test.go, introspect_example_test.go) that double as living documentation, and a dedicated regression_test.go with a regression_data fixture directory guarding against protocol-parsing regressions. CI runs go test -race -v -coverpkg=./pkg/... ./pkg/... across two Go versions with Codecov upload, plus a separate CodeQL workflow scanning every push and PR. Error handling is explicit and typed throughout (oidc/error.go, op/error.go define named error variables and spec-shaped OAuth2 error responses rather than swallowing failures), naming follows idiomatic Go conventions, and Dependabot keeps dependencies current.

API Design The public API favors functional-option constructors over sprawling config structs, keeping most integrations to a handful of lines to build a RelyingParty or OpenIDProvider; package-level GoDoc (doc.go) and per-symbol comments are consistently present, and runnable _example_test.go files double as verified documentation kept in sync with the API by go test. Naming mirrors the spec’s own vocabulary (RP/OP/RS, PKCE, JWT Profile) rather than inventing project-specific jargon, flattening the learning curve for anyone already familiar with OIDC — though the breadth of the spec surface (device flow, token exchange, back-channel logout) means a newcomer building only a simple client still pulls in a moderately large dependency surface and needs to read the /example folder to find their minimal entry point.