This manual is a work in progress and is currently incomplete.
If you'd like to help improve it, and we hope you do, please see the README.

20 pac4j

The ratpack-pac4j extension provides authentication and authorization support via integration with pac4j.

The pac4j library is a security engine which abstracts over different authentication protocols such as OAuth, CAS, OpenID (Connect), SAML, Google App Engine and HTTP (form and basic auth) as well as custom authentication mechanisms (e.g. database backed). It also supports various authorization mechanisms: roles / permissions checks, CSRF token, security headers, etc.

The RatpackPac4j class provides the entirety of the integration. This class provides static methods that provide handler implementations along with other finer grained constructs for use within your handler implementations. The API reference for this class provides usage examples of each of the methods.

The ratpack-pac4j library requires the ratpack-session library, and use of the associated SessionModule.

20.1 Usage

Each authentication mechanism in pac4j is defined as a “client”. For example, pac4j provides the FacebookClient type that implements the Facebook authentication protocol. Please see pac4j’s documentation on clients for more information.

The RatpackPac4j.authenticator(Client<?, ?>... clients) method provides a handler that defines the clients for an application. It must be placed early in the handler chain as it makes the configured client instance(s) available to the downstream handlers that require auth operations.

There are two ways to initiate auth:

Note that pac4j provides many Authorizer implementations out of the box.

These methods take a client type as an argument. It is required that a client instance of the given type was specified via the, upstream, RatpackPac4j.authenticator(Client<?, ?>... clients) handler.

The RatpackPac4j.userProfile() method can be used to obtain the user profile if the user is logged in, without requiring authentication.

20.2 Session Usage

As previously mentioned, using ratpack-pac4j requires session support via ratpack-session. When authenticated, the user’s profile is stored in the session. Therefore, terminating the session will effectively log the user out.

20.3 Demo application

Please see the ratpack-pac4j-demo application for a complete application that demonstrates how to use pac4j with Ratpack.