アプリケーションをあるメジャーリリースから別のメジャーリリース (JBoss EAP 7 から JBoss EAP 8.0 など) に移動した場合は、メジャーアップグレードまたは移行が必要です。Jakarta EE 8 仕様に準拠しているアプリケーション、独自のコードが含まれているアプリケーション、または非推奨の API を使用しているアプリケーションを JBoss EAP 8.0 で実行するには、アプリケーションコードの変更が必要になる場合があります。Jakarta EE 10 の導入には、Java パッケージ名やその他の側面の変更が含まれており、JBoss EAP 8.0 との互換性を確保するために Jakarta EE アプリケーションコードの調整が必要になります。さらに、JBoss EAP 8.0 ではサーバー設定が変更されたため、移行が必要です。本書ではこのような移行を取り上げます。

JBoss EAP のマイナーアップデートは、バグ修正、セキュリティー修正、および新機能を提供するポイントリリースです。各ポイントリリースで行われた変更は、Red Hat JBoss Enterprise Application Platform 8.0 のリリースノート に記載されています。

JBoss Server Migration Tool を使用して、あるポイントリリースから別のポイントリリースに自動的にアップグレードします (たとえば、JBoss EAP 7.0 から JBoss EAP 7.1 など)。詳細は、JBoss Server Migration Tool の使用 を参照してください。

JBoss EAP は、バグ修正とセキュリティー修正を含む累積パッチを定期的に提供します。累積パッチのリリースでは、リリース番号の最後の数字が 1 ずつ増えます (例: バージョン 7.1.0 から 7.1.1 へのアップグレードなど)。

JBoss Server Migration Tool は、JBoss EAP バージョン 7 のすべてのリリースから JBoss EAP 8.0 への移行をサポートします。

CDI 4.0 仕様変更ノート に従って、空の beans.xml ファイルを使用したデプロイメントで Contexts and Dependency Injection (CDI) Bean を検出するためのデフォルトの動作が、all から annotated に変更されました。これは、そのようなデプロイメントの場合、Bean 定義アノテーション を持つデプロイメントクラスのみが、CDI によって検出されることを意味します。Bean を使用するすべてのアプリケーションクラスにそのようなアノテーションがある場合、この CDI の変更は影響しません。そうでない場合は、CDI が特定の Bean を提供する型を見つけられず、アプリケーションのデプロイメントが失敗する可能性があります。

アプリケーションがこの変更の影響を受ける場合、いくつかのオプションがあります。

Jakarta Contexts and Dependency Injection 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 にパラメーターのいずれかが欠落している場合は、デフォルト値が使用されます。JSON 内にすべてのパラメーターが存在することを必要とする EE 8 の動作は、jakarta.json.bind.JsonbConfig().withCreatorParametersRequired(true) を呼び出すことで有効化できます。

次の非推奨の機能は Jakarta Faces 4.0 で削除されました。

Jakarta Servlet 6.0 では、Servlet 5.0 以前 (主に Servlet 2.x リリース) で非推奨となった多数の API クラスとメソッドが削除されています。

javax.servlet.SingleThreadModel マーカーインターフェイスは削除されたため、このインターフェイスを実装するサーブレットはインターフェイス宣言を削除し、サーブレットコードが状態および他のリソースアクセスを同時アクセスから適切に保護するようにする必要があります。たとえば、インスタンス変数の使用を回避したり、リソースにアクセスするコードのブロックを同期したりします。ただし、このような同期はパフォーマンスに悪影響を与えるため、開発者は service メソッド (またはサービスメソッドのディスパッチ先である doGet や doPost などのメソッド) を同期しないことが推奨されます。

javax.servlet.http.HttpSessionContext インターフェイスは、javax.servlet.http.HttpSession.getSessionContext() メソッドとともに削除されました。サーブレット 2.1 以降、このインターフェイスの実装では使用可能なデータを提供しないことが仕様で要求されていたため、このインターフェイスの使用例はありませんでした。

javax.servlet.http.HttpUtils ユーティリティークラスは削除されました。アプリケーションは、次のメソッドの代わりに ServletRequest インターフェイスと HttpServletRequest インターフェイスを使用する必要があります。

また、次のさまざまなメソッドとコンストラクターが削除されました。

jaxm.properties ファイルによるプロバイダー検索のサポートは削除されました。

非推奨の javax.xml.soap.SOAPElementFactory クラスは削除されました。SOAPElements の作成には、jakarta.xml.soap.SOAPFactory を使用します。

xml バインディングファイルで使用する必要がある XML 名前空間が変更されました。http://java.sun.com/xml/ns/jaxb 名前空間は https://jakarta.ee/xml/ns/jaxb に置き換える必要があります。

非推奨の javax.xml.bind.Validator インターフェイスは、associated javax.xml.bind.JAXBContext.createValidator() メソッドと同様に削除されました。マーシャリングおよびアンマーシャリング操作を検証するには、javax.xml.validation.Schema を jakarta.xml.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 specification を参照してください。

javax.xml.bind.Marshaller インターフェイスの多くのメソッドの一般的な要件は、次のように変更されました。

Jakarta XML Binding API の変更とは別に、実装ライブラリー EAP 8 のパッケージ名が大幅に変更されました。これは、実装ライブラリーに直接アクセスする一部のアプリケーションに影響を与える可能性があります。

JBoss EAP 7.0 では、Web アプリケーションのルートコンテキストは mod_cluster でデフォルトで無効になっていました。

JBoss EAP 7.1 よりこれが変更にななりました。そのため、ルートコンテキストが無効になっていることを想定している場合は予期せぬ結果が生じる可能性があります。たとえば、リクエストが誤って不都合なノードにルーティングされたり、公開してはならないプライベートアプリケーションにパブリックプロキシーを介してアクセスされる可能性があります。Undertow の場所は、明示的に除外されない限り、mod_cluster ロードバランサーにも自動的に登録されるようになりました。

以下の管理 CLI コマンドを使用して、modcluster サブシステム設定から ROOT を除外します。

/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 応答に追加される 2 つの応答ヘッダーフィルターが含まれていました。

使用中のサーバーに関する情報を無意識に公開しないようにするため、これらの応答ヘッダーフィルターはデフォルトの 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 以降のバージョンでは、パッシベーションが有効になっているカスタムステートフルセッション Bean (SFSB) キャッシュが変更されました。パッシベーションを使用して SFSB キャッシュを設定する場合は、次の重要な変更点を考慮してください。

JBoss EAP 7.1 以降のバージョンでパッシベーション用のカスタム SFSB キャッシュを設定する場合は、以下の制限を考慮してください。

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 JavaBeans (EJB) サブシステム設定への変更が導入されています。JBoss EAP 6 および 7 で使用されるいくつかのリソースも非推奨になりました。これらの変更により、サーバー設定の移行が可能になり、アプリケーションが今後のメジャーリリースと確実に互換性を持つことができます。

JBoss EAP 8.0 は、JBoss EAP 6 および 7 で使用されていた非推奨のリソースを 2 つの新しいリソースと、SFSB キャッシングを分散的に設定するための distributable-ejb サブシステムに置き換えます。次の表は、非推奨のリソースと、それらに代わる新しいリソースの概要を示しています。

非分散 SFSB キャッシュ /subsystem=ejb3/simple-cache は、パッシベーションストアが定義されていない JBoss EAP 7 で使用される SFSB キャッシュ /subsystem=ejb3/cache と同等になります。

分散可能 SFSB キャッシュ /subsystem=ejb3/distributable-cache には、distributable-ejb サブシステムからの対応するリソースを参照するオプションの bean-management 属性が含まれています。リソースを定義しない場合、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 は、Jakarta Messaging サポートプロバイダーとして ActiveMQ Artemis を引き続き使用します。これにより、移行プロセスがよりスムーズになります。

サードパーティーの Jakarta Messaging プロバイダーで使用する汎用 Jakarta Messaging リソースアダプターを設定する方法が、Red Hat JBoss Enterprise Application Platform 8.0 で変更されました。詳細は、JBoss EAP 7.4 メッセージングの設定 ガイドの 汎用 Java Message Service リソースアダプターのデプロイ を参照してください。

Red Hat JBoss Enterprise Application Platform 7.0 では、check-for-live-server 属性を指定せずに replication-primary ポリシーを設定した場合、そのデフォルト値は false に設定されました。これは JBoss EAP 7.1 で変更されました。check-for-live-server 属性のデフォルト値が true に設定されるようになりました。

以下は、check-for-live-server 属性を指定せずに replication-primary ポリシーを設定する管理 CLI コマンドの例です。

/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 では、この機能は、embedded-activemq と呼ばれる新しい Galleon レイヤーに追加されました。

この新しいレイヤーはデフォルト設定の一部ではないため、JBoss EAP にブローカーが組み込まれていることを信頼するユーザーは、それを明示的に設定に含める必要があります。

このレイヤーは、お客様が OpenShift 上の専用 AMQ クラスターを使用することが推奨されている場合でも、組み込みブローカーを備えた messaging-activemq サブシステムを提供します。また、このユースケースをサポートするために必要なソケットバインディングや必要な依存関係などの従属リソースもプロビジョニングします。

Vault は JBoss EAP 8.0 から削除されました。気密性の高い文字列の保存には、elytron サブシステムによって提供される認証情報ストアを使用してください。

レガシーセキュリティーサブシステムとレガシーセキュリティーレルムは、JBoss EAP 8.0 から削除されました。elytron サブシステムによって提供されるセキュリティーレルムを使用してください。

PicketLink サブシステムは JBoss EAP 8.0 から削除されました。PicketLink アイデンティティープロバイダーの代わりに Red Hat build of Keycloak を使用し、PicketLink サービスプロバイダーの代わりに Red Hat build of Keycloak SAML アダプターを使用してください。

keycloak サブシステムは、JBoss EAP 8.0 ではサポートされず、elytron-oidc-client サブシステムに置き換えられます。移行は、デフォルトで JBoss Server Migration Tool が実行します。

JBoss EAP 8.0 では、レガシーセキュリティーサブシステムが削除されました。elytron サブシステムでカスタムログインモジュールを引き続き使用するには、新しい Java Authentication and Authorization Service (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 (JAX-RPC) は Java EE 6 で非推奨となり、Java EE 7 ではオプションとなりました。JBoss EAP 7 以降、サポートされなくなりました。JAX-RPC を使用するアプリケーションは、現在の Jakarta EE 標準 Web サービスフレームワークである Jakarta XML Web Services を使用するように移行する必要があります。

JAX-RPC web サービスの使用は、以下のいずれかの方法で特定できます。

以前のリリースの JBoss EAP では、エンドポイントデプロイメントアーカイブを jbossws-cxf.xml 設定ファイルに含め、JBossWS と Apache CXF の統合をカスタマイズすることができました。このユースケースの 1 つが、Apache CXF バスで Web サービスクライアントおよびサーバーエンドポイントのインターセプターチェインを設定することでした。この統合には、JBoss EAP サーバーに Spring をデプロイする必要がありました。

Spring 統合は JBoss EAP 8 ではサポートされなくなりました。jbossws-cxf.xml 記述子設定ファイルが含まれるアプリケーションを編集し、このファイルに定義されているカスタム設定を置き換える必要があります。JBoss EAP 7 でも Apache CXF API に直接アクセスすることはできますが、アプリケーションは移植できないことに注意してください。

可能な場合は、Spring のカスタム設定を新しい JBossWS 記述子設定オプションに置き換えることが推奨されます。この JBossWS 記述子ベースの方法では、クライアントエンドポイントコードを編集する必要がなく、同様の機能を提供できます。場合によっては、Spring を Context and Dependency Injection (コンテキストと依存性の注入、CDI) に置き換えることができます。

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

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

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

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

client.setChunkingThreshold(8192);
...

このセクションでは、JBoss EAP 6.4 および JBoss EAP 7.0 でのアプリケーションの WS-Security のさまざまな変更について説明します。

cxf-api および cxf-rt-core JAR が 1 つの cxf-core JAR に統合されました。そのため、JBoss EAP の org.apache.cxf モジュールに cxf-core JAR が含まれるようになり、これまでのリリースよりも多いクラスが公開されました。

XML/WS-Security での対称暗号化で Galois/Counter Mode (GCM) を用いた AES 暗号化を使用したい場合、BouncyCastle Security Provider が必要になります。

JBoss EAP 7 以降、これは org.bouncycastle モジュールに含まれており、JBossWS はそのクラスローダーを信頼して BouncyCastle セキュリティープロバイダーを取得して使用できるようになりました。そのため、現在の 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 で、変更はありません。以下の方法の 1 つを使用すると、以前のリリースでの動作を復元できます。

コンテナーは、コンストラクターで WebServiceFeature クラスが引数として含まれる Jakarta XML Web Services 2.2 スタイルのコンストラクターを使用して、web サービス参照に注入されるクライアントをビルドする必要があります。JBossWS 4 が同梱される JBoss EAP 6.4 はこの要件を隠します。JBossWS 5 を含む JBoss EAP 7 以降、この要件は隠蔽されていません。これは、コンテナーによって注入されるユーザー提供のサービスクラスは、1 つ以上の WebServiceFeature 引数を含む jakarta.xml.ws.Service コンストラクターを使用するように既存のコードを更新することにより、Jakarta XML Web Services 2.2 以降を実装する必要があることを示しています。

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 モジュールから自動的にハンドラークラスをロードすることができなくなりました。アプリケーションが事前定義の設定に依存する場合、デプロイメントの新しいモジュール依存関係を明示的に定義する必要があることがあります。詳細は、明示的なモジュール依存関係の移行 を参照してください。

Java Endorsed Standards Override Mechanism は JDK 1.8_40 では非推奨になり、JDK 9 では削除される予定です。これは、JAR を JRE 内の endorsed ディレクトリーに置くことで、デプロイされたアプリケーションすべてがライブラリーを利用できるメカニズムです。

JBoss EAP 7 リリース以降、アプリケーションが Apache CXF の JBossWS 実装を使用している場合は、必要な依存関係が正しい順序で確実に追加されるようになり、ユーザーはこの変更による影響を受けることはありません。アプリケーションが Apache CXF に直接アクセスする場合、アプリケーションデプロイメントの一部として JBossWS の依存関係の後に Apache CXF の依存関係を提供する必要があります。

以前のリリースの JBoss EAP では、Jakarta Enterprise Beans Web サービスデプロイメントの jboss-webservices.xml デプロイメント記述子ファイルを JAR アーカイブの META-INF/ ディレクトリーまたは POJO Web サービスデプロイメントの WEB-INF/ ディレクトリーと、WAR アーカイブにバンドル化された Jakarta Enterprise Beans Web サービスエンドポイントに設定することができました。

JBoss EAP 7 以降では、EAR アーカイブの META-INF/ ディレクトリーに jboss-webservices.xml デプロイメント記述子ファイルを設定できるようになりました。jboss-webservices.xml ファイルが EAR アーカイブおよび JAR または WAR アーカイブで見つかった場合、JAR または WAR の jboss-webservices.xml ファイル内の設定データは、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 platform の Resource Definition and 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 を使用できました。

JBoss EAP 7 では、Apache ActiveMQ Artemis が 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 より、クライアントアプリケーションが直接 Artemis クライアント JAR (artemis-jms-client、artemis-commons、artemis-core-client、artemis-selector など) に依存する場合は wildfly-client-properties の pom.xml ファイルに以下の依存関係を追加する必要があります。

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

これにより、JBEAP-15889 に記載されているように、旧バージョンの JBoss EAP 7 クライアントから message.getJMSReplyTo() を呼び出すときに JMSRuntimeException が発生しないようにします。

インターセプターおよび MessageBody クラス

JSR 311: JAX-RS: The Java™ API for RESTful Web Services にはインターセプターフレームワークが含まれなかったため、RESTEasy 2 によって提供されました。JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services は、公式のインターセプターおよびフィルターフレームワークを導入したため、RESTEasy 2 に含まれるインターセプターフレームワークは現在非推奨となり、RESTEasy 3.x の Jakarta REST 準拠インターセプター機能に置き換えられました。関連するインターフェイスは、jakarta.ws.rs.api モジュールの jakarta.ws.rs.ext パッケージで定義されています。

以下のプロバイダーは JBoss EAP 8.0 で削除されました。

以下は Jakarta RESTful Web Services に置き換えられたため、JBoss EAP 8.0 では削除されました。

クライアント 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 Add メソッド

RESTEasy 3.0 では、org.jboss.resteasy.spi.ResteasyProviderFactory add() メソッドのほとんどが削除または保護されています。たとえば、addBuiltInMessageBodyReader() および addBuiltInMessageBodyWriter() メソッドは削除されaddMessageBodyReader() および addMessageBodyWriter() メソッドは保護されました。

現時点では、registerProvider() と registerProviderInstance() のメソッドを使用してください。

RESTEasy 3 から削除された他のクラス

Jakarta REST メソッドへの応答をサーバー上にキャッシュする必要があることを指定した @org.jboss.resteasy.annotations.cache.ServerCached アノテーションは RESTEasy 3 から削除されたため、アプリケーションコードから削除する必要があります。

このセクションでは、JBoss EAP の RESTEasy への追加的な変更点について説明します。

SignedInput および SignedOuput

セキュリティーフィルター

@RolesAllowed、@PermitAll、および @DenyAll のセキュリティーフィルターは、"401 Unauthorized" ではなく "403 Forbidden" を返すようになりました。

クライアント側のフィルター

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 によって使用される SnakeYAML ライブラリーにセキュリティー上の問題があるため、YAML プロバイダーの使用はサポートされず、アプリケーションで明示的に有効にする必要があります。アプリケーションで YAML プロバイダーを有効にし、Maven 依存関係を追加する方法は、JBoss EAP 7.4 Web サービスアプリケーションの開発の YAML プロバイダー を参照してください。

Content-Type ヘッダーのデフォルトの文字セット UTF-8

JBoss EAP 7.1 より、デフォルトで resteasy.add.charset パラメーターが true に設定されています。リソースメソッドが明示的な文字セットなしで text/* または application/xml* メディアタイプを返すときに、返された content-type ヘッダーに charset=UTF-8 を追加したくない場合は、resteasy.add.charset パラメーターを false に設定できます。

テキストメディアタイプと文字セットの詳細は、JBoss EAP 7.4 Web サービスアプリケーションの開発の テキストメディアタイプおよび文字セット を参照してください。

SerializableProvider

信用できないソースから Java オブジェクトをデシリアライズすることは危険です。そのため、JBoss EAP 7 以降では org.jboss.resteasy.plugins.providers.SerializableProvider クラスがデフォルトで無効となり、このプロバイダーの使用は推奨されません。

リソースメソッドへのリクエストの一致

RESTEasy 3 では、JAX-RS 仕様の定義どおりに、一致ルールの実装に改善および修正が加えられました。特に、サブリソースメソッドおよびサブリソースロケーターのあいまいな URI の処理方法が変更されました。

RESTEasy 2 では、同じ URI を持つ別のサブリソースが存在していても、サブリソースロケーターが正常に実行される可能性がありました。仕様上ではこの挙動は適切ではありません。

RESTEasy 3 では、サブリソースおよびサブリソースロケーターのあいまいな URI が存在する場合、サブリソースの呼び出しには成功しますが、サブリソースロケーターの呼び出しは HTTP ステータス 405 Method Not Allowed のエラーによって失敗します。

以下の例には、サブリソースメソッドおよびサブリソースロケーターのあいまいな @Path アノテーションが含まれています。エンドポイント anotherResource および anotherResourceLocator 両方の URI は同じであることに注目してください。この 2 つのエンドポイントの違いは、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();
    }
}

RESTEasy SPI プロバイダーは JBoss EAP 8 で削除されました。

SPI 例外

すべての SPI 失敗例外は非推奨となり、内部的には使用されません。これらは、対応する Jakarta REST 例外に置き換えられました。

InjectorFactory および 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 のサポートを提供します。JBoss EAP 8.0 で Spring 6.0 フレームワークを使用する予定の場合は、Java 17 を使用する必要があります。

Spring 4.0 フレームワークには、Java 8 のサポートが導入されました。Spring と RESTEasy 3.x 統合を使用する場合は、使用するデプロイメントで最小 Spring バージョンに 4.2.x を指定してください。 これは JBoss EAP 7 がサポートする安定性のある最も早期のバージョンです。

RESTEasy Jettison JSON プロバイダーは JBoss EAP 7 以降非推奨となり、デフォルトでデプロイメントに追加されなくなりました。推奨される 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 クラスは、CDI によって検出され、Bean として処理されるように、Bean アーカイブにデプロイされる必要があります。

CDI 1.1 には 暗黙的 bean アーカイブが導入されました。これは bean を定義するアノテーションを持つ bean クラスが 1 つ以上またはセッション bean が 1 つ以上含まれるアーカイブです。暗黙的な bean アーカイブは CDI によってスキャンされ、型検索中に bean を定義するアノテーションを持つクラスのみが検出されます。詳細は、JSR 365: Contexts and Dependency Injection for Java^™ 2.0 の Type and Bean Discovery を参照してください。bean 定義アノテーションの Jakarta に相当するものは、Jakarta Context Dependency Injection 2.0 specification で定義されています。

CDI 4.0 の場合:

CDI 4.0 の詳細は、Jakarta Contexts and Dependency Injection 4.0 を参照してください。

bean アーカイブは all、annotated、または none の bean 検索モードを持ちます。空ではない beans.xml を含む Bean アーカイブでは、bean-discovery-mode 属性を指定する必要があります。この属性のデフォルト値は annotated です。

以下の場合、アーカイブは bean アーカイブではありません。

次の場合、アーカイブは 明示的な Bean アーカイブです。

以下の場合、アーカイブは 暗黙的 bean アーカイブになります。

CDI 1.2 は bean を定義するアノテーション を以下に限定します。

会話コンテキストのライフサイクルは、CDI Specification Issue CDI-411 で説明されているサーブレット仕様との競合を回避するために、CDI 1.2 で変更されました。会話スコープはすべてのサーブレットリクエストの間はアクティブで、他のサーブレットやサーブレットフィルターによるリクエストボディーや文字エンコードの設定を妨害してはなりません。詳細は、Conversation context lifecycle in Jakarta EE を参照してください。

イベント解決は、CDI 1.2 で部分的に書き直されました。CDI 1.0 では、オブザーバーメソッドにすべてのイベント修飾子がある場合にイベントがオブザーバーメソッドに送信されます。CDI 1.2 では、オブザーバーメソッドにイベント修飾子がない場合やイベント修飾子のサブセットがある場合にイベントがオブザーバーメソッドに送信されます。詳細は、Observer resolution を参照してください。

このセクションでは、Hibernate ORM バージョン 5.3 から 5.4 に移行する際に必要な変更点について説明します。Hibernate ORM 5.3 と Hibernate ORM 5.4 の間で実装された変更の詳細は、Hibernate ORM 5.4 Migration Guide を参照してください。

既知の変更点

以下では、Hibernate ORM バージョン 5.3 から 5.4 に移行する際の変更点の一部について説明します。

このセクションでは、Hibernate ORM バージョン 5.4 から 5.5 に移行する際に必要な変更点について説明します。Hibernate ORM 5.4 と Hibernate ORM 5.5 の間で実装された変更の詳細は、Hibernate ORM 5.5 Migration Guide を参照してください。

既知の変更点

Hibernate ORM 5.5 バージョンは、5.4 メンテナンスリリースに適用されたすべてのバグ修正が含まれており、Jakarta Persistence API のサポートが導入されているため、Hibernate ORM 5.4 に似ています。

このセクションでは、Hibernate ORM バージョン 5.5 から 5.6 に移行する際に必要な変更点について説明します。Hibernate ORM 5.5 と Hibernate ORM 5.6 の間で実装された変更の詳細は、Hibernate ORM 5.6 Migration Guide を参照してください。

非推奨の機能

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 Migration Guide を参照してください。

Hibernate 6.0 リリースには次の変更が含まれています。

これらの機能の詳細は、Hibernate ORM 6.0 Migration Guide を参照してください。

以下に示すように、Hibernate 6.0 リリースでは、以前の Hibernate リリースの機能が多数削除されました。

Hibernate 6.0 で削除された機能の詳細は、Hibernate ORM 6.0 Migration Guide を参照してください。

このセクションでは、Hibernate ORM バージョン 6.0 から 6.1 に移行する際に必要な変更点について説明します。Hibernate ORM 6.0 と Hibernate ORM 6.1 の間で実装された変更の詳細は、Hibernate ORM 6.1 Migration Guide を参照してください。

Hibernate 6.1 リリースには次の変更が含まれています。

Hibernate 6.1 に含まれる機能の詳細は、Hibernate ORM 6.1 Migration Guide を参照してください。

このセクションでは、Hibernate ORM バージョン 6.1 から 6.2 に移行する際に必要な変更点について説明します。Hibernate ORM 6.1 と Hibernate ORM 6.2 の間で実装された変更の詳細は、Hibernate ORM 6.2 Migration Guide を参照してください。

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 Migration Guide を参照してください。

削除および非推奨となったクラス

以下のクラスは非推奨となり、Hibernate ORM 5 から削除されました。

クラスおよびパッケージのその他の変更

タイプ処理

トランザクション管理

Hibernate ORM 5 のその他の変更

JBoss EAP 7.1 には Hibernate ORM 5.1 が含まれていました。ここでは、この 2 つの違いと、Hibernate ORM のバージョン 5.0 からバージョン 5.1 に移行する際に必要な変更について説明します。

Hibernate ORM 5.1 の機能

Hibernate のこのリリースには、パフォーマンスの向上とバグ修正が含まれています。詳細は、JBoss EAP 7.1.0 リリースノート の Hibernate ORM 5.1 の機能 を参照してください。Hibernate ORM 5.0 から Hibernate ORM 5.1 の間に実装された変更に関する詳細は、Hibernate ORM 5.1 Migration Guide を参照してください。

スキーマ管理ツールの変更

JBoss EAP 7 でのスキーマ管理ツールの変更

Hibernate ORM 5.1 のスキーマ管理ツールの変更は、次の領域に重点を置いています。

スキーマ管理ツールの変更は、次のクラスを直接使用するアプリケーションにとってのみ移行の問題となります。

JBoss EAP 7.1 でのスキーマ管理ツールの変更

JBoss EAP 7.1 に含まれる Hibernate ORM 5.1.10 では、SchemaMigrator および SchemaValidator の パフォーマンスを向上させるデータベーステーブルを取得するストラテジーが導入されました。このストラテジーは、単一の java.sql.DatabaseMetaData#getTables(String, String, String, String[]) 呼び出しを実行して、各 javax.persistence.Entity がマップされたデータベーステーブルを持っているかどうかを判断します。これはデフォルトのストラテジーで、hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped プロパティー設定を使用します。このストラテジーには、hibernate.default_schema や hibernate.default_catalog を提供する必要があることがあります。

each javax.persistence.Entity に対して java.sql.DatabaseMetaData#getTables(String, String, String, String[]) 呼び出しを実行する古いストラテジーを使用するには、hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually プロパティー設定を使用します。

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 Migration Guide を参照してください。

Hibernate ORM 5.3 の機能

Hibernate ORM 5.3 には、Jakarta Persistence 2.2 仕様のサポートが追加されました。本リリースにはこの仕様に準拠する変更と、その他の改善点が含まれています。以下にこれらの変更の一部を示します。

Hibernate 5.3 に実装された変更の完全リストは、Hibernate ORM 5.3 Migration Guide を参照してください。

Hibernate 5.1 および Hibernate 5.3 間の例外処理の変更

Hibernate 5.2 と 5.3 では、Jakarta Persistence 仕様に準拠して、Hibernate のネイティブブートストラップを使用して構築される SessionFactory の例外処理は HibernateException をラッピングまたは変換しました。Session.save() や Session.saveOrUpdate() のように操作が Hibernate 固有の場合のみこの動作の例外となります。

Hibernate 5.3.3 では、hibernate.native_exception_handling_51_compliance プロパティーが追加されました。このプロパティーは、Hibernate のネイティブブートストラップを使用して構築された SessionFactory の例外処理が、Hibernate ORM 5.1 でのネイティブの例外処理と同じように動作すべきかどうかを示します。true に設定すると HibernateException は Jakarta Persistence 仕様のとおりにラップまたは変換されません。この設定は、Jakarta Persistence ブートストラップを使用して構築された SessionFactory では無視されます。

互換性トランスフォーマー

JBoss EAP 7.4 には、Hibernate ORM 5.1 との互換性がなくなった Hibernate ORM 5.3 API メソッドに対応する互換性トランスフォーマーが含まれています。トランスフォーマーは、Hibernate ORM 5.1 を使用して構築されたアプリケーションが JBoss EAP 7.4 の Hibernate 5.3 で同じ動作を実行できるようにするための一時的な措置です。これは一時的な対策であり、これらのメソッド呼び出しを推奨される Jakarta Persistence メソッド呼び出しに置き換える必要があります。

トランスフォーマーを有効にするには、以下の方法の 1 つを使用します。

以下の表は、変換前の Hibernate 5.1 メソッドと、変換後の Hibernate 5.3 メソッドを表しています。

JBoss EAP 8.0 では 、Hibernate Search 5 API が削除され、Hibernate Search 6 API に置き換えられました。

削除された機能のリストを確認するには、Hibernate Search 5 APIs Deprecated in JBoss EAP 7.4 and removed in 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 Search アーキテクチャーとバックエンドのリストを確認するには、Hibernate Search 6.2 リファレンスドキュメントの Table 2. Comparison of architectures を参照してください。

Hibernate Search 6 の設定の詳細は、「WildFly Developer guide」の Using Hibernate Search を参照してください。

JBoss EAP 7 以降、デフォルトのリモートコネクターとポートが変更されました。この変更の詳細は、リモート URL コネクターおよびポートの更新 を参照してください。

JBoss Server Migration Tool を使用してサーバー設定を移行した場合、古い設定が保存されるため、ここで説明する変更を行う必要はありません。ただし、新しい 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 に含まれていました。4.0.x には API に対する多くの変更が含まれています。

JBoss EAP 6.4 で AuthenticatorBase を拡張するカスタムオーセンティケーターバルブを作成した場合、JBoss EAP 7.1 では手作業でカスタム HTTP 認証実装に置き換える必要があります。HTTP 認証メカニズムは elytron サブシステムで作成され、undertow サブシステムで登録されます。カスタム HTTP 認証メカニズムの実装方法の詳細は、JBoss EAP 7.4 開発ガイド の カスタム HTTP メカニズムの開発 を参照してください。

PicketLink は JBoss EAP 8.0 から削除されました。

PicketLink SP

PicketLink サービスプロバイダーの代わりに Keycloak SAML アダプターを使用します。

Keycloak SAML アダプターを設定して PicketLink から移行するには、次のタスクを実行します。

PicketLink IDP

JBoss EAP 8.0 以降では、PicketLink IDP を使用できません。代わりに Red Hat build of Keycloak を設定できます。詳細は、Red Hat build of Keycloak の設定 を参照してください。

PicketLink STS

以前のリリースでは、Apache CXF Security Token Service 実装の代替として PicketLink STS を設定できました。PicketLink STS 設定には、レガシーセキュリティードメインが含まれていました。STS アプリケーション内のレガシーセキュリティードメインおよび PicketLink への参照はすべて削除する必要があるため、代わりに Apache CXF STS を設定する必要があります。

Apache CXF STS の設定方法に関する詳細は、JBoss EAP 7.4 Web サービスアプリケーションの開発 の セキュリテイートークンサービス (STS) を参照してください。

Vault は JBoss EAP 8.0 から削除されました。アプリケーションでレガシー Vault 式を使用している場合は、Elytron 暗号化式を移行して使用する必要があります。

デプロイメントファイル内の ${VAULT:: のインスタンス (アノテーションやデプロイメント記述子にある可能性があります) を確認し、それらを対応する暗号化された式に置き換えます。

Keycloak OIDC クライアントアダプターは JBoss EAP 8.0 ではサポートされておらず、同様の機能と設定を提供するネイティブ Elytron OIDC クライアントに置き換えられました。

Keycloak OIDC クライアントアダプターからネイティブ Elytron OIDC クライアントに移行するには、次の手順を実行します。

JBoss EAP 8.0 では、レガシーセキュリティーサブシステムが削除されました。elytron サブシステムでカスタムログインモジュールを引き続き使用するには、新しい Java Authentication and Authorization Service (JAAS) セキュリティーレルムと jaas-realm を使用します。

JBoss EAP 7.2 以降とそれ以前のバージョンの間には、いくつかの顕著な違いがあります。

以下のリストでは、アプリケーションを JBoss EAP 6 から JBoss EAP 8.0 に移行する場合に注意が必要な新しいクラスタリング機能の一部について説明します。

JBoss EAP 7 では、新しい Web セッションクラスタリング実装が導入されました。これは、レガシーの JBoss Web サブシステムソースコードに密に結合された以前の実装に代わる実装です。

新しい Web セッションクラスタリング実装は、JBoss EAP プロプライエタリー Web アプリケーションの XML 記述子ファイルである jboss-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>

デプロイメント固有のセッション管理プロファイルの使用

単一の 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 では、以下の方法の 1 つでステートフルセッション Bean (SFSB) のクラスタリング動作を有効化する必要がありました。

JBoss EAP 7 以降では、クラスタリング動作を有効にする必要がなくなりました。デフォルトでは、HA プロファイルを使用してサーバーが起動された場合は SFSB の状態が自動的にレプリケートされます。以下の方法の 1 つを使用すると、このデフォルト動作を無効にできます。

JBoss EAP 6 では、クラスタリングサービスの API はプライベートモジュールでサポートされませんでした。

JBoss EAP 7 には、アプリケーションによって使用されるパブリッククラスタリングサービス API が導入されました。新しいサービスは、ライトウェイトで簡単にインジェクトできるよう設計されています。 外部の依存関係は必要ありません。

これらのサービスは、JBoss EAP 5 の HAPartition、JBoss EAP 6 の GroupCommunicationService、GroupMembershipNotifier、および GroupRpcDispatcher に代わるサービスです。 これらの API は以前のリリースで利用できました。

詳細は、JBoss EAP 7.4 開発ガイド の クラスタリングサービスのパブリック API を参照してください。

JBoss EAP 6 では、クラスター全体の HA シングルトンサービスに使用できるパブリック API がありませんでした。プライベート org.jboss.as.clustering.singleton.* クラスを使用した場合は、アプリケーションを JBoss EAP 8 に移行するときに、新しいパブリック org.wildfly.clustering.singleton.* パッケージを使用するようにコードを変更する必要があります。

HA シングルトンに関する詳細は、JBoss EAP 7.4 開発ガイド の HA シングルトンサービス を参照してください。HA シングルトンのデプロイメントに関する詳細は、JBoss EAP 7.4 開発ガイド の HA シングルトンデプロイメント を参照してください。

IBM MQ は、IBM のメッセージ指向ミドルウェア (MOM) 製品で、分散システム上のアプリケーションが互いに通信できるようにします。これは、メッセージとメッセージキューを使用して実行できます。IBM MQ は、メッセージキューにメッセージを配信し、メッセージチャネルを使用してデータを他のキューマネージャーへ転送します。IBM MQ の詳細は、IBM の製品 Web サイトの IBM MQ を参照してください。

summary

IBM MQ は、JBoss EAP 8.0 の外部 Java Message Service プロバイダーとして設定できます。このセクションでは、JBoss EAP で IBM MQ リソースアダプターをデプロイして設定する手順を説明します。このデプロイメントと設定は、管理 CLI ツールまたは Web ベースの管理コンソールを使用して実行できます。IBM MQ のサポートされる設定に関する最新情報は、JBoss EAP supported configurations を参照してください。

JBoss EAP 8.0 は Jakarta EE 10 実装であるため、すべての EE API に使用されるパッケージは javax から jakarta に変更され、Jakarta EE 10 準拠のリソースアダプターが必要となります。JBoss EAP 7.x 以前で IBM MQ リソースアダプターを使用していた場合は、この jakarta 名前空間を使用する IBM MQ リソースアダプターである wmq.jakarta.jmsra.rar を使用する必要があります。

@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 設定をパッケージ化していないアプリケーションは更新する必要があります。

影響:

ログメッセージは、ロギングサブシステムに基づいてルーティングされなくなります。アプリケーションが log4j.jar をパッケージ化しておらず、次のステートメントのいずれかに該当する場合は、移行の変更が必要です。

移行:

OR

さらなる詳細:

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

詳細は、Apache Log4j version 1 is no longer provided in JBoss EAP 8.0 を参照してください。

JBoss EAP 7.0 のレガシー security サブシステムにプレーンテキスト文字列暗号化を保存するために使用される安全な vault は、JBoss EAP 7.1 以降の Elytron と互換性がありません。JBoss EAP 7.1 以降は、クレデンシャルストアを使用して文字列を保存します。クレデンシャルストアは、JBoss EAP 設定ファイル以外のストレージファイル内の認証情報を暗号化します。Elytron によって提供される実装を使用するか、クレデンシャルストア API および SPI を使用して設定をカスタマイズすることができます。各 JBoss EAP サーバーに複数のクレデンシャルストアを含めることができます。

クレデンシャルストアに関する詳細は、JBoss EAP 7.4 サーバーセキュリティーの設定方法 の クレデンシャルストア を参照してください。

$ 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 コマンドで map 操作を使用します。

/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 セキュリティーをアプリケーションサーバーに追加する理由の 1 つは、サーバー全体で一貫したセキュリティーソリューションを使用できるようにすることでした。プロパティーベースのレガシーセキュリティーレルムを Elytron に移行する最初のステップは、PicketBox プロパティーベースの認証を Elytron に移行する方法と似ています。以下の手順に従って、プロパティーベースのレガシーセキュリティーレルムを Elytron に移行します。

これで、レガシープロパティーベースの設定の Elytron への移行が完了しました。

elytron.sh ツールの filesystem-realm コマンドを使用して、レガシープロパティーベースのセキュリティーレルムを Elytron のファイルシステムベースのレルムに移行します。

ファイルシステムベースのレルムは、ユーザー ID を保存するための、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)
)

認証の目的で、ユーザー名は username 列に格納されたデータと照合され、パスワードは 16 進エンコードされた MD5 ハッシュとして password 列に格納されることが想定されます。 さらに、承認目的のユーザーロールは role 列に格納されます。

PicketBox セキュリティードメインは、データベーステーブルからデータを取得するために JBDC データソースを使用します。PicketBox セキュリティードメインは以下の管理 CLI コマンドを使用して設定されることを仮定します。

/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 またはレガシーセキュリティーレルムを使用する場合、承認に使用される情報を 1 つのアイデンティティーストアからロードしながら別のアイデンティティーストアに対して認証を実行する設定を定義することが可能です。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 で実現することができます。このセクションでは、PicketBox 設定の例と、Elytron を使用する場合の同等のセキュリティードメインキャッシュ設定を示します。

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

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

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

デフォルトでは、JBoss EAP 7.4 以前では、レガシーセキュリティーサブシステムを使用して Jakarta Authorization ポリシープロバイダーおよびファクトリーを設定します。デフォルト設定は PicketBox から実装へマップします。

elytron サブシステムは、Java Authorization Contract for Containers (JACC) 仕様をベースとした組み込みポリシープロバイダーを提供します。

elytron サブシステムで Java Authorization Contract for Containers ポリシープロバイダーを有効にして定義する方法は、JBoss EAP 7.4 開発ガイド の Jakarta Authentication ポリシープロバイダーの定義 を参照してください。

設定アプローチを使用して、ネーミングクライアントを 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 を検索し、メソッドの 1 つを呼び出します。

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

以下の移行方法の 1 つを選択できます。

// 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 認証を有効にするには、truststore 要素を authentication 要素に追加します。

<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 の使用方法は 2 つあります。

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