12.2. Configuration

Prev
PicketLink Reference Documentation
Next

⁠12.2. Configuration

The configuration is based on which web resources or paths you want to protect. Paths always start with a slash and are relative to your application's context path. Examples of paths are:

/protected/*, defines all resources starting with /protected. eg.: /protected/admin
/protected, defines a single resource /protected
/*.jsf, defines all resources with a suffix .jsf
/home.jsf, defines a single resource /home.jsf

Once you define which paths you want to protect, you just need to provide the security policies you want to enforce for each of them. The security policies are related with the two major areas of application security: authentication and authorization.

Let's suppose you want to enforce FORM authentication to all your JSF pages and define for some of them which roles are allowed to access.

public class HttpSecurityConfiguration {

    public void configureHttpSecurity(@Observes SecurityConfigurationEvent event) {
        SecurityConfigurationBuilder builder = event.getBuilder();

        builder
            .http()
                .forPath("/*.jsf")
                    .authenticateWith()
                        .form()
                            .loginPage("/login.jsf")
                            .errorPage("/loginFailed.jsf")
                .forPath("/admin/*")
                    .authorizeWith()
                        .role("Administrator");
    }
}

You may notice that in the configuration above we're defining two path configurations. One more generic, covering all JSF pages and enforcing FORM authentication. The second, /admin/*, is enforcing RBAC(Role-Based Access Control) for a subset of paths starting with a specific pattern.

In this case, PicketLink will enforce FORM authentication to all your JSF pages but only allow access to the /admin/* pages if the authenticated user is granted with a Administrator role.

Simple isn't it ? The most important thing you should know is that all configuration is defined using an easy and fluent API provided by org.picketlink.config.http.HttpSecurityBuilder, retrieved when you invoke the http() method of org.picketlink.config.SecurityConfigurationBuilder. And also, that you must observe for the SecurityConfigurationEvent in order to obtain a reference to the HttpSecurityBuilder and start providing your security policies.

Report a bug

⁠12.2.1. Protecting Paths

As mentioned before, all configuration is based on the web resources or paths you want to protect. The HttpSecurityBuilder provides you a few methods to start protecting the paths of your application.

The most common way to configure a path is using the following method:

httpBuilder.forPath("/*.jsf")

It expects a string value starting with a slash and relative to your application's context path. PicketLink will try to match a incoming request to a specific path configuration using the value you provided to this method. You can provide this value using any pattern, such as those supported by the Java Servlet API specification. Keep in mind that depending on the paths you provided PicketLink will decide which requests should be handled or not.

The path is the main identifier of a HTTP resource. But you may want to handle different requests to the same path based on additional information such as the request method or headers. By default, PicketLink will match any request to a particular path regardless these additional information. But, if you want to configure a path with a specific method or header you can do so.

Let's assume you have a path /user/profile. And a configuration as follows:

httpBuilder
    .forPath("/user/profile")
        .authenticateWith()
            .form()
    .forPath("/user/profile")
        .withHeaders()
            .header("X-Requested-With", "XMLHttpRequest")
        .authenticateWith()
            basic()

This is a useful example about how to support different authentication mechanisms from a single path. In this case, PicketLink will identify the proper configuration for a specific path based on the existence of the X-Requested-With header. If this header is present, PicketLink will enforce BASIC authentication, otherwise FORM will be used.

The same applies for HTTP methods. You may distinguish requests for a specific path based on the method of a incoming request.

You may also tell PicketLink that a specific path should not be protected, for that you just need to:

httpBuilder
    .forPath("/unprotected/resource")
        .unprotected()

In this case, PicketLink will just allow any request to a specific resource without enforce any security policy.

The HttpSecurityBuilder also provides some additional methods to configure your paths, some of them we'll cover in more details on the next sections.

Report a bug