当应用从一个主版本移到另一个主要版本（如从 JBoss EAP 7 移到 JBoss EAP 8.0）时，需要进行重大升级或迁移。符合 Jakarta EE 8 规范、包含专有代码或已弃用 API 的应用可能需要修改其应用程序代码以便在 JBoss EAP 8.0 上运行。引入 Jakarta EE 10 涉及 Java 软件包名称的变化，以及需要调整 Jakarta EE 应用程序代码的其他方面，以便与 JBoss EAP 8.0 兼容。此外，JBoss EAP 8.0 中更改了服务器配置，需要迁移。本指南解决了此类迁移问题。

JBoss EAP 中的小更新是提供程序错误修复、安全修复和新功能的点版本。每个点版本中所做的更改记录在 Red Hat JBoss Enterprise Application Platform 8.0 的发行注记 中。

使用 JBoss 服务器迁移工具自动从一个点版本升级到另一个点版本，例如从 JBoss EAP 7.0 升级到 JBoss EAP 7.1。如需更多信息 ，请参阅使用 JBoss 服务器迁移工具。

JBoss EAP 定期提供包含漏洞和安全修复的累积补丁。累积修补程序将发行版递增到最后一个数字，例如从 7.1.0 升级到 71.1。

JBoss 服务器迁移工具支持从所有版本的 JBoss EAP 7 迁移到 JBoss EAP 8.0。

根据 CDI 4.0 spec 更改备注，在带有空 beans.xml 文件的部署中发现上下文和依赖注入或 CDI Bean 的默认行为已从 all 改为 annotated。这意味着，CDI 只发现一个带有 bean 定义注解的 部署类。如果使用 Bean 的所有应用程序类都有这样的注解，则此 CDI 更改不会影响。否则，当 CDI 找不到提供特定 bean 的类型时，应用程序部署可能会失败。

如果您的应用程序受这个更改的影响，则有几个选项：

Jakarta 上下文和依赖注入 4.0 删除了以下已弃用的 API 元素：

Java SE 14 删除了 java.security.Identity 类，因此其使用量已从 Jakarta Enterprise Beans 4.0 API 中删除。

删除了错误拼写 javax.el.MethodExpression.isParmetersProvided （） 方法。您可以使用 MethodExpression.isParametersProvided （） 替代。

默认情况下，使用 jakarta.json.bind.annotation.JsonbCreator 注解标注的类型不需要 JSON 内容中的所有参数都可用。如果被解析的 JSON 缺少其中一个参数，则将使用默认值。可以通过调用 jakarta.json.bind.JsonbConfig （）.withCreatorParametersRequired (true) 来开启需要 JSON 中的所有参数的 EE 8 行为。

Jakarta Faces 4.0 中删除了以下已弃用的功能。

Jakarta Servlet 6.0 删除了在 Servlet 5.0 及更早版本中被弃用的数字 API 类和方法，主要在 Servlet 2.x 版本中。

javax.servlet.SingleThreadModel marker 接口已被删除，且实施此接口的 servlets 必须删除 interface 声明，并确保 servlet 代码正确保护状态，以及针对并发访问的其他资源访问。例如，通过避免使用实例变量或同步代码访问资源的块。但是，建议开发人员不同步 服务 方法（或 doGet 和 doPost 等方法），因为此类同步性能会降低此类同步的影响。

javax.servlet.http.HttpSessionContext 接口已被删除，以及 javax.servlet.http.HttpSession.getSessionContext （） 方法。由于 Servlet 2.1 需要它的实现，因此此界面没有用例，因为规格不需要提供任何可用的数据。

javax.servlet.http.HttpUtils 实用程序类已被删除。应用程序应使用 ServletRequest 和 HttpServletRequest 接口，而不是以下方法：

另外，以下各种方法和构造器已被删除：

删除了对通过 jaxm.properties 文件进行供应商查找的支持。

弃用的 javax.xml.soap.SOAPElementFactory 类已被删除。使用 jakarta.xml.soap.SOAPFactory 创建 SOAPElements。

xml 绑定文件中使用的 XML 命名空间已更改。http://java.sun.com/xml/ns/jaxb 命名空间应该替换为 https://jakarta.ee/xml/ns/jaxb。

弃用的 javax.xml.bind.Validator 接口已被删除，因为 关联的 javax.xml.bind.JAXBContext.createValidator （） 方法。要验证 marshalling 和 unmarshalling 操作，请为 jakarta.xml.validation.Schema 提供 javax.xml.validation.Schema.bind.Marshaller.setSchema (Schema)。

删除了对与 JAXB 1.0 兼容的支持。

JAXBContext 实施查找算法中的一些已弃用步骤已被删除。通过 jaxb.properties 文件、javax.xml.bind.context.factory 或 jakarta.xml.bind.JAXBContext 属性和 /META-INF/services/javax.xml.bind.JAXBContext 资源文件搜索实施类名称已被丢弃。有关当前实现发现算法的更多信息，请参阅 Jakarta XML Binding 4.0 规范。

javax.xml.bind.Marshaller 接口中的多个方法的通用要求已更改，如下所示：

除了 Jakarta XML Binding API 的更改外，实施库 EAP 8 中还有显著的软件包名称更改，这可能会影响访问实施库的一些应用：

在 JBoss EAP 7.0 中，mod_cluster 中默认禁用 Web 应用的根上下文。

自 JBoss EAP 7.1 起，情况已不再如此。如果您希望禁用根上下文，这可能会造成意外的后果。例如，可以将请求错误路由到不合要求的节点，或者不应公开的私有应用可以通过公共代理意外访问。Undertow 位置现在会自动注册到 mod_cluster 负载平衡器，除非它们被明确排除。

使用以下管理 CLI 命令，将 ROOT 从 modcluster 子系统配置中排除：

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

使用以下管理 CLI 命令，禁用默认的欢迎 Web 应用：

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

在 Red Hat JBoss Enterprise Application Platform 7.2 之前，默认的 undertow 子系统配置包括两个响应标头过滤器，这些标头被 default-host 附加到每个 HTTP 响应中：

这些响应标头过滤器已从默认的 JBoss EAP 7.2 配置中删除，以防止意外泄漏有关正在使用的服务器的信息。

以下是 JBoss EAP 7.1 中默认 undertow 子系统配置的示例。

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

以下是 JBoss EAP 7.4 中默认 undertow 子系统配置的示例：

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

以下是 JBoss EAP 8.0 中默认 undertow 子系统配置的示例。

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

在 JBoss EAP 7.1 及更高版本中，启用了 passivation 的自定义有状态会话 Bean (SFSB)缓存已更改。当使用 passivation 配置 SFSB 缓存时，请考虑以下密钥更改：

在配置自定义 SFSB 缓存以便在 JBoss EAP 7.1 及更高版本中传递时，请考虑以下限制：

JBoss EAP 7.0 及更新版本之间的行为更改需要在批处理模式下执行对缓存容器传输协议的更新，或使用特殊标头。此更改还影响用于管理 JBoss EAP 服务器的工具。

以下是用于在 JBoss EAP 7.0 中配置缓存容器传输协议的管理 CLI 命令示例。

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

以下是在 JBoss EAP 7.1 中执行相同配置所需的管理 CLI 命令示例。请注意，命令是以批处理模式执行的。

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

如果您不希望使用批处理模式，您可以在定义传输时指定操作标头 allow-resource-service-restart=true。

如果您使用脚本更新缓存容器传输协议，请务必检查它们并添加批处理模式。

JBoss EAP 8.0 引入了对可分布式有状态会话 Bean (SFSB)的 Enterprise 3.0.0 (EJB)子系统配置的更改，包括对多个资源的新子系统和更新。JBoss EAP 6 和 7 中使用的几个资源也被弃用。这些更改启用了服务器配置迁移，以确保您的应用程序与未来的主要版本兼容。

JBoss EAP 8.0 将 JBoss EAP 6 和 7 中使用的资源替换为两个新资源，以及一个 distributable-ejb 子系统来配置 SFSB 缓存。下表概述了已弃用的资源和替换它们的新资源。

非不同 SFSB 缓存 /subsystem=ejb3/simple-cache 相当于 SFSB 缓存 /subsystem=ejb3/cache，在 JBoss EAP 7 中使用，没有定义 passivation 存储。

distributable SFSB 缓存 /subsystem=ejb3/distributable-cache 包含一个可选的 bean-management 属性，引用 distributable-ejb 子系统的对应资源。如果您没有定义资源，则默认为 distributable-ejb 子系统中的 bean-management 资源。

考虑将服务器配置迁移到 JBoss EAP 8.0 中更新的方法。虽然当前发行版本继续使用已弃用的资源，但当它们被删除时，可能不会出现在将来的版本中。

JBoss EAP 7 和首选 JBoss EAP 8.0 配置之间的比较示例如下：

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

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

采用首选 JBoss EAP 8.0 配置可确保您的服务器与最新版本和将来的主版本兼容。您还可以从改进的资源和子系统中受益，用于可分布式 SFSB。

以下 DuplicateServiceException 错误是由 JBoss EAP 7 中的缓存更改导致的。

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

若要解决由于 JBoss EAP 7 中缓存更改导致的 DuplicateServiceException，请运行以下命令在 ejb3 子系统中重新配置缓存：

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

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

通过重新配置缓存，您可以解决这个错误并防止 DuplicateServiceException 发生。

回顾在 Red Hat JBoss Enterprise Application Platform 中迁移消息传递数据的方法。

要将消息传递数据从以前的 JBoss EAP 7.x 版本迁移到 JBoss EAP 8.0，您可以使用导出和导入方法迁移消息传递数据。此方法涉及从上一版本导出消息传递数据，并使用管理 CLI import-journal 操作将其导入到 JBoss EAP 8.0 中。请注意，这种方法仅适用于基于文件的消息传递系统。

与版本 7 一样，JBoss EAP 8.0 继续使用 ActiveMQ Artemis 作为 Jakarta 消息传递支持提供程序，这有助于使迁移过程平稳进行。

在 Red Hat JBoss Enterprise Application Platform 8.0 中更改了配置通用 Jakarta 消息传递资源适配器以用于第三方 Jakarta 消息传递提供程序的方法。如需更多信息，请参阅 JBoss EAP 7.4 配置消息传递指南中的 部署通用 Java 消息服务资源适配器。

在 Red Hat JBoss Enterprise Application Platform 7.0 中，如果您在没有指定 check-for-live-server 属性的情况下配置了 replication-primary 策略，则其默认值被设置为 false。JBoss EAP 7.1 及更高版本中发生了这一变化。check-for-live-server 属性的默认值现在设为 true。

以下是管理 CLI 命令的示例，该命令配置 replication-primary 策略，而不指定 check-for-live-server 属性。

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

使用管理 CLI 读取资源时，请注意 check-for-live-server 属性值设为 true。

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

在 JBoss EAP 7 中，嵌入式消息传递代理是默认安装的一部分。在 JBoss EAP 8 中，这个功能被添加到一个新的 Galleon 层中，称为 embedded-activemq。

这个新层不是默认配置的一部分，因此希望依赖在 JBoss EAP 中嵌入代理的用户必须在其配置中明确包含该代理。

该层提供了一个带有嵌入式代理的 messaging-activemq 子系统，即使建议客户在 OpenShift 上使用专用 AMQ 集群。它还置备辅助资源，如 socket-bindings 和支持此用例所需的依赖项。

Vault 已从 JBoss EAP 8.0 中删除。使用 elytron 子系统提供的凭据存储来存储敏感字符串。

旧的 security 子系统和旧的安全域已从 JBoss EAP 8.0 中删除。使用 elytron 子系统提供的安全域。

PicketLink 子系统已从 JBoss EAP 8.0 中删除。使用 Red Hat build of Keycloak 而不是 PicketLink 身份提供程序，以及红帽构建的 Keycloak SAML 适配器而不是 PicketLink 服务供应商。

JBoss EAP 8.0 不支持 keycloak 子系统，它被 elytron-oidc-client 子系统替代。JBoss 服务器迁移工具 默认执行迁移。

在 JBoss EAP 8.0 中，旧的 security 子系统已被删除。要继续使用 elytron 子系统的自定义登录模块，请使用新的 Java 身份验证和授权服务(JAAS)安全域和 jaas-realm。

从 JBoss EAP 7.1 开始，默认启用自动生成自签名证书用于开发目的。如果您以 FIPS 模式运行，请配置服务器以禁用自动自签名证书创建。否则，在启动服务器时可能会导致以下错误：

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

基于 XML 的 RPC Java API (JAX-RPC)在 Java EE 6 中已被弃用，在 Java EE 7 中是可选的。从 JBoss EAP 7 开始，它不再被支持。使用 JAX-RPC 的应用必须迁移到使用 Jakarta XML Web 服务，该服务为当前的 Jakarta EE 标准 Web 服务框架。

可使用以下任一方式识别 JAX-RPC Web 服务：

在以前的 JBoss EAP 版本中，您可以通过包含带有端点部署存档的 jbossws-cxf.xml 配置文件来自定义 JBossWS 和 Apache CXF 集成。一个用例是，为 Apache CXF 总线上的 Web 服务客户端和服务器端点配置拦截器链。此集成需要在 JBoss EAP 服务器中部署 Spring。

JBoss EAP 8 不再支持 Spring 集成。必须修改包含 jbossws-cxf.xml 描述符配置文件的任何应用程序，以替换该文件中定义的自定义配置。虽然仍然可以直接访问 Apache CXF API，但请注意，应用程序将无法可移植。

建议的方法将 Spring 自定义配置替换为新的 JBossWS 描述符配置选项。基于 JBossWS 描述符的方法提供类似功能，无需修改客户端端点代码。在某些情况下，您可以将 Spring 替换为上下文依赖注入(CDI)。

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

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

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

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

client.setChunkingThreshold(8192);
...

本节介绍 JBoss EAP 6.4 和 JBoss EAP 7.0 中应用的各种 WS-Security 更改。

cxf-api 和 cxf-rt-core JARs 已合并到一个 cxf-core JAR 中。因此，JBoss EAP 中的 org.apache.cxf 模块现在包含 cxf-core JAR，并公开比上一版本更多的类。

如果要将 AES 加密与 Galois/Counter Mode(GCM)用于 XML/WS-Security 中的对称加密，则需要 BouncyCastle Security Provider。

从 JBoss EAP 7 开始，它包含在 org.bouncycastle 模块中，JBossWS 能够依赖其类加载程序来获取和使用 BouncyCastle Security Provider。因此，在当前 JVM 中静态安装 BouncyCastle 不再需要。对于在容器外运行的应用程序，可以通过向类路径添加 BouncyCastle 库来向 JBossWS 提供安全供应商。

您可以禁用此行为：把 jaxws-endpoint-config.xml 部署描述符文件（对于服务器）或 jaxws-client-config.xml 部署描述符文件（对于客户端）中的 org.jboss.ws.cxf.noLocalBC 属性值设置为true。

如果要使用与 JBoss EAP 附带的版本不同的版本，您仍然可以静态将 BouncyCastle 安装到 JVM。在这种情况下，按照类路径中的提供者选择静态安装的 BouncyCastle Security Provider。要避免任何问题，您必须使用 BouncyCastle 1.72 或更高版本。

在容器中运行的客户端的默认总线选择策略已从 THREAD_BUS 改为 TCCL_BUS。对于运行内存不足的客户端，默认的策略仍然是 THREAD_BUS。您可以使用以下方法之一将行为恢复到上一版本的行为。

容器必须使用 Jakarta XML Web Services 2.2 风格构造器（在构造器中包含 WebServiceFeature 类）以构建注入 Web 服务引用的客户端。JBoss EAP 6.4 包括了 JBossWS 4，隐藏了这一要求。从包含 JBossWS 5 的 JBoss EAP 7 开始，此要求不会被隐藏。这表明，容器注入的服务类必须通过更新现有代码来实现 Jakarta XML Web 服务 2.2 或更高版本，以使用包含一个或多个 WebServiceFeature 参数的 jakarta.xml.ws.Service 构造器。

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

在以前的版本中，您可以通过将系统属性 org.jboss.security.ignoreHttpsHost 设置为 true 来禁用对证书中提供的服务通用名称(CN)的 HTTPS URL 主机名检查。这个系统属性名称已被 cxf.tls-client.disableCNCheck 替代。

由于启用注入服务端点和服务客户端处理程序，便无法再自动加载来自 org.jboss.as.webservices.server.integration JBoss 模块的处理程序类。如果您的应用程序依赖于给定的预定义配置，您可能需要为部署显式定义新的模块依赖项。如需更多信息，请参阅 迁移显式模块依赖项。

JDK 1.8_40 中弃用了 Java 背书的标准覆盖机制，旨在将其从 JDK 9 中删除。这种机制允许开发人员通过将 JAR 放置到 JRE 中的终端目录中，使库可供所有部署的应用程序使用。

从 JBoss EAP 7 发行版本开始，如果您的应用程序使用了 Apache CXF 的 JBossWS 实施，它会确保以正确顺序添加所需的依赖项，您不应受到此更改的影响。如果您的应用程序直接访问 Apache CXF，则现在必须在 JBossWS 依赖项后提供 Apache CXF 依赖项，作为应用程序部署的一部分。

在以前的 JBoss EAP 版本中，您可以在 JAR 归档的 META-INF/ 目录中为 Jakarta Enterprise Beans Web 服务部署配置 jboss-webservices.xml 部署描述符文件，或在 POJO Web 服务部署和 POJO Web 服务部署和 Jakarta Enterprise Beans Web 服务端点中捆绑在 WAR 归档的 WEB-INF/ 目录中配置 jboss-webservices.xml 部署描述符文件。

从 JBoss EAP 7 开始，您可以在 EAR 存档的 META-INF/ 目录中配置 jboss-webservices.xml 部署描述符文件。如果在 EAR 归档和 JAR 或 WAR 归档中找到 jboss-webservices.xml 文件，则 JAR 或 WAR 文件中的配置数据会覆盖 EAR 描述符文件中的对应数据。

从 JBoss EAP 7 开始，由命名模式 -jms.xml 标识的专有 HornetQ 消息传递资源部署描述符文件无法正常工作。以下是 JBoss EAP 6 中的 Java Message Service 资源部署描述符文件的示例：

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

如果您在上一发行版本中的应用程序中使用 -jms.xml Java Message Service 部署描述符，您可以转换应用程序以使用 Jakarta EE 平台的 Resource Definition 和 Configuration 部分中指定的标准部署描述符，或者您可以更新部署描述符以使用 messaging-activemq-deployment 模式。如果您选择更新描述符，您需要进行以下修改：

修改的文件应类似以下示例。

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

JBoss EAP 6 包含 org.hornetq 模块，允许您在应用源代码中使用 HornetQ API。

Apache ActiveMQ Artemis 取代了 JBoss EAP 7 中的 HornetQ，因此您必须迁移使用 HornetQ API 的任何代码以使用 Apache ActiveMQ Artemis API。此 API 的库包含在 org.apache.activemq.artemis 模块中。

ActiveMQ Artemis 是 HornetQ 的演进，因此许多概念仍然适用。

使用 auto-create-jms-queues、 auto-delete-jms-queues 、auto-create-jms-topics 和 auto-delete-jms-topics 属性自动创建和自动删除主题和队列的功能仅在 JBoss EAP 7 中完全配置。这些属性已弃用，它们 仅作为技术预览功能提供，且不被支持。

您必须使用以下替换属性替换这些已弃用的属性。

在 JBoss EAP 6 中，默认的地址设置属性设为 false。从 JBoss EAP 7 开始，默认情况下替换属性设为 true。

如果您希望保留 JBoss EAP 6 行为，您必须将替换属性设置为 false。

有关这些替换属性的更多信息，请参阅 JBoss EAP 7.4 配置消息传递 指南中的 地址设置属性。

从 JBoss EAP 7.2 开始，如果客户端应用直接依赖于 INVENTORY 客户端 JAR，例如： artemis-jms-client、artemis-commons、artemis-core-client，或 artemis-selector，那么您必须在 pom.xml 文件中为 wildfly-client-properties 添加以下依赖关系。

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

在从旧的 JBoss EAP 7 客户端中调用 message.getJMSReplyTo() 时，避免 JMSRuntimeException，如 JBEAP-15889 所述。

拦截器和 MessageBody 类

JSR 311：JAX-RS：RESTful Web 服务的 Java™ API 没有包含拦截器框架，因此 RESTEasy 2 提供一个。JSR 339：JAX-RS 2.0：RESTful Web 服务的 Java API 引入了官方拦截器和过滤框架，因此 RESTEasy 2 中包含的拦截器框架现已弃用，并由 RESTEasy 3.x 中的 Jakarta REST 兼容拦截器工具替代。相关的接口在 jakarta.ws.rs.api 模块的 jakarta.ws.rs.ext 软件包中定义。

JBoss EAP 8.0 中删除了以下提供程序：

JBoss EAP 8.0 中删除了以下内容，因为它们现在有 Jakarta RESTful Web Services 替换。

客户端 API

resteasy-jaxrs 中的 RESTEasy 客户端框架被 JBoss EAP 7.0 中的遵循 JAX-RS 2.0 的 resteasy-client 模块替代。因此，一些 RESTEasy 客户端 API 类和方法已弃用。

StringConverter

org.jboss.resteasy.spi.StringConverter 类在 RESTEasy 3.x 和 JBoss EAP 8.0 中被弃用。可以使用 Jakarta REST jakarta.ws.rs.ext.ParamConverterProvider 类替换此功能。

ResteasyProviderFactory 添加方法

大多数 org.jboss.resteasy.spi.ResteasyProviderFactory add （） 方法已被删除或在 RESTEasy 3.0 中受到保护。例如，addBuiltInMessageBodyReader() 和 addBuiltInMessageBodyWriter() 方法已被删除，并且 addMessageBodyReader() 和 addMessageBodyWriter() 方法受保护。

您现在应使用 registerProvider （） 和 registerProviderInstance （） 方法。

从 RESTEasy 3 中删除额外的类

@org.jboss.resteasy.annotations.cache.ServerCached 注释指定对 Jakarta REST 方法的响应，应从 RESTEasy 3 中删除，且必须从应用程序代码中删除。

本节提供有关 JBoss EAP 的 RESTEasy 中一些其他更改的信息。

SignedInput 和 SignedOuput

安全过滤器

@RolesAllowed、@PermitAll 和 @DenyAll 的安全过滤器现在返回 "403 Forbidden" 而不是 "401 Unauthorized"。

客户端过滤器

从 RESTEasy 3.0 之前，从版本使用 RESTEasy 客户端 API 时，在 JAX-RS 2.0 中引入的客户端侧过滤器不会绑定并运行。

异步 HTTP 支持

由于 JAX-RS 2.0 规范增加了使用 @Suspended 注释和 AsynResponse 接口的异步 HTTP 支持，因此用于异步 HTTP 的 RESTEasy 专有 API 已被弃用，并可能在以后的 RESTEasy 发行版本中删除。异步 Tomcat 和异步 JBoss Web 模块也已从服务器安装中删除。如果您不使用 Servlet 3.0 容器或更高，则异步 HTTP 服务器端处理将模拟，并在同一个请求线程中异步运行。

服务器端缓存

服务器端缓存设置已更改。如需更多信息，请参阅 RESTEasy 文档。

YAML 供应商设置更改

在以前的 JBoss EAP 版本中，RESTEasy YAML 供应商设置被默认启用。这在 JBoss EAP 7 中有所改变。现在默认禁用 YAML 供应商。由于 RESTEasy 用于 unmarshalling 的 SnakeYAML 库中的安全问题，它不被支持，因此必须在应用中明确启用。有关如何在应用中启用 YAML 提供程序并添加 Maven 依赖项的信息，请参阅 JBoss EAP 7.4 开发 Web Services Applications 中的 YAML 提供程序。

Content-Type Header 中的默认 Charset UTF-8

自 JBoss EAP 7.1 起，resteasy.add.charset 参数默认设置为 true。当资源方法返回一个 text/* 或 application/xml* 媒介类型且没有明确的字符集时，如果您不希望 RESTEasy 将 charset=UTF-8 添加到返回的 content-type 头时，可以将 resteasy.add.charset 参数设置为 false。

如需有关文本媒体类型和字符集的更多信息，请参阅 JBoss EAP 7.4 开发 Web 服务应用程序 中的文本介质类型和 字符集。

SerializableProvider

从不受信任的源中反序列化 Java 对象是不安全的。因此，从 JBoss EAP 7 开始，默认禁用 org.jboss.resteasy.plugins.providers.SerializableProvider 类，我们不推荐使用此提供程序。

将请求与资源方法匹配

在 RESTEasy 3 中，对匹配规则的实施进行了改进和更正，如 JAX-RS 规范中定义的。特别是，对子资源方法和子资源 locator 的模糊 URI 进行了更改。

在 RESTEasy 2 中，子资源 locator 可以成功执行，即使存在具有相同 URI 的另一个子资源。这个行为根据规格不正确。

在 RESTEasy 3 中，当子资源和子资源 locator 有模糊的 URI 时，调用子资源将成功；但是，调用子资源 locator 将会导致 HTTP 状态 405 方法 Not Allowed 错误。

以下示例包含子资源方法和子资源 locator 上的模糊 @Path 注释。请注意，对两个端点的 URI ( anotherResource 和 anotherResourceLocator )都相同。两个端点之间的区别在于 anotherResource 方法与 REST 动词 POST 关联。anotherResourceLocator 方法不与任何 REST 动词关联。根据规范，将始终选择具有 REST 动词的端点（本例中为 anotherResource 方法）。

@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();
    }
}

JBoss EAP 8 中删除了 RESTEasy SPI 提供程序。

SPI Exceptions

所有 SPI 失败例外都已弃用，不再在内部使用。它们已被对应的 Jakarta REST 异常替代。

InjectoronnectionFactoryy 和 Registry

InjectorFactory 和 Registry SPI 已更改。如果使用 RESTEasy 作为文档和支持，这不应有问题。

JBoss EAP 6.4 中包含的 Jackson 版本已更改。从 JBoss EAP 7 开始，Jackson 提供程序已从 resteasy-jackson-provider 更改为 resteasy-jackson2-provider。

升级到 resteasy-jackson2-provider 需要一些软件包更改。例如，Jackson 注解软件包已从 org.codehaus.jackson.annotate 改为 com.fasterxml.jackson.annotation。

JBoss EAP 8.0 支持 RESTEasy 6.2。如果您计划将 Spring 6.0 框架与 JBoss EAP 8.0 搭配使用，则必须使用 Java 17。

Spring 4.0 框架引入了对 Java 8 的支持。如果您计划将 RESTEasy 3.x 与 Spring 集成，请确保将 4.2.x 指定为部署中的最低 Spring 版本，因为这是 JBoss EAP 7 支持的最早稳定版本。

自 JBoss EAP 7 起，RESTEasy Jettison JSON 提供程序已被弃用，默认情况下不再添加到部署中。建议您切换到推荐的 RESTEasy Jackson 提供程序。如果您希望继续使用 Jettison 提供程序，您必须在 jboss-deployment-descriptor.xml 文件中定义显式依赖项，如下例所示。

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

有关如何定义显式依赖项的更多信息，请参阅 JBoss EAP 7.4 开发指南中的 将显式模块依赖部署到部署。

MicroProfile 是可供开发人员用来将应用和微服务配置为在多个环境中运行的规范名称，而无需修改或重新打包这些应用程序。在以前的版本中，MicroProfile 作为技术预览提供 JBoss EAP 7.3，但自此后已被删除。MicroProfile 现在仅适用于 JBoss EAP XP。

已启用 Bean 的 Bean 类必须在 bean 存档中部署，以确保它们由 CDI 发现，并作为 Bean 进行处理。

CDI 1.1 引入了 隐式 bean 归档，存档包含一个或多个带有定义注解的 bean 类，或者一个或多个 session Bean。隐式 Bean 归档由 CDI 扫描，在类型发现期间只发现带有 bean 定义注解的类。如需更多信息，请参阅 JSR 365: 上下文和依赖注入 Java^™ 2.0 中的 Type 和 Bean Discovery。Jakarta 等同于 bean 定义注解，在 Jakarta 上下文依赖注入 2.0 规格中定义。

在 CDI 4.0 中：

有关 CDI 4.0 的更多信息，请参阅 Jakarta 上下文和依赖注入 4.0。

bean 归档具有 all, annotated 或 none 的 bean 发现模式。包含非空 Bean.xml 的 bean 归档必须指定 bean-discovery-mode 属性。属性的默认值被 annotated。

在以下情况下，存档不是 bean 归档：

归档是 在以下情况下明确的 bean 归档：

在以下情况下，存档是一个 隐式 bean 归档：

CDI 1.2 限于定义以下注解 ：

CDI 1.2 中更改了对话上下文生命周期，以防止与 Servlet 规范冲突，如 CDI 规范问题 CDI-411 所述。对话范围在所有 servlet 请求期间处于活跃状态，不应阻止其他 servlet 或 servlet 过滤器设置请求正文或字符编码。如需更多信息，请参阅 Jakarta EE 中的对话上下文生命周期。

在 CDI 1.2 中，事件解析部分被重写。在 CDI 1.0 中，如果观察器方法具有所有事件限定符，则会向观察器发送事件。在 CDI 1.2 中，如果观察器方法没有事件限定符或事件限定符的子集，则会向观察者发送事件。如需更多信息，请参阅 Observer 解析。

本节重点介绍从 Hibernate ORM 版本 5.3 迁移到 5.4 时所需的更改。有关 Hibernate ORM 5.3 和 Hibernate ORM 5.4 之间实施的更改的更多信息，请参阅 Hibernate ORM 5.4 迁移指南。

已知的更改

下面描述了从 Hibernate ORM 版本 5.3 迁移到 5.4 时的一些变化。

本节重点介绍从 Hibernate ORM 版本 5.4 迁移到 5.5 时所需的更改。有关 Hibernate ORM 5.4 和 Hibernate ORM 5.5 之间实施的更改的更多信息，请参阅 Hibernate ORM 5.5 迁移指南。

已知的更改

Hibernate ORM 5.5 版本与 Hibernate ORM 5.4 类似，因为它包括应用到 5.4 维护版本的所有 bug 修复，并引入对 Jakarta Persistence API 的支持。

本节重点介绍从 Hibernate ORM 版本 5.5 迁移到 5.6 时所需的更改。有关 Hibernate ORM 5.5 和 Hibernate ORM 5.6 之间实施的更改的更多信息，请参阅 Hibernate ORM 5.6 迁移指南。

已弃用的功能

Hibernate 5.6 版本与之前的 Hibernate 5.5 版本非常相似，但从之前的 Hibernate 版本中删除一些已弃用的功能除外。

本节重点介绍从 Hibernate ORM 版本 5.6 迁移到 6.0 时所需的更改。有关 Hibernate ORM 5.6 和 Hibernate ORM 6.0 之间实施的更改的更多信息，请参阅 Hibernate ORM 6.0 迁移指南。

Hibernate 6.0 发行版本包括以下更改：

有关这些功能的更多信息，请参阅 Hibernate ORM 6.0 迁移指南。

Hibernate 6.0 发行版本还包含从以前的 Hibernate 版本中删除的许多功能，如下所示：

有关 Hibernate 6.0 中删除的功能的更多信息，请参阅 Hibernate ORM 6.0 迁移指南。

本节重点介绍从 Hibernate ORM 版本 6.0 迁移到 6.1 所需的更改。有关 Hibernate ORM 6.0 和 Hibernate ORM 6.1 间实施的更改的更多信息，请参阅 Hibernate ORM 6.1 迁移指南。

Hibernate 6.1 发行版本包含以下更改：

有关 Hibernate 6.1 中包含的功能的详细信息，请参阅 Hibernate ORM 6.1 迁移指南。

本节重点介绍从 Hibernate ORM 版本 6.1 迁移到 6.2 所需的更改。有关 Hibernate ORM 6.1 和 Hibernate ORM 6.2 之间实现的更改的更多信息，请参阅 Hibernate ORM 6.2 迁移指南。

Hibernate 6.2 发行版本包含以下改进，如下所示：

DDL 类型更改：

JBoss EAP 7.0 包括 Hibernate ORM 5.0。本节重点介绍从 Hibernate ORM 版本 4.3 迁移到版本 5 时所需的更改。有关 Hibernate ORM 4 和 Hibernate ORM 5 之间实施的更改的更多信息，请参阅 Hibernate ORM 5.0 迁移指南。

删除和弃用的类

以下已弃用的类已从 Hibernate ORM 5 中删除：

对类和软件包的其他更改

类型处理

事务管理

其他 Hibernate ORM 5 更改

JBoss EAP 7.1 包括 Hibernate ORM 5.1。本节重点介绍从 Hibernate ORM 版本 5.0 迁移到版本 5.1 所需的区别和所需更改。

Hibernate ORM 5.1 功能

Hibernate 的这个版本包括性能改进和程序错误修复。如需更多信息，请参阅 7.1.0 的 JBoss EAP 发行注记中的 Hibernate ORM 5.1 功能。有关在 Hibernate ORM 5.0 和 Hibernate ORM 5.1 之间实施的更改的更多信息，请参阅 Hibernate ORM 5.1 迁移指南。

模式管理工具更改

JBoss EAP 7 中的模式管理工具更改

Hibernate ORM 5.1 中的模式管理工具更改专注于以下区域：

模式管理工具更改只是直接使用以下类的应用程序的迁移问题：

JBoss EAP 7.1 中的模式管理工具更改

Hibernate ORM 5.1.10 包含在 JBoss EAP 7.1 中，引入了检索数据库表的策略，用于改进 SchemaMigrator 和 SchemaValidator 性能。此策略执行单个 java.sql.DatabaseMetaData#getTables (String, String, String[]) 调用来确定每个 javax.persistence.Entity 是否具有映射的数据库表。这是默认策略，它使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped 属性设置。此策略可能要求提供 hibernate.default_schema 和/或 hibernate.default_catalog。

要使用执行 java.sql.DatabaseMetaData#getTables (String, String, String[]) 调用 的每个 javax.persistence.Entity 的旧策略，请使用 hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=indivivi ally 属性设置。

JBoss EAP 7.4 包括 Hibernate ORM 5.3。本节重点介绍从 Hibernate ORM 5.1 迁移到 Hibernate ORM 5.2 时所需的一些更改，然后介绍 Hibernate ORM 5.3。

Hibernate ORM 5.2 功能

Hibernate ORM 5.2 使用 Java 8 JDK 构建，在运行时需要 Java 8 JRE。以下是本发行版本中进行的一些更改列表：

有关 Hibernate 5.2 中实施的更改的完整列表，请参阅 Hibernate ORM 5.2 迁移指南。

Hibernate ORM 5.3 功能

Hibernate ORM 5.3 添加了对 Jakarta Persistence 2.2 规范的支持。此发行版本包含遵守此规格的更改以及其他改进。以下是其中一些更改的列表：

有关 Hibernate 5.3 中所实施的其他更改的完整列表，请参阅 Hibernate ORM 5.3 迁移指南。

Hibernate 5.1 和 Hibernate 5.3 之间的更改异常

在 Hibernate 5.2 和 5.3 中，使用 Hibernate 的原生 Bootstrap 构建的 SessionFactory 异常处理，按照 Jakarta Persistence 规格嵌套或转换 HibernateException。这个行为的唯一例外是在操作是特定于 Hibernate 时，如 Session.save （） 或 Session.saveOrUpdate （）。

在 Hibernate 5.3.3 中，添加了 hibernate.native_exception_handling_51_compliance 属性。此属性指示使用 Hibernate 的原生 bootstrap 构建的 SessionFactory 异常处理是否与 Hibernate ORM 5.1 中的原生异常处理行为相同。当设置为 true 时，会根据 Jakarta Persistence 规范，不会嵌套或转换HibernateException。对于使用 Jakarta Persistence bootstrapping 构建的 SessionFactory，会忽略此设置。

兼容性转换器

JBoss EAP 7.4 包含一个兼容性转换器，它解决了 Hibernate ORM 5.3 API 方法，它们不再与 Hibernate ORM 5.1 兼容。转换程序是一种临时措施，允许使用 Hibernate ORM 5.1 构建的应用程序在 JBoss EAP 7.4 中表现出与 Hibernate 5.3 相同的行为。这是一个临时解决方案，您应该将这些方法调用替换为推荐的 Jakarta Persistence 方法调用。

您可以使用以下方法之一启用转换器：

下表列出了正在转换的 Hibernate 5.1 方法，并将其转换为 Hibernate 5.3 方法：

Hibernate Search 5 API 已被删除，并被 JBoss EAP 8.0 中的 Hibernate Search 6 API 替换。

要查看删除的功能列表，请参阅 JBoss EAP 7.4 中的 Hibernate Search 5 API 已弃用，并在 EAP 8.0 中删除。

JBoss EAP 8.0 中包含的 Hibernate Search 6 的最新版本是 6.2。如果您要从 Hibernate Search 5 迁移，您应该考虑迁移到 6.0、6.1 和 6.2 版本。

如需更多信息，请参阅以下迁移指南：

JBoss EAP 8.0 还支持在 Hibernate Search 6 中使用 Elasticsearch 后端，将数据索引到远程 Elasticsearch 或 OpenSearch 集群中。

要查看可能的 Hibernate 搜索架构和后端列表，请参阅 Table 2。构架的比较 中的 Hibernate Search 6.2 参考文档。

有关配置 Hibernate Search 6 的更多信息，请参阅 WildFly Developer 指南中的使用 Hibernate Search。

从 JBoss EAP 7 开始，默认的远程连接器和端口已更改。有关此更改的详情，请参阅更新 远程 URL 连接器和端口。

如果您使用 JBoss 服务器迁移工具迁移服务器配置，旧的设置会被保留，您不需要在此处进行详细更改。但是，如果您使用新的 JBoss EAP 8.0 默认配置，您必须进行以下更改。

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

如果您使用新的默认 JBoss EAP 7 配置运行，您必须修改客户端代码以使用新的默认远程端口和连接器。

以下是如何在 JBoss EAP 6 中的客户端代码中指定远程命名属性的示例。

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

以下是如何在 JBoss EAP 7 中的客户端代码中指定远程命名属性的示例。

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

JBoss EAP 7.0 包含在 JBoss Enterprise Java Beans 客户端 2.1.4 中，JBoss EAP 7.1 及更高版本包含在 JBoss Enterprise Java Beans 客户端 4.0.x 中，其中包括很多对 API 的更改。

如果您创建了在 JBoss EAP 6.4 中扩展 AuthenticatorBase 的自定义验证器 valve，则必须手动将它替换为 JBoss EAP 7 中的自定义 HTTP 身份验证实施。HTTP 身份验证机制是在 elytron 子系统中创建的，然后注册到 undertow 子系统。有关如何实现自定义 HTTP 身份验证机制的详情，请参考 JBoss EAP 7.4 开发指南中的 自定义 HTTP 机制。

PicketLink 已从 JBoss EAP 8.0 中删除。

PicketLink SP

使用 Keycloak SAML 适配器而不是 PicketLink 服务供应商。

要通过配置 Keycloak SAML 适配器从 PicketLink 迁移，请执行以下任务：

PicketLink IDP

从 JBoss EAP 8.0 开始，PicketLink IDP 不可用，您可以配置红帽构建的 Keycloak。如需更多信息，请参阅配置红帽构建的 Keycloak。

PicketLink STS

在以前的版本中，您可以将 PicketLink STS 配置为 Apache CXF 安全令牌服务实现的替代选择。PicketLink STS 配置涉及旧的安全域。需要删除对 STS 应用程序中的旧安全域和 PicketLink 的任何引用，因此您必须配置 Apache CXF STS。

有关如何配置 Apache CXF STS 的更多信息，请参阅 JBoss EAP 7.4 开发 Web 服务应用程序 中的 安全令牌服务(STS)。

Vault 已从 JBoss EAP 8.0 中删除。如果您的应用程序使用传统的 vault 表达式，则必须迁移和使用 Elytron 加密表达式。

检查部署文件中的 ${VAULT:: 实例，它们可能位于注解或部署描述符中，并将它们替换为对应的加密表达式。

JBoss EAP 8.0 不支持 Keycloak OIDC 客户端适配器，并被原生 Elytron OIDC 客户端替代，提供类似的功能和配置。

要从 Keycloak OIDC 客户端适配器迁移到原生 Elytron OIDC 客户端，请按照以下步骤执行：

在 JBoss EAP 8.0 中，旧的 security 子系统已被删除。要继续使用 elytron 子系统的自定义登录模块，请使用新的 Java 身份验证和授权服务(JAAS)安全域和 jaas-realm。

JBoss EAP 7.2 或更高版本和更早的版本之间存在一些显著区别：

下表介绍了将应用从 JBoss EAP 6 迁移到 JBoss EAP 8.0 时应注意的一些新集群功能。

JBoss EAP 7 引入了一个新的 Web 会话集群实施。它取代了以前的实施，它与旧的 JBoss Web 子系统源代码紧密耦合。

新的 Web 会话集群实施会影响如何在 jboss-web.xml JBoss EAP 专有 Web 应用程序 XML 描述符文件中配置应用程序。以下是此文件中唯一保留的集群配置元素。

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

distributable-web 子系统弃用了 jboss-web.xml 的 <replication-config> 元素。它通过生成临时分布式 web 会话配置集来提高 <replication-config> 的使用。

您可以通过按名称或提供特定于部署的会话管理配置来覆盖默认的可分布式会话管理行为。如需更多信息，请参阅 覆盖默认的可分布式会话管理行为。

下表论述了如何为 jboss-web.xml 文件中的元素实现类似行为，这些行为现已过时。

这个新实施还支持直写缓存存储和仅传递缓存存储。通常，直写缓存存储与无效缓存结合使用。与无效缓存一起使用时，JBoss EAP 6 中的 Web 会话集群实施不正确。

您可以使用以下方法之一覆盖默认的可分布式会话管理行为：

引用现有的会话管理配置集

/WEB-INF/distributable-web.xml

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

/META-INF/jboss-all.xml

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

使用特定于 Deployment 的 Session Management 配置集

如果只有一个 Web 应用使用自定义会话管理配置，您可以在部署描述符本身中定义配置。临时配置与 distributable-web 子系统使用的配置相同。

/WEB-INF/distributable-web.xml

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

/META-INF/jboss-all.xml

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

在 JBoss EAP 6 中，您需要使用以下方法之一为有状态会话 Bean (SFSB)启用集群行为：

从 JBoss EAP 7 开始，您不再需要启用集群行为。默认情况下，如果服务器使用 HA 配置文件启动，SFSB 的状态将自动复制。您可以使用以下方法之一禁用此默认行为：

在 JBoss EAP 6 中，集群服务的 API 位于私有模块中，且不被支持。

JBoss EAP 7 引入了应用程序使用的公共集群服务 API。新服务旨在轻便、易注入，不需要外部依赖项。

这些服务取代了之前版本中提供的类似 API，即 JBoss EAP 5 中的 HAPartition，以及 JBoss EAP 6 中的 GroupCommunicationService, GroupMembershipNotifier, 和 GroupRpcDispatcher

如需更多信息，请参阅 JBoss EAP 7.4 开发指南中的 集群服务的公共 API。

在 JBoss EAP 6 中，没有可用于集群范围的 HA 单例服务的公共 API。如果您使用私有 org.jboss.as.clustering.singleton prerequisites 类，您必须在将应用程序迁移到 JBoss EAP 8 时更改您的代码以使用新的公共 org.wildfly.clustering.singleton prerequisites 软件包。

有关 HA 单例服务的更多信息，请参阅 JBoss EAP 7.4 开发指南中的 HA 单例服务。有关 HA 单例部署的信息，请参阅 JBoss EAP 7.4 开发指南中的 HA 单例部署。

IBM MQ 是 IBM 提供的消息传递导向中间件(MOM)产品，允许分布式系统上的应用程序相互通信。这可以通过使用消息和消息队列来实现。IBM MQ 负责将消息发送到消息队列，并使用消息通道将数据传送到其他队列管理器。有关 IBM MQ 的更多信息，请参阅 IBM 产品网站上的 IBM MQ。

概述

IBM MQ 可以配置为 JBoss EAP 8.0 的外部 Java 消息服务供应商。本节介绍在 JBoss EAP 中部署和配置 IBM MQ 资源适配器的步骤。此部署和配置可以通过管理 CLI 工具或基于 Web 的管理控制台来完成。有关 IBM MQ 支持的配置，请参阅 JBoss EAP 支持的配置。

JBoss EAP 8.0 是一个 Jakarta EE 10 实现，因此用于所有 EE API 的软件包已从 javax 改为 jakarta，这需要 Jakarta EE 10 兼容资源适配器。如果您在 JBoss EAP 7.x 或更早版本中使用 IBM MQ 资源适配器，则必须使用 wmq.jakarta.jakarta.rar，使用这个 jakarta 命名空间的 IBM MQ 资源适配器。

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

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

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

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

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

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

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

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

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

从 JBoss EAP 8 开始，停止了对 Apache Log4j 版本 1 API 的支持。任何未打包 log4j.jar 和 log4j 配置的应用程序都必须更新。

影响：

日志消息将不再基于 logging 子系统进行路由。如果应用程序没有打包 log4j.jar，且以下任何语句都为 true，则需要迁移更改：

迁移：

或者

额外详情：

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

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

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

如需更多信息，请参阅 JBoss EAP 8.0 中不再提供 Apache Log4j 版本 1。

在 JBoss EAP 7.0 中，用来存储纯文本字符串加密的 安全 库与 JBoss EAP 7.1 或更高版本中的 Elytron 不兼容。JBoss EAP 7.1 或更高版本使用凭证存储来存储字符串。凭据将加密凭据存储在 JBoss EAP 配置文件之外的存储文件中。您可以使用 Elytron 提供的实现，也可以使用凭证存储 API 和 SPI 自定义配置。每个 JBoss EAP 服务器都可以包含多个凭据存储。

有关凭证存储的更多信息，请参阅 JBoss EAP 7.4 如何配置服务器安全性 中的凭据存储。https://access.redhat.com/documentation/zh-cn/red_hat_jboss_enterprise_application_platform/7.4/html-single/how_to_configure_server_security/#credential_store

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

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

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

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

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

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

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

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

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

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

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

以下示例假定 group.name 和 encoding.algorithm 安全属性在传统的 security 子系统中被定义为 security-properties。

在 security 子系统中定义的安全属性：

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

要在 elytron 子系统中定义这些安全属性，请使用以下管理 CLI 命令设置 elytron 子系统的 security-properties 属性：

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

这会在服务器配置文件中的 elytron 子系统中定义 security-properties。

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

上一命令中的 write-attribute 操作会覆盖现有属性。要在不影响其他安全属性的情况下添加或更改安全属性，请在管理 CLI 命令中使用 映射 操作：

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

同样，您可以使用 map-remove 操作删除特定的安全属性：

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

使用以下示例，将基于 PicketBox 属性的身份验证迁移到 Elytron。

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

这会生成以下服务器配置。

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

这部分论述了如何在 JBoss EAP 7.4 及更早版本中将用户、密码和组信息从属性文件加载到 Elytron 的传统安全域。这种类型的传统安全域通常用于保护管理接口或远程连接器。

在 JBoss EAP 8.0 中，filesystem-realm 优先于 properties-realm。

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

这会生成以下服务器配置。

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

在应用服务器中添加 Elytron 安全性的原因之一是允许跨服务器使用一致的安全解决方案。将基于属性的传统安全域迁移到 Elytron 的初始步骤与用于将 PicketBox 属性验证迁移到 Elytron 的验证类似。按照以下步骤，将基于属性的传统安全域迁移到 Elytron。

现在完成将基于旧属性的配置迁移到 Elytron。

使用 elytron.sh 工具的 filesystem-realm 命令将基于文件系统的安全域迁移到 Elytron 中的基于文件系统的域。

基于文件系统的域是 Elytron 用于存储用户身份的基于文件系统的身份存储。filesystem-realm 命令将 properties-realm 文件转换为 filesystem-realm。它还生成将这个域和安全域添加到 elytron 子系统的命令。

将旧的 LDAP 身份验证迁移到 Elytron，以便它可以作为身份属性管理信息。

以下示例假定组或角色信息直接从 LDAP 加载，并且传统的 LDAP 身份验证配置如下。

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

将基于 JDBC 数据源的 PicketBox 身份验证迁移到 Elytron。有关定义安全域、身份验证工厂和映射用于身份验证的说明，请参阅 迁移基于属性的身份验证和授权到 Elytron。

以下示例假定用户身份验证数据存储在使用类似以下示例的语法创建的数据库表中。

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

出于身份验证目的，用户名与用户名列中存储的数据匹配，密码应以十六进制编码的 MD5 哈希存储在 password 列中，以及用于授权目的的用户角色存储在 role 列中。

PicketBox 安全域配置为使用 JBDC 数据源从数据库表中检索数据，然后使用它验证用户名和密码，并分配角色。使用以下管理 CLI 命令，假设 PicketBox 安全域已配置：

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

这会在传统的 security 子系统中生成以下 login-module 配置。

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

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

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

在使用 Kerberos 配置时，JBoss EAP 服务器可以依赖环境中的配置信息，或者使用系统属性来指定密钥配置。

这些系统属性适用于传统配置和迁移的 Elytron 配置。

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

根据您的身份验证机制，选择以下迁移选项之一：

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

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

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

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

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

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

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

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

本节论述了如何将使用多个身份存储的 PicketBox 或 传统的安全域 配置迁移到 Elytron Aggregate Security Realm 配置。

使用 PicketBox 或旧的安全域时，可以在其中定义一个配置，当用于授权的信息从不同的存储加载时。迁移到 Elytron 时，可以使用聚合安全域来实现。

以下示例使用 example-users.properties 属性文件执行用户身份验证，然后查询 LDAP 来加载组和角色信息。

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

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

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

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

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

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

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

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

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

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

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

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

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

使用 PicketBox 时，可以定义一个安全域并启用内存缓存来访问。这样，您可以在内存中访问身份数据，并避免额外的直接访问身份存储。可以通过 Elytron 实现类似的配置。本节显示在使用 Elytron 时示例 PicketBox 配置和等同的安全域缓存配置。

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

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

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

默认情况下，JBoss EAP 7.4 及更早版本使用传统的 security 子系统配置 Jakarta 授权策略提供程序和工厂。默认配置映射从 PicketBox 映射到实施。

elytron 子系统根据容器的 Java 授权合同(JACC)规范提供内置的策略提供程序。

有关如何在 elytron 子系统中为容器策略提供程序启用和定义 Java 授权合同的信息，请参阅 JBoss EAP 7.4 开发指南中的 定义 Jakarta 身份验证策略提供程序。

使用配置方法将您的命名客户端迁移到 Elytron。

使用此方法，您可以提供用于在应用程序代码中直接建立连接的用户凭证。

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

此迁移示例假定客户端应用已配置为通过 jboss-ejb-client.properties 文件调用部署到远程服务器的 Jakarta Enterprise Beans。此文件位于客户端应用程序 META-INF/ 目录中，包含连接到远程服务器所需的以下信息：

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

客户端使用类似以下示例的代码查找 Jakarta Enterprise Beans 并调用其方法之一。

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

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

您可以从以下迁移方法之一进行选择：

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

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

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

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

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

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

要启用 CLIENT-CERT SSL 身份验证，请在 authentication 元素中添加 truststore 元素。

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

传统的 truststore 可以通过两种方式使用：

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

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

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

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

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

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

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