To secure browser routes in an Undertow application with OpenID Connect, use the undertow-pac4j integration: configure pac4j’s indirect OIDC client and security configuration, protect the routes with a SecurityHandler, and register a CallbackHandler for the identity provider’s return redirect. Add a LogoutHandler if users should be logged out of the identity provider as well as the application. Choose compatible released dependencies before implementing: the project’s master-branch build values are snapshot declarations, not a stable release recipe.
How the Undertow and pac4j login flow fits together
For a browser-based application, use an indirect client: the application redirects an unauthenticated visitor to the identity provider, then handles the return to complete login. The project distinguishes this from a direct client, which is intended for web-service authentication. OIDC is one of the supported authentication mechanisms. See the undertow-pac4j project README.
As an Amazon Associate I earn from qualifying purchases.
- Protect a route: the
SecurityHandlerchecks authentication and authorization against the configured clients and authorizers. If a visitor is not authenticated, it starts the indirect-client login flow. - Return from the identity provider: the provider redirects the browser to the application’s callback URL. The
CallbackHandlerfinishes the indirect login. - Use the authenticated identity: after security is applied, retrieve the user profile through the pac4j context/session integration appropriate to the selected release.
- Log out: the
LogoutHandlercan log the user out of the application and trigger logout at the identity-provider level.
These are distinct jobs, so a protected route alone is not the entire web login integration: the callback must be handled, and logout behavior must be configured deliberately.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsChoose compatible releases before adding dependencies
The project README describes undertow-pac4j as based on Java 17, Undertow 2, and pac4j 6. Those are project-level compatibility signals, not a guarantee that every combination of Undertow 2.x releases works together. The inspected master-branch pom declares module version 6.0.2-SNAPSHOT, pac4j 6.5.5, and Undertow 2.4.2.Final; these are branch build declarations, not confirmation of the latest published release or a recommended set of versions. The master pom is useful for understanding that distinction, but should not be copied as a release bill of materials.
#1 Best Overall
First identify the released undertow-pac4j artifact your application will use. Then follow that release’s Java and transitive-dependency requirements. The project’s README places dependency setup at the start of its integration sequence, but exact Maven coordinates and versions should come from the selected release’s published artifact metadata or matching dependency documentation; do not infer them from the snapshot pom.
Implementation sequence
- Add the release-matched integration dependencies. Select the integration release first, then obtain its dependency coordinates and required versions from that release’s metadata or documentation. Avoid combining arbitrary Undertow, pac4j, and integration versions.
- Configure an OIDC client and pac4j security configuration. Use the indirect OIDC client for browser login and configure the provider-specific issuer, client credentials, redirect URI, scopes, and any provider logout behavior. pac4j’s
OidcClientis an OpenID Connect 1.0 client; its source documentscodeas the default response type. See the OidcClient source. The actual provider values are not interchangeable, so use the identity provider’s instructions and the documentation matching your pac4j release. - Protect only the routes that require login. Attach a
SecurityHandlerto the intended protected paths and configure the client and any needed authorizers. Keep public routes and operational endpoints outside that protection unless they are meant to require authentication. The handler’s authentication and authorization role is described in the project README. - Register and handle the callback. Configure a
CallbackHandlerfor the indirect login return. Register the application’s externally visible callback URL with the identity provider and make it match the URL used by the application, including scheme, host, path, and any deployment proxy behavior. The default callback path is not established here; do not assume one. - Choose the logout scope. Configure a
LogoutHandlerand decide whether logging out should end only the local application session or also initiate logout with the identity provider. The project documents both application logout and identity-provider logout at a high level, while exact settings depend on release and provider. - Read the authenticated profile. Retrieve the profile through the context/session integration documented for your chosen release. The project setup guide identifies profile retrieval as a step after applying security, but the exact API should be checked in version-matched documentation rather than guessed.
- Validate with the version-matched example and real provider. The project README points to a demo application with OpenID Connect among its authentication examples. Use its matching configuration as a reference, then verify the redirect, callback, public and protected routes, authorization decisions, profile access, and logout against the identity provider you actually use.
Configuration details to verify for your identity provider
OIDC is a protocol, but its deployment values come from the provider and application environment. Before testing, confirm the following items rather than relying on a generic sample with invented values:
Quick Recap
Rank #3
Rank #2
- Comes with secure packaging
- It can be a gift item
- Easy to read text
- Issuer and client registration: use the issuer and client credentials issued for this application.
- Redirect URI: the registered URI must match the callback address the provider sees, especially when TLS terminates at a reverse proxy or the app is mounted below a path prefix.
- Scopes: request the scopes required for the identity claims and application behavior you need; do not assume every provider grants the same claims by default.
- Logout: determine whether the provider supports the logout behavior you intend and configure it in a way compatible with the application’s local session handling.
- Release-specific API: verify handler construction, configuration, callback routing, and profile access against the exact
undertow-pac4jand pac4j release in use.
Common integration failures and what to check
- Login starts but the provider rejects the return URL: compare the provider-registered redirect URI with the externally visible callback URL, not merely the internal Undertow address.
- The callback returns but login does not complete: confirm that the callback path is routed to
CallbackHandler, that the selected indirect client is configured in pac4j, and that the integration and pac4j releases are compatible. - A route unexpectedly redirects to login: inspect which paths are protected by
SecurityHandler; public pages and operational endpoints may need separate routing. - Users remain signed in at the provider after application logout: check whether the logout configuration requests provider-level logout. Local application logout and identity-provider logout are separate behaviors.
- Examples do not compile against the application: confirm that the example and its APIs match the selected released artifact. The master pom’s snapshot dependencies do not establish compatibility with an older release.
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.
