go-oidc

go-oidc adds OpenID Connect support to Go applications that already use golang.org/x/oauth2 for OAuth2 flows. It handles provider discovery via the .well-known/openid-configuration document, exposes the discovered authorization and token endpoints as a standard oauth2.Endpoint, and verifies ID Tokens against the provider’s published JSON Web Key Set — checking signature, issuer, audience, and expiry so callers don’t have to hand-roll JWT validation.

Maintained by CoreOS (now under Red Hat/IBM) and imported by well over a thousand open source projects, it is one of the most widely used Go OIDC clients and is commonly used to integrate with identity providers like Google, Microsoft Entra ID, Okta, Auth0, and Kubernetes service-account tokens, as well as workload-identity flows such as GitHub Actions OIDC.

What You Get

• OpenID Connect discovery via oidc.NewProvider, resolving the issuer’s authorization, token, device-authorization, userinfo, and JWKS endpoints from its .well-known/openid-configuration document
• Provider.Endpoint() returning a ready-to-use oauth2.Endpoint so the standard golang.org/x/oauth2 package drives the actual authorization-code exchange
• An IDTokenVerifier that checks JWT signature, issuer, audience, expiry, and (optionally) access-token hash binding against a remote or static key set
• NewRemoteKeySet for long-lived, self-refreshing JWKS caching, plus a StaticKeySet for tests or key material supplied out of band
• Provider.UserInfo for querying the OpenID Connect userinfo endpoint with an oauth2 token source
• A ProviderConfig escape hatch for providers that don’t implement discovery or host it at a non-spec path
• Logout token verification (VerifyLogout) for OpenID Connect back-channel logout flows
• An oidctest subpackage exposing test helpers for exercising the verifier without a live identity provider

Common Use Cases

• Adding “Sign in with Google/Microsoft/Okta” login to a Go web app on top of an existing oauth2.Config
• Verifying Kubernetes service-account OIDC tokens or GitHub Actions workload-identity tokens for keyless CI/CD authentication
• Building an internal SSO gateway that federates to multiple enterprise identity providers via standard OIDC discovery
• Validating ID tokens received from a client-side SPA before establishing a server-side session
• Implementing OpenID Connect back-channel logout handling in a multi-service backend

Under The Hood

Architecture go-oidc is organized as a single oidc package with a small, composable surface: Provider (discovery result), IDTokenVerifier (validation), and KeySet (a pluggable interface with NewRemoteKeySet and StaticKeySet implementations in jwks.go). oidc.go owns discovery (NewProvider) and the ID Token/UserInfo data model; verify.go owns the IDTokenVerifier/Config validation logic and delegates signature checking to whatever KeySet it was constructed with; jwks.go implements the two KeySet variants, using github.com/go-jose/go-jose/v4 for JWS parsing; logout.go layers back-channel logout token verification on the same primitives. There is no global state beyond a per-Provider mutex guarding a lazily-created shared remote key set, and HTTP clients are threaded through context.Context via ClientContext/oauth2.HTTPClient, so swapping the transport (e.g. for testing or custom TLS) requires no API changes — a change to the KeySet interface would be the one modification that ripples through every consumer, since both discovery-based and manual verifiers depend on it.

Tech Stack The module (github.com/coreos/go-oidc/v3, requiring Go 1.25) has exactly two runtime dependencies: golang.org/x/oauth2 for the underlying OAuth2 token exchange and HTTP client context plumbing, and github.com/go-jose/go-jose/v4 for JWS/JWK parsing and signature verification (RS256/384/512, ES256/384/512, PS256/384/512, and EdDSA). There is no web framework, ORM, or database layer — this is a pure protocol/client library meant to be embedded in a caller’s own HTTP handlers, with releases and dependency updates driven by GitHub Actions and Dependabot.

Code Quality Each core source file has a directly corresponding test file of comparable or greater size (e.g. oidc_test.go at 881 lines against oidc.go at 687, verify_test.go at 622 lines against verify.go at 340, plus a dedicated oidctest package providing reusable test doubles), indicating deliberate, thorough test coverage of discovery, verification, and logout paths rather than incidental testing. Errors are returned as typed values (IssuerMismatchError, TokenExpiredError) or wrapped with fmt.Errorf/%v rather than swallowed, exported identifiers carry Go-doc comments with runnable examples, and CI runs via .github/workflows/test.yaml on every change alongside Dependabot-managed dependency bumps.

What Makes It Unique Rather than binding to one identity provider’s SDK, go-oidc implements the OpenID Connect discovery and verification spec generically, so the same client code works against any spec-compliant issuer — consumer providers like Google and Apple, enterprise providers like Entra ID and Okta, and workload-identity issuers like GitHub Actions or Kubernetes — while deliberately deferring the OAuth2 authorization-code exchange itself to the standard golang.org/x/oauth2 package instead of reimplementing it, keeping the library’s scope narrow and its behavior predictable.