Migration Guide

Log messages are prefixed with the project code for the subsystem that reports the message. The prefixes for all log messages have changed in JBoss EAP 7.

For a complete list of the new log message project code prefixes used in JBoss EAP 7, see Project Codes Used in JBoss EAP in the JBoss EAP Development Guide.

The JBoss EAP 7.0 root logger included a console log handler for all domain server profiles and for all default standalone profiles except the standalone-full-ha profile. The JBoss EAP 7.1 root logger no longer includes a console log handler for the managed domain profiles. The host controller and process controller log to the console by default. To achieve the same functionality that was provided in JBoss EAP 7.0, see Configure a Console Log Handler in the Configuration Guide for JBoss EAP.

Undertow replaces JBoss Web as the web server in JBoss EAP 7. This means the legacy web subsystem configuration must be migrated to the new JBoss EAP 7 undertow subsystem configuration.

You can use the management CLI migrate operation to migrate the web subsystem to undertow in the server configuration file. However, be aware that this operation is not able to migrate all JBoss Web subsystem configurations. If you see "migration-warning" entries, you must run additional management CLI commands to migrate those configurations to Undertow. For more information about the management CLI migrate operation, see Management CLI Migration Operation.

The following is an example of the default web subsystem configuration in JBoss EAP 6.

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
    <virtual-server name="default-host" enable-welcome-root="true">
        <alias name="localhost"/>
        <alias name="example.com"/>
    </virtual-server>
</subsystem>

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

<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"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
        </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 management CLI migrate operation is not able to automatically migrate rewrite conditions. They are reported as "migration-warnings", and you must migrate them manually. You can create the equivalent configuration in JBoss EAP 7 by using Undertow Predicates Attributes and Handlers.

The following is an example of a web subsystem configuration in JBoss EAP 6 that includes rewrite configuration.

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default" native="false">
    <virtual-server name="default" enable-welcome-root="true">
        <alias name="localhost"/>
        <rewrite name="test" pattern="(.*)/toberewritten/(.*)" substitution="$1/rewritten/$2" flags="NC"/>
        <rewrite name="test2" pattern="(.*)" substitution="-" flags="F">
            <condition name="get" test="%{REQUEST_METHOD}" pattern="GET"/>
            <condition name="andCond" test="%{REQUEST_URI}" pattern=".*index.html" flags="NC"/>
        </rewrite>
    </virtual-server>
</subsystem>

Follow the Management CLI Migration Operation instructions to start your server and the management CLI, then migrate the web subsystem configuration file using the following command.

/subsystem=web:migrate

The following "migration-warnings" are reported when you run the migrate operation on the above configuration.

/subsystem=web:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => [
        "WFLYWEB0002: Could not migrate resource {
    \"pattern\" => \"(.*)\",
    \"substitution\" => \"-\",
    \"flags\" => \"F\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_METHOD}\",
    \"pattern\" => \"GET\",
    \"flags\" => undefined,
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"get\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_URI}\",
    \"pattern\" => \".*index.html\",
    \"flags\" => \"NC\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"andCond\")
    ]
}"
    ]}
}

Review the server configuration file and you see the following configuration for the undertow subsystem.

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
     <buffer-cache name="default"/>
     <server name="default-server">
         <http-listener name="http" socket-binding="http"/>
         <host name="default-host" alias="localhost, example.com">
             <location name="/" handler="welcome-content"/>
         </host>
     </server>
     <servlet-container name="default">
         <jsp-config/>
     </servlet-container>
     <handlers>
         <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
     </handlers>
 </subsystem>

Use the management CLI to create the filter to replace the rewrite configuration in the undertow subsystem. You should see "{"outcome" ⇒ "success"}" for each command.

# Create the filters
/subsystem=undertow/configuration=filter/expression-filter="test1":add(expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')")
/subsystem=undertow/configuration=filter/expression-filter="test2":add(expression="method('GET') and path('.*index.html') -> response-code(403)")

# Add the filters to the default server
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test1":add
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test2":add

Review the updated server configuration file. The JBoss Web subsystem is now completely migrated and configured in the undertow subsystem.

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="http" socket-binding="http"/>
        <host name="default-host" alias="localhost, example.com">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="test1"/>
            <filter-ref name="test2"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <expression-filter name="test1" expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')"/>
        <expression-filter name="test2" expression="method('GET') and path('.*index.html') -> response-code(403)"/>
    </filters>
</subsystem>

For more information about how to configure filters and handlers using the management CLI, see Configuring the Web Server in the JBoss EAP 7 Configuration Guide.

In the previous release of JBoss EAP, system properties could be used to modify the default JBoss Web behavior. For information about how to configure the same behavior in Undertow, see JBoss Web System Properties Migration Reference

When you migrate from JBoss EAP 6.4 to JBoss EAP 7.1, you might find that the access logs no longer write the expected "Referer" and "User-agent" values. This is because JBoss Web, which was included in JBoss EAP 6.4, used a pattern of %{headername}i in the access-log to log an incoming header.

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{Referer}i&quot; &quot;%{User-agent}i&quot;"/>

With the change to use Undertow in JBoss EAP 7.1, the pattern for an incoming header has changed to %{i,headername}.

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{i,Referer}&quot; &quot;%{i,User-Agent}&quot;"/>

Previous releases of JBoss EAP supported valves. Valves are custom classes inserted into the request processing pipeline for an application before servlet filters to make changes to the request or perform additional processing.

This section describes how to migrate global valves. Migration of custom and authenticator valves are covered in the Migrate Custom Application Valves section of this guide.

Undertow, which replaces JBoss Web in JBoss EAP 7, does not support global valves; however, you should be able to achieve similar functionality by using Undertow handlers. Undertow includes a number of built-in handlers that provide common functionality. It also provides the ability to create custom handlers, which can be used to replace custom valve functionality.

If your application uses valves, you must replace them with the appropriate Undertow handler code to achieve the same functionality when you migrate to JBoss EAP 7.

For more information about how to configure handlers, see Configuring Handlers in the JBoss EAP 7 Configuration Guide.

For more information about how to configure filters, see Configuring Filters in the JBoss EAP 7 Configuration Guide.

Migrate JBoss Web Valves

The following table lists the valves that were provided by JBoss Web in the previous release of JBoss EAP and the corresponding Undertow built-in handler. The JBoss Web valves are located in the org.apache.catalina.valves package.

You can use the management CLI migrate operation to automatically migrate global valves that meet the following criteria:

For more information about the management CLI migrate operation, see Management CLI Migration Operation.

JDBCAccessLogValve Manual Migration Procedure

The org.apache.catalina.valves.JDBCAccessLogValve valve is an exception to the rule and can not be automatically migrated to io.undertow.server.handlers.JDBCLogHandler. Follow the steps below to migrate the following example valve.

<valve name="jdbc" module="org.jboss.as.web" class-name="org.apache.catalina.valves.JDBCAccessLogValve">
    <param param-name="driverName" param-value="com.mysql.jdbc.Driver" />
    <param param-name="connectionName" param-value="root" />
    <param param-name="connectionPassword" param-value="password" />
    <param param-name="connectionURL" param-value="jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull" />
    <param param-name="format" param-value="combined" />
</valve>

Previous specifications for Set-Cookie HTTP response header syntax, for example RFC2109 and RFC2965, allowed white space and other separator characters in the cookie value when the cookie value was quoted. JBoss Web in JBoss EAP 6.4 conformed to the previous specifications and automatically quoted a cookie value when it contained any separator characters.

The RFC6265 specification for Set-Cookie HTTP response header syntax states that cookie values in the Set-Cookie response header must conform to specific grammar constraints. For example, they must be US-ASCII characters, but they cannot include CTRLs (controls), whitespace, double quotes, commas, semicolons, or backslash characters.

In JBoss EAP 7.0, prior to cumulative patch Red Hat JBoss Enterprise Application Platform 7.0 Update 08, Undertow does not restrict these invalid characters and does not quote cookies that contained the excluded characters. If you apply this cumulative patch or a newer cumulative patch you can enable RFC6265 compliant cookie validation by setting the io.undertow.cookie.DEFAULT_ENABLE_RFC6265_COOKIE_VALIDATION system property to true.

In JBoss EAP 7.1, by default, Undertow does not enable RFC6265 compliant cookie validation. It does quote cookies that contain the excluded characters. In JBoss EAP 7.1, you cannot use the io.undertow.cookie.DEFAULT_ENABLE_RFC6265_COOKIE_VALIDATION system property to enable RFC6265 compliant cookie validation. Instead, you enable RFC6265 compliant cookie validation for an HTTP, HTTPS, or AJP listener by setting the rfc6265-cookie-validation listener attribute to true. The default value for this attribute is false. The following example enables RFC6265 compliant cookie validation for the HTTP listener.

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=rfc6265-cookie-validation,value=true)

JBoss EAP 6.4, which included JBoss Web as the web server, allowed HTTP TRACE method calls by default.

Undertow, which replaces JBoss Web as the web server in JBoss EAP 7, disallows HTTP TRACE method calls by default. This setting is configured using the disallowed-methods attribute of the http-listener element in the undertow subsystem. This can be confirmed by reviewing the output from the following read-resource command. Note that the value for the disallowed-methods attribute is ["TRACE"].

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => ["TRACE"],
         ...
    }
}

To enable HTTP TRACE method calls in JBoss EAP 7 and later, you must remove the "TRACE" entry from the disallowed-methods attribute list by running the following command.

/subsystem=undertow/server=default-server/http-listener=default:list-remove(name=disallowed-methods,value="TRACE")

When you run the read-resource command again, you will notice the TRACE method call is no longer in the list of disallowed methods.

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => [],
         ...
    }
}

For more information about the default behavior of HTTP methods, see Default Behavior of HTTP Methods in the JBoss EAP Configuration Guide.

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

This is no longer the case in JBoss EAP 7.1. 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

For more information about how to configure the default welcome web application, see Configure the Default Welcome Web Application in the Development Guide for JBoss EAP.

In the JBoss EAP 6 default configuration, JGroups used the public interface defined in the <interfaces> section of the server configuration file.

Because it is a recommended practice to use a dedicated network interface, JGroups now defaults to using the new private interface that is defined in the <interfaces> section of the server configuration file in JBoss EAP 7.

JGroups provides group communication support for HA services in the form of JGroups channels. JBoss EAP 7 introduces <channel> elements to the jgroups subsystem in the server configuration file. You can add, remove, or change the configuration of JGroups channels using the management CLI.

For more information about how to configure JGroups, see Cluster Communication with JGroups in the JBoss EAP Configuration Guide.

In JBoss EAP 6, the default clustered caches for web session replication and EJB replication were replicated ASYNC caches. This has changed in JBoss EAP 7. The default clustered caches are now distributed ASYNC caches. The replicated caches are no longer even configured by default. See Configure the Cache Mode in the JBoss EAP Configuration Guide for information about how to add a replicated cache and make it the default.

This only affects you when you use the new JBoss EAP 7 default configuration. If you migrate the configuration from JBoss EAP 6, the configuration of the infinispan subsystem will be preserved.

The behavior of ASYNC cache strategy has changed in JBoss EAP 7.

In JBoss EAP 6, ASYNC cache reads were lock free. Although they would never block, the were prone to dirty reads of stale data, for example on failover. This is because it would allow subsequent requests for the same user to start before the previous request completed. This permissiveness is not acceptable when using distributed mode, since cluster topology changes can affect session affinity and easily result in stale data.

In JBoss EAP 7, ASYNC cache reads require locks. Since they now block new requests from the same user until the previous replication finishes, dirty reads are prevented.

Be aware of the following restrictions when configuring a custom stateful session bean (SFSB) cache for passivation in JBoss EAP 7.1.

A change in behavior between JBoss EAP 7.0 and JBoss EAP 7.1 requires that any updates to the cache container transport protocol to be done in batch mode or using a special header. This change in behavior also impacts any tools that are used to manage 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. Be aware that this restarts the service so that the operations can take effect, and some services might stop working until the service is restarted.

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

The org.jboss.as.messaging module extension, located in EAP_HOME/modules/system/layers/base/, has been replaced by the org.wildfly.extension.messaging-activemq extension module.

The urn:jboss:domain:messaging:3.0 subsystem configuration namespace has been replaced by the urn:jboss:domain:messaging-activemq:2.0 namespace.

Management Model

In most cases, an effort was made to keep the element and attribute names as similar as possible to those used in previous releases. The following table lists some of the changes.

The management operations invoked on the new messaging-activemq subsystem have changed from /subsystem=messaging/hornetq-server= to /subsystem=messaging-activemq/server=.

You can migrate an existing JBoss EAP 6 messaging subsystem configuration to the messaging-activemq subsystem on a JBoss EAP 7 server by invoking its migrate operation.

/subsystem=messaging:migrate

Before you execute the migrate operation, you can invoke the describe-migration operation to review the list of management operations that will be performed to migrate from the existing JBoss EAP 6 messaging subsystem configuration to the messaging-activemq subsystem on the JBoss EAP 7 server.

/subsystem=messaging:describe-migration

The migrate and describe-migration operations also display a list of migration-warnings for resources or attributes that can not be migrated automatically.

Messaging Subsystem Migration and Forward Compatibility

The describe-migration and migrate operations for the messaging subsystem provide an additional configuration argument. If you want to configure messaging to allow legacy JBoss EAP 6 clients to connect to the JBoss EAP 7 server, you can add the boolean add-legacy-entries argument to the describe-migration or migrate operation as follows.

/subsystem=messaging:describe-migration(add-legacy-entries=true)
/subsystem=messaging:migrate(add-legacy-entries=true)

If the boolean argument add-legacy-entries is set to true, the messaging-activemq subsystem creates the legacy-connection-factory resource and adds legacy-entries to the jms-queue and jms-topic resources.

If the boolean argument add-legacy-entries is set to false, no legacy resources are created in the messaging-activemq subsystem and legacy JMS clients will not be able to communicate with the JBoss EAP 7 servers. This is the default value.

For more information about forward and backward compatibility see the Backward and Forward Compatibility in Configuring Messaging for JBoss EAP.

For more information about the management CLI migrate and describe-migration operations, see Management CLI Migration Operation.

Change in Behavior of forward-when-no-consumers Attribute

The behavior of the forward-when-no-consumers attribute has changed in JBoss EAP 7.

In JBoss EAP 6, when forward-when-no-consumers was set to false and there were no consumers in a cluster, messages were redistributed to all nodes in a cluster.

This behavior has changed in JBoss EAP 7. When forward-when-no-consumers is set to false and there are no consumers in a cluster, messages are not redistributed. Instead, they are kept on the original node to which they were sent.

Change in Default Cluster Load Balancing Policy

The default cluster load balancing policy has changed in JBoss EAP 7.

In JBoss EAP 6, the default cluster load balancing policy was similar to STRICT, which is like setting the legacy forward-when-no-consumers parameter to true. In JBoss EAP 7, the default is now ON_DEMAND, which is like setting the legacy forward-when-no-consumers parameter to false. For more information about these settings, see Cluster Connection Attributes in Configuring Messaging for JBoss EAP.

Messaging Subsystem XML Configuration

The XML configuration has changed significantly with the new messaging-activemq subsystem, and now provides an XML scheme more consistent with other JBoss EAP subsystems.

It is strongly advised that you do not attempt to modify the JBoss EAP messaging subsystem XML configuration to conform to the new messaging-activemq subsystem. Instead, invoke the legacy subsystem migrate operation. This operation will write the XML configuration of the new messaging-activemq subsystem as a part of its execution.

You can use one of the following approaches to migrate messaging data from a previous release to the current release of JBoss EAP.

Due to the change from HornetQ to ActiveMQ Artemis as the JMS support provider, both the format and the location of the messaging data changed in JBoss EAP 7.0 and later. See Mapping Messaging Folder Names for details of the changes to the messaging data folder names and locations between the 6.4 and 7.x releases.

$ java -jar -mp MODULE_PATH org.hornetq.exporter MESSAGING_BINDINGS_DIRECTORY MESSAGING_JOURNAL_DIRECTORY MESSAGING_PAGING_DIRECTORY MESSAGING_LARGE_MESSAGES_DIRECTORY > OUTPUT_DATA.xml

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.hornetq.exporter">
    <main-class name="org.hornetq.jms.persistence.impl.journal.XmlDataExporter"/>
    <properties>
        <property name="jboss.api" value="deprecated"/>
    </properties>
    <dependencies>
        <module name="org.hornetq"/>
    </dependencies>
</module>

/subsystem=messaging-activemq/server=default/path=journal-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=paging-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=bindings-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=large-messages-directory:resolve-path

In previous releases of JBoss EAP, JMS destination queues were configured in the <jms-destinations> element under the <hornetq-server> element in the messaging subsystem.

<hornetq-server>
  ...
  <jms-destinations>
     <jms-queue name="testQueue">
        <entry name="queue/test"/>
         <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
  </jms-destinations>
  ...
</hornetq-server>

In JBoss EAP 7, the JMS destination queue is configured in the default <server> element of the messaging-activemq subsystem.

<server name="default">
  ...
  <jms-queue name="testQueue" entries="queue/test java:jboss/exported/jms/queue/test"/>
  ...
</server>

Messaging interceptors have changed significantly in JBoss EAP 7 with the replacement of HornetQ with ActiveMQ Artemis as the JMS messaging provider.

The HornetQ messaging subsystem included in the previous release of JBoss EAP required that you install the HornetQ interceptors by adding them to a JAR and then modifying the HornetQ module.xml file.

The messaging-activemq subsystem included in JBoss EAP 7 does not require modification of a module.xml file. User interceptor classes, which now implement the Apache ActiveMQ Artemis Interceptor interface, can now be loaded from any server module. You specify the module from which the interceptor should be loaded in the messaging-activemq subsystem of the server configuration file.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:2.0">
  <server name="default">
    ...
    <incoming-interceptors>
      <class name="com.mycompany.incoming.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.incoming.myOtherInterceptor" module="com.othercompany" />
    </incoming-interceptors>
    <outgoing-interceptors>
      <class name="com.mycompany.outgoing.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.outgoing.myOtherInterceptor" module="com.othercompany" />
    </outgoing-interceptors>
  </server>
</subsystem>

In JBoss EAP 6, you could configure a servlet engine to work with the Netty Servlet transport. Because ActiveMQ Artemis replaces HornetQ as the built-in messaging provider in JBoss EAP 7, this configuration is no longer available. You must replace the servlet configuration to use the new built-in messaging HTTP connectors and HTTP acceptors instead.

The way you configure a generic JMS resource adapter for use with a third-party JMS provider has changed in JBoss EAP 7. For more information, see Deploying a Generic JMS Resource Adapter in Configuring Messaging for JBoss EAP.

In JBoss EAP 7.0, if you configured the replication-master policy without specifying the check-for-live-server attribute, its default value was false. This has changed in JBoss EAP 7.1. The default value for the check-for-live-server attribute is now true.

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

/subsystem=messaging-activemq/server=default/ha-policy=replication-master: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-master: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"}
}

The serialVersionUID of javax.jms.JMSException changed between JMS 1.1 and JMS 2.0.0. This means that if an instance of a JMSException, or any of its subclasses, is serialized using JMS 1.1, it cannot be deserialized using JMS 2.0.0. The reverse is also true. If an instance of JMSException is serialized using JMS 2.0.0, it cannot be deserialized using JMS 1.1. In both of these cases, it throws an exception similar to the following:

javax.jms.JMSException: javax.jms.JMSException; local class incompatible: stream classdesc serialVersionUID = 8951994251593378324, local class serialVersionUID = 2368476267211489441

This issue is fixed in the JMS 2.0.1 maintenance release.

The following table details the JMS implementation for each JBoss EAP release.

Be aware that the serialVersionUID incompatibility can result in a migration issue in the following situations:

Note that if you send a message that contains a JMSException using a JBoss EAP 6.4 client, migrate your messaging data to JBoss EAP 7.1, and then attempt to deserialize that message using a JBoss EAP 7.1 client, the deserialization will succeed because the serialVersionUID in JMS 1.1 is compatible with the one in JMS 2.0.1.

When you configured a datasource in the previous release of JBoss EAP, the value specified for the driver name depended on the number of classes listed in the META-INF/services/java.sql.Driver file contained in the JDBC driver JAR.

Driver Containing a Single Class

If the META-INF/services/java.sql.Driver file specified only one class, the driver name value was simply the name of the JDBC driver JAR. This has not changed in JBoss EAP 7.

Driver Containing Multiple Classes

IIn JBoss EAP 6, if there was more than one class listed in META-INF/services/java.sql.Driver file, you specified which class was the driver class by appending its name to the JAR name, along with the major and minor version, in the following format.

JAR_NAME + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION

In JBoss EAP 7, this has changed. You now specify the driver name using the following format.

JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION

The MySQL 5.1.31 JDBC driver is an example of a driver that contains two classes. The driver class name is com.mysql.jdbc.Driver. The following examples demonstrate the differences between how you specify the driver name in the previous and current release of JBoss EAP.

mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1

mysql-connector-java-5.1.31-bin.jar_com.mysql.jdbc.Driver_5_1

If you are running in FIPS mode, be aware that the default behavior has changed between JBoss EAP 7.0 and JBoss EAP 7.1.

When using legacy security realms, JBoss EAP 7.1 provides the automatic generation of a self-signed certificate for development purposes. This feature, which was not available in JBoss EAP 7.0, is enabled by default. This means that if you are running in FIPS mode, you must configure the server to disable automatic self-signed certificate creation. Otherwise, you might see the following error when you start 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

For information about automatic self-signed certificate creation, see Automatic Self-signed Certificate Creation for Applications in How to Configure Server Security for JBoss EAP.

The Java API for XML-based RPC (JAX-RPC) was deprecated in Java EE 6 and is optional in Java EE 7. It is no longer available or supported in JBoss EAP 7. Applications that use JAX-RPC must be migrated to use JAX-WS, which is the current Java 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 7. 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).

Apache CXF Interceptors

The JBossWS descriptor provides new configuration options that allow you to declare the interceptors without modifying the client endpoint code. Instead you declare interceptors within predefined client and endpoint configurations by specifying a list of interceptor class names for the cxf.interceptors.in and cxf.interceptors.out properties.

The following is an example of a jaxws-endpoint-config.xml file that declares interceptors using these properties.

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_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>

Apache CXF Features

The JBossWS descriptor allows you to declare features within predefined client and endpoint configurations by specifying a list of feature class names for the cxf.features property.

The following is an example of a jaxws-endpoint-config.xml file that declares a feature using this property.

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_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>

Apache CXF HTTP Transport

In Apache CXF, HTTP transport configuration is achieved by specifying org.apache.cxf.transport.http.HTTPConduit options. JBossWS integration allows conduits to be modified programmatically using the Apache CXF API as follows.

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);
...

You can also control and override the Apache CXF HTTPConduit default values by setting system properties.

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.

JBoss EAP 7 ships with the org.bouncycastle module and JBossWS is now 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.49, 1.51, 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 JAX-WS 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. JBoss EAP 7 ships with JBossWS 5, which no longer hides this requirement. This means that user provided service classes injected by the container must implement JAX-WS 2.2 or later by updating the existing code to use the javax.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.

If your application uses the JBossWS implementation of Apache CXF, JBoss EAP 7 ensures 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 EJB web service deployments in the META-INF/ directory of JAR archives or in the WEB-INF/ directory for POJO web service deployments and EJB web service endpoints bundled in WAR archives.

In JBoss EAP 7, you can now 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 both 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.

The proprietary HornetQ JMS resource deployment descriptor files identified by the naming pattern -jms.xml no longer work in JBoss EAP 7. The following is an example of a JMS 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 JMS deployment descriptors in your application in the previous release, you can either convert your application to use the standard Java EE 7 deployment descriptor as specified in section EE.5.18 of the Java EE 7 specification 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>

For information about server configuration changes related to messaging, see Messaging Server Configuration Changes.

JBoss EAP 7 still supports the JMS 1.1 API, so you do not need to modify your code.

The default remote connector and port has changed in JBoss EAP 7. For details about this change, see Update the Remote URL Connector and Port.

If you migrate your server configuration using the migrate operation, the old settings are preserved and you do not need to update your PROVIDER_URL. However, if you run with the new JBoss EAP 7 default configuration, you must change the PROVIDER_URL in the client code to use the new http-remoting://localhost:8080 setting. For more information, see Migrate Remote Naming Client Code.

If you plan to migrate your code to use the JMS 2.0 API, see the helloworld-jms quickstart for a working example.

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.

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 is replaced by the JAX-RS 2.0 compliant interceptor facility in RESTEasy 3.x. The relevant interfaces are defined in the javax.ws.rs.ext package of the jaxrs-api module.

For more information about interceptors, see RESTEasy Interceptors in Developing Web Services Applications for JBoss EAP.

For more information about the new replacement API, see the RESTEasy JAX-RS 3.0.13.Final API or later.

Client API

The RESTEasy client framework in resteasy-jaxrs has been replaced by the JAX-RS 2.0 compliant resteasy-client module. 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. This functionality can be replaced using the JAX-RS 2.0 jax.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 JAX-RS method should be cached on the server, was removed from RESTEasy 3 and must be removed from the application code.

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 new JAX-RS 2.0 client-side filters will not be bound and run when you are using the RESTEasy client API from the previous release.

Asynchronous HTTP Support

Because the JAX-RS 2.0 specification adds asynchronous HTTP support using the @Suspended annotation and the AsynResponse interface, the RESTEasy proprietary API for asynchronous HTTP has been 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 Developing Web Services Applications for JBoss EAP.

Default Charset UTF-8 in Content-Type Header

In 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 Developing Web Services Applications for JBoss EAP.

SerializableProvider

Deserializing Java objects from untrusted sources is not safe. For this reason, in 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 have been made to the implementation of matching rules, as defined in the JAX-RS 2.0 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();
    }
}

SPI Exceptions

All SPI failure exceptions have been deprecated and are no longer used internally. They have been replaced with the corresponding JAX-RS 2.0 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 has changed. The previous version of JBoss EAP included Jackson 1.9.9. JBoss EAP 7 now includes Jackson 2.6.3 or greater. As a result, 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.

To switch your application to use the default provider that was included in the previous release of JBoss EAP, see Switching the Default Jackson Provider in Developing Web Services Applications for JBoss EAP.

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 in 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 Development Guide.

The integration classes that made it easier to use Hibernate ORM 3 in the previous release were removed from JBoss EAP 7. If your application still uses Hibernate ORM 3 libraries, it is strongly recommended that you migrate your application to use Hibernate ORM 5 as Hibernate ORM 3 will no longer work in JBoss EAP without a lot of effort. If you can not migrate to Hibernate ORM 5, you must define a custom JBoss Module for the Hibernate ORM 3 JARs and exclude the Hibernate ORM 5 classes from your application.

If your application needs second-level cache enabled, you should migrate to Hibernate ORM 5, which is integrated with Infinispan 8.x.

Applications written with Hibernate ORM 4.x can still use Hibernate ORM 4.x. You must define a custom JBoss module for the Hibernate ORM 4.x JARs and exclude the Hibernate ORM 5 classes from your application. However, it is strongly recommended that you rewrite your application code to use Hibernate ORM 5. For information about migrating to Hibernate ORM 5, see Migrating to Hibernate ORM 5.

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

While JBoss EAP 7.0 included Hibernate ORM 5.0, JBoss EAP 7.1 now includes 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 includes many performance improvements and bug fixes, which are detailed in Hibernate ORM 5.1 Features in the JBoss EAP 7.1.0 Release Notes. 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 mainly focused in the following areas:

The schema management tooling changes should only be a migration concern for applications that directly use any of the following classes:

Schema Management Tooling Changes in JBoss EAP 7.1

Hibernate ORM 5.1.10 which is included in JBoss EAP 7.1, introduced a new strategy for retrieving database tables that improves 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, which executes 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.

In JBoss EAP 7.0, unsynchronized persistence context error checking was not as strict as it should have been in the following areas.

In addition, PersistenceProperty hints in the @PersistenceContext were mistakenly ignored in JBoss EAP 7.0.

These issues were addressed and fixed in JBoss EAP 7.1. Because these updates can result in an unwanted change in application behavior, two new persistence unit properties were introduced in JBoss EAP 7.1 to provide backward compatibility and preserve the previous behavior.

The default remote connector and port has changed in JBoss EAP 7. For details about this change, see Update the Remote URL Connector and Port.

If you used the migrate operation to migrate your server configuration, the old settings are preserved and you do not need to make the changes detailed below. However, if you run with the new JBoss EAP 7 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

While JBoss EAP 7.0 shipped with JBoss EJB Client 2.1.4, JBoss EAP 7.1 ships with JBoss EJB 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.1. 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 Implementing a Custom HTTP Mechanism in the Development Guide for JBoss EAP.

For information about the changes required for SSO with SAML v2 configuration, see Changes from Previous Versions of JBoss EAP in How To Set Up SSO with SAML v2 for JBoss EAP.

For information about the differences in SSO configuration with Kerberos, see Differences from Configuring Previous Versions JBoss EAP in How to Set Up SSO with Kerberos for JBoss EAP.

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 7.

The remainder of this section describes how clustering changes might impact the migration of your applications to JBoss EAP 7.

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 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.

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

JBoss EAP 7 no longer requires you 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 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 7.

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

The vault that was 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, which uses a newly designed credential store to store strings. Credential stores safely 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.

If you continue to use the legacy security subsystem, you should not need to modify or update your vault data. However, if you plan to migrate your application to use Elytron, you must convert your existing vaults to credential stores so that they can be processed by the elytron subsystem. For more information about credential stores, see Credential Stores in How to Configure Server Security for JBoss EAP.

Migrating Vault Data Using the WildFly Elytron Tool

The WildFly Elytron Tool that ships with JBoss EAP provides a vault command to help you migrate vault content to credential stores. You execute the tool by running the elytron-tool script, which is located in the EAP_HOME/bin directory.

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

If you prefer, you can execute the tool by running the java -jar command.

$ java -jar EAP_HOME/bin/wildfly-elytron-tool.jar vault VAULT_ARGUMENTS

You can use the following command to get a description of all of the available arguments.

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

Choose one of the following migration options:

Migrate a Single Security Vault to a Credential Store

The following is an example of the command used to convert a single security vault to a credential store.

$ 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

This command converts the security vault to a credential store and prints the summary of the management CLI commands that were used to convert it in the output.

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"})

Migrate Multiple Security Vaults to a Credential Store in Bulk

You can convert multiple vaults to a credential store using the --bulk-convert argument and pointing to a bulk conversion descriptor file.

The examples in this section use the following bulk conversion descriptor file.

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

A new conversion starts when each new keystore: line is encountered. All options are mandatory except for salt, iteration, and properties.

To perform the bulk conversion and generate output that formats the management CLI commands, execute the following command.

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

This command converts all of the security vaults specified in the file to a credential store and prints the summary of the management CLI commands that were used to convert them in the output.

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 examples in this section assume that the group.name and encoding.algorithm security properties are defined as security-properties in the legacy security subsystem as follows.

<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 the same 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 configures the following security-properties in the elytron subsystem in the server configuration file.

<subsystem xmlns="urn:wildfly:elytron:1.2" 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 used 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)

This section describes how to migrate legacy LDAP authentication to Elytron so that it can manage the information as identity attributes. Much of the information provided in the section entitled Migrate Properties-based Authentication and Authorization to Elytron applies here, particularly regarding how to define security domains and authentication factories, and how to map them to be used for authentication. This section does not repeat those instructions, so be sure to read through that section before you continue.

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:1.2" 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>

This section describes how to migrate JDBC datasource-based PicketBox authentication to Elytron. Much of the information provided in the section entitled Migrate Properties-based Authentication and Authorization to Elytron applies here, particularly regarding how to define security domains and authentication factories, and how to map them to be used for authentication. This section does not repeat those instructions, so be sure to read through that section before you continue.

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:1.2" 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. This section discusses how to migrate Kerberos HTTP and Kerberos SASL authentication.

The examples that follow assume that Kerberos is configured using the following 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>

Choose one of the following migration options:

Migrate Kerberos HTTP Authentication

In legacy security configurations, you can define a security realm to enable SPNEGO authentication for the HTTP management interface as follows.

/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>

You can also define a pair of legacy security domains to allow applications to use Kerberos HTTP authentication.

# 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>

The legacy applications are then deployed referencing the SPNEGO security domain and secured with the SPNEGO mechanism.

Migrate the Kerberos HTTP Authentication to Elytron

Both the management interface and applications can be secured in Elytron by using a security realm and a Kerberos security factory.

Migrate Kerberos Remoting SASL Authentication

It is possible to define a legacy security realm for Kerberos / GSSAPI SASL authentication to be used for remoting authentication, such as the native management interface.

/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>

Migrate the Kerberos Remoting SASL Authentication to Elytron

The steps to define the equivalent Elytron configuration are very similar to those described in Migrate Kerberos HTTP Authentication.

This results in the following configuration in the elytron subsystem of the server configuration file.

<subsystem xmlns="urn:wildfly:elytron:1.2" 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>

The management interface or remoting connectors can now be updated to reference the SASL authentication factory.

The two Elytron examples defined here could also be combined to use a shared security domain and security realm and just use protocol-specific authentication factories each referencing their own Kerberos security factory.

This section describes how to migrate a PicketBox or legacy security realm configuration that uses multiple identity stores to Elytron. 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.

PicketBox Composite Store Configuration

The PicketBox security domain for this scenario 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=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" }}])

This results in the following server configuration.

<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>

See Elytron Aggregate Security Realm Configuration for how to configure an aggregate security realm in the elytron subsystem to accomplish this.

Legacy Security Realm Composite Store Configuration

The legacy security realm configuration for this scenario is configured using the following management CLI commands.

/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

This results in the following server configuration.

<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>

See Elytron Aggregate Security Realm Configuration for how to configure an aggregate security realm in the elytron subsystem to accomplish this.

Elytron Aggregate Security Realm Configuration

The equivalent Elytron configuration for this scenario is configured using the following management CLI commands.

/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}])

This results in the following server configuration.

<subsystem xmlns="urn:wildfly:elytron:1.2" 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>

In the elytron subsystem, an aggregate-realm has been defined that specifies which security realms to use for authentication and which to use for authorization decisions.

When using PicketBox, it is possible to define a security domain and enable in-memory caching for its access. This allows you to access the identity data in memory and avoids additional direct access to the identity store. It is possible to achieve a similar configuration with Elytron. This section describes how to configure security domain caching when using Elytron.

PicketBox Cached Security Domain Configuration

The following commands show how to configure a PicketBox security domain that enables caching.

/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" }}])

This results in the following server configuration.

<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>

Elytron Cached Security Domain Configuration

Follow the steps below to create a similar configuration that caches a security domain when using Elytron.

These commands result in the following additions to the server configuration.

<subsystem xmlns="urn:wildfly:elytron:1.2" 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 uses the legacy security subsystem to configure the Java Authorization Contract for Containers (JACC) policy provider and factory. The default configuration maps to implementations from PicketBox.

The elytron subsystem provides a built-in policy provider based on the JACC specification. Before you configure your server to allow Elytron to manage JACC configurations and other policies, you must first disable JACC in the legacy security subsystem by using the following management CLI command.

/subsystem=security:write-attribute(name=initialize-jacc, value=false)

Failure to do so can result in the following error in the server log: MSC000004: Failure during stop of service org.wildfly.security.policy: java.lang.StackOverflowError.

For information about how to enable JACC and define a JACC policy provider in the elytron subsystem, see Enabling JACC Using the elytron Subsystem in the Development Guide for JBoss EAP.

This section describes how to migrate a client application that performs a remote JNDI lookup using an org.jboss.naming.remote.client.InitialContext class, which is backed by an org.jboss.naming.remote.client.InitialContextFactory class, to Elytron.

The following examples assume that the InitialContextFactory class is created by specifying properties for the user credentials and for the URL of the naming provider that it connects to.

Properties properties = new Properties();
properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
properties.put(Context.PROVIDER_URL,"http-remoting://127.0.0.1:8080");
properties.put(Context.SECURITY_PRINCIPAL, "bob");
properties.put(Context.SECURITY_CREDENTIALS, "secret");
InitialContext context = new InitialContext(properties);
Bar bar = (Bar) context.lookup("foo/bar");
...

You can choose from one of the following migration approaches:

// 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 EJB 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 EJB 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 EJB 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 EJB
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 EJB 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);

If you secured HTTP connections to the JBoss EAP server using a security realm, you can migrate that configuration to Elytron using the information provided in this section.

The following examples assume you have the following keystore configured in the security-realm.

<security-realm name="ApplicationRealm">
  <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>
</security-realm>

Follow the steps below to achieve the same configuration using Elytron.

This results in the following elytron subsystem configuration in the server configuration file.

<subsystem xmlns="urn:wildfly:elytron:1.2" ...>
  ...
  <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-stores>
    <key-managers>
      <key-manager name="LocalhostKeyManager" key-store="LocalhostKeyStore"  alias-filter="server">
        <credential-reference clear-text="key_password"/>
      </key-manager>
    </key-managers>
    <server-ssl-contexts>
      <server-ssl-context name="LocalhostSslContext" key-manager="LocalhostKeyManager"/>
    </server-ssl-contexts>
  </tls>
</subsystem>

This results in the following undertow subsystem configuration in the server configuration file.

<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>

For more information, see Elytron Subsystem and How to Secure the Management Interfaces in How to Configure Server Security for JBoss EAP.

If you configured Client-Cert SSL authentication using a security realm truststore, you can migrate that configuration to Elytron using the information provided in this section.

The steps below assume you have the following truststore configured in the security-realm.

<security-realm name="ApplicationRealm">
  <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="application-users.properties" relative-to="jboss.server.config.dir"/>
  </authentication>
  <authorization>
    <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/>
  </authorization>
</security-realm>

Follow these steps to configure the server to prevent users without a valid certificate and private key from accessing the server using Elytron.

This results in the following elytron subsystem configuration in the server configuration file.

<subsystem xmlns="urn:wildfly:elytron:1.2" ...>
  ...
  <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>

This results in the following undertow subsystem configuration in the server configuration file.

<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>

For more information, see Elytron Subsystem and Using a client-ssl-context in How to Configure Server Security for JBoss EAP.