openidconnect-rs

openidconnect is a Rust library that implements the OpenID Connect protocol as a set of extensible, strongly-typed interfaces built on top of the oauth2 crate. Rather than hard-coding the OIDC Core spec’s claim sets and algorithms, the crate exposes generic types parameterized over claims, signing algorithms, and response types, with a core module providing ready-made type aliases (CoreClient, CoreProviderMetadata, etc.) that cover the common case out of the box.

It supports the Authorization Code, Implicit, and Hybrid relying-party flows with PKCE, OpenID Connect Discovery (provider metadata and JWKS), Dynamic Client Registration, RP-Initiated Logout, Token Introspection and Revocation, and the Device Authorization Grant. ID token verification covers RSA, HMAC, ECDSA (P-256/P-384), and EdDSA (Ed25519) signing algorithms. HTTP transport is pluggable across synchronous and asynchronous modes, with built-in support for reqwest, curl, and ureq, or a custom client implementing the crate’s SyncHttpClient/AsyncHttpClient traits.

Used to authenticate against providers like Google, GitLab, Microsoft Entra ID, and any OpenID-certified identity provider, it is a common building block for Rust web services and CLIs that need federated login rather than rolling their own OAuth2/OIDC token handling.

What You Get

• A generic Client type parameterized over claims, error responses, and signing algorithms, plus a core module of ready-made type aliases (CoreClient, CoreProviderMetadata, CoreIdToken) for the common OIDC Core configuration
• Authorization Code, Implicit, and Hybrid relying-party flows with PKCE support, CSRF token and nonce handling built in
• OpenID Connect Discovery support that fetches and parses provider metadata and JSON Web Key Sets automatically
• ID token verification across RSA, HMAC, ECDSA (P-256/P-384), and EdDSA (Ed25519) signing algorithms, plus standard and UserInfo claim handling
• RP-Initiated Logout, Dynamic Client Registration, Token Introspection (RFC 7662), Token Revocation (RFC 7009), and the Device Authorization Grant (RFC 8628)
• Pluggable HTTP transport with synchronous and asynchronous modes and built-in reqwest, curl, and ureq client implementations, or a trait-based interface for custom clients

Common Use Cases

• Adding “Sign in with Google/Microsoft/GitLab” login to a Rust web application via the Authorization Code + PKCE flow
• Implementing a relying party that verifies ID tokens issued by an internal or third-party OpenID Connect provider
• Building CLI tools or native/mobile clients that authenticate users through the OAuth 2.0 Device Authorization Grant
• Standing up service-to-service authentication that relies on OIDC Discovery to fetch provider metadata and rotate signing keys automatically

Under The Hood

Architecture The crate is organized around a central generic Client<...> struct (src/client.rs, ~1,470 lines) parameterized over token error types, revocable token types, and token introspection/response types, so that compile-time guarantees track exactly which RFC-defined errors a given operation (token exchange, introspection, revocation) can surface. Protocol-specific concerns are split into focused modules — discovery (provider metadata and JWKS retrieval), id_token (claims and verification orchestration), jwt (low-level JWS parsing/signing), verification (signature and claim validation policy), registration (dynamic client registration), and authorization/logout/token for their respective flows — with a core module supplying concrete type aliases (CoreClient, CoreProviderMetadata) that fill in the generic parameters for the common OIDC Core configuration. A macros.rs module (750 lines) generates repetitive trait impls and accessor boilerplate across these generic types. HTTP transport is abstracted behind SyncHttpClient/AsyncHttpClient traits, decoupling protocol logic from any specific HTTP client.

Tech Stack Built on the oauth2 crate for OAuth2 token exchange primitives, with serde/serde_json/serde_path_to_error/serde_with for typed (de)serialization of provider metadata and claims, chrono for timestamp handling, and a set of dedicated cryptography crates — rsa, p256, p384, ed25519-dalek, hmac, sha2, subtle — for ID token signature verification across RSA, ECDSA, EdDSA, and HMAC. thiserror provides typed error enums throughout. HTTP transport is feature-gated across reqwest (default), curl, and ureq backends, letting consumers pick sync or async clients or disable the default dependency entirely for a custom implementation. The crate targets Rust 1.65+ as its MSRV and supports wasm32-unknown-unknown as a compile target.

Code Quality Each protocol module ships with a co-located tests.rs file exercising discovery parsing, JWT verification, and registration flows against fixture data, with the verification and discovery suites being the most extensive. CI runs the full test suite (including doctests, with and without default features) across stable, beta, nightly, and the pinned MSRV toolchain, enforces cargo fmt --check and cargo clippy --all --all-features -- --deny warnings, and runs a scheduled cargo audit to catch new advisories. Error handling is explicit and typed via thiserror-derived enums rather than string errors or panics in library code, and public types are covered by #![warn(missing_docs)]. Secret-bearing types deliberately omit PartialEq to force constant-time comparison via an opt-in feature flag, a deliberate security-conscious API design choice.

What Makes It Unique Rather than hard-coding claim sets, signing algorithms, and response types, the crate exposes them as generic parameters, letting consumers define custom claims or extension types while still getting compile-time verification of which errors a given RFC-defined operation can produce — a stronger static-typing approach than most dynamically-typed or trait-object-based OIDC client libraries. The explicit security note steering users toward disabling HTTP redirect-following (to prevent SSRF) and the opt-in, documented rationale for omitting PartialEq on secret types reflect an unusually security-conscious API design for a general-purpose auth library.