pac4j/vertx-pac4j

Security library for Vert.x: OAuth, CAS, SAML, OpenID Connect, LDAP, JWT...

The vertx-pac4j project is an easy and powerful security library for Vert.x 4 web applications and web services which supports authentication and authorization, but also application logout and advanced features like CSRF protection. It supports authentication and authorization, but also advanced features like session fixation and CSRF protection. It's based on Java 11, Vert.x 4.2 and on the pac4j security engine v5. It's available under the Apache 2 license.

Main concepts and components:

1. A client represents an authentication mechanism. It performs the login process and returns a user profile. An indirect client is for web applications authentication while a direct client is for web services authentication:

▸ OAuth - SAML - CAS - OpenID Connect - HTTP - OpenID - Google App Engine - Kerberos - LDAP - SQL - JWT - MongoDB - CouchDB - IP address - REST API

2. An authorizer is meant to check authorizations on the authenticated user profile(s) or on the current web context:

▸ Roles/permissions - Anonymous/remember-me/(fully) authenticated - Profile type, attribute - CORS - CSRF - Security headers - IP address, HTTP method

3. A matcher defines whether the SecurityHandler must be applied and can be used for additional web processing

4. The SecurityHandler protects an url by checking that the user is authenticated and that the authorizations are valid, according to the clients and authorizers configuration. If the user is not authenticated, it performs authentication for direct clients or starts the login process for indirect clients

5. The CallbackHandler finishes the login process for an indirect client

6. The LogoutHandler logs out the user from the application and triggers the logout at the identity provider level.

Usage

1) Add the required dependencies

2) Define:

- the security configuration

- the callback configuration, only for web applications

- the logout configuration

3) Apply security

4) Get the authenticated user profiles

Demo

The demo webapp: vertx-pac4j-demo is available for tests and implement many authentication mechanisms: Facebook, Twitter, form, basic auth, CAS, SAML, OpenID Connect, Strava, JWT...

Versions

The latest released version is the , available in the Maven central repository. The next version is under development.

See the release notes. Learn more by browsing the pac4j documentation and the vertx-pac4j Javadoc.

See the migration guide as well.

Need help?

You can use the mailing lists or the commercial support.

vertx-pac4j's Issues

Support for vertx3

Are there any plans for vert.x 3 support? Version 3 contains many changes including concept changes (services with service proxies instead of modules), extended event bus, data objects etc., so it would require some serious code changes.

Create a cas logout handler

(See https://github.com/pac4j/play-pac4j/blob/master/play-pac4j-java/src/main/java/org/pac4j/play/cas/logout/PlayCacheLogoutHandler.java for example)

Retire ClientsBuilder and associated tests

We shouldn't be building Clients instances from Json files now. Not type-safe, error-prone and unnecessary.

Consider use of Rx version of executeBlocking

Where we currently use executeBlocking, consider switching to the Rx version and investigate whether that results in cleaner, or uglier code. I suspect the latter, as the executeBlocking calls than then return
an observable, to which the main handler can simply subscribe, and this approach also lends itself to
flatMapping of results, for example.

However, give it a review and see how the code ends up looking.

Upgrade to pac4j-1.8 RC1

Make vertx-pac4j depend on RC1 of 1.8 now it's available

CallbackHandler not always ending response

CallbackHandler does not end response when using the default URL. It should complete the response when doing this.

Remove references to SimpleTestUsernameProfileCreator

SimpleTestUsernameProfileCreator has been deprecated and now removed, causing compilation failures.

Remove references to this class.

Refactor EventBus Converter

Not every object implements Serializable

Update README to cover CallbackDeployingPac4jAuthHandler

This isn't adequately documented, causing confusion on the PR review

Migrate vertx-pac4j to use vert.x 3.1.0 release and vertx-web 3.1.0 release

Update the vertx-pac4j library to use the 3.1.0 release versions of vertx and vertx-web since these are now released (and we haven't yet completed the update of vertx-pac4j to vertx 3)

IndirectAuthenticationFlow doesn't properly handle failure

Currently it looks as though we only print the stack trace (ugh) - should log and then pass to the http action handler, as per the play implementation https://github.com/pac4j/play-pac4j/blob/master/play-pac4j-java/src/main/java/org/pac4j/play/java/RequiresAuthenticationAction.java#L197

Remove Pac4jWrapper from the Pac4jAuthHandler API

Stateful - and Stateless - Pac4jAuthHandlers should not expose Pac4jWrapper in their constructors,

Instead they should expose the elements from which a Pac4jWrapper is constructed, and create the
wrapper internally when constructed. There is no need to externalize the Pac4jWrapper creation.

Since the stateful handler auto creates the callback handler with which it is associated, it can pass its
internal Pac4JWrapper into the callback handler when it creates it.

Add a validation of client being an IndirectClient to CallbackHandler

There will be a check to ensure the client is an IndirectClient one: https://github.com/pac4j/j2e-pac4j/pull/20/files#diff-dd8336ff9f7458dadab996b4d74c7cb8R74

Update README to reflect vert.x 3 reality

Update the README on master so it reflects the vert.x 3 situation (e.g. no longer a busmod, Clients object should currently be provided via code, rather than json config file)

Provide the URL of the 1.1.x code branch on github in the README for anyone who wishes to access it.

Add more failure-handling tests

Add more tests for validation of authentication and authorization failure scenarios for both stateless and stateful authentication flows.

Test for cookie handling within VertxWebContext

We don't currently have any tests around the new Cookie implementation within pac4j-vertx. The code
which has been written should work but we need to exercise it through some tests to identify any problems.

Respect WebContext Matchers defined in a Pac4j configuration

Respect WebContext Matchers defined in the configuration. As of pac4j 8.1 it's possible to add matchers to the configuration. These expose arbitrary mechanisms for determining whether to apply the pac4j authentication mechanism to a specific request (as expressed by the context).

j2e-pac4j has a sample implementation for applying the matchers to a web request. Mimic this mechanism in vertx-pac4j (and add simple tests to demonstrate success).

Cluster serialization/deserialization of Pac4jUser round trip fails

As noted on PR #64 (which doesn't fix things the way I want), cluster serializing a Pac4jUser via writeToBuffer then deserializing via readFromBuffer fails with the following error

Caused by: java.lang.ClassCastException: java.lang.String cannot be cast to org.pac4j.core.profile.UserProfile
at org.pac4j.vertx.auth.Pac4jUser.readFromBuffer(Pac4jUser.java:85)
at io.vertx.ext.web.handler.impl.UserHolder.readFromBuffer(UserHolder.java:76)

Resolve this by continuing to use Json-based serialization, also include test to avoid regressions

Modify Javadoc headers in source files to include @since header and use full author name

User in vertx-web.session is null

I always null for the webUser in a SocksJSHandler BridgeEvent:

SockJSHandler sockJSHandler = SockJSHandler.create(vertx);
sockJSHandler.bridge(options, be -> {
if (be.socket().webUser() == null) {
// no active session, no game
be.complete(false);
...

I think this is because the UserHolder for the vertx session does not get filled.

I worked around this issue by using be.socket().webSession().data().get(Pac4jConstants.USER_PROFILE) to get the Pac4j profile instead of using be.socket().webUser()

Unfortunately this issue breaks the vertx-web documentation when using Pac4jAuthProvider.

Retire UrlBuildingTest

This is a throwback to the vertx-oauth2 implementation. Not required when using Pac4j

IndirectAuthenticationFlow

Separate out saving of requested URL and redirect into separate methods, as per the play implementation, this enables overriding in subclasses and therefore the ability to alter the behaviour.

Modify vertx-pac4j pattern to match latest play-pac4j and j2e-pac4j implementations

Now we've moved to a more standard pac4j framework implementation for vert.x, bring the implementation up to date with the latest ones implemented for play and j2e which were the model for what's been done so far but have both progressed further while the move to the latest vert.x implementation was in progress.

Clients with isDirectRedirection returning false fail

The twitter client in vertx-pac4j-demo fails on the base "authenticate with..." link because the client is marked as "isDirectRedirection false" which in turn means that a 302 is returned and not properly handled by DefaultHttpActionAdapter (where isDirectRedirection returns true, this is handled correctly).

It looks like a straightforward fix, but raising an issue to ensure that an automated test is added to cover this scenario to prevent future regressions when modifying the vertx implementation

Direct client example

I configured my client on the OpenID Connect provider as bearer only but the sample app still tries to redirect.

Is there any configuration I need to specify in the sample application to support direct client?

Don't deploy PR on Sonatype

Upgrade pac4j version to 1.8.5

Investigate possible use of ProfileManager in Pac4j

At present the vert.x auth providers must be separate because they encapsulate dealing with the web session.

Investigate using the ProfileManager for this, and if possible, switch to its use. This might mean that we can have a single Pac4jAuthProvider for vert.x which simply rejects so that the underlying vertx-pac4j subsystem can take care of authentication fully. Pac4j offers the abstractions we want to use, so it makes
sense to make use of those.

Make public API use Config object for consistency with Pac3j idioms

Make the public Handler API (constructors of handlers) use the Pac4j Config object rather than the Clients object.

Make callback URL use the one specified in the Clients config

Make callback URL use the one specified in the Clients config. If none is supplied, default tp "/callback"

Rename HttpActionHandlers to Adapters (as per Play implementation, for example)

Tidy up rewritten vertx-pac4j codebase

Look for hardcoded strings which are really in Pac4jConstants and reference them
Add Javadocs to public methods for more clarity
Where there are magic strings not in Pac4jConstants, turn them into local constants.
Look for anything which doesn't seem smooth.

RequiresAuthenticationHandler (and derivatives) should not require an authorizer name to be set

Currently RequiresAuthenticationHandler and its derivatives mandate that an authorizer name be supplied on instantiation (via the Pac4jAuthHandlerOptions constructor). This is inconsistent with the play-pac4j implementation and more critically means that if an authorizer is required for any endpoint protected by Pac4j, an authorizer is required for all endpoints.

Modify the vertx-pac4j library so that authorizer name and client name are not necessary and default to empty string (as per play-pac4j implementation). Where authorizer name is not supplied, then authorization should succeed on that endpoint for all authenticated users.

Maven dependency in Readme file is wrong

GroupId should be org.pac4j.vertx instead of org.pac4j for 2.0.0-SNAPSHOT

https://github.com/pac4j/vertx-pac4j#dependencies-1

:)

Modify README section referring to AuthProviders

Now we've simplified to a single Pac4j auth provider, which delegates fully to Pac4j, update the section of the README which mentions the auth providers to only refer to the new unified one.

Fix CI build

Since switching to vert.x 3 support, the travis CI build is broken, due to lack of configuration for the maven deploy plugin.

Refit the original configuration for this plugin.

Migrate vertx-pac4j to use pac4j 1.8.0 release

Bring vertx-pac4j up to date to use the released version of pac4j 1.8.0

Example of vertx pac4j LDAP implementation

Hello all,

I have a LDAP server that I am trying to connect using a backend written in vertx. I am looking for an example / client program in vertx-pac4j which I can use to connect to the LDAP server. I browsed through the documentation available in Github but I was not able to locate the example.

May I know is there an example in the github to which I can refer. If not, can somebody kindly suggest any pointers / source code using which I can write the LDAP client program specific to vertx-pac4j.

Regards,
Krishnaprasad

Using CommonProfile with Google provider result in cast exception

Using CommonProfile profile = profileManager.get(true); on a Google profile for email attribute (profile.getEmail()) will fail because Google provider setup a Map for this and CommonProfile cast directly to String.

Version 2.0.2

Documentation

I'd like to have the documentation looks like the one from pac4j, with all the providers, the latest stable version...

Trying to build vertx-packj and test fails

Test set: org.pac4j.vertx.DefaultEventBusObjectConverterTest

Tests run: 2, Failures: 0, Errors: 2, Skipped: 0, Time elapsed: 0.329 sec <<< FAILURE!
testEncodeAndDecode(org.pac4j.vertx.DefaultEventBusObjectConverterTest) Time elapsed: 0.012 sec <<< ERROR!
java.lang.NoSuchMethodError: com.fasterxml.jackson.core.JsonFactory.requiresPropertyOrdering()Z

Test set: org.pac4j.vertx.DefaultEventBusObjectConverterTest

Tests run: 2, Failures: 0, Errors: 2, Skipped: 0, Time elapsed: 0.329 sec <<< FAILURE!
testEncodeAndDecode(org.pac4j.vertx.DefaultEventBusObjectConverterTest) Time elapsed: 0.012 sec <<< ERROR!
java.lang.NoSuchMethodError: com.fasterxml.jackson.core.JsonFactory.requiresPropertyOrdering()Z
at com.fasterxml.jackson.databind.ObjectMapper.(ObjectMapper.java:472)
at com.fasterxml.jackson.databind.ObjectMapper.(ObjectMapper.java:391)
at org.pac4j.vertx.DefaultEventBusObjectConverter.(DefaultEventBusObjectConverter.java:58)
at org.pac4j.vertx.DefaultEventBusObjectConverterTest.(DefaultEventBusObjectConverterTest.java:20)
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
at java.lang.reflect.Constructor.newInstance(Constructor.java:408)
at org.junit.runners.BlockJUnit4ClassRunner.createTest(BlockJUnit4ClassRunner.java:195)
at org.junit.runners.BlockJUnit4ClassRunner$1.runReflectiveCall(BlockJUnit4ClassRunner.java:244)
at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)
at org.junit.runners.BlockJUnit4ClassRunner.methodBlock(BlockJUnit4ClassRunner.java:241)
at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:70)
at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:50)
at org.junit.runners.ParentRunner$3.run(ParentRunner.java:238)
at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:63)
at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:236)
at org.junit.runners.ParentRunner.access$000(ParentRunner.java:53)
at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:229)
at org.junit.runners.ParentRunner.run(ParentRunner.java:309)
at org.apache.maven.surefire.junit4.JUnit4Provider.execute(JUnit4Provider.java:252)
at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:141)
at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:112)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:483)
at org.apache.maven.surefire.util.ReflectionUtils.invokeMethodWithArray(ReflectionUtils.java:189)
at org.apache.maven.surefire.booter.ProviderFactory$ProviderProxy.invoke(ProviderFactory.java:165)
at org.apache.maven.surefire.booter.ProviderFactory.invokeProvider(ProviderFactory.java:85)
at org.apache.maven.surefire.booter.ForkedBooter.runSuitesInProcess(ForkedBooter.java:115)
at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:75)

Not very serious but maybe I have some version conflict (new version of something)

Direct authentication flow - check that null profile is handled correctly

Ensure (including an integration test) that getting a null profile/credentials from the client is handled correctly as an authentication failure and 401 response.

Multiple auth mechanisms

Hi,

I try to implement multiple auth mechanisms with form and oauth for now but I can't figure out hox to to do that.

Here's my pseudo implementation:
final FormClient formClient = new FormClient("http://localhost:8080/auth/", new FormAuthenticator());
final TwitterClient twitterClient = new TwitterClient("twId", "twSecret");

final Clients clients = new Clients("http://localhost:8080/callback", twitterClient, formClient);
final Config config = new Config(clients);

CallbackHandler callbackHandler = new CallbackHandler(vertx, config);
router.get("/callback").handler(callbackHandler);
router.post("/callback").handler(BodyHandler.create().setMergeFormAttributes(true));
router.post("/callback").handler(callbackHandler);
Pac4jAuthHandlerOptions options = new Pac4jAuthHandlerOptions().withClientName("twitter");
router.get("/protected/*").handler(new RequiresAuthenticationHandler(vertx, config, (Pac4jAuthProvider) authProvider, options));

the endpoint for the form longin is given threw with constructor, but how to setup an endpoint to tell I want to be logged in with Twitter ?

Thanks for your help.

CallbackHandler: Extract the default URL in a separate method

This code is the code in question:-

public static String defaultUrl(final String url, final String defaultUrl) {

• String redirectUrl = defaultUrl;
• if (url != null && !"".equals(url)) {

•  redirectUrl = url;
  

• }
• logger.debug("defaultUrl : {}", redirectUrl);
• return redirectUrl;
• vertx.executeBlocking(future -> {

•  final CommonProfile profile = (CommonProfile) client.getUserProfile(credentials, webContext);
  

•  future.complete(profile);
  

• }, result -> {

•  if (result.succeeded()) {
  

•    Optional.ofNullable(result.result()).ifPresent(commonProfile -> {
  

DefaultHttpActionAdapter should handle failure scenarios (specifically 401/403) by failing the RoutingContext

Currently the DefaultHttpActionAdapter for vert.x handles the authentication/authorization failure scenarios incorrectly from a vert.x point of view. Right now, we set the status code, write out a default response body (which noone is likely to want to use) and end the response normally.

This essentially makes it impossible for someone using vertx-pac4j to customise those error responses, meaning that the default response bodies will always be received. The correct approach from a vert.x idiom would be to add a failure handler to all routes which checks the status code and delivers an appropriate (in the context of the application) response to the client. However, because we end the response normally, no failure handler would be called.

Therefore for failure, we should ultimately call RoutingContext::Fail (which requires a modification to VertxWebContext to expose a fail method wrapping RoutingContext::Fail) which will trigger the failure handler with the relevant status code, and then the vertx-pac4j user should provide a failure handler which delivers appropriate content for 401/403 failures (and any other failure scenarios for which they wish to deliver a response body).

Create LogoutHandler

We need to be able to define a logout handler so that a "logout" link can be offered.

This should clear out any session information regarding the current user profile (in the case of our vertx and pac4j infrastructure, this entails removal of the user profile held in the session for the vert.x infrastructure such as UserSessionHandler) and the pac4j user profile, also held in the session.

Remove allowDynamicClientSelection

Remove allowDynamicClientSelection - this will be removed from other implementations

When available use new components for finding correct client and auth check

Jérôme is adding new components for the above purpose, once they're available use them in the vert.x-pac4j implementation

CallbackHandler throwing RuntimeException when it should throw a TechnicalException

event.fail(new RuntimeException("Failed to retrieve user profile")); needs to be changed

Migrate authorization to use exclusively Pac4j authorization

At the moment the post-authentication authorization follows vert.x semantics. Provide the option of using configured Pac4j authorizer(s) for the approach (by overriding the authorise method on the handler).

Suggest the choice of which approach to use (i.e. vert.x restricted method or more open Pac4j config approach) is offered as one of the options for the handler, the reason being that those who want to retain a pure vert.x idiom don't have to learn about authorization in Pac4j, those who would rather use the Pac4j versatility can do so easily.