PicketBox is the legacy security framework for JBoss / WildFly applications. This security framework is now deprecated on newer versions of WildFly and it’s therefore recommended to switch to Elytron.
Within the Security section of this site, you will find introduction and advanced tutorials to get started with Elytron.
Overview of PicketBox Security Framework
Security is a fundamental part of any enterprise application .The JBoss component framework that handles security is the JBossSX extension framework. The JBossSX security extension provides support for both the role-based declarative J2EE security model as well as integration of custom security via a security proxy layer.
The default implementation of the declarative security model is based on Java Authentication and Authorization Service (JAAS) login modules and subjects.
JAAS delivers a framework for providing authentication and authorization for all the Java applications.
Authentication is a mechanism to verify the client
Authorization is a mechanism to ensure that the client has the permissions required to access a secured resource.
The four steps to enable JAAS:
1. Identify which resources needs to be secured: a Web Application ? an EJB ?
2. Identify a suitable Security Provider. In the case of JBOSS, the security is provided by the JBOSS security manager.
3. Use a Security Implementation to secure the identified resources.
4. Make the clients of the secured resources aware of the security implementation and usage mechanisms.
Coding a LoginModule
WildFly / JBoss AS provides pluggable security managers. The Web and the EJB Containers use the security managers to perform authentication and authorization. The JAAS-based security manager is the default security manager provided with JBOSS
The LoginModule is the module is in charge to provide the security implementation that authenticates and authorizes the clients. A typical implementation involves validating the username/password combination
Out of the box the following Login Modules are available:
- UserRolesLoginModule: This is the default login module : it reads the username, password and role information from files that are packaged with the applications.
- DatabaseServerLoginModule: This module reads the username, password and role information from the tables in a database. The database is accessed using JDBC and the JDBC driver needs to be available in the application classpath.
- LDAPLoginModule: This module requires the username and password. This is used to connect to LDAP as a means of verification. If successful, the roles are based on the group memberships of the user. This module is not very configurable as it doesn’t expose enough configuration options to work with all LDAPs.
- BaseCertLoginModule: This module uses client certificates to perform authentication. It cannot provide role information. This is typically used in conjunction with one of the other LoginModules to obtain the role memberships
Securing a Web Application with UserRolesLoginModule
In this first tutorial we’ll explore how to secure a Web application and an EJB application using the UserRolesLoginModule
Step 1: Add the Security Policy to your conf/login-config.xml
<application-policy name = "jboss-secure"> <authentication> <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag = "required"> <module-option name="usersProperties">users.properties</module-option> <module-option name="rolesProperties">roles.properties</module-option> </login-module> </authentication> </application-policy>
This tells JBoss to associate the UserRolesLoginModules for the policy named “jboss-secure”.
Note: Security domains are created on demand. Putting an entry in login config.xml doesn’t have any effect until an application tries to use it.
Step 2: Add security constraints to web.xml
<security-constraint> <web-resource-collection> <web-resource-name>Restricted to Secure role</web-resource-name> <description>Declarative security</description> <url-pattern>/*</url-pattern> <http-method>HEAD</http-method> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>Administrator</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>JBoss Secured Realm</realm-name> </login-config> <security-role> <role-name>Administrator</role-name> </security-role>
In this sample all resources of the web application are restricted to the “Administrator” role. Now you need only
Step 3: Add security domain to your jboss-web.xml
<jboss-web> <security-domain>java:/jaas/jboss-secure</security-domain> </jboss-web>
Last configuration file is JBoss web’s deployment descriptors. This file is by default under the WEB-INF folder. To link to a specific security domain, you need to set the security-domain element to the JNDI name of the security domain to link to. Security domains are bound under java:/jaas in JNDI, so the todo domain would be java:/jaas/jboss-secure.
Step 4: Add users.properties and roles.properties
Usernames and passwords are stored in users.properties file (you can place it anywhere JBoss classloader can reach it for example under WEB-INF/classes)
A minimalist user.properties file can be:
The roles.properties associate the usernames to Security Roles.
A minimalist roles.properties file can be:
Securing an EJB Application
Securing the EJB tier is not much different: the server configuration stays the same, we need to group the EJB methods based on the roles that can access these methods.
Step 1: add <method-permission> tag in the ejb-jar.xml file.
<method-permission> <role-name>Administrator</role-name> <method> <ejb-name>SampleEJB</ejb-name> <method-name>securedMethod</method-name> </method> </method-permission> <method-permission> <unchecked/> <method> <ejb-name>SampleEJB</ejb-name> <method-name>unsecuredMethod</method-name> </method> </method-permission>
In the above example, the method “securedMethod” in the EJB “SampleEJB” is available only to the
client belonging to the “Secure” role. However, the method “unsecuredMethod” in the same bean is available to all the clients.
Step 2: Add security domain to your jboss.xml
During the application packaging, the administrator must choose the security domain used to protect
the application. This is exactly the same as for the web tier except that the EJB tier uses another d.descriptor file called jboss.xml.
<jboss> <security-domain>java:/jaas/jboss-secure</security-domain> </jboss>
Java 17 update
Please note that Java 17 (and newer version) removed the API from the java.security.acl package. The ‘legacy’ security framework (e.g. PicketBox) relies on the java.security.acl package, and therefore it is not compatible with a Java 17 runtime.
On the other hand, the Elytron security framework does not use the java.security.acl package and therefore will work fine on a Java 17 JVM.