<dependency>
<groupId>org.picketbox</groupId>
<artifactId>picketbox-solder</artifactId>
<version>${picketbox.version}</version>
</dependency>
The PicketBox Solder provides an easy to use API and non-intrusive integration to applications using CDI.
It is based on Solder to create a transparent security layer for applications that need to provide for their users:
Authentication using any of the Authentication Schemes provided by PicketBox (FORM, BASIC, DIGEST, CLIENT_CERT or your own implementation)
Authorization using any of the built-in Authorization Managers provided by PicketBox. Eg.: PicketBox Drools Authorization
To use PicketBox in your CDI application you need to follow these steps:
Configure PicketBox Solder dependency in your pom.xml
Create a META-INF/seam-beans.xml file where all the PicketBox configuration will be defined
If you want to use FORM authentication, you also need to create a login page.
To use PicketBox in your CDI application you need to add PicketBox Solder as a dependency in your project. If you are using Maven, you can use the following configuration:
<dependency>
<groupId>org.picketbox</groupId>
<artifactId>picketbox-solder</artifactId>
<version>${picketbox.version}</version>
</dependency>
After configuring the dependencies you need to create a Solder XML Configuration file in your classpath META-INF/seam-beans.xml. If you are using Maven this file is usually located at your src/main/resources directory.
<beans
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:s="urn:java:ee"
xmlns:mail="urn:java:org.jboss.seam.mail.core"
xmlns:pb="urn:java:org.picketbox.http.authentication"
xmlns:pbauthmgr="urn:java:org.picketbox.core.authentication.manager"
xmlns:pbs="urn:java:org.picketbox.solder.authentication"
xmlns:pbauthzd="urn:java:org.picketbox.drools.authorization"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://docs.jboss.org/cdi/beans_1_0.xsd">
<!-- Configures a HTTPFormAuthentication bean -->
<pb:HTTPFormAuthentication>
<s:replaces/>
<pbs:AuthenticationScheme/>
</pb:HTTPFormAuthentication>
<!-- Configures a properties-based Authentication Manager -->
<pbauthmgr:PropertiesFileBasedAuthenticationManager/>
<!-- Configures the PicketBox Drools Authorization Manager -->
<pbauthzd:PicketBoxDroolsAuthorizationManager />
</beans>
During the authentication process we need to retrieve users credentials in order to authenticate them. When using PicketBox, this is achieved using an Authentication Manager.
PicketBox provides some built-in implementations of Authentication Managers for integration with different identity stores like LDAP, database, properties files and so on. You can even write your own implementation.
In the previous configuration we defined an properties-based Authentication Manager.
<!-- Configure a properties-based Authentication Manager --> <pbauthmgr:PropertiesFileBasedAuthenticationManager/>
The configuration above tells PicketBox that users credentials should be retrieved using a properties file called users.properties located in your classpath. If you are using Maven this file is usually located at your src/main/resources directory. The example bellow shows how this file looks like:
admin=admin guest=guest
If you want to protect your application's resources from unauthorized access you can also configure an Authorization Manager. It provides a specific implementations to authorize users using some mechanism, like for example using Drools rules.
In the previous configuration we defined an Drools-based Authorization Manager. This is a built-in Authorization Manager implementation provided by PicketBox Drools module.
<!-- Configures the PicketBox Drools Authorization Manager --> <pbauthzd:PicketBoxDroolsAuthorizationManager />
The configuration above tells PicketBox to authorize users using some Drools rules defined in a file called authorization.drl located in your classpath. If you are using Maven this file is usually located at your src/main/resources directory.
As we are using FORM authentication as described in the previous sections, we need to create a login page for users provide their credentials. By default, PicketBox uses a file named login.jsp that must be located at your application's root path.
This page must define a JEE compliant authentication HTML form like the one bellow:
<form id="authenticationForm" name="authenticationForm" method="POST" action="j_security_check" enctype="application/x-www-form-urlencoded">
<div style="margin-left: 15px;">
<p>
<label for="username"> Username</label><br />
<input id="username" type="text" name="j_username" size="20" />
</p>
<p>
<label for="password"> Password</label><br />
<input id="password" type="password" name="j_password" value="" size="20" />
</p>
<center>
<input id="submit" type="submit" name="submit" value="Login" />
</center>
</div>
</form>
After configuring your application as described above and having everything working fine, you can now use some beans instances produced by the PicketBox Solder integration in order to get the authenticated user, the PicketBoxManager instance and so on.
After a successful authentication users will be represented and referenced inside your application as org.picketbox.core.PicketBoxSubject instances, from where you can retrieve information about your authenticated users.
When using PicketBox Solder you can always get a reference for a PicketBoxSubject instance by injecting it in any bean definition:
@Inject private PicketBoxSubject authenticatedUser;
You can also reference the authenticated user instance from any JSF page using:
Hi #{authenticatedUser.user.name} !
As you can see, the authenticated user instance can be always referenced in EL using the authenticatedUser name.
The PicketBoxManager is a Security Facade from which all security operations (authorization, authentication, etc) are invoked. Althought is not recommended, you can use it anywhere in your application. Just define a injection point like the one bellow:
@Inject private PicketBoxManager picketBoxManager;