To add OIDC login to a Spring WebFlux client with pac4j, use spring-webflux-pac4j for the WebFlux integration and pac4j-oidc for its OIDC client. Configure the provider, register pac4j’s exact callback URL, protect the intended routes with a SecurityFilter, and register the integration’s callback and logout controllers. The example below follows the official guide’s Spring Boot 3 and Java 17 setup; check version compatibility against your project before adopting its dependency numbers.
What pac4j adds to a WebFlux OIDC login
OpenID Connect (OIDC) builds an identity layer on OAuth 2.0. In this flow, pac4j’s OidcClient redirects a user to an identity provider (IdP), handles the callback, and uses the ID token to establish the signed-in identity. Its OidcConfiguration holds the client credentials and provider settings. See the pac4j OIDC client reference.
As an Amazon Associate I earn from qualifying purchases.
This is a client-application login setup, not a requirement for every reactive Spring application. Spring Security also provides reactive OAuth2 Client and OIDC Login support; choose based on your existing security model, profile handling, outbound API needs, and provider behavior.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallAdd the dependencies
The pac4j guide’s example uses Spring Boot 3, Java 17, spring-webflux-pac4j 3.0.1, and pac4j-oidc 6.5.9. These are the example’s versions, not a claim that they are the latest or suitable for every Spring baseline. The guide also adds spring-jcl: that pac4j version excludes it from a transitive Spring dependency, while Spring 6 needs the logging bridge at runtime.
#1 Best Overall
Use your project’s dependency management to align Spring, Boot, and pac4j versions. The official implementation guide includes the Maven setup: pac4j OIDC client documentation and OIDC reference.
Configure the OIDC client and callback
Create an OidcConfiguration with the IdP discovery URI, client ID, and client secret, then create an OidcClient and add it to pac4j’s Config. The guide demonstrates a public pac4j test provider at https://www.casserverpac4j.dev/oidc/.well-known/openid-configuration; replace it with the metadata URL and credentials for your own provider.
The guide’s base callback is http://localhost:8080/callback. Register the full pac4j callback URI with the provider, including the client name query parameter:
Recommended Free Tools
http://localhost:8080/callback?client_name=OidcClient
For deployment, register the externally visible HTTPS callback URL and make sure proxy and application URL handling agree. A mismatch between the URI sent in the authorization flow and the provider registration can cause a redirect error.
The demo configuration enables unsigned ID tokens with setAllowUnsignedIdTokens(true) for its public test provider. Do not copy that setting for a real identity provider.
Protect the routes that require login
Create a pac4j SecurityFilter using the OIDC client name and a PathMatcher. Pay close attention to the documented prefix behavior: includePath("/protected/") matches /protected/index and deeper paths, but not /protected itself or a sibling such as /protected-other.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose matchers that cover every route meant to require authentication, including any edge route without a trailing slash. Keep callback and logout routes outside the protected prefix so the authentication flow can complete. Test public and protected paths explicitly rather than assuming a near-match is covered.
Register the callback and logout controllers
Scan org.pac4j.springframework.web so the integration registers its callback and logout controllers, conventionally at /callback and /logout. Configure callback session renewal and logout behavior in application properties. If you use the built-in controllers, remove any duplicate custom endpoint mappings.
Callback session renewal can change the session identifier to help protect against session fixation. Let the integration complete its session operations before the request continues.
Understand blocking work in the reactive flow
WebFlux is reactive, but pac4j’s security logic and OIDC HTTP calls are synchronous. The WebFlux integration schedules that work on Reactor’s bounded elastic scheduler, away from Netty’s event loop; the guide does not require you to add a separate scheduler wrapper. This distinction matters when diagnosing latency or threading behavior: the application’s reactive stack does not make the underlying OIDC calls non-blocking.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Read the authenticated OIDC profile
In a protected controller, construct a SpringWebfluxWebContext and SpringWebfluxSessionStore from the request’s ServerWebExchange, then use pac4j’s ProfileManager to retrieve an OidcProfile. The profile exposes standard claims and token access, but the claims actually available depend on the identity provider and requested scopes.
Treat profile values as untrusted input when rendering responses: encode them for the output context. The guide’s plain-text response is illustrative, not a safe default for HTML rendering. If you map provider groups to application roles, verify the claim’s real shape and ensure only trusted administrators can change group membership.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose local or provider logout
Local pac4j logout removes the profile and destroys the application session. Central logout is an additional provider-dependent flow: the provider must support an end_session_endpoint, and the post-logout redirect URI must be allowed by the provider.
Restrict dynamic logout return URLs. The guide’s local HTTP example and regular-expression allowlist should be changed to the application’s actual public HTTPS origin in production.
When Spring Security may be a better fit
Spring Security has native reactive OAuth2 Client and OIDC Login support. Its WebFlux documentation shows oauth2Login() with a reactive client registration, an issuer-uri, and the openid scope. It also documents outbound protected-resource access through a reactive authorized-client manager and WebClient. See Spring Security’s reactive OAuth2 Login documentation.
- Consider pac4j when its client and profile ecosystem fits an existing application.
- Consider Spring Security when the project already uses its authentication model or needs its documented reactive login and authorized-client configuration.
- For either approach, verify provider compatibility, logout support, session behavior, and version alignment with the Spring baseline.
Troubleshoot common integration failures
- The protected filter does not run: check the path matcher, especially trailing-slash prefixes and similarly named routes.
/callbackor/logoutreturns 404: confirm theorg.pac4j.springframework.webcomponent scan is active.- Endpoint mapping conflicts appear: remove duplicate custom callback or logout mappings if the built-in controllers are enabled.
- The provider rejects the redirect: compare the registered callback against the actual redirect URI, including
?client_name=OidcClient, scheme, host, port, and path.
Implementation reference
The full pac4j walkthrough is at How to secure a Spring WebFlux client application with OIDC (using pac4j). For pac4j’s client configuration details, consult its OIDC client documentation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
