Chapter 15. Jakarta Authorization
15.1. About Jakarta Authorization
Jakarta Authorization is a standard which defines a contract between containers and authorization service providers, which results in the implementation of providers for use by containers. For details about the specifications, see Jakarta Authorization specification.
JBoss EAP implements support for Jakarta Authorization within the security functionality of the security subsystem.
15.2. Configure Jakarta Authorization Security
You can configure Jakarta Authorization by configuring your security domain with the correct module, and then modifying your jboss-web.xml to include the required parameters.
Add Jakarta Authentication to the Security Domain
To add Jakarta Authorization support to the security domain, add the Jakarta Authorization 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 Jakarta Authorization 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 Jakarta Authentication
<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 Jakarta Authentication
The 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 Jakarta Authorization-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 Jakarta Authorization security domain above.
Example: Use the Jakarta Authentication Security Domain
<jboss-web>
<security-domain>jacc</security-domain>
<use-jboss-authorization>true</use-jboss-authorization>
</jboss-web>
Configure an Jakarta Enterprise Beans Application to Use Jakarta Authentication
Configuring Jakarta Enterprise Beans to use a security domain and to use Jakarta Authorization differs from web applications. For an Jakarta Enterprise Beans, 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 Jakarta Authorization roles. See the example configuration below for details. The EJBMethodPermission class is part of the Jakarta EE API, and is documented at Class EJBMethodPermission.
Example: Jakarta Authentication Method Permissions in an Jakarta Enterprise Beans
<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 Jakarta Enterprise Beans 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 Jakarta Enterprise Beans runs as.
Example: Security Domain Declaration in an Jakarta Enterprise Beans
<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 Jakarta Authorization Using the elytron Subsystem
Disable Jakarta Authentication in the Legacy Security Subsystem
By default, the application server uses the legacy security subsystem to configure the Jakarta Authorization policy provider and factory. The default configuration maps to implementations from PicketBox.
In order to use Elytron to manage Jakarta Authorization configuration, or any other policy you want to install to the application server, you must first disable Jakarta Authorization in the legacy security subsystem. For that, you can use the following management CLI command:
/subsystem=security:write-attribute(name=initialize-jacc, value=false)
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 Jakarta Authentication Policy Provider
The elytron subsystem provides a built-in policy provider based on Jakarta Authorization specification. To create the policy provider you can execute the following management CLI command:
/subsystem=elytron/policy=jacc:add(jacc-policy={})
reloadEnable Jakarta Authentication to a Web Deployment
Once a Jakarta Authorization policy provider is defined, you can enable Jakarta Authorization for web deployments by executing the following command:
/subsystem=undertow/application-security-domain=other:add(security-domain=ApplicationDomain,enable-jacc=true)
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 Jakarta Authorization you can execute the following command:
/subsystem=undertow/application-security-domain=my-security-domain:write-attribute(name=enable-jacc,value=true)
Enable Jakarta Authentication to an Jakarta Enterprise Beans Deployment
Once a Jakarta Authorization policy provider is defined, you can enable Jakarta Authorization for Jakarta Enterprise Beans deployments by executing the following command:
/subsystem=ejb3/application-security-domain=other:add(security-domain=ApplicationDomain,enable-jacc=true)
The command above defines a default security domain for Jakarta Enterprise Beans. In case you already have a application-security-domain defined and just want to enable Jakarta Authorization you can execute a command as follows:
/subsystem=ejb3/application-security-domain=my-security-domain:write-attribute(name=enable-jacc,value=true)
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 elytron subsystem.
/subsystem=elytron/policy=policy-provider-a:add(custom-policy={class-name=MyPolicyProviderA, module=x.y.z})For more information, see the Policy Provider Properties.
In most cases, you can use the Jakarta Authorization policy provider as it is expected to be part of any Jakarta EE compliant application server.
