hendriklanghammer / vertx-pac4j

Security library for Vert.x 3

Pac4j module for Vert.x

vertx-pac4j is a Profile & Authentication Client, it's a general security library to authenticate users, get their profiles, manage their authorizations in order to secure Vert.x web applications.

Vert.x version compatibility

For vert.x 2 and previous use vertx-pac4j 1.1.x - this codebase can be found at 1.1.x

For vert.x 3 and subsequent use vertx-pac4j 2.0.x. Please note that vertx-pac4j 2.0.x is currently work in progress and the codebase should be treated with caution at present. In addition, many parts of this README are yet to be updated for vert.x 3 and vertx-pac4j 2.0.x. This will be updated over the coming days

Supported authentication methods

Although pac4j historically targets external authentication protocols, it supports direct authentication methods as well. See the authentication flows.

External/stateful authentication protocols

1. From the client application, save the requested url and redirect the user to the identity provider for authentication (HTTP 302)
2. After a successful authentication, redirect back the user from the identity provider to the client application (HTTP 302) and get the user credentials
3. With these credentials, get the profile of the authenticated user (direct call from the client application to the identity provider)
4. Redirect the user to the originally requested url and allow or disallow the access.

Supported protocols are:

1. OAuth (1.0 & 2.0)
2. CAS (1.0, 2.0, SAML, logout & proxy)
3. HTTP (form & basic auth authentications)
4. OpenID
5. SAML (2.0)
6. Google App Engine UserService
7. OpenID Connect 1.0

Stateless authentication protocols (REST operations)

The current HTTP request contains the required credentials to validate the user identity and retrieve his profile. It works from a basic authentication.

It relies on specific Authenticator to validate user credentials and ProfileCreator to create user profiles.

Authentication flows

Providers supported

Provider	Protocol	Maven dependency	Client class	Profile class
CAS server	CAS	pac4j-cas	CasClient & CasProxyReceptor	CasProfile
CAS server using OAuth Wrapper	OAuth 2.0	pac4j-oauth	CasOAuthWrapperClient	CasOAuthWrapperProfile
DropBox	OAuth 1.0	pac4j-oauth	DropBoxClient	DropBoxProfile
Facebook	OAuth 2.0	pac4j-oauth	FacebookClient	FacebookProfile
GitHub	OAuth 2.0	pac4j-oauth	GitHubClient	GitHubProfile
Google	OAuth 2.0	pac4j-oauth	Google2Client	Google2Profile
LinkedIn	OAuth 1.0 & 2.0	pac4j-oauth	LinkedInClient & LinkedIn2Client	LinkedInProfile & LinkedIn2Profile
Twitter	OAuth 1.0	pac4j-oauth	TwitterClient	TwitterProfile
Windows Live	OAuth 2.0	pac4j-oauth	WindowsLiveClient	WindowsLiveProfile
WordPress	OAuth 2.0	pac4j-oauth	WordPressClient	WordPressProfile
Yahoo	OAuth 1.0	pac4j-oauth	YahooClient	YahooProfile
PayPal	OAuth 2.0	pac4j-oauth	PayPalClient	PayPalProfile
Vk	OAuth 2.0	pac4j-oauth	VkClient	VkProfile
Foursquare	OAuth 2.0	pac4j-oauth	FoursquareClient	FoursquareProfile
Bitbucket	OAuth 1.0	pac4j-oauth	BitbucketClient	BitbucketProfile
ORCiD	OAuth 2.0	pac4j-oauth	OrcidClient	OrcidProfile
Strava	OAuth 2.0	pac4j-oauth	StravaClient	StravaProfile
Web sites with basic auth authentication	HTTP	pac4j-http	BasicAuthClient	HttpProfile
Web sites with form authentication	HTTP	pac4j-http	FormClient	HttpProfile
Google - Deprecated	OpenID	pac4j-openid	GoogleOpenIdClient	GoogleOpenIdProfile
Yahoo	OpenID	pac4j-openid	YahooOpenIdClient	YahooOpenIdProfile
SAML Identity Provider	SAML 2.0	pac4j-saml	Saml2Client	Saml2Profile
Google App Engine User Service	Gae User Service Mechanism	pac4j-gae	GaeUserServiceClient	GaeUserServiceProfile
OpenID Connect Provider	OpenID Connect 1.0	pac4j-oidc	OidcClient	OidcProfile

Technical description

vertx-pac4j consists of a single maven module vertx-pac4j which you should import as a maven dependency. It is designed specifically for use in the vertx-web framework which sits atop vert.x

Auth providers

Auth handlers

The stateful provider/handler combination requires a session. This can be achieved using a vertx-web SessionHandler.

Dependencies

When using stateful session handling, you need to use a vertx-web SessionHandler (and to enable this you need to use a Cookie handler, to enable session cookies)

Configuration

At present the file-based configuration option is deprecated in favour of type-safe code-based assembly of a Clients object.

Redirect

Redirect Urls

Authenticate

Serialization Methods

For distributed session management to work correctly, we serialize all Pac4j objects stored in the session into vertx JsonObjects. We now operate a type-safe "SessionAttributes" class, which can hold a UserProfile and a set of custom attributes.

By default, a serialization based on Jackson is used (org.pac4j.vertx.DefaultEventBusObjectConverter).

Dependencies

Import the following dependency in your Vertx project:

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>vertx-pac4j</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>

Main Classes

• org.pac4j.vertx.impl.Pac4jAuthProvider implementation of the vert.x AuthProvider interface for Pac4j handling. It simply delegates everything to Pac4j
• org.pac4j.vertx.handler.impl.RequiresAuthenticationHandler this class implements the vert.x AuthHandler interface for Pac4j authentication.
• org.pac4j.vertx.handler.impl.CallbackDeployingPac4jAuthHandler this class extends RequiresAuthenticationHandler to auto-deploy a callback handler rather than writing additional code to do so
• org.pac4j.vertx.flow.DirectClientAuthenticationFlow abstracts the authentication flow for direct clients
• org.pac4j.vertx.flow.IndirectClientAuthenticationFlow abstracts the beginning of the authentication flow for indirect clients
• org.pac4j.vertx.handler.impl.CallbackHandler this class finishes the authentication process if stateful, by validating the authentication information (e.g. a form with username and password) and storing the user profile in session
• org.pac4j.vertx.handler.impl.LogoutHandler this class removes the user profile from the session

The last three classes inherit from the org.pac4j.vertx.handler.impl.BasePac4jAuthHandler which uses a modified version of the session-manager helper from campudus.

Integration example

Stateful application

Please note that this is subject to change - the vertx-pac4j code is still evolving

Define the application verticle:

public class DemoServerVerticle extends Verticle {
@Override
public void start() {

    Router router = Router.router(vertx);
    
    // Set up session handling in the vertx-web router
    // Note that if you want to use clustered session storage you need to use a ClusteredSessionStore
    // The default json encoder/decoder handles clustered session storage fine
    // It is necessary to use the same session store in the session handler and the auth provider
    SessionStore sessionStore = LocalSessionStore.create(vertx); 
    router.route().handler(CookieHandler.create());
    router.route().handler(SessionHandler.create(sessionStore).setSessionCookieName("oAuth2Consumer.session"));
    
    // Construct pac4j Clients object and wrap in a Config
    Clients clients = ...; 
    Config config = ...;

    DefaultJsonConverter ebConverter = new DefaultJsonConverter();
    Pac4jAuthProvider authProvider = new Pac4jAuthProvider();
    Pac4jAuthHandlerOptions options = new Pac4jAuthHandlerOptions(TEST_CLIENT_NAME);
    // The next line could be separated into deployment of a separate RequiresAuthenticationHandler
    // and CallbackHandler if preferred. 
    CallbackDeployingPac4jAuthHandler authHandler = CallbackDeployingPac4jAuthHandler(vertx, config, router, authProvider, options);
    // Note that use of a stateful handler automatically configures the callback url
    router.route(HttpMethod.GET, "/facebook/index.html").handler(authHandler);
    // index page
    router.route(HttpMethod.GET, "/").handler(new Handler());
            
    vertx.createHttpServer()
        .requestHandler(router::accept)
        .listen(8080, "localhost");
    
}}

Please note that in the above code it is perfectly legitimate to use a RequiresAuthenticationHandler and deploy a CallbackHandler separately. The CallbackDeployingPac4jAuthHandler is a convenience class which automatically deploys a CallbackHandler at the callback url specified in the config supplied to it. It therefore saves a small amount of code when using a single callback handler, but could prove useful for simple indirect authentication configurations. If you intend to use the same callback handler for multiple paths with different RequiresAuthenticationHandler, it would make sense to explicitly deploy the CallbackHandler.

Stateless application

Define the application verticle:

public class DemoRestServerVerticle extends Verticle {

@Override
public void start() {

    Router router = Router.router(vertx);
    // Construct pac4j Clients object and wrap in a Config
    Clients clients = ...; 
    Config config = ...;

    final Pac4jAuthProvider authProvider = new Pac4jAuthProvider();
    final Pac4jAuthHandlerOptions options = new Pac4jAuthHandlerOptions("BasicAuthClient");
    final RequiresAuthenticationHandler handler =  new RequiresAuthenticationHandler(vertx, config), authProvider, options);
    router.route(HttpMethod.GET, "/").handler(handler);

    RouteMatcher rm = new RouteMatcher();

    vertx.createHttpServer()
        .requestHandler(router::accept)
        .listen(8080, "localhost");

}

Demo

A demo with Facebook, Twitter, CAS, form authentication and basic auth authentication providers will shortly be available with vertx-pac4j-demo.

Versions

The current version 2.0.0-SNAPSHOT is under development. It's available on the Sonatype snapshots repository as a Maven dependency:

The latest release of the vertx-pac4j project is the 1.1.0 version:

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>vertx-pac4j</artifactId>
    <version>1.1.0</version>
</dependency>

See the release notes.

Contact

If you have any question, please use the following mailing lists:

• pac4j users
• pac4j developers