Migration Guide

A major upgrade or migration is necessary when an application is moved from one major release to another, such as from JBoss EAP 7 to JBoss EAP 8.0. Applications that comply with the Jakarta EE 8 specification, contain proprietary code, or use deprecated APIs might require modifications to their application code to run on JBoss EAP 8.0. The introduction of Jakarta EE 10 involves changes in Java package names and other aspects that require adjustments to Jakarta EE application code for compatibility with JBoss EAP 8.0. Additionally, the server configuration has changed in JBoss EAP 8.0 and requires migration. This type of migration is addressed in this guide.

Minor Updates in JBoss EAP are point releases that provide bug fixes, security fixes, and new features. The changes made in each point release are documented in the Release notes for Red Hat JBoss Enterprise Application Platform 8.0.

Use the JBoss Server Migration Tool to automatically upgrade from one point release to another, for example from JBoss EAP 7.0 to JBoss EAP 7.1. For more information, see Using the JBoss Server Migration Tool.

JBoss EAP periodically provides cumulative patches that contain bug and security fixes. Cumulative patches increment the release by the last digit, for example, upgrading from version 7.1.0 to 7.1.1.

The JBoss Server Migration Tool supports migration from all releases of JBoss EAP version 7, to JBoss EAP 8.0.

As per the CDI 4.0 spec change notes, the default behavior for discovering Contexts and Dependency Injection or CDI beans in a deployment with an empty beans.xml file has changed from all to annotated. This means that for such a deployment only deployment classes with a bean defining annotation is discovered by CDI. If all application classes using beans have such an annotation, this CDI change will have no impact. Otherwise, an application deployment might fail when CDI cannot find a type that provides a particular bean.

If your application is impacted by this change, you have several options:

Jakarta Contexts and Dependency Injection 4.0 removed the following deprecated API elements:

Java SE 14 has removed the java.security.Identity class, so it’s usage has been removed from the Jakarta Enterprise Beans 4.0 API.

The incorrectly spelled javax.el.MethodExpression.isParmetersProvided() method has been removed. You can use MethodExpression.isParametersProvided() instead.

By default, types annotated with the jakarta.json.bind.annotation.JsonbCreator annotation does not require all parameters to be available in the JSON content. Default values will be used if the JSON being parsed is missing one of the parameters. The EE 8 behavior that requires all the parameters to be present in the JSON can be turned on by calling jakarta.json.bind.JsonbConfig().withCreatorParametersRequired(true).

The following deprecated functionality has been removed in Jakarta Faces 4.0.

Jakarta Servlet 6.0 removes a number API classes and methods that were deprecated in Servlet 5.0 and earlier, mostly in the Servlet 2.x releases.

The javax.servlet.SingleThreadModel marker interface has been removed and servlets that implement this interface must remove the interface declaration and ensure that the servlet code properly guards state and other resource access against concurrent access. For example, by avoiding the usage of an instance variable or synchronizing the block of code accessing resources. However, it is recommended that developers do not synchronize the service method (or methods like doGet and doPost that it dispatches to) because of the detrimental effect of such synchronization on performance.

The javax.servlet.http.HttpSessionContext interface has been removed, along with the javax.servlet.http.HttpSession.getSessionContext() method. There have been no use cases for this interface since Servlet 2.1 as its implementations were required by specifications not to provide any usable data.

The javax.servlet.http.HttpUtils utility class has been removed. Applications should use the ServletRequest and HttpServletRequest interfaces instead of the following methods:

Also, the following miscellaneous methods and constructors have been removed:

Support for provider lookup through a jaxm.properties file has been removed.

The deprecated javax.xml.soap.SOAPElementFactory class has been removed. Use jakarta.xml.soap.SOAPFactory for creating SOAPElements.

The XML namespace that should be used in xml binding files has changed. The http://java.sun.com/xml/ns/jaxb namespace should be replaced with https://jakarta.ee/xml/ns/jaxb.

The deprecated javax.xml.bind.Validator interface has been removed, as has the associated javax.xml.bind.JAXBContext.createValidator() method. To validate marshalling and unmarshalling operations, provide a javax.xml.validation.Schema to jakarta.xml.bind.Marshaller.setSchema(Schema).

Support for compatibility with JAXB 1.0 has been removed.

Some of the deprecated steps in the JAXBContext implementation lookup algorithm have been removed. Searches for implementation class names through jaxb.properties files, javax.xml.bind.context.factory or jakarta.xml.bind.JAXBContext properties and /META-INF/services/javax.xml.bind.JAXBContext resource files have been dropped. For more informatoin about the current implementation discovery algorithm, see the Jakarta XML Binding 4.0 specification.

The generic requirements for a number of methods in the javax.xml.bind.Marshaller interface have changed as follows:

Apart from the changes in the Jakarta XML Binding API, there have been significant package name changes in the implementation library EAP 8, which might affect some applications that access the implementation library directly:

In JBoss EAP 7.0, the root context of a web application was disabled by default in mod_cluster.

As of JBoss EAP 7.1, this is no longer the case. This can have unexpected consequences if you are expecting the root context to be disabled. For example, requests can be misrouted to undesired nodes or a private application that should not be exposed can be inadvertently accessible through a public proxy. Undertow locations are also now registered with the mod_cluster load balancer automatically unless they are explicitly excluded.

Use the following management CLI command to exclude ROOT from the modcluster subsystem configuration.

/subsystem=modcluster/mod-cluster-config=configuration:write-attribute(name=excluded-contexts,value=ROOT)

Use the following management CLI command to disable the default welcome web application.

/subsystem=undertow/server=default-server/host=default-host/location=\/:remove
/subsystem=undertow/configuration=handler/file=welcome-content:remove
reload

Prior to Red Hat JBoss Enterprise Application Platform 7.2, the default undertow subsystem configuration included two response header filters that were appended to each HTTP response by the default-host:

These response header filters were removed from the default JBoss EAP 7.2 configuration to prevent inadvertent disclosure of information about the server in use.

The following is an example of the default undertow subsystem configuration in JBoss EAP 7.1.

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
        <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
    </filters>
</subsystem>

The following is an example of the default undertow subsystem configuration in JBoss EAP 7.4.

<subsystem xmlns="urn:jboss:domain:undertow:12.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
</subsystem>

The following is an example of the default undertow subsystem configuration in JBoss EAP 8.0.

<subsystem xmlns="urn:jboss:domain:undertow:14.0" default-virtual-host="default-host" default-servlet-container="default" default-server="default-server" statistics-enabled="${wildfly.undertow.statistics-enabled:${wildfly.statistics-enabled:false}}" default-security-domain="other">
    <byte-buffer-pool name="default"/>
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" ssl-context="applicationSSC" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker http-authentication-factory="application-http-authentication"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <application-security-domains>
        <application-security-domain name="other" security-domain="ApplicationDomain"/>
    </application-security-domains>
</subsystem>

In JBoss EAP 7.1 and later versions, a custom stateful session beans (SFSB) cache with passivation enabled has changed. When configuring SFSB cache with passivation, consider the following key changes:

When configuring a custom SFSB cache for passivation in JBoss EAP 7.1 and later versions, consider the following restrictions:

A behavior change between JBoss EAP 7.0 and later versions requires performing updates to the cache container transport protocol in batch mode or using a special header. This change also affects tools used for managing the JBoss EAP server.

The following is an example of the management CLI commands used to configure the cache container transport protocol in JBoss EAP 7.0.

/subsystem=infinispan/cache-container=my:add()
/subsystem=infinispan/cache-container=my/transport=jgroups:add()
/subsystem=infinispan/cache-container=my/invalidation-cache=mycache:add(mode=SYNC)

The following is an example of the management CLI commands needed to perform the same configuration in JBoss EAP 7.1. Note that the commands are executed in batch mode.

batch
/subsystem=infinispan/cache-container=my:add()
/subsystem=infinispan/cache-container=my/transport=jgroups:add()
/subsystem=infinispan/cache-container=my/invalidation-cache=mycache:add(mode=SYNC)
run-batch

If you prefer not to use batch mode, you can instead specify the operation header allow-resource-service-restart=true when defining the transport.

If you use scripts to update the cache container transport protocol, be sure to review them and add batch mode.

JBoss EAP 8.0 introduces changes to the Enterprise JavaBeans (EJB) subsystem configuration for distributable stateful session beans (SFSB), including a new subsystem and updates to several resources. Several resources used in JBoss EAP 6 and 7 are also deprecated. These changes enable server configuration migration to ensure that your applications are compatible with future major releases.

JBoss EAP 8.0 replaces the deprecated resources used in JBoss EAP 6 and 7 with two new resources and a distributable-ejb subsystem for configuring SFSB caching distributively. The following table outlines the deprecated resources and the new resources that replace them.

Non-distributable SFSB cache, /subsystem=ejb3/simple-cache, is equivalent to the SFSB cache, /subsystem=ejb3/cache, used in JBoss EAP 7, where no passivation store was defined.

Distributable SFSB cache, /subsystem=ejb3/distributable-cache, includes an optional bean-management attribute that refers to a corresponding resource from the distributable-ejb subsystem. If you do not define the resource, it defaults to the bean-management resource within the distributable-ejb subsystem.

Consider migrating your server configuration to the updated approach in JBoss EAP 8.0. Although the current release continues to function with the deprecated resources, this might not be the case with future releases when they get removed.

An example of a comparison between JBoss EAP 7 and preferred JBoss EAP 8.0 configurations is as follows:

/subsystem=ejb3/cache=example-simple-cache:add()
/subsystem=ejb3/passivation-store=infinispan:add(cache-container=ejb, bean-cache=default, max-size=1024)
/subsystem=ejb3/cache=example-distributed-cache:add(passivation-store=infinispan)

/subsystem=ejb3/simple-cache=example-simple-cache:add()
/subsystem=distributable-ejb=example-distributed-cache/infinispan-bean-management=example-bean-cache:add(cache-container=ejb, cache=default, max-active-beans=1024)
/subsystem=ejb3/distributable-cache=example-distributed-cache:add(bean-management=example-bean-cache)

Adopting the preferred JBoss EAP 8.0 configuration ensures that your servers are compatible with the latest version and future major releases. You will also benefit from improved resources and subsystems for distributable SFSBs.

The following DuplicateServiceException error is caused by caching changes in JBoss EAP 7.

ERROR [org.jboss.msc.service.fail] (MSC service thread 1-3) MSC000001: Failed to start service jboss.deployment.unit."mdb-1.0-SNAPSHOT.jar".cache-dependencies-installer: org.jboss.msc.service.StartException in service jboss.deployment.unit."mdb-1.0-SNAPSHOT.jar".cache-dependencies-installer: Failed to start service
...
Caused by: org.jboss.msc.service.DuplicateServiceException: Service jboss.infinispan.ejb."mdb-1.0-SNAPSHOT.jar".config is already registered

To resolve the DuplicateServiceException caused by caching changes in JBoss EAP 7, run the following commands to reconfigure caching in the ejb3 subsystem.

/subsystem=ejb3/file-passivation-store=file:remove
/subsystem=ejb3/cluster-passivation-store=infinispan:remove
/subsystem=ejb3/passivation-store=infinispan:add(cache-container=ejb, max-size=10000)

/subsystem=ejb3/cache=passivating:remove
/subsystem=ejb3/cache=clustered:remove
/subsystem=ejb3/cache=distributable:add(passivation-store=infinispan, aliases=[passivating, clustered])

By reconfiguring the cache, you can resolve this error and prevent the DuplicateServiceException from occurring.

Review the approaches you can take to migrate messaging data in Red Hat JBoss Enterprise Application Platform.

To migrate messaging data from a previous JBoss EAP 7.x release to JBoss EAP 8.0, you can Migrate messaging data by using export and import approaches. This method involves exporting messaging data from the previous release and importing it into JBoss EAP 8.0 using the management CLI import-journal operation. Note that this approach is specifically applicable to file-based messaging systems.

As with version 7, JBoss EAP 8.0 continues to use ActiveMQ Artemis as the Jakarta Messaging support provider, which helps to make the migration process smoother.

The way you configure a generic Jakarta Messaging resource adapter for use with a third-party Jakarta Messaging provider has changed in Red Hat JBoss Enterprise Application Platform 8.0. For more information, see Deploying a generic Java Message Service resource adapter in the JBoss EAP 7.4 Configuring Messaging guide.

In Red Hat JBoss Enterprise Application Platform 7.0, if you configured the replication-primary policy without specifying the check-for-live-server attribute, its default value was set to false. This has changed in JBoss EAP 7.1 and later. The default value for the check-for-live-server attribute is now set to true.

The following is an example of a management CLI command that configures the replication-primary policy without specifying the check-for-live-server attribute.

/subsystem=messaging-activemq/server=default/ha-policy=replication-primary:add(cluster-name=my-cluster,group-name=group1)

When you read the resource using the management CLI, note that the check-for-live-server attribute value is set to true.

/subsystem=messaging-activemq/server=default/ha-policy=replication-primary:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "check-for-live-server" => true,
        "cluster-name" => "my-cluster",
        "group-name" => "group1",
        "initial-replication-sync-timeout" => 30000L
    },
    "response-headers" => {"process-state" => "reload-required"}
}

In JBoss EAP 7, an embedded messaging broker was part of the default installation. In JBoss EAP 8, this functionality was added to a new Galleon layer called as embedded-activemq.

This new layer is not a part of the default configuration so users who want to rely on having a broker embedded in JBoss EAP must include it explicitly in their configuration.

The layer provides a messaging-activemq subsystem with an embedded broker even if it is recommended for customers to use a dedicated AMQ cluster on OpenShift. It also provisions ancillary resources, for example, socket-bindings and necessary dependencies needed to support this use case.

Vaults has been removed from JBoss EAP 8.0. Use the credential store provided by the elytron subsystem to store sensitive strings.

The legacy security subsystem and legacy security realms have been removed from JBoss EAP 8.0. Use the security realms provided by the elytron subsystem.

The PicketLink subsystem has been removed from JBoss EAP 8.0. Use Red Hat build of Keycloak instead of the PicketLink identity provider, and the Red Hat build of Keycloak SAML adapter instead of the PicketLink service provider.

The keycloak subsystem is not supported in JBoss EAP 8.0 and is replaced by the elytron-oidc-client subsystem. JBoss Server Migration Tool performs the migration by default.

In JBoss EAP 8.0, the legacy security subsystem has been removed. To continue using your custom login modules with the elytron subsystem, use the new Java Authentication and Authorization Service (JAAS) security realm and jaas-realm.

Starting from JBoss EAP 7.1, automatic generation of a self-signed certificate is enabled by default for development purposes. If you are running in FIPS mode, configure the server to disable automatic self-signed certificate creation. Failure to do so may lead to the following error upon starting the server:

ERROR [org.xnio.listener] (default I/O-6) XNIO001007: A channel event listener threw an exception: java.lang.RuntimeException: WFLYDM0114: Failed to lazily initialize SSL context
...
Caused by: java.lang.RuntimeException: WFLYDM0112: Failed to generate self signed certificate
...
Caused by: java.security.KeyStoreException: Cannot get key bytes, not PKCS#8 encoded

The Java API for XML-based RPC (JAX-RPC) was deprecated in Java EE 6 and was optional in Java EE 7. Starting with JBoss EAP 7, it is no longer supported. Applications that use JAX-RPC must be migrated to use Jakarta XML Web Services, which is the current Jakarta EE standard web services framework.

Use of JAX-RPC web services can be identified in any of the following ways:

In previous releases of JBoss EAP, you could customize the JBossWS and Apache CXF integration by including a jbossws-cxf.xml configuration file with the endpoint deployment archive. One use case for this was to configure interceptor chains for web service client and server endpoints on the Apache CXF bus. This integration required Spring to be deployed in the JBoss EAP server.

Spring integration is no longer supported in JBoss EAP 8. Any application that contains a jbossws-cxf.xml descriptor configuration file must be modified to replace the custom configuration defined in that file. While it is still possible to directly access the Apache CXF API, be aware that the application will not be portable.

The suggested approach is to replace Spring custom configurations with the new JBossWS descriptor configuration options where possible. The JBossWS descriptor-based approach provides similar functionality without requiring modification of the client endpoint code. In some cases, you can replace Spring with Context Dependency Injection (CDI).

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:5.0 schema/jbossws-jaxws-config_5_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:5.0 schema/jbossws-jaxws-config_5_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.transports.http.configuration.HTTPClientPolicy;

// Set chunking threshold before using a JAX-WS port client
...
HTTPConduit conduit = (HTTPConduit)ClientProxy.getClient(port).getConduit();
HTTPClientPolicy client = conduit.getClient();

client.setChunkingThreshold(8192);
...

This section describes the various WS-Security changes for your application in JBoss EAP 6.4 and JBoss EAP 7.0.

The cxf-api and cxf-rt-core JARs have been merged into one cxf-core JAR. As a consequence, the org.apache.cxf module in JBoss EAP now contains the cxf-core JAR and exposes more classes than in the previous release.

If you want to use AES encryption with Galois/Counter Mode (GCM) for symmetric encryption in XML/WS-Security, you need the BouncyCastle Security Provider.

Starting with JBoss EAP 7, it was included with the org.bouncycastle module and JBossWS was able to rely on its class loader to get and use the BouncyCastle Security Provider. Therefore it is no longer necessary to statically install BouncyCastle in the current JVM. For applications running outside of the container, the security provider can be made available to JBossWS by adding a BouncyCastle library to the class path.

You can disable this behavior by setting the org.jboss.ws.cxf.noLocalBC property value to true in the jaxws-endpoint-config.xml deployment descriptor file for the server or the jaxws-client-config.xml descriptor file for clients.

If you want to use a different version than the one that ships with JBoss EAP, you can still statically install BouncyCastle to the JVM. In that case, the statically installed BouncyCastle Security Provider is chosen over the provider present in the class path. To avoid any issues, you must use BouncyCastle 1.72 or greater.

The default bus selection strategy for clients running in-container has changed from THREAD_BUS to TCCL_BUS. For clients running out-of container, the default strategy is still THREAD_BUS. You can restore the behavior to that of the previous release by using either of the following methods.

Containers must use Jakarta XML Web Services 2.2 style constructors, which include the WebServiceFeature class as an argument in the constructor, to build clients that are injected into web service references. JBoss EAP 6.4, which ships with JBossWS 4, hides that requirement. Starting with JBoss EAP 7 that included JBossWS 5, this requirement is not hidden. This states that user provided service classes injected by the container must implement Jakarta XML Web Services 2.2 or later by updating the existing code to use the jakarta.xml.ws.Service constructor that includes one or more WebServiceFeature arguments.

protected Service(URL wsdlDocumentLocation,
       QName serviceName,
       WebServiceFeature... features)

In previous releases, you could disable the HTTPS URL hostname check against a service’s Common Name (CN) given in its certificate by setting the system property org.jboss.security.ignoreHttpsHost to true. This system property name has been replaced with cxf.tls-client.disableCNCheck.

As a consequence of enabling injections into service endpoint and service client handlers, it is no longer possible to automatically load handler classes from the org.jboss.as.webservices.server.integration JBoss module. If your application depends on a given predefined configuration, you might need to explicitly define new module dependencies for your deployment. For more information, see Migrate explicit module dependencies.

The Java-endorsed standards override mechanism was deprecated in JDK 1.8_40 with intent to remove it in JDK 9. This mechanism allowed developers to make libraries available to all deployed applications by placing JARs into an endorsed directory within the JRE.

Starting with the JBoss EAP 7 release, if your application used the JBossWS implementation of Apache CXF, it ensured that the required dependencies are added in the correct order and you should not be impacted by this change. If your application accesses Apache CXF directly, you must now provide the Apache CXF dependencies after the JBossWS dependencies as part of your application deployment.

In previous releases of JBoss EAP, you could configure the jboss-webservices.xml deployment descriptor file for Jakarta Enterprise Beans web service deployments in the META-INF/ directory of JAR archives or in the WEB-INF/ directory for POJO web service deployments and Jakarta Enterprise Beans web service endpoints bundled in WAR archives.

Starting with JBoss EAP 7, you can configure the jboss-webservices.xml deployment descriptor file in the META-INF/ directory of an EAR archive. If a jboss-webservices.xml file is found in the EAR archive and the JAR or WAR archive, the configuration data in the jboss-webservices.xml file for the JAR or WAR overrides the corresponding data in the EAR descriptor file.

Starting with JBoss EAP 7, the proprietary HornetQ messaging resource deployment descriptor files identified by the naming pattern -jms.xml does not work. The following is an example of a Java Message Service resource deployment descriptor file in JBoss EAP 6:

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
  <hornetq-server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </hornetq-server>
</messaging-deployment>

If you used -jms.xml Java Message Service deployment descriptors in your application in the previous release, you can either convert your application to use the standard deployment descriptor as specified in the Resource Definition and Configuration section of the Jakarta EE platform, or you can update the deployment descriptor to use the messaging-activemq-deployment schema instead. If you choose to update the descriptor, you need to make the following modifications:

The modified file should look like the following example.

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-activemq-deployment:1.0">
  <server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </server>
</messaging-deployment>

JBoss EAP 6 included the org.hornetq module, which allowed you to use the HornetQ API in your application source code.

Apache ActiveMQ Artemis replaces HornetQ in JBoss EAP 7, so you must migrate any code that used the HornetQ API to use the Apache ActiveMQ Artemis API. The libraries for this API are included in the org.apache.activemq.artemis module.

ActiveMQ Artemis is an evolution of HornetQ, so many of the concepts still apply.

The ability to auto-create and auto-delete topics and queues using the auto-create-jms-queues, auto-delete-jms-queues, auto-create-jms-topics, and auto-delete-jms-topics attributes was only partially implemented and not fully configurable in JBoss EAP 7. These attributes, which are deprecated, were provided as a technology preview feature only and were not supported.

You must replace any usage of these deprecated attributes with the following replacement attributes.

In JBoss EAP 6, the default address setting attributes were set to false. Starting with JBoss EAP 7, the replacement attributes are set to true by default.

If you prefer to preserve the JBoss EAP 6 behavior, you must set the replacement attributes to false.

For more information about these replacement attributes, see Address Setting Attributes in the JBoss EAP 7.4 Configuring Messaging Guide.

Starting with JBoss EAP 7.2, if a client application directly depends on Artemis client JARs, for example, artemis-jms-client, artemis-commons, artemis-core-client, or artemis-selector, then you must add the following dependency in your pom.xml file for wildfly-client-properties.

<dependency>
  <groupId>org.jboss.eap</groupId>
  <artifactId>wildfly-client-properties</artifactId>
</dependency>

This is to avoid a JMSRuntimeException when calling message.getJMSReplyTo() from an older JBoss EAP 7 client as described in JBEAP-15889.

Interceptor and MessageBody Classes

JSR 311: JAX-RS: The Java™ API for RESTful Web Services did not include an interceptor framework, so RESTEasy 2 provided one. JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services introduced an official interceptor and filter framework, so the interceptor framework included in RESTEasy 2 is now deprecated, and was replaced by the Jakarta REST compliant interceptor facility in RESTEasy 3.x. The relevant interfaces are defined in the jakarta.ws.rs.ext package of the jakarta.ws.rs.api module.

The following providers have been removed in JBoss EAP 8.0:

The following has been removed in JBoss EAP 8.0 as they now have Jakarta RESTful Web Services replacements.

Client API

The RESTEasy client framework in resteasy-jaxrs was replaced by the JAX-RS 2.0 compliant resteasy-client module in JBoss EAP 7.0. As a result, some RESTEasy client API classes and methods are deprecated.

StringConverter

The org.jboss.resteasy.spi.StringConverter class is deprecated in RESTEasy 3.x and JBoss EAP 8.0. This functionality can be replaced using the Jakarta REST jakarta.ws.rs.ext.ParamConverterProvider class.

ResteasyProviderFactory Add methods

Most of the org.jboss.resteasy.spi.ResteasyProviderFactory add() methods have been removed or made protected in RESTEasy 3.0. For example, the addBuiltInMessageBodyReader() and addBuiltInMessageBodyWriter() methods have been removed and the addMessageBodyReader() and addMessageBodyWriter() methods have been made protected.

You should now use the registerProvider() and registerProviderInstance() methods.

Additional Classes Removed From RESTEasy 3

The @org.jboss.resteasy.annotations.cache.ServerCached annotation, which specified the response to the Jakarta REST method should be cached on the server, was removed from RESTEasy 3 and must be removed from the application code.

This section provides information about some additional changes in RESTEasy for JBoss EAP.

SignedInput and SignedOuput

Security Filters

The security filters for @RolesAllowed, @PermitAll, and @DenyAll now return "403 Forbidden" instead of "401 Unauthorized".

Client-side Filters

The client-side filters that were introduced in JAX-RS 2.0 will not be bound and run when you are using the RESTEasy client API from a release prior to RESTEasy 3.0.

Asynchronous HTTP Support

Because the JAX-RS 2.0 specification added asynchronous HTTP support using the @Suspended annotation and the AsynResponse interface, the RESTEasy proprietary API for asynchronous HTTP was deprecated and might be removed in a future RESTEasy release. The asynchronous Tomcat and asynchronous JBoss Web modules have also been removed from the server installation. If you are not using the Servlet 3.0 container or higher, asynchronous HTTP server-side processing will be simulated and run synchronously in same request thread.

Server-side Cache

Server-side cache setup has changed. Please see the RESTEasy Documentation for more information.

YAML Provider Setting Changes

In previous releases of JBoss EAP, the RESTEasy YAML provider setting was enabled by default. This has changed in JBoss EAP 7. The YAML provider is now disabled by default. Its use is not supported due to a security issue in the SnakeYAML library used by RESTEasy for unmarshalling and it must be explicitly enabled in the application. For information about how to enable the YAML provider in your application and add the Maven dependencies, see YAML Provider in JBoss EAP 7.4 Developing Web Services Applications.

Default Charset UTF-8 in Content-Type Header

As of JBoss EAP 7.1, the resteasy.add.charset parameter is set to true by default. You can set the resteasy.add.charset parameter to false if you do not want RESTEasy to add charset=UTF-8 to the returned content-type header when the resource method returns a text/* or application/xml* media type without an explicit charset.

For more information about text media types and character sets, see Text Media Types and Character Sets in JBoss EAP 7.4 Developing Web Services Applications.

SerializableProvider

Deserializing Java objects from untrusted sources is not safe. For this reason, starting with JBoss EAP 7, the org.jboss.resteasy.plugins.providers.SerializableProvider class is disabled by default, and it is not recommended to use this provider.

Matching Requests to Resource Methods

In RESTEasy 3, improvements and corrections were made to the implementation of matching rules, as defined in the JAX-RS specification. In particular, a change was made to how an ambiguous URI on a sub-resource method and a sub-resource locator is handled.

In RESTEasy 2, it was possible for a sub-resource locator to execute successfully even when there was another sub-resource with the same URI. This behavior was incorrect according to the specification.

In RESTEasy 3, when there is an ambiguous URI for a sub-resource and a sub-resource locator, calling the sub-resource will be successful; however, calling the sub-resource locator will result in an HTTP status 405 Method Not Allowed error.

The following example contains an ambiguous @Path annotation on a sub-resource method and a sub-resource locator. Notice that the URI to both endpoints, anotherResource and anotherResourceLocator, is the same. The difference between the two endpoints is that the anotherResource method is associated with the REST verb, POST. The anotherResourceLocator method is not associated with any REST verb. According to the specification, the endpoint with the REST verb, in this case the anotherResource method, will always be selected.

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}

The RESTEasy SPI provider has been removed in JBoss EAP 8.

SPI Exceptions

All SPI failure exceptions were deprecated and are no longer used internally. They have been replaced with the corresponding Jakarta REST exception.

InjectorFactory and Registry

The InjectorFactory and Registry SPIs have changed. This should not be an issue if you use RESTEasy as documented and supported.

The version of Jackson included in JBoss EAP 6.4 has changed. Starting with JBoss EAP 7, the Jackson provider has changed from resteasy-jackson-provider to resteasy-jackson2-provider.

The upgrade to the resteasy-jackson2-provider requires some package changes. For example, the Jackson annotation package has changed from org.codehaus.jackson.annotate to com.fasterxml.jackson.annotation.

JBoss EAP 8.0 provides support for RESTEasy 6.2. If you plan to use the Spring 6.0 framework with JBoss EAP 8.0, you must use Java 17.

The Spring 4.0 framework introduced support for Java 8. If you plan to use the RESTEasy 3.x integration with Spring, be sure to specify 4.2.x as the minimum Spring version in your deployment as this is the earliest stable version supported by JBoss EAP 7.

The RESTEasy Jettison JSON provider is deprecated since JBoss EAP 7 and is no longer added to deployments by default. You are encouraged to switch to the recommended RESTEasy Jackson provider. If you prefer to continue to use the Jettison provider, you must define an explicit dependency for it in the jboss-deployment-descriptor.xml file as demonstrated in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

For more information about how to define explicit dependencies, see Add an Explicit Module Dependency to a Deployment in the JBoss EAP 7.4 Development Guide.

MicroProfile is the name of a specification that developers can use to configure applications and microservices to run in multiple environments without having to modify or repackage those apps. Previously, MicroProfile was available for JBoss EAP 7.3 as a technology preview, but it has since been removed. MicroProfile is now available only on JBoss EAP XP.

Bean classes of enabled beans must be deployed in bean archives to ensure they are discovered by CDI and processed as beans.

CDI 1.1 introduced implicit bean archives, which are archives that contain one or more bean classes with a bean defining annotation, or one or more session beans. Implicit bean archives are scanned by CDI and, during type discovery, only classes with bean defining annotations are discovered. For more information, see Type and Bean Discovery in JSR 365: Contexts and Dependency Injection for Java^™ 2.0. The Jakarta equivalents for bean defining annotations are defined in the Jakarta Context Dependency Injection 2.0 specification.

In CDI 4.0:

For more information about CDI 4.0, see Jakarta Contexts and Dependency Injection 4.0.

A bean archive has a bean discovery mode of all, annotated or none. A bean archive which contains non-empty beans.xml must specify the bean-discovery-mode attribute. The default value for the attribute is annotated.

An archive is not a bean archive in the following cases:

An archive is an explicit bean archive in the following case:

An archive is an implicit bean archive in the following cases:

CDI 1.2 limited bean defining annotations to the following:

The conversation context lifecycle was changed in CDI 1.2 to prevent conflicts with the Servlet specification as described in CDI Specification Issue CDI-411. The conversation scope is active during all servlet requests and should not prevent other servlets or servlet filters from setting the request body or character encoding. For more information, see Conversation context lifecycle in Jakarta EE.

Event resolution was partly rewritten in CDI 1.2. In CDI 1.0, an event is delivered to an observer method if the observer method has all the event qualifiers. In CDI 1.2, an event is delivered to an observer method if the observer method has no event qualifiers or has a subset of the event qualifiers. For more information, see Observer resolution.

This section highlights the changes required when migrating from Hibernate ORM version 5.3 to 5.4. For more information about the changes implemented between Hibernate ORM 5.3 and Hibernate ORM 5.4, see the Hibernate ORM 5.4 Migration Guide.

Known Changes

The following describes some of the changes when migrating from Hibernate ORM version 5.3 to 5.4.

This section highlights the changes required when migrating from Hibernate ORM version 5.4 to 5.5. For more information about the changes implemented between Hibernate ORM 5.4 and Hibernate ORM 5.5, see the Hibernate ORM 5.5 Migration Guide.

Known Changes

The Hibernate ORM 5.5 version is similar to Hibernate ORM 5.4 as it includes all bugfixes applied to the 5.4 maintenance releases and introduces support for Jakarta Persistence API.

This section highlights the changes required when migrating from Hibernate ORM version 5.5 to 5.6. For more information about the changes implemented between Hibernate ORM 5.5 and Hibernate ORM 5.6, see the Hibernate ORM 5.6 Migration Guide.

Deprecated features

The Hibernate 5.6 version is very similar to the previous Hibernate 5.5 version, with the exception of removal of some of the deprecated features from previous Hibernate releases.

This section highlights the changes required when migrating from Hibernate ORM version 5.6 to 6.0. For more information about the changes implemented between Hibernate ORM 5.6 and Hibernate ORM 6.0, see the Hibernate ORM 6.0 Migration Guide.

The Hibernate 6.0 release includes the following changes:

For more information about these features, see Hibernate ORM 6.0 Migration Guide.

The Hibernate 6.0 release contains also contains lot of feature removals from previous Hibernate releases, which are listed as follows:

For more information about features removed in Hibernate 6.0, see Hibernate ORM 6.0 Migration Guide.

This section highlights the changes required when migrating from Hibernate ORM version 6.0 to 6.1. For more information about the changes implemented between Hibernate ORM 6.0 and Hibernate ORM 6.1, see the Hibernate ORM 6.1 Migration Guide.

The Hibernate 6.1 release contains the following changes:

For more detailed information about features included in the Hibernate 6.1, see the Hibernate ORM 6.1 Migration Guide.

This section highlights the changes required when migrating from Hibernate ORM version 6.1 to 6.2. For more information about the changes implemented between Hibernate ORM 6.1 and Hibernate ORM 6.2, see the Hibernate ORM 6.2 Migration Guide.

The Hibernate 6.2 release contains the following enhancements, which are listed as follows:

DDL type changes:

JBoss EAP 7.0 included Hibernate ORM 5.0. This section highlights the changes you need to make when migrating from Hibernate ORM version 4.3 to version 5. For more information about the changes implemented between Hibernate ORM 4 and Hibernate ORM 5, see the Hibernate ORM 5.0 Migration Guide.

Removed and deprecated classes

The following deprecated classes were removed from Hibernate ORM 5:

Other changes to classes and packages

Type handling

Transaction management

Other Hibernate ORM 5 changes

JBoss EAP 7.1 included Hibernate ORM 5.1. This section highlights the differences and the changes needed when migrating from Hibernate ORM version 5.0 to version 5.1.

Hibernate ORM 5.1 features

This release of Hibernate includes performance improvements and bug fixes. For more information, see Hibernate ORM 5.1 Features in the JBoss EAP Release notes for 7.1.0. For additional information about the changes implemented between Hibernate ORM 5.0 and Hibernate ORM 5.1, see the Hibernate ORM 5.1 Migration Guide.

Schema management tooling changes

Schema management tooling changes in JBoss EAP 7

Schema management tooling changes in Hibernate ORM 5.1 are focused on the following areas:

The schema management tooling changes are only a migration concern for applications that directly use the following classes:

Schema management tooling changes in JBoss EAP 7.1

Hibernate ORM 5.1.10, included in JBoss EAP 7.1, introduced a strategy for retrieving database tables that improve SchemaMigrator and SchemaValidator performance. This strategy executes a single java.sql.DatabaseMetaData#getTables(String, String, String, String[]) call to determine if each javax.persistence.Entity has a mapped database table. This is the default strategy, and it uses the hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped property setting. This strategy might require hibernate.default_schema and/or hibernate.default_catalog to be provided.

To use the old strategy of executing a java.sql.DatabaseMetaData#getTables(String, String, String, String[]) call for each javax.persistence.Entity, use the hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually property setting.

JBoss EAP 7.4 includes Hibernate ORM 5.3. This section highlights some of the changes needed when migrating from Hibernate ORM 5.1 to Hibernate ORM 5.2 and then to Hibernate ORM 5.3.

Hibernate ORM 5.2 features

Hibernate ORM 5.2 is built using the Java 8 JDK and requires the Java 8 JRE at runtime. The following is a list of some of the changes made in this release:

For the complete list of changes implemented in Hibernate 5.2, see Hibernate ORM 5.2 Migration Guide.

Hibernate ORM 5.3 features

Hibernate ORM 5.3 adds support for the Jakarta Persistence 2.2 specification. This release contains changes to comply with this specification along with other improvements. The following is a list of some of these changes:

For the complete list of these and other changes implemented in Hibernate 5.3, see the Hibernate ORM 5.3 Migration Guide.

Exception handling changes between Hibernate 5.1 and Hibernate 5.3

In Hibernate 5.2 and 5.3, exception handling for a SessionFactory that is built using Hibernate’s native bootstrapping, wraps or converts HibernateException according to the Jakarta Persistence specification. The only exception to this behavior is when the operation is Hibernate-specific, for example Session.save() or Session.saveOrUpdate().

In Hibernate 5.3.3, the hibernate.native_exception_handling_51_compliance property was added. This property indicates whether exception handling for a SessionFactory built using Hibernate’s native bootstrapping should behave the same as native exception handling in Hibernate ORM 5.1. When set to true, HibernateException is not wrapped or converted according to the Jakarta Persistence specification. This setting is ignored for a SessionFactory built using Jakarta Persistence bootstrapping.

Compatibility transformer

JBoss EAP 7.4 includes a compatibility transformer that addresses Hibernate ORM 5.3 API methods that are no longer compatible with Hibernate ORM 5.1. The transformer is a temporary measure to allow applications built using Hibernate ORM 5.1 to exhibit the same behavior with Hibernate 5.3 in JBoss EAP 7.4. This is a temporary solution and you should replace these method calls with the recommended Jakarta Persistence method calls.

You can enable the transformer in one of the following ways:

The following table lists the Hibernate 5.1 methods that are transformed and the Hibernate 5.3 method it is converted to:

Hibernate Search 5 APIs have been removed and are replaced with Hibernate Search 6 APIs in JBoss EAP 8.0.

To view a list of the removed features, see Hibernate Search 5 APIs Deprecated in JBoss EAP 7.4 and removed in EAP 8.0.

The latest version of Hibernate Search 6 included in JBoss EAP 8.0 is 6.2. If you are migrating from Hibernate Search 5, you should take into account the migration to version 6.0, 6.1, and 6.2.

See the following migrations guides for more information:

JBoss EAP 8.0 also provides support for using an Elasticsearch backend in Hibernate Search 6 to index data into remote Elasticsearch or OpenSearch clusters.

To see a list of possible Hibernate Search architectures and backends, see Table 2. Comparison of architectures in the Hibernate Search 6.2 reference documentation.

For more information about configuring Hibernate Search 6, see Using Hibernate Search in the WildFly Developer guide.

Starting with JBoss EAP 7, the default remote connector and port have been changed. For details about this change, see Update the Remote URL connector and port.

If you used the JBoss Server Migration Tool to migrate your server configuration, the old settings are preserved and you do not need to make the changes detailed here. However, if you use the new JBoss EAP 8.0 default configuration, you must make the following changes.

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=4447
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=8080
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

If you are running with the new default JBoss EAP 7 configuration, you must modify your client code to use the new default remote port and connector.

The following is an example of how remote naming properties were specified in the client code in JBoss EAP 6.

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=remote://localhost:4447

The following is an example of how to specify the remote naming properties in the client code in JBoss EAP 7.

java.naming.factory.initial=org.wildfly.naming.client.WildFlyInitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

JBoss EAP 7.0 is included with JBoss Enterprise Java Beans client 2.1.4, JBoss EAP 7.1 and later was included with JBoss Enterprise Java Beans client 4.0.x, which includes a number of changes to the API.

If you created a custom authenticator valve that extended AuthenticatorBase in JBoss EAP 6.4, you must manually replace it with a custom HTTP authentication implementation in JBoss EAP 7. The HTTP authentication mechanism is created in the elytron subsystem and then registered with the undertow subsystem. For information about how to implement a custom HTTP authentication mechanism, see Developing a Custom HTTP Mechanism in the JBoss EAP 7.4 Development Guide.

PicketLink has been removed from JBoss EAP 8.0.

PicketLink SP

Use Keycloak SAML adapter instead of the PicketLink service provider.

To migrate from PicketLink by configuring the Keycloak SAML adapter, perform the following tasks:

PicketLink IDP

PicketLink IDP is not available since JBoss EAP 8.0 and you can configure Red Hat build of Keycloak instead. For more information, see Configuring Red Hat build of Keycloak.

PicketLink STS

In previous releases, you could configure PicketLink STS as an alternative to the Apache CXF Security Token Service implementation. PicketLink STS configuration involved a legacy security domain. Any references to legacy security domains and PicketLink in the STS application needs to be removed, so you must configure Apache CXF STS instead.

For more information on how to configure Apache CXF STS, see Security Token Service (STS) in the JBoss EAP 7.4 Developing Web Services Applications.

Vaults has been removed from JBoss EAP 8.0. If your applications use legacy vault expressions, you must migrate and use Elytron encrypted expressions.

Check for instances of ${VAULT:: in your deployment files, which could be in annotations or deployment descriptors, and replace them with the corresponding encrypted expressions.

The Keycloak OIDC client adapter is not supported in JBoss EAP 8.0 and is replaced by the native Elytron OIDC client, providing similar functionality and configuration.

To migrate from the Keycloak OIDC client adapter to the native Elytron OIDC client, follow these steps:

In JBoss EAP 8.0, the legacy security subsystem has been removed. To continue using your custom login modules with the elytron subsystem, use the new Java Authentication and Authorization Service (JAAS) security realm and jaas-realm.

There are a few noticeable differences between JBoss EAP 7.2 or higher and earlier versions:

The following list describes some of the new clustering features to be aware of when migrating your application from JBoss EAP 6 to JBoss EAP 8.0.

JBoss EAP 7 introduces a new web session clustering implementation. It replaces the previous implementation, which was tightly coupled to the legacy JBoss Web subsystem source code.

The new web session clustering implementation impacts how the application is configured in the jboss-web.xml JBoss EAP proprietary web application XML descriptor file. The following are the only clustering configuration elements that remain in this file.

<jboss-web>
  ...
  <max-active-sessions>...</max-active-sessions>
  ...
  <replication-config>
    <replication-granularity>...</replication-granularity>
    <cache-name>...</cache-name>
  </replication-config>
  ...
</jboss-web>

The distributable-web subsystem deprecates the <replication-config> element of jboss-web.xml. It enhances the usage of <replication-config> by generating an ad hoc distributable web session profile.

You can override the default distributable session management behavior by referencing a session management profile by name or by providing a deployment-specific session management configuration. For more information, see Overriding the default distributable session management behavior.

The following table describes how to achieve similar behavior for elements in the jboss-web.xml file that are now obsolete.

This new implementation also supports write-through cache stores as well as passivation-only cache stores. Typically, a write-through cache store is used in conjunction with an invalidation cache. The web session clustering implementation in JBoss EAP 6 did not operate correctly when used with an invalidation cache.

You can override the default distributable session management behavior in one of the following ways:

Referencing an existing session management profile

/WEB-INF/distributable-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <session-management name="foo"/>
</distributable-web>

/META-INF/jboss-all.xml

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <session-management name="foo"/>
    </distributable-web>
</jboss>

Using a Deployment-specific Session Management Profile

If only a single web application uses the custom session management configuration, you can define the configuration within the deployment descriptor itself. Ad hoc configuration looks identical to the configuration used by the distributable-web subsystem.

/WEB-INF/distributable-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <infinispan-session-management cache-container="foo" cache="bar" granularity="SESSION">
        <primary-owner-affinity/>
    </infinispan-session-management>
</distributable-web>

/META-INF/jboss-all.xml

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <infinispan-session-management cache-container="foo" cache="bar" granularity="ATTRIBUTE">
            <local-affinity/>
        </infinispan-session-management>
    </distributable-web>
</jboss>

In JBoss EAP 6, you were required to enabled the clustering behavior for stateful session beans (SFSBs) in one of the following ways:

Starting with JBoss EAP 7, you no longer need to enable the clustering behavior. By default, if the server is started using an HA profile, the state of SFSBs will be replicated automatically. You can disable this default behavior in one of the following ways:

In JBoss EAP 6, the APIs for clustering services were in private modules and were not supported.

JBoss EAP 7 introduces a public clustering services API for use by applications. The new services are designed to be lightweight, easily injectable, and require no external dependencies.

These services replace similar APIs that were available in previous releases, namely HAPartition from JBoss EAP 5 and GroupCommunicationService, GroupMembershipNotifier, and GroupRpcDispatcher in JBoss EAP 6.

For more information, see Public API for Clustering Services in the JBoss EAP 7.4 Development Guide.

In JBoss EAP 6, there was no public API available for the cluster-wide HA singleton service. If you used the private org.jboss.as.clustering.singleton.* classes, you must change your code to use the new public org.wildfly.clustering.singleton.* packages when you migrate your application to JBoss EAP 8.

For more information about HA singleton services, see HA Singleton Service in the JBoss EAP 7.4 Development Guide. For information about HA singleton deployments, see HA Singleton Deployments in the JBoss EAP 7.4 Development Guide.

IBM MQ is the Messaging Oriented Middleware (MOM) product offering from IBM that allows applications on distributed systems to communicate with each other. This is accomplished through the use of messages and message queues. IBM MQ is responsible for delivering messages to the message queues and for transferring data to other queue managers using message channels. For more information about IBM MQ, see IBM MQ on the IBM products website.

Summary

IBM MQ can be configured as an external Java Message Service provider for JBoss EAP 8.0. This section covers the steps to deploy and configure the IBM MQ resource adapter in JBoss EAP. This deployment and configuration can be accomplished by using the management CLI tool or the web-based management console. See JBoss EAP supported configurations for the most current information about the supported configurations of IBM MQ.

JBoss EAP  8.0 is a Jakarta EE 10 implementation, so the packages used for all EE APIs have changed from javax to jakarta, which requires a Jakarta EE 10 compliant resource adapter. If you were using the IBM MQ Resource adapter in JBoss EAP  7.x or earlier, you must use wmq.jakarta.jmsra.rar, the IBM MQ Resource Adapter that uses this jakarta namespace.

@ActivationConfigProperty(propertyName = "destination", propertyValue = "QUEUE")

@JMSConnectionFactoryDefinition(
    name = "java:/jms/WMQConnectionFactory",
    interfaceName = "javax.jms.ConnectionFactory",
    resourceAdapter = "wmq.jmsra",
    properties = {
        "channel=<channel>",
        "hostName=<hostname_wmq_broker>",
        "transportType=<transport_type>",
        "queueManager=<queue_manager>"
    }
)

@Inject
@JMSConnectionFactory("jms/CF")
@JMSPasswordCredential(userName="myusername", password="mypassword")
@JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE)
transient JMSContext context3;

WARN  [org.jboss.jca.core.connectionmanager.pool.strategy.PoolByCri] (EJB default - 7) IJ000604: Throwable while attempting to get a new connection: null: com.ibm.mq.connector.DetailedResourceException: MQJCA1011: Failed to allocate a JMS connection., error code: MQJCA1011 An internal error caused an attempt to allocate a connection to fail. See the linked exception for details of the failure.

QueueConnection qc = queueConnectionFactory.createQueueConnection("invalidUserName", "invalidPassword");

SVR-ERROR: Expected JMSException, received com.ibm.mq.connector.outbound.MQQueueProxy cannot be cast to com.ibm.mq.jms.MQDestination

ERROR [io.undertow.request] (default task-1) UT005023: Exception handling request to /jmsServlet-1.0-SNAPSHOT/: com.ibm.msg.client.jms.DetailedJMSRuntimeException: MQJCA0002: An exception occurred in the IBM MQ layer. See the linked exception for details.
A call to IBM MQ classes for Java(tm) caused an exception to be thrown.

SVR-ERROR: com.ibm.msg.client.jms.DetailedJMSException: JMSWMQ2007: Failed to send a message to destination 'MDB_NAME TOPIC_NAME'

com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2072' ('MQRC_SYNCPOINT_NOT_AVAILABLE')

Starting with JBoss EAP 8, support for Apache Log4j version 1 APIs has been stopped. Any application that is not packaging log4j.jar and log4j configuration must be updated.

Impact:

Log messages will no longer be routed based on the logging subsystem. If an application is not packaging log4j.jar and any of the following statements are true, then migration changes are required:

Migration:

OR

Additional Details:

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <deployment>
    <exclude-subsystems>
      <subsystem name="logging"/>
    </exclude-subsystems>
  </deployment>
</jboss-deployment-structure>

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <sub-deployment name="example.war">
    <exclude-subsystems>
      <subsystem name="logging"/>
    </exclude-subsystems>
  </sub-deployment>
</jboss-deployment-structure>

<subsystem xmlns="urn:jboss:domain:logging:8.0">
    <add-logging-api-dependencies value="false"/>
  ...
</subsystem>

For more information, see Apache Log4j version 1 is no longer provided in JBoss EAP 8.0.

The secure vault used to store plain text string encryption in the legacy security subsystem in JBoss EAP 7.0 is not compatible with Elytron in JBoss EAP 7.1 or later. JBoss EAP 7.1 or later uses a credential store to store strings. Credential stores encrypt credentials in a storage file outside of the JBoss EAP configuration files. You can use the implementation provided by Elytron or you can customize the configuration using the credential store APIs and SPIs. Each JBoss EAP server can contain multiple credential stores.

For more information about credential stores, see Credential Stores in the JBoss EAP 7.4 How to Configure Server Security.

$ EAP_HOME/bin/elytron-tool.sh vault VAULT_ARGUMENTS

$ EAP_HOME/bin/elytron-tool.sh vault --help

$ EAP_HOME/bin/elytron-tool.sh vault --enc-dir vault_data/ --keystore vault-jceks.keystore --keystore-password MASK-2hKo56F1a3jYGnJwhPmiF5 --iteration 34 --salt 12345678 --alias test --location cs-v1.store --summary

Vault (enc-dir="vault_data/";keystore="vault-jceks.keystore") converted to credential store "cs-v1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="cs-v1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})

keystore:vault-v1/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:vault-v1/vault_data/
salt:12345678
iteration:34
location:v1-cs-1.store
alias:test

keystore:vault-v1/vault-jceks.keystore
keystore-password:secretsecret
enc-dir:vault-v1/vault_data/
location:v1-cs-2.store
alias:test

# different vault vault-v1-more
keystore:vault-v1-more/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:vault-v1-more/vault_data/
salt:12345678
iteration:34
location:v1-cs-more.store
alias:test

$ EAP_HOME/bin/elytron-tool.sh vault --bulk-convert path/to/bulk-vault-conversion-descriptor.txt --summary

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-2.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-2.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="secretsecret"})
--------------------------------------

Vault (enc-dir="vault-v1-more/vault_data/";keystore="vault-v1-more/vault-jceks.keystore") converted to credential store "v1-cs-more.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-more.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

The following examples assume that the group.name and encoding.algorithm security properties are defined as security-properties in the legacy security subsystem.

Security Properties Defined in the security Subsystem:

<subsystem xmlns="urn:jboss:domain:security:2.0">
    ...
    <security-properties>
        <property name="group.name" value="engineering-group" />
        <property name="encoding.algorithm" value="BASE64" />
    </security-properties>
</subsystem>

To define these security properties in the elytron subsystem, set the security-properties attribute of the elytron subsystem using the following management CLI command:

/subsystem=elytron:write-attribute(name=security-properties, value={ group.name = "engineering-group", encoding.algorithm = "BASE64" })

This defines the security-properties in the elytron subsystem in the server configuration file.

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
    <security-properties>
        <security-property name="group.name" value="engineering-group"/>
        <security-property name="encoding.algorithm" value="BASE64"/>
    </security-properties>
    ...
</subsystem>

The write-attribute operation in the previous command overwrites the existing properties. To add or change a security property without impacting other security properties, use the map operation in the management CLI command:

/subsystem=elytron:map-put(name=security-properties, key=group.name, value=technical-support)

In a similar manner, you can remove a specific security property by using the map-remove operation:

/subsystem=elytron:map-remove(name=security-properties, key=group.name)

Migrate PicketBox properties-based authentication to Elytron using the following example.

/subsystem=security/security-domain=application-security:add
/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=UsersRoles, flag=Required, module-options={usersProperties=file://${jboss.server.config.dir}/example-users.properties, rolesProperties=file://${jboss.server.config.dir}/example-roles.properties}}])

This results in the following server configuration.

<security-domain name="application-security">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="usersProperties" value="file://${jboss.server.config.dir}/example-users.properties"/>
      <module-option name="rolesProperties" value="file://${jboss.server.config.dir}/example-roles.properties"/>
    </login-module>
  </authentication>
</security-domain>

This section describes how to migrate a legacy security realm that loads user, password, and group information from properties files to Elytron in JBoss EAP 7.4 and earlier. This type of legacy security realm was typically used to secure either the management interfaces or remoting connectors.

In JBoss EAP 8.0, filesystem-realm is preferred over properties-realm.

/core-service=management/security-realm=ApplicationSecurity:add
/core-service=management/security-realm=ApplicationSecurity/authentication=properties:add(relative-to=jboss.server.config.dir, path=example-users.properties, plain-text=true)
/core-service=management/security-realm=ApplicationSecurity/authorization=properties:add(relative-to=jboss.server.config.dir, path=example-roles.properties)

This results in the following server configuration.

<security-realm name="ApplicationSecurity">
  <authentication>
    <properties path="example-users.properties" relative-to="jboss.server.config.dir" plain-text="true"/>
  </authentication>
  <authorization>
    <properties path="example-roles.properties" relative-to="jboss.server.config.dir"/>
  </authorization>
</security-realm>

One of the reasons for adding the Elytron security to the application server was to allow a consistent security solution to be used across the server. The initial steps to migrate a properties-based legacy security realm to Elytron are similar to those used to migrate a PicketBox properties-based authentication to Elytron. Follow these steps to migrate a properties-based legacy security realm to Elytron.

The migration of the legacy properties-based configuration to Elytron is now complete.

Migrate the legacy properties-based security realm to a filesystem-based realm in Elytron using the filesystem-realm command of the elytron.sh tool.

A filesystem-based realm is a filesystem-based identity store used by Elytron for storing user identities. The filesystem-realm command converts the properties-realm files to filesystem-realm. It also generates commands for adding this realm and a security domain to the elytron subsystem.

Migrate legacy LDAP authentication to Elytron so that it can manage the information as identity attributes.

The following examples assume that group or role information is loaded directly from LDAP and that the legacy LDAP authentication is configured as follows.

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-realms>
    ...
    <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
      <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
        <attribute-mapping>
          <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
        </attribute-mapping>
      </identity-mapping>
    </ldap-realm>
  </security-realms>
  ...
  <dir-contexts>
    <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
      <credential-reference clear-text="secret"/>
    </dir-context>
  </dir-contexts>
</subsystem>

Migrate JDBC datasource-based PicketBox authentication to Elytron. For instructions on defining security domains, authentication factories, and mapping them for authentication, see Migrate Properties-based Authentication and Authorization to Elytron.

The following examples assume that the user authentication data is stored in a database table created using syntax similar to the following example.

CREATE TABLE User (
    id BIGINT NOT NULL,
    username VARCHAR(255),
    password VARCHAR(255),
    role ENUM('admin', 'manager', 'user'),
    PRIMARY KEY (id),
    UNIQUE (username)
)

For authentication purposes the username is matched against data stored in the username column, the password is expected to be stored as a hex-encoded MD5 hash in the password column, and the user role for authorization purposes is stored in the role column.

The PicketBox security domain is configured to use a JBDC datasource to retrieve data from the database table, and then use it to verify the username and password, and to assign roles. Assume the PicketBox security domain is configured using the following management CLI commands.

/subsystem=security/security-domain=application-security:add
/subsystem=security/security-domain=application-security/authentication=classic:add( login-modules=[ { code=Database, flag=Required, module-options={ dsJndiName="java:jboss/datasources/ExampleDS", principalsQuery="SELECT password FROM User WHERE username = ?", rolesQuery="SELECT role, 'Roles' FROM User WHERE username = ?", hashAlgorithm=MD5, hashEncoding=base64 } } ] )

This results in the following login-module configuration in the legacy security subsystem.

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="application-security">
      <authentication>
        <login-module code="Database" flag="required">
          <module-option name="dsJndiName" value="java:jboss/datasources/ExampleDS"/>
          <module-option name="principalsQuery" value="SELECT password FROM User WHERE username = ?"/>
          <module-option name="rolesQuery" value="SELECT role, 'Roles' FROM User WHERE username = ?"/>
          <module-option name="hashAlgorithm" value="MD5"/>
          <module-option name="hashEncoding" value="base64"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

/subsystem=elytron/jdbc-realm=jdbc-realm:add(principal-query=[ { data-source=ExampleDS, sql="SELECT role, password FROM User WHERE username = ?", attribute-mapping=[{index=1, to=Roles } ] simple-digest-mapper={algorithm=simple-digest-md5, password-index=2} } ] )

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-realms>
    ...
    <jdbc-realm name="jdbc-realm">
      <principal-query sql="SELECT role, password FROM User WHERE username = ?" data-source="ExampleDS">
        <attribute-mapping>
          <attribute to="Roles" index="1"/>
        </attribute-mapping>
        <simple-digest-mapper password-index="2"/>
      </principal-query>
    </jdbc-realm>
    ...
  </security-realms>
  ...
</subsystem>

When working with a Kerberos configuration, the JBoss EAP server can rely on configuration information from the environment, or the key configuration can be specified using system properties.

These system properties are applicable to both the legacy configuration and the migrated Elytron configuration.

# Enable debugging
/system-property=sun.security.krb5.debug:add(value=true)
# Identify the Kerberos realm to use
/system-property=java.security.krb5.realm:add(value=ELYTRON.ORG)
# Identify the address of the KDC
/system-property=java.security.krb5.kdc:add(value=kdc.elytron.org)

<system-properties>
  <property name="sun.security.krb5.debug" value="true"/>
  <property name="java.security.krb5.realm" value="ELYTRON.ORG"/>
  <property name="java.security.krb5.kdc" value="kdc.elytron.org"/>
</system-properties>

Depending on your authentication mechanisms, choose one of the following migration options:

/core-service=management/security-realm=Kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos/keytab=HTTP\/test-server.elytron.org@ELYTRON.ORG:add(path=/path/to/test-server.keytab, debug=true)
/core-service=management/security-realm=Kerberos/authentication=kerberos:add(remove-realm=true)

<security-realms>
  ...
  <security-realm name="Kerberos">
    <server-identities>
      <kerberos>
        <keytab principal="HTTP/test-server.elytron.org@ELYTRON.ORG" path="/path/to/test-server.keytab" debug="true"/>
      </kerberos>
    </server-identities>
    <authentication>
      <kerberos remove-realm="true"/>
    </authentication>
  </security-realm>
</security-realms>

# Define the first security domain
/subsystem=security/security-domain=host:add
/subsystem=security/security-domain=host/authentication=classic:add
/subsystem=security/security-domain=host/authentication=classic/login-module=1:add(code=Kerberos, flag=Required, module-options={storeKey=true, useKeyTab=true, principal=HTTP/test-server.elytron.org@ELYTRON.ORG, keyTab=path/to/test-server.keytab, debug=true}

# Define the second SPNEGO security domain
/subsystem=security/security-domain=SPNEGO:add
/subsystem=security/security-domain=SPNEGO/authentication=classic:add
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=1:add(code=SPNEGO, flag=requisite,  module-options={password-stacking=useFirstPass, serverSecurityDomain=host})
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=1:write-attribute(name=module, value=org.jboss.security.negotiation)
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=2:add(code=UsersRoles, flag=required, module-options={password-stacking=useFirstPass, usersProperties=  /path/to/kerberos/spnego-users.properties, rolesProperties=  /path/to/kerberos/spnego-roles.properties, defaultUsersProperties=  /path/to/kerberos/spnego-users.properties, defaultRolesProperties=  /path/to/kerberos/spnego-roles.properties})

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="host">
      <authentication>
        <login-module name="1" code="Kerberos" flag="required">
          <module-option name="storeKey" value="true"/>
          <module-option name="useKeyTab" value="true"/>
          <module-option name="principal" value="HTTP/test-server.elytron.org@ELYTRON.ORG"/>
          <module-option name="keyTab" value="/path/to/test-server.keytab"/>
          <module-option name="debug" value="true"/>
        </login-module>
      </authentication>
    </security-domain>
    <security-domain name="SPNEGO">
      <authentication>
        <login-module name="1" code="SPNEGO" flag="requisite" module="org.jboss.security.negotiation">
          <module-option name="password-stacking" value="useFirstPass"/>
          <module-option name="serverSecurityDomain" value="host"/>
        </login-module>
        <login-module name="2" code="UsersRoles" flag="required">
          <module-option name="password-stacking" value="useFirstPass"/>
          <module-option name="usersProperties" value="path/to/kerberos/spnego-users.properties"/>
          <module-option name="rolesProperties" value="  /path/to/kerberos/spnego-roles.properties"/>
          <module-option name="defaultUsersProperties" value="  /path/to/kerberos/spnego-users.properties"/>
          <module-option name="defaultRolesProperties" value="  /path/to/kerberos/spnego-roles.properties"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

/core-service=management/security-realm=Kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos:add
/core-service=management/security-realm=Kerberos/server-identity=kerberos/keytab=remote\/test-server.elytron.org@ELYTRON.ORG:add(path=path/to/remote-test-server.keytab, debug=true)
/core-service=management/security-realm=Kerberos/authentication=kerberos:add(remove-realm=true)

<management>
  <security-realms>
    ...
    <security-realm name="Kerberos">
      <server-identities>
        <kerberos>
          <keytab principal="remote/test-server.elytron.org@ELYTRON.ORG" path="path/to/remote-test-server.keytab" debug="true"/>
        </kerberos>
      </server-identities>
      <authentication>
        <kerberos remove-realm="true"/>
      </authentication>
    </security-realm>
  </security-realms>
  ...
</management>

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="KerberosDomain" default-realm="kerberos-properties" permission-mapper="default-permission-mapper">
      <realm name="kerberos-properties" role-decoder="groups-to-roles"/>
    </security-domain>
  </security-domains>
  <security-realms>
   ...
     <properties-realm name="kerberos-properties">
       <users-properties path="kerberos-users.properties" relative-to="kerberos" digest-realm-name="ELYTRON.ORG"/>
       <groups-properties path="kerberos-groups.properties" relative-to="kerberos"/>
     </properties-realm>
   </security-realms>
   <credential-security-factories>
     <kerberos-security-factory name="test-server" principal="remote/test-server.elytron.org@ELYTRON.ORG" path="remote-test-server.keytab" relative-to="kerberos"/>
   </credential-security-factories>
   ...
   <sasl>
     ...
     <sasl-authentication-factory name="gssapi-authentication-factory" sasl-server-factory="elytron" security-domain="KerberosDomain">
       <mechanism-configuration>
         <mechanism mechanism-name="GSSAPI" credential-security-factory="test-server"/>
       </mechanism-configuration>
     </sasl-authentication-factory>
     ...
   </sasl>
 </subsystem>

This section describes how to migrate a PicketBox or legacy security realm configuration that uses multiple identity stores to Elytron Aggregate Security Realm Configuration.

When using either PicketBox or the legacy security realms, it is possible to define a configuration where authentication is performed against one identity store while the information used for authorization is loaded from a different store. When migrating to Elytron, this can be achieved by using an aggregate security realm.

The following examples perform user authentication using the example-users.properties properties file, and then query LDAP to load the group and role information.

/subsystem=security/security-domain=application-security:add

/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[ {code=UsersRoles, flag=Required, module-options={ password-stacking=useFirstPass, usersProperties=file://${jboss.server.config.dir}/example-users.properties}} {code=LdapExtended, flag=Required, module-options={ password-stacking=useFirstPass, java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org",roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

<security-domain name="application-security">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="usersProperties" value="file://${jboss.server.config.dir}/example-users.properties"/>
    </login-module>
    <login-module code="LdapExtended" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
      <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
      <module-option name="java.naming.security.authentication" value="simple"/>
      <module-option name="bindDN" value="uid=admin,ou=system"/>
      <module-option name="bindCredential" value="secret"/>
      <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
      <module-option name="baseFilter" value="(uid={0})"/>
      <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
      <module-option name="roleFilter" value="(uniqueMember={1})"/>
      <module-option name="roleAttributeID" value="uid"/>
    </login-module>
  </authentication>
</security-domain>

/core-service=management/ldap-connection=MyLdapConnection:add(url="ldap://localhost:10389", search-dn="uid=admin,ou=system", search-credential="secret")

/core-service=management/security-realm=ApplicationSecurity:add
/core-service=management/security-realm=ApplicationSecurity/authentication=properties:add(path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true)

batch
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap:add(connection=MyLdapConnection)
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap/username-to-dn=username-filter:add(attribute=uid, base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org")
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap/group-search=group-to-principal:add(base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", iterative=true, prefer-original-connection=true, principal-attribute=uniqueMember, search-by=DISTINGUISHED_NAME, group-name=SIMPLE, group-name-attribute=uid)
run-batch

<security-realms>
  ...
  <security-realm name="ApplicationSecurity">
    <authentication>
      <properties path="example-users.properties" relative-to="jboss.server.config.dir" plain-text="true"/>
    </authentication>
    <authorization>
      <ldap connection="MyLdapConnection">
        <username-to-dn>
          <username-filter base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org" attribute="uid"/>
        </username-to-dn>
        <group-search group-name="SIMPLE" iterative="true" group-name-attribute="uid">
          <group-to-principal search-by="DISTINGUISHED_NAME" base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org" prefer-original-connection="true">
            <membership-filter principal-attribute="uniqueMember"/>
          </group-to-principal>
        </group-search>
      </ldap>
    </authorization>
  </security-realm>
</security-realms>
<outbound-connections>
  <ldap name="MyLdapConnection" url="ldap://localhost:10389" search-dn="uid=admin,ou=system" search-credential="secret"/>
</outbound-connections>

/subsystem=elytron/dir-context=ldap-connection:add(url=ldap://localhost:10389, principal="uid=admin,ou=system", credential-reference={clear-text=secret})

/subsystem=elytron/ldap-realm=ldap-realm:add(dir-context=ldap-connection, direct-verification=true, identity-mapping={search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org", rdn-identifier="uid", attribute-mapping=[{filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org",filter="(uniqueMember={1})",from="uid",to="Roles"}]})

/subsystem=elytron/properties-realm=application-properties:add(users-properties={path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true, digest-realm-name="Application Security"})

/subsystem=elytron/aggregate-realm=combined-realm:add(authentication-realm=application-properties, authorization-realm=ldap-realm)

/subsystem=elytron/security-domain=application-security:add(realms=[{realm=combined-realm}], default-realm=combined-realm, permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=application-security-http:add(http-server-mechanism-factory=global, security-domain=application-security, mechanism-configurations=[{mechanism-name=BASIC}])

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="application-security" default-realm="combined-realm" permission-mapper="default-permission-mapper">
      <realm name="combined-realm"/>
    </security-domain>
  </security-domains>
  <security-realms>
    <aggregate-realm name="combined-realm" authentication-realm="application-properties" authorization-realm="ldap-realm"/>
      ...
      <properties-realm name="application-properties">
        <users-properties path="example-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="Application Security" plain-text="true"/>
      </properties-realm>
      <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
        <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
          <attribute-mapping>
            <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
          </attribute-mapping>
        </identity-mapping>
      </ldap-realm>
  </security-realms>
  ...
  <http>
    ...
    <http-authentication-factory name="application-security-http" http-server-mechanism-factory="global" security-domain="application-security">
      <mechanism-configuration>
        <mechanism mechanism-name="BASIC"/>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
  </http>
  ...
  <dir-contexts>
    <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
      <credential-reference clear-text="secret"/>
    </dir-context>
  </dir-contexts>
</subsystem>

When using PicketBox, it was possible to define a security domain and enable in-memory caching for its access. This allowed you to access the identity data in memory and avoid additional direct access to the identity store. It is possible to achieve a similar configuration with Elytron. This section shows an example PicketBox configuration and equivalent security domain caching configuration when using Elytron.

/subsystem=security/security-domain=application-security:add(cache-type=default)
/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=LdapExtended, flag=Required, module-options={ java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="application-security" cache-type="default">
      <authentication>
        <login-module code="LdapExtended" flag="required">
          <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
          <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
          <module-option name="java.naming.security.authentication" value="simple"/>
          <module-option name="bindDN" value="uid=admin,ou=system"/>
          <module-option name="bindCredential" value="secret"/>
          <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="baseFilter" value="(uid={0})"/>
          <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="roleFilter" value="(uniqueMember={1})"/>
          <module-option name="roleAttributeID" value="uid"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="application-security" default-realm="cached-ldap" permission-mapper="default-permission-mapper">
      <realm name="cached-ldap"/>
    </security-domain>
  </security-domains>
  ...
  <security-realms>
    ....
  <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
      <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
        <attribute-mapping>
          <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
        </attribute-mapping>
      </identity-mapping>
    </ldap-realm>
    <caching-realm name="cached-ldap" realm="ldap-realm"/>
  </security-realms>
  ...
  <http>
    ...
    <http-authentication-factory name="application-security-http" http-server-mechanism-factory="global" security-domain="application-security">
      <mechanism-configuration>
        <mechanism mechanism-name="BASIC"/>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
  </http>
   ...
  <dir-contexts>
    <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
      <credential-reference clear-text="secret"/>
    </dir-context>
  </dir-contexts>
  ...

By default, JBoss EAP 7.4 and earlier uses the legacy security subsystem to configure the Jakarta Authorization policy provider and factory. The default configuration maps to implementations from PicketBox.

The elytron subsystem provides a built-in policy provider based on the Java Authorization Contract for Containers (JACC) specification.

For information about how to enable and define a Java Authorization Contract for Containers policy provider in the elytron subsystem, see Define a Jakarta Authentication Policy Provider in the JBoss EAP 7.4 Development Guide.

Migrate your naming client to Elytron using the configuration approach.

Using this approach, you provide the user credentials that are used to establish a connection to the naming provider directly in the application code.

// Create the authentication configuration
AuthenticationConfiguration namingConfig = AuthenticationConfiguration.empty().useName("bob").usePassword("secret");

// Create the authentication context
AuthenticationContext context = AuthenticationContext.empty().with(MatchRule.ALL.matchHost("127.0.0.1"), namingConfig);

// Create a callable that creates and uses an InitialContext
Callable<Void> callable = () -> {
    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY,"org.wildfly.naming.client.WildFlyInitialContextFactory");
    properties.put(Context.PROVIDER_URL,"remote+http://127.0.0.1:8080");
    InitialContext context = new InitialContext(properties);
    Bar bar = (Bar) context.lookup("foo/bar");
    ...
    return null;
};

// Use the authentication context to run the callable
context.runCallable(callable);

This migration example assumes that the client application is configured to invoke an Jakarta Enterprise Beans deployed to a remote server using a jboss-ejb-client.properties file. This file, which is located in the client application META-INF/ directory, contains the following information needed to connect to the remote server.

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=127.0.0.1
remote.connection.default.port = 8080
remote.connection.default.username=bob
remote.connection.default.password=secret

The client looks up the Jakarta Enterprise Beans and calls one of its methods using code similar to the following example.

// Create an InitialContext
Properties properties = new Properties();
properties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
InitialContext context = new InitialContext(properties);

// Look up the Jakarta Enterprise Beans and invoke one of its methods
RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
    "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
int sum = statelessRemoteCalculator.add(101, 202);

You can choose from one of the following migration approaches:

// Create the authentication configuration
AuthenticationConfiguration ejbConfig = AuthenticationConfiguration.empty().useName("bob").usePassword("secret");

// Create the authentication context
AuthenticationContext context = AuthenticationContext.empty().with(MatchRule.ALL.matchHost("127.0.0.1"), ejbConfig);

// Create a callable that invokes the Jakarta Enterprise Beans
Callable<Void> callable = () -> {

    // Create an InitialContext
    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.wildfly.naming.client.WildFlyInitialContextFactory");
    properties.put(Context.PROVIDER_URL, "remote+http://127.0.0.1:8080");
    InitialContext context = new InitialContext(properties);

    // Look up the Jakarta Enterprise Beans and invoke one of its methods
    // Note that this code is the same as before
    RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
        "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
    int sum = statelessRemoteCalculator.add(101, 202);
    ...
    return null;
};

// Use the authentication context to run the callable
context.runCallable(callable);

To enable CLIENT-CERT SSL authentication, add a truststore element to the authentication element.

<security-realm name="ManagementRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="KEYSTORE_PASSWORD" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
  <authentication>
    <truststore path="server.truststore" relative-to="jboss.server.config.dir" keystore-password="TRUSTSTORE_PASSWORD" />
    <local default-user="$local"/>
    <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
  </authentication>
</security-realm>

A legacy truststore can be used in two ways:

<subsystem xmlns="urn:wildfly:elytron:4.0"...>
  ...
  <tls>
    <key-stores>
      <key-store name="LocalhostKeyStore">
        <credential-reference clear-text="keystore_password"/>
        <implementation type="JKS"/>
        <file path="server.keystore" relative-to="jboss.server.config.dir"/>
      </key-store>
      <key-store name="TrustStore">
        <credential-reference clear-text="truststore_password"/>
        <implementation type="JKS"/>
        <file path="server.truststore" relative-to="jboss.server.config.dir"/>
      </key-store>
    </key-stores>
    <key-managers>
      <key-manager name="LocalhostKeyManager" key-store="LocalhostKeyStore" alias-filter="server">
        <credential-reference clear-text="key_password"/>
      </key-manager>
    </key-managers>
    <trust-managers>
      <trust-manager name="TrustManager" key-store="TrustStore"/>
    </trust-managers>
    <server-ssl-contexts>
      <server-ssl-context name="LocalhostSslContext" need-client-auth="true" key-manager="LocalhostKeyManager" trust-manager="TrustManager"/>
    </server-ssl-contexts>
  </tls>
</subsystem>

<subsystem xmlns="urn:jboss:domain:undertow:14.0">
...
<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>
...
</subsystem>

<security-domains>
    <security-domain name="ManagementDomain" default-realm="ManagementRealm" permission-mapper="default-permission-mapper">
        <realm name="ManagementRealm" role-decoder="groups-to-roles"/>
        <realm name="local"/>
    </security-domain>
</security-domains>
<security-realms>
    <properties-realm name="ManagementRealm">
        <users-properties path="mgmt-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="ManagementRealm"/>
        <groups-properties path="mgmt-groups.properties" relative-to="jboss.server.config.dir"/>
    </properties-realm>
</security-realms>

/subsystem=elytron/x500-attribute-principal-decoder=x500-decoder:add(attribute-name=CN)

/subsystem=elytron/configurable-http-server-mechanism-factory=configured-cert:add(http-server-mechanism-factory=global, properties={org.wildfly.security.http.skip-certificate-verification=true})

./subsystem=elytron/http-authentication-factory=client-cert-digest:add(http-server-mechanism-factory=configured-cert,security-domain=ManagementDomain,mechanism-configurations=[{mechanism-name=CLIENT_CERT,pre-realm-principal-transformer=x500-decoder},{mechanism-name=DIGEST, mechanism-realm-configurations=[{realm-name=ManagementRealm}]}])

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <http>
    ...
    <http-authentication-factory name="client-cert-digest" http-server-mechanism-factory="configured-cert" security-domain="ManagementDomain">
      <mechanism-configuration>
        <mechanism mechanism-name="CLIENT_CERT" pre-realm-principal-transformer="x500-decoder"/>
        <mechanism mechanism-name="DIGEST">
          <mechanism-realm realm-name="ManagementRealm"/>
        </mechanism>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
    <configurable-http-server-mechanism-factory name="configured-cert" http-server-mechanism-factory="configured-cert">
        <properties>
            <property name="org.wildfly.security.http.skip-certificate-verification" value="true"/>
        </properties>
    </configurable-http-server-mechanism-factory>
    ...
  </http>
  ...
</subsystem>