Chapter 15. Java Authorization Contract for Containers (JACC)
15.1. About Java Authorization Contract for Containers (JACC)
Java Authorization Contract for Containers (JACC) is a standard which defines a contract between containers and authorization service providers, which results in the implementation of providers for use by containers. It is defined in JSR-115 of the Java Community Process. For details about the specifications, see Java™ Authorization Contract for Containers.
JBoss EAP implements support for JACC within the security functionality of the
15.2. Configure Java Authorization Contract for Containers (JACC) Security
You can configure Java Authorization Contract for Containers (JACC) by configuring your security domain with the correct module, and then modifying your
jboss-web.xml to include the required parameters.
Add JACC Support to the Security Domain
To add JACC support to the security domain, add the
JACC authorization policy to the authorization stack of the security domain, with the
required flag set. The following is an example of a security domain with JACC support. However, it is recommended to configure the security domain from the management console or the management CLI, rather than directly modifying the XML.
Example: Security Domain with JACC Support
<security-domain name="jacc" cache-type="default"> <authentication> <login-module code="UsersRoles" flag="required"> </login-module> </authentication> <authorization> <policy-module code="JACC" flag="required"/> </authorization> </security-domain>
Configure a Web Application to Use JACC
jboss-web.xml file is located in the
WEB-INF/ directory of your deployment, and contains overrides and additional JBoss-specific configuration for the web container. To use your JACC-enabled security domain, you need to include the
<security-domain> element, and also set the
<use-jboss-authorization> element to
true. The following XML is configured to use the JACC security domain above.
Example: Utilize the JACC Security Domain
<jboss-web> <security-domain>jacc</security-domain> <use-jboss-authorization>true</use-jboss-authorization> </jboss-web>
Configure an EJB Application to Use JACC
Configuring EJBs to use a security domain and to use JACC differs from web applications. For an EJB, you can declare method permissions on a method or group of methods, in the
ejb-jar.xml descriptor. Within the
<ejb-jar> element, any child
<method-permission> elements contain information about JACC roles. See the example configuration below for details. The
EJBMethodPermission class is part of the Java EE 7 API, and is documented at http://docs.oracle.com/javaee/7/api/javax/security/jacc/EJBMethodPermission.html.
Example: JACC Method Permissions in an EJB
<ejb-jar> <assembly-descriptor> <method-permission> <description>The employee and temp-employee roles can access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission> </assembly-descriptor> </ejb-jar>
You can also constrain the authentication and authorization mechanisms for an EJB by using a security domain, just as you can do for a web application. Security domains are declared in the
jboss-ejb3.xml descriptor, in the
<security> child element. In addition to the security domain, you can also specify the
<run-as-principal>, which changes the principal that the EJB runs as.
Example: Security Domain Declaration in an EJB
<ejb-jar> <assembly-descriptor> <security> <ejb-name>*</ejb-name> <security-domain>myDomain</security-domain> <run-as-principal>myPrincipal</run-as-principal> </security> </assembly-descriptor> </ejb-jar>
Enabling JACC Using the
Disable JACC in the Legacy Security Subsystem
By default, the application server uses the legacy
security subsystem to configure the JACC policy provider and factory. The default configuration maps to implementations from PicketBox.
In order to use Elytron to manage JACC configuration, or any other policy you want to install to the application server, you must first disable JACC in the legacy
security subsystem. For that, you can use the following management CLI command:
Failure to do so can result in the following error in the server log:
MSC000004: Failure during stop of service org.wildfly.security.policy: java.lang.StackOverflowError.
Define a JACC Policy Provider
elytron subsystem provides a built-in policy provider based on JACC specification. To create the policy provider you can execute the following management CLI command:
Enable JACC to a Web Deployment
Once a JACC policy provider is defined, you can enable JACC for web deployments by executing the following command:
The command above defines a default security domain for applications, if none is provided in the
jboss-web.xml file. In case you already have a
application-security-domain defined and just want to enable JACC you can execute the following command:
Enable JACC to an EJB Deployment
Once a JACC policy provider is defined, you can enable JACC for EJB deployments by executing the following command:
The command above defines a default security domain for EJBs. In case you already have a
application-security-domain defined and just want to enable JACC you can execute a command as follows:
Creating a Custom Elytron Policy Provider
A custom policy provider is used when you need a custom
java.security.Policy, like when you want to integrate with some external authorization service in order to check permissions. To create a custom policy provider, you will need to implement the
java.security.Policy, create and plug in a custom module with the implementation and use the implementation from the module in the
For more information, see the Policy Provider Properties.
In most cases, you can use the JACC policy provider as it is expected to be part of any Java EE compliant application server.