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 secure a browser-facing Vert.x application with CAS, configure pac4j’s indirect CasClient, register its complete callback service URL with CAS, install a Vert.x session handler before pac4j, and protect routes with SecurityHandler. Use CallbackHandler to finish login and LogoutHandler for sign-out. Keep synchronous ticket validation off Vert.x event-loop threads.
What you need and which flow to choose
This setup is for browser-based single sign-on using the CAS protocol. The browser is redirected to CAS to authenticate, then returns to your application with a service ticket. pac4j’s indirect CasClient handles that flow.
The pac4j integration guide’s example lists Vert.x Web 5.1.5, vertx-pac4j 7.0.3, and pac4j-cas 6.5.8; it describes vertx-pac4j 7 as targeting Vert.x 5 and pac4j 6. These are documented example versions, not a claim that they are the latest compatible releases. Check the project’s current release information before choosing versions.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsUse a different pac4j integration when the interaction is different: proxy-ticket support is for a web application calling another CAS-protected service on a user’s behalf; CAS REST clients are for a service accepting credentials when the CAS REST feature is enabled. If your identity provider is being used through OIDC or SAML, use pac4j’s support for that protocol rather than CAS protocol support.
#1 Best Overall
Configure the CAS client and callback
Add Vert.x Web, vertx-pac4j, and pac4j-cas to the application. Create a pac4j Config with a CasClient and a callback URL that is reachable by the browser. For example, the client can be configured with a CAS login endpoint using new CasClient(new CasConfiguration("https://your-cas.example/login")). CAS 3.0 is the documented default; explicitly configure a different supported protocol if your CAS server requires it. See the pac4j CAS client reference.
Register the full callback service URL in the CAS service registry. pac4j appends ?client_name=CasClient to the callback URL when it constructs the service value sent during authentication. The registry entry must match that complete value, and its service pattern must permit the intended callback. Configure the CAS service’s attribute-release and proxy policies to match what the application actually needs.
For example, if the callback URL configured for the application is https://app.example/callback, account for pac4j’s client-name suffix in the registered service URL. The public callback URL, reverse-proxy routing, and CAS service registration must agree; registering only the unsuffixed callback can result in CAS rejecting the application.
Install sessions and protect routes
Install Vert.x SessionHandler before pac4j security and callback handlers. Back pac4j with a VertxSessionStore; in a multi-instance deployment, use a clustered Vert.x session store so a user’s session is available regardless of which instance handles the next request.
- Install session handling first. Add
SessionHandlerto the router before the routes that invoke pac4j, including the protected route and callback. - Protect the application routes. Use
SecurityHandlerwith the CAS client for routes requiring authentication. An unauthenticated browser is redirected to CAS. - Complete the callback. Register
CallbackHandlerat the callback path. CAS returns the browser there with a service ticket; the handler validates the ticket, stores the profile, and redirects to the destination. - Keep synchronous security work off the event loop. The guide notes that
SecurityHandlerinvokes synchronous pac4j logic. Register that work with Vert.x’s blocking-handler mechanism. The callback and logout handlers already useexecuteBlockinginternally.
The callback can renew the session identifier, which helps protect against session fixation. The exact router wiring depends on the application, but handler order matters: session handling must be in place before pac4j needs to read or update the user’s session. The pac4j Vert.x integration guide provides the integration example.
Use profiles and authorization deliberately
After successful login, pac4j provides a CasProfile. Its identifier is the CAS principal, often a username. Other profile attributes are available only if the CAS service releases them to the application. An empty or incomplete attributes map is therefore a reason to inspect the CAS service’s attribute-release policy, not to assume that a requested field must exist.
Rank #4
Authentication alone does not grant permission to every protected operation. Use SecurityHandlerOptions to select clients and authorizers, then apply authorization checks where needed—for example, an administrator-role requirement for an administrative route. pac4j documents authorizers for roles, permissions, profile attributes, CSRF, security headers, and other checks in the integration guide and project documentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose local or central logout
Use LogoutHandler to remove the application’s profile or session at sign-out. If users should also leave the CAS single sign-on session, configure central logout and ensure CAS permits the return URL. If a return URL is dynamic, validate it against an application-owned allowlist or pattern rather than accepting arbitrary destinations.
Fix common CAS and Vert.x problems
- “Application Not Authorized to Use CAS”: Compare the service registered in CAS with the complete callback service URL, including
?client_name=CasClient, and check that the registry pattern matches. - Login loops or lost state: Confirm that
SessionHandlerruns before pac4j on both protected routes and the callback route. - Expected attributes are missing: Check which attributes the CAS service releases. A
CasProfilecannot contain attributes the service did not provide. - Requests are slow or event-loop threads are blocked: Move synchronous ticket-validation work invoked by
SecurityHandlerto Vert.x’s blocking handler mechanism. - Logout ends only the application session: Enable central logout if the CAS SSO session must also end, and check that CAS allows the configured return URL.
When proxy tickets or another protocol are appropriate
For a CAS-authenticated web application that must call another CAS-protected service on the user’s behalf, configure proxy-ticket support with CasProxyReceptor and protect the receiving service with DirectCasProxyClient. Restrict accepted proxy chains to the callers intended for the deployment. If the CAS server’s REST feature is enabled and a service needs to submit credentials, consider the CAS REST clients instead. For an identity-provider connection using OIDC or SAML, choose the corresponding pac4j client for that protocol.
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.
