iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To add browser-based OpenID Connect (OIDC) login to a Jakarta Servlet application with pac4j, connect the jakartaee-pac4j servlet integration to pac4j-oidc, configure an OIDC client and its exact callback URL, then map pac4j’s security, callback, and logout filters. Authentication identifies the user; your application must still decide which users may access each function.
Choose the integration that matches your application
The pac4j Servlet guide’s current example targets Java 17 or later, Maven, a WAR deployment, and a Servlet 6.0 container. It uses jakartaee-pac4j 8.0.3 with pac4j-oidc 6.5.8; Tomcat 10.1 and Jetty 12 with the Jakarta EE 10 environment are cited as examples. These are the guide’s version snapshots, not a guarantee that every server and provider combination is interchangeable. Check the compatibility table and release information for the versions you deploy. pac4j OIDC guide
- For Jakarta Servlet APIs, use
jakartaee-pac4jand compatible pac4j 6 dependencies. The repository compatibility table maps integration 8+ to Java 17 and pac4j 6. - For a legacy Java EE application using
javax.servlet, use the Java EE integration artifact,javaee-pac4j, rather than mixing namespaces. The compatibility table maps integration 7+ to Java 11 and pac4j 5. jakartaee-pac4j repository and compatibility information
pac4j filters and Jakarta Security’s built-in OIDC mechanism are separate implementation routes. The steps below use pac4j; Jakarta EE’s tutorial documents its own OIDC mechanism and application identity-store option. Jakarta EE Security tutorial
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteHow the OIDC login flow works
- A browser requests a URL protected by pac4j’s
SecurityFilter. - If the user is not authenticated, the filter redirects the browser to the identity provider.
- After login, the provider returns the browser to the registered callback URL.
CallbackFiltercompletes the authorization-code exchange and validates the ID token. - pac4j stores the resulting profile in the session and returns the browser to the original URL or a configured default.
The provider’s discovery document supplies protocol endpoints, including authorization, token, user-info, and JWKS endpoints. Use the exact discovery URL from your provider rather than guessing endpoint paths. The Jakarta Security 5.0 milestone 2 specification describes required metadata such as the issuer, JWKS URI, supported response types, and ID-token signing algorithms; because that is a milestone specification, verify final specification and server behavior before relying on details specific to Jakarta Security 5.0. Jakarta Security 5.0 milestone 2 specification
#1 Best Overall
Add dependencies and configure the OIDC client
Start with a Maven web application packaged as a WAR. Add the Jakarta Servlet integration and OIDC module, and declare the Servlet API with provided scope as in the pac4j guide. Pin versions known to be compatible with your Java runtime and container; do not assume that one version pairing works across every deployment.
Create an OidcConfiguration with the provider’s discovery URI, client ID, and client secret. Use it to create an OidcClient, then supply that client and the callback URL to pac4j’s Config. Keep the secret in deployment configuration or a secrets manager rather than source control. Any literal values shown in a demo are examples, not credentials to reuse. The pac4j guide’s public demo configuration permits unsigned ID tokens as a demo concession; do not enable setAllowUnsignedIdTokens(true) for a real provider. pac4j OIDC client configuration
Rank #2
Register the exact callback with the identity provider
The redirect URI in the provider’s client registration must match the callback configured in the application exactly, including scheme, host, path, and query string. In the documented pac4j configuration, the callback includes ?client_name=OidcClient. Register the complete URL rather than only its path. pac4j OIDC guide
In production, register the public HTTPS URL that the browser uses. If the application sits behind a reverse proxy, an internal hostname or port is not the right redirect URI. The proxy and application configuration must agree on the externally visible URL.
Map the three filters
Configure the filters in WEB-INF/web.xml, or register them in application code with FilterHelper; do not configure both routes for the same filters. The pac4j guide demonstrates the following responsibilities and a /logout mapping. pac4j Jakarta EE integration guide
SecurityFilter: protect the application routes that require login. Map only the intended paths, or deliberately choose catch-all protection. Configure authorizers where role or profile-attribute restrictions are needed.CallbackFilter: map the provider’s return path so pac4j can complete authentication.LogoutFilter: map the application’s logout path. The guide’s example setsdestroySession=trueand returns to a default URL.
Session renewal is enabled in the guide’s example to guard against session fixation. If metadata-complete="true" is present in web.xml, annotation scanning is suppressed unless components are declared explicitly; check this when a filter appears not to run. pac4j Jakarta EE integration guide
Read the authenticated profile
In a protected servlet, use pac4j’s ProfileManager to retrieve the authenticated OidcProfile. A profile is available only where the request has passed through the security filter and authentication succeeded. The guide’s default requested scopes are openid profile email; those scopes do not guarantee that every provider will return name or email claims. The identity provider’s configuration and the user’s data determine which claims are available. pac4j Jakarta EE integration guide
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Keep authorization separate from login
Successful OIDC authentication establishes an identity; it does not automatically authorize business actions. In pac4j, use authorizers to check whether a request requires an authenticated profile, a role, or a profile attribute. Decide which trusted claims or application-managed data supply those roles, and test both an allowed user and a user who should be denied.
Best Value
Do not assume the provider supplies groups just because login works. Jakarta EE’s OIDC tutorial describes using an application identity store when provider claims do not contain the groups the application needs. It also discusses configuring claimsDefinition to obtain group claims from an access token, identity token, or user-info response, depending on provider support and configuration. Jakarta EE Security tutorial
Choose local or provider logout
Local logout removes the application’s profile and can invalidate the HTTP session. To also end the user’s identity-provider session, enable central logout and configure the provider’s supported OIDC end-session endpoint and a registered post-logout return URL. Provider logout support and registration requirements vary.
If a logout return URL is supplied dynamically through a url parameter, constrain it with pac4j’s logoutUrlPattern so the application cannot be used for unsafe redirects. pac4j Jakarta EE integration guide
Test the complete path before deployment
The pac4j guide shows building with mvn clean package and accessing a protected URL. That documentation is not an independent test of your application, so verify the flow in your own container and provider configuration.
Quick Recap
- Request a protected page in a fresh browser session and confirm the app redirects to the identity provider.
- Complete provider login and confirm the browser returns to the registered callback and then to the requested page.
- Inspect the protected servlet’s profile and verify only the claims your app actually needs are used.
- Test authorization with a user who should be allowed and one who should be denied.
- Log out and verify the local session is gone; if central logout is enabled, verify the provider session behavior separately.
Troubleshoot common failures
- Invalid redirect URI: compare the callback configured in pac4j with the provider registration character for character, including the
client_namequery parameter and public URL. - Login loop behind a proxy: make sure the configured callback uses the browser-visible HTTPS host and path rather than an internal host or port.
- Filter does not run: inspect servlet filter mappings and check whether
metadata-complete="true"prevents annotation scanning. - No profile in a servlet: confirm the servlet’s URL is protected by
SecurityFilterand that the login callback completed successfully. - Name or email is missing: check requested scopes and the provider’s claim configuration; scopes alone do not ensure claims will be returned.
- ID-token validation fails: check the discovery issuer and signing-key publication, including the provider’s JWKS metadata. Do not work around validation errors by allowing unsigned ID tokens for a real provider.
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.
