Configuration

Introduction

This section will show you how to enable PicketBox in web applications using the PicketBox HTTP extension.

You'll notice that some of the configuration is done by the same way when using PicketBox. That said, is very important that you are already familiar with the basic concepts and the way it works.

To enable your application with PicketBox only a few steps are required:

Configure some Maven dependencies, if you're using Maven in your project.
Configure a specific servlet filter in your web.xml.
Configure which authentication scheme do you want use: FORM, DIGEST, BASIC or CLIENT_CERT.
Provide a configuration builder that will be used to configure and starat the PicketBox Manager.

The PicketBox HTTP extension provides some additional configuration when building the PicketBox configuration (eg.: web resources protection). That will be discussed in the next sections.

Maven Dependencies

<dependency>
    <groupId>org.picketbox</groupId>
    <artifactId>picketbox-http</artifactId>
    <version>${picketbox.version}</version>
</dependency>

Security Filter

To enable your web application with PicketBox you should first configure a specific servlet filter. This is done by adding the following configuration to your application's web.xml file:

<filter>
    <filter-name>PicketBox Security Filter</filter-name>
    <filter-class>org.picketbox.http.filters.DelegatingSecurityFilter</filter-class>
</filter>

<!-- Defines which resources should be protected by the PicketBox Security Filter. In this case all resources are processed by the filter. -->
<filter-mapping>
    <filter-name>PicketBox Delegating Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Choosing a HTTP Authentication Scheme

The next step is define the authentication scheme/mechanism that you want to use. You can choose between FORM, BASIC, DIGEST AND CLIENT_CERT authentication:

<context-param>
    <param-name>org.picketbox.authentication</param-name>
    <param-value>FORM|BASIC|DIGEST|CLIENT_CERT</param-value>
</context-param>

If you do not explicit define one, it will be used HTTP FORM authentication.

Providing the PicketBox configuration

Some times you need to have more control about how the configuration is built. For that you can use the org.picketbox.http.config.ConfigurationBuilderProvider interface to create your own configuration.

Configuring PicketBox using the configuration provider

public class CustomConfigurationPovider implements ConfigurationBuilderProvider {

    @Override
    public HTTPConfigurationBuilder getBuilder(ServletContext servletcontext) {
        HTTPConfigurationBuilder configurationBuilder = new HTTPConfigurationBuilder();

        // protected resources configuration
        configurationBuilder.protectedResource()
                // unprotected resource. Usually this will be your application's static resources like CSS, JS, etc.
                .resource("/resources/*", ProtectedResourceConstraint.NOT_PROTECTED)

                // the login page is marked as not protected.
                .resource("/login.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // the register page is marked as not protected.
                .resource("/signup.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // the register page is marked as not protected.
                .resource("/signup", ProtectedResourceConstraint.NOT_PROTECTED)

                // the error page is marked as not protected.
                .resource("/error.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // protected all resources. They will be available only for users with a role named 'guest'.
                .resource("/*", "guest");

        return configurationBuilder;
    }

Check the URL Security documentation for more information about how resources are protected.

To use your own configuration add the following configuration to your application's web.xml file:

Configuring the configuration provider

<context-param>
    <param-name>org.picketbox.configuration.provider</param-name>
    <param-value>com.mycompany.web.security.config.CustomConfigurationProvider</param-value>
</context-param>

Take a look at the Configuration API for more information.

Servlet Context Parameters

You can configure some of the PicketBox aspects like authentication, authorization and identity management using context parameters. The table bellow summarizes all supported parameters:

Name	Description	Values
org.picketbox.authentication	Defines the authentication mechanism to be used.	Possible values are: FORM, DIGEST, BASIC, CLIENT_CERT. Defaults to *FORM*.
org.picketbox.authorization.manager	Configures how resources should be protected by using a specific Authorization Manager implementation.	Possible values are: drools and simple. If you provide a full qualified class name it will be used to create a new instance.
org.picketbox.configuration.provider	Defines a custom ConfigurationBuilderProvider that will be used to construct the configuration.	Full qualified class name.
org.picketbox.http.session.user.attribute	Defines the HttpSession attribute name where the authenticated user context will be stored.	Any valid string.

HTTP Configuration Builder (Configuration API Extension)

PicketBox HTTP provides some extensions to the Configuration API to allow additional and specific configuration for web applications.

When using PicketBox HTTP you should always use the org.picketbox.http.config.HTTPConfigurationBuilder.

Examples

You can always look at our examples to get familiar with the configuration. They are useful to help you quickly enable PicketBox in your application.

Please, look at the following github repository:

https://github.com/picketbox/picketbox-quickstarts

Check the README.md file for more information about building and deploying the examples.