ログメッセージには、メッセージを報告するサブシステムのプロジェクトコードが接頭辞として付けられます。JBoss EAP 7 では、すべてのログメッセージの接頭辞が変更になりました。

JBoss EAP 7 で使用されるログメッセージの新しいプロジェクトコード接頭辞の完全リストは、JBoss EAP開発ガイドの JBoss EAP で使用されるプロジェクトコード を参照してください。

JBoss EAP 7.0 のルートロガーには、すべてのドメインサーバープロファイルと standalone-full-ha プロファイル以外のデフォルトのスタンドアロンプロファイル用のコンソールログハンドラーが含まれていました。JBoss EAP 7.1 より、ルートロガーには管理対象ドメインプロファイルのコンソールログハンドラーは含まれていません。ホストコントローラーとプロセスコントローラーはデフォルトでコンソールにログが記録されます。JBoss EAP 7.0 で提供された機能を実現するには、JBoss EAP 設定ガイドの Console ログハンドラーの設定 を参照してください。

JBoss EAP 7 の web サーバーは、JBoss Web から Undertow に変更になりました。そのため、web サブシステム設定を新しい JBoss EAP 7 undertow サブシステム設定に移行する必要があります。

管理 CLI migrate 操作を使うと、 web サブシステムをサーバー設定ファイル内の undertow に移行することができます。ただし、この操作では JBoss Web サブシステムのすべての設定が移行できるわけではないことに注意してください。"migration-warning" エントリーが表示される場合は、追加の管理 CLI コマンドを実行して設定を Undertow に移行する必要があります。管理 CLI migrate 操作についての詳細情報は、管理 CLI の移行操作 を参照してください。

以下の例は、JBoss EAP 6.4 のデフォルトの web サブシステム設定を示しています。

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

以下の例は、JBoss EAP 7.4 undertow サブシステムのデフォルト設定を示しています。

<subsystem xmlns="urn:jboss:domain:undertow:10.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>
    ...
</subsystem>

管理 CLI の migrate 操作はリライト条件を自動的に移行できません。"migration-warnings" として報告され、手作業で移行する必要があります。Undertow の述語属性およびハンドラーを使用すると (Undertow Predicates Attributes and Handlers を参照)、JBoss EAP 7 で同等の設定を作成できます。

以下の例は、rewrite 設定を含む JBoss EAP 6 の web サブシステム設定を示しています。

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

管理 CLI の移行操作 にある手順にしたがってサーバーと管理 CLI を開始し、以下のコマンドを使用して web サブシステム設定ファイルを移行します。

/subsystem=web:migrate

上記の設定で migrate 操作を実行すると、以下の "migration-warnings" がレポートされます。

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

サーバー設定ファイルを確認すると、undertow サブシステムが以下の設定になっています。

<subsystem xmlns="urn:jboss:domain:undertow:10.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="http" socket-binding="http"/>
         <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
         <host name="default-host" alias="localhost, example.com">
             <location name="/" handler="welcome-content"/>
         </host>
     </server>
     <servlet-container name="default">
         <jsp-config/>
     </servlet-container>
     <handlers>
         <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
     </handlers>
 </subsystem>

管理 CLI を使用してフィルターを作成し、undertow サブシステムのリライト設定を置き換えます。各コマンドで "{"outcome" ⇒ "success"}" が表示されるはずです。

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

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

更新されたサーバー設定ファイルを確認します。JBoss Web サブシステムは完全に移行され、undertow サブシステムに設定されます。

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

管理 CLI を使用してフィルターとハンドラーを設定する方法については、JBoss EAP 7設定ガイドの Web サーバーの設定 を参照してください。

以前のリリースの JBoss EAP では、システムプロパティーを使用して JBoss Web のデフォルトの動作を変更することが可能でした。Undertow で同じ動作を設定する方法は、JBoss Web システムプロパティー移行のリファレンス を参照してください。

JBoss EAP 6.4 から JBoss EAP 7 に移行するときに、アクセスログに予期される "Referer" および "User-agent" 値が書き込まれないことに気付くかもしれません。これは、JBoss EAP 6.4 に含まれていた JBoss Web は access-log で %{headername}i パターンを使用して受信ヘッダーをログに記録したためです。

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

JBoss EAP 7 では Undertow が使用されるようになったため、受信ヘッダーのパターンは %{i,headername} に変更になりました。

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

以前のリリースの JBoss EAP ではバルブがサポートされました。バルブとは、リクエストの変更や追加処理を実行するために、サーブレットフィルターの前にアプリケーションのリクエスト処理パイプラインへ挿入されるカスタムクラスのことです。

この項では、グローバルバルブの移行方法について説明します。カスタムおよびオーセンティケーターバルブの移行については、本ガイドの カスタムアプリケーションバルブの移行 を参照してください。

JBoss EAP 7 で JBoss Web の代わりに導入された Undertow はグローバルバルブをサポートしませんが、Undertow ハンドラーを使用すると同様の機能を実現できます。Undertow には共通の機能を提供する複数のビルトインハンドラーが含まれています。また、カスタムハンドラーを作成する機能も含まれ、カスタムバルブの機能を置き換えるために使用することができます。

アプリケーションがバルブを使用する場合、JBoss EAP 7 へ移行するときに適切な Undertow ハンドラーコードに置き換え、同様の機能を実現する必要があります。

ハンドラーの設定方法に関する詳細は、JBoss EAP 7設定ガイドの ハンドラーの設定 を参照してください。

フィルターの設定方法に関する詳細は、JBoss EAP 7設定ガイドの フィルターの設定 を参照してください。

JBoss Web バルブの移行

以下の表では、JBoss EAP の前リリースで JBoss Web が提供していたバルブとそれに対応する Undertow ビルトインハンドラーを示しています。JBoss Web バルブは、org.apache.catalina.valves パッケージにあります。

管理 CLI の migrate 操作を使用すると、以下の基準を満たすグローバルバルブを自動的に移行できます。

管理 CLI migrate 操作についての詳細情報は、管理 CLI の移行操作 を参照してください。

JDBCAccessLogValve の手動移行の手順

org.apache.catalina.valves.JDBCAccessLogValve バルブはルールの例外で、io.undertow.server.handlers.JDBCLogHandler へ自動的に移行することができません。以下の手順に従って、次のバルブ例を移行します。

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

RFC2109 や RFC2965 など、Set-Cookie HTTP 応答ヘッダー構文の以前の仕様では、クッキー値が引用符で囲まれている場合はクッキー値に空白やその他の区切り文字を使用することができました。JBoss EAP 6.4 の JBoss Web は以前の仕様に準拠し、区切り文字が含まれるクッキー値を自動的に引用符で囲みました。

Set-Cookie HTTP 応答ヘッダー構文の RFC6265 仕様には、Set-Cookie 応答ヘッダーのクッキー値は特定の文法制約に準拠しなければならないと記載されています。たとえば、US-ASCII 文字でなければならず、CTRL (コントロール)、空白、2 重引用符、コンマ、セミコロン、またはバックスラッシュ文字を含んではいけません。

JBoss EAP 7.0 の累積パッチ Red Hat JBoss Enterprise Application Platform 7.0 Update 08 以前では、Undertow はこれらの無効な文字を制限せず、除外された文字が含まれたクッキーを引用符で囲みません。この累積パッチまたはこれ以降の累積パッチを適用し、 io.undertow.cookie.DEFAULT_ENABLE_RFC6265_COOKIE_VALIDATION システムプロパティーを true に設定すると、RFC6265 に準拠するクッキーの検証を有効にすることができます。

JBoss EAP 7.1 より、Undertow はデフォルトで RFC6265 に準拠するクッキーの検証を有効化しないようになりました。除外された文字が含まれたクッキーを引用符で囲みます。JBoss EAP 7.1 より、io.undertow.cookie.DEFAULT_ENABLE_RFC6265_COOKIE_VALIDATION システムプロパティーを使用して RFC6265 に準拠するクッキーの検証を有効にすることはできません。代わりに、rfc6265-cookie-validation リスナー属性を true に設定して HTTP、HTTPS、または AJP リスナーの RFC6265 に準拠するクッキーの検証を有効にします。この属性のデフォルト値は false です。以下の例は、HTTP リスナーの RFC6265 に準拠するクッキーの検証を有効にします。

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

JBoss Web が web サーバーとして含まれていた JBoss EAP 6.4 では、デフォルトで HTTP TRACE メソッド呼び出しが許可されていました。

JBoss EAP 7 で JBoss Web の代わりに web サーバーとして導入された Undertow は、デフォルトでは HTTP TRACE メソッド呼び出しを許可しません。この設定は、undertow サブシステムで http-listener 要素の disallowed-methods 属性を使用して設定されます。この設定を確認するには、以下の read-resource コマンドの出力を確認します。disallowed-methods 属性の値が ["TRACE"] であることに注目してください。

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

JBoss EAP 7 およびそれ以降のバージョンで HTTP TRACE メソッド呼び出しを有効にするには、以下のコマンドを実行して disallowed-methods 属性リストから "TRACE" エントリーを削除する必要があります。

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

read-resource コマンドを再度実行すると、TRACE メソッド呼び出しが許可されないメソッドのリストから削除されたことが確認できます。

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

HTTP メソッドのデフォルト動作に関する詳細は、JBoss EAP設定ガイドの HTTP メソッドのデフォルトの動作 を参照してください。

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

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

デフォルトのウェルカム Web アプリケーションを設定する方法の詳細は、JBoss EAP開発ガイドの デフォルトの Welcome Web アプリケーションの設定 を参照してください。

JBoss EAP 7.2 よりも前のリリースでは、undertow サブシステムのデフォルト設定に 2 つの応答ヘッダーフィルターが含まれ、これらのフィルターは 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:10.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 6 のデフォルト設定では、JGroups はサーバー設定ファイルの <interfaces> セクションに定義された public インターフェイスを使用しました。

専用のネットワークインターフェイスを使用することが推奨されるため、JBoss EAP 7 では JGroups はデフォルトでサーバー設定ファイルの <interfaces> セクションに定義された新しい private インターフェイスを使用します。

JGroups は JGroups チャネルで HA サービスのグループ通信サポートを提供します。JBoss EAP 7 では、サーバー設定ファイルの jgroups サブシステムに <channel> 要素が導入されました。管理 CLI を使用して JGroups チャネル設定を追加、削除、および変更できます。

JGroups の設定方法の詳細は、JBoss EAP設定ガイドの JGroups を用いたクラスター通信 を参照してください。

JBoss EAP 6 では、Web セッションレプリケーションおよび EJB レプリケーションのデフォルトのクラスター化キャッシュはレプリケートされた ASYNC キャッシュでした。これは JBoss EAP 7 で変更になりました。デフォルトのクラスター化されたキャッシュは ASYNC キャッシュを分散するようになりました。レプリケートされたキャッシュは、デフォルトでは設定されなくなりました。レプリケートされたキャッシュを追加して、デフォルトに設定する方法は、JBoss EAP 設定ガイド の キャッシュモードの設定 を参照してください。

これは、新しい JBoss EAP 7 のデフォルト設定を使用する場合のみ影響します。JBoss EAP 6 から設定を移行する場合は、infinispan サブシステムの設定は保持されます。

ASYNC キャッシュストラテジーの動作が JBoss EAP 7 では変更になりました。

JBoss EAP 6 では、ASYNC キャッシュの読み取りにロックはありませんでした。ブロックは発生しませんでしたが、フェイルオーバーなどで陳腐データのダーティーリードが発生する傾向にありました。これは、リクエストの完了前に同じユーザーの次のリクエストを開始できたためです。これは、クラスタートポロジーの変更がセッションアフィニティーに影響し、容易にデータが陳腐化することがあるため、分散モードを使用するときは許可されません。

JBoss EAP 7 では、ASYNC キャッシュの読み取りにロックが必要になりました。レプリケーションが終了するまで同じユーザーの新しいリクエストをブロックするようになったため、ダーティーリードが発生しないようになりました。

JBoss EAP 7.1 以上のリリースで、パッシベーションに対してカスタムステートフルセッション bean (SFSB) を設定する場合は、以下の制限に注意してください。

JBoss EAP 7.0 の動作が JBoss EAP 7.1 以上のバージョンで変更になったため、キャッシュコンテナートランスポートプロトコルの更新はバッチモードで実行するか、特別なヘッダーを使用して実行する必要があります。この動作の変更は、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 操作ヘッダーを指定できます。これによりサービスが再起動され、操作が適用されますが、このサービスが再起動するまで一部のサービスが停止する可能性があります。

スクリプトを使用してキャッシュコンテナートランスポートプロトコルを更新する場合は、スクリプトを確認し、バッチモードを追加してください。

EAP_HOME/modules/system/layers/base/ にあった org.jboss.as.messaging モジュール拡張は、 org.wildfly.extension.messaging-activemq 拡張モジュールに置き換えられました。

urn:jboss:domain:messaging:3.0 サブシステム設定ネームスペースは urn:jboss:domain:messaging-activemq:4.0 ネームスペースに置き換えられました。

管理モデル

ほとんどの場合で、要素名と属性名は以前のリリースとできる限り同じになるよう努力しています。以下の表は変更の一部を表しています。

新しい messaging-activemq サブシステム上で呼び出される管理操作は、/subsystem=messaging/hornetq-server= から /subsystem=messaging-activemq/server= に変更になりました。

migrate 操作を呼び出すと、既存の JBoss EAP 6 の messaging サブシステム設定を JBoss EAP 7 の messaging-activemq サブシステムに移行できます。

/subsystem=messaging:migrate

migrate 操作を実行する前に describe-migration 操作を呼び出して、既存の JBoss EAP 6 の messaging サブシステム設定から JBoss EAP 7 サーバーの messaging-activemq サブシステムへの移行を実行する管理操作のリストを確認することができます。

/subsystem=messaging:describe-migration

migrate および describe-migration 操作は、自動的に移行されないリソースや属性の migration-warnings のリストも表示します。

Messaging サブシステムの移行および前方互換性

messaging サブシステムの describe-migration および migrate 操作は、追加の設定引数を提供します。メッセージングを設定してレガシー JBoss EAP 6 クライアントが JBoss EAP 7 サーバーに接続できるようにするには、以下のようにブール値の add-legacy-entries 引数を describe-migration または migrate 操作に追加します。

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

ブール値の引数 add-legacy-entries が true に設定されていると、messaging-activemq サブシステムが legacy-connection-factory リソースを作成し、legacy-entries を jms-queue および jms-topic リソースに追加します。

ブール値の引数 add-legacy-entries が false に設定されていると、messaging-activemq サブシステムにはレガシーリソースが作成されず、レガシーメッセージングクライアントは JBoss EAP 7 サーバーと通信できません。これはデフォルト値です。

前方互換性および後方互換性に関する詳細は、JBoss EAPメッセージングの設定の 後方互換性と前方互換性 を参照してください。

管理 CLI の migrate および describe-migration 操作の詳細は、管理 CLI の移行操作 を参照してください。

forward-when-no-consumers 属性の動作変更

JBoss EAP 7 では、forward-when-no-consumers 属性の動作が変更になりました。

JBoss EAP 6 では、forward-when-no-consumers が false に設定され、クラスターにコンシューマーがない場合に、メッセージはクラスターのすべてのノードへ再分散されました。

この動作は JBoss EAP 7 では変更になりました。forward-when-no-consumers が false に設定され、クラスターにコンシューマーがない場合は、メッセージは再分散されません。代わりに、それらが送信される元のノードに保管されます。

デフォルトのクラスター負荷分散ポリシーの変更

JBoss EAP 7 では、デフォルトのクラスター負荷分散ポリシーが変更になりました。

JBoss EAP 6 ではデフォルトの負荷分散ポリシーは STRICT と似ており、レガシーの forward-when-no-consumers パラメーターを true に設定した場合と同様でした。JBoss EAP 7 では、デフォルトは ON_DEMAND になり、レガシーの forward-when-no-consumers パラメーターを false に設定した場合と同様になります。これらの設定の詳細は、JBoss EAPメッセージングの設定の クラスター接続の属性 を参照してください。

Messaging サブシステムの XML 設定

新しい messaging-activemq サブシステムにより、XML の設定が大幅に変更になり、他の JBoss EAP サブシステムとより一貫性のある XML スキームが提供されるようになりました。

新しい messaging-activemq サブシステムに準拠するために JBoss EAP messaging サブシステムの XML 設定を変更しないでください。この代わりに、レガシーサブシステムの migrate 操作を呼び出してください。この操作は、実行の一部として新しい messaging-activemq の XML 設定を書き込みます。

以下の方法のいずれかを使用してメッセージングデータを以前のリリースの JBoss EAP から現在のリリースに移行します。

Jakarta Messaging サポートプロバイダーが HornetQ から ActiveMQ Artemis に変更になったため、JBoss EAP 7.0 以上のリリースではメッセージングデータの形式と場所が変更になりました。6.4 から 7.x リリースで変更になったメッセージングデータフォルダー名と場所の詳細は、メッセージングフォルダー名のマッピング を参照してください。

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

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

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

JBoss EAP 6 では、メッセージング宛先キューは messaging サブシステムの <hornetq-server> 要素下にある <jms-destinations> 要素に設定されました。

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

JBoss EAP 7 では、Jakarta Messaging 宛先キューは messaging-activemq サブシステムのデフォルトの <server> 要素に設定されます。

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

JBoss EAP 7 では、Jakarta Messaging プロバイダーが HornetQ から ActiveMQ Artemis に変更されたため、メッセージングインターセプターが大幅に変更されました。

以前の JBoss EAP リリースに含まれていた HornetQ messaging サブシステムでは、HornetQ インターセプターを JAR に追加し、HornetQ module.xml ファイルを修正するというインストール方法が必要でした。

JBoss EAP 7 に含まれる messaging-activemq サブシステムは、module.xml ファイルの修正を必要としません。Apache ActiveMQ Artemis Interceptor インターフェイスを実装するユーザーインターセプタークラスは、どのサーバーモジュールからでもロードできるようになりました。インターセプターのロード先となるモジュールは、サーバー設定ファイルの messaging-activemq サブシステムで指定します。

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

JBoss EAP 6 では、Netty サーブレットトランスポートと動作するようサーブレットエンジンを設定することができました。JBoss EAP 7 では、ビルトインメッセージングプロバイダーが HornetQ から ActiveMQ Artemis に変更になったため、この設定は使用できなくなりました。新しいビルトインメッセージング HTTP コネクターおよび HTTP アクセプターを使用するよう、サーブレット設定を変更する必要があります。

サードパーティー Jakarta Messaging プロバイダーで使用する汎用 Jakarta Messaging リソースアダプターを設定する方法は JBoss EAP 7 で変更になりました。詳細は、JBoss EAPメッセージングの設定の 汎用 Jakarta メッセージングリソースアダプターのデプロイ を参照してください。

JBoss EAP 7.0 では、check-for-live-server 属性を指定せずに replication-master ポリシーを設定した場合のデフォルト値が false でした。これは JBoss EAP 7.1 で変更になりました。check-for-live-server 属性のデフォルト値は true です。

以下は、check-for-live-server 属性を指定せずに replication-master を設定する管理 CLI コマンドの例になります。

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

管理 CLI を使用してリソースを読み取ると、check-for-live-server 属性の値が true に設定されることに注意してください。

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

JMS 1.1 と JMS 2.0.0 では、javax.jms.JMSException の serialVersionUID が変更になりました。そのため、JMS 1.1 を使用して JMSException のインスタンスまたは JMSException のサブクラスをシリアライズした場合、JMS 2.0.0 を使用してデシリアライズすることはできません。その逆も同様です。JMS 2.0.0 を使用して JMSException のインスタンスをシリアライズした場合、JMS 1.1 を使用してデシリアライズすることはできません。両方の場合で以下のような例外が発生します。

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

この問題は、Jakarta Messaging 2.0.1 メンテナーンスリリースで修正されました。

以下の表は、各 JBoss EAP リリースの詳細実装です。

serialVersionUID の互換性が維持されないと、以下の状況で移行時に問題が発生することがあります。

JBoss EAP 6.4 クライアントを使用して JMSException が含まれるメッセージを送信し、メッセージングデータを JBoss EAP 7.1 以上のリリースに移行した後、JBoss EAP 7.1 以上のクライアントを使用してそのメッセージをデシリアライズした場合、JMS 1.1 の serialVersionUID は Jakarta Messaging 2.0.3 以降の serialVersionUID と互換性があるため、デシリアライズに成功します。

以前のリリースの JBoss EAP でデータソースを設定した場合、ドライバー名に指定される値は JDBC ドライバー JAR に含まれる META-INF/services/java.sql.Driver ファイルにリストされたクラスの数によって決まりました。

単一クラスを含むドライバー

META-INF/services/java.sql.Driver ファイルで指定されたクラスが 1 つのみであった場合、ドライバー名は単に JDBC ドライバー JAR の名前でした。これは JBoss EAP 7 でも変更ありません。

複数クラスを含むドライバー

JBoss EAP 6 では、META-INF/services/java.sql.Driver ファイルに複数のクラスが記載されている場合、以下の形式で JAR 名にドライバークラスにするクラスの名前とメジャーおよびマイナーバージョンを追加してクラスを指定していました。

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

これは JBoss EAP 7 で変更になりました。以下の形式でドライバー名を指定できるようになりました。

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

2 つのクラスが含まれるドライバーの例としては、MySQL 5.1.31 JDBC ドライバーが挙げられます。このドライバークラス名は com.mysql.jdbc.Driver となります。以下の 2 つの例では、JBoss EAP の以前のリリースと現行リリースにおけるドライバー名の指定方法の違いが示されています。

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

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

FIPS モードで実行している場合、JBoss EAP 7.0 のデフォルト動作が JBoss EAP 7.1 では変更になったことに注意してください。

レガシーセキュリティーレルムを使用している場合、JBoss EAP 7.1 以上では開発の目的で自己署名証明書が自動的に生成されます。この機能は JBoss EAP 7.0 にはなく、デフォルトで有効になっています。そのため、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

自己署名証明書の自動作成に関する詳細は、JBoss EAPサーバーセキュリティーの設定方法の アプリケーション用の自己署名証明書の自動作成 を参照してください。

XML ベースの RPC (JAX-RPC) は Java EE 6 で非推奨となり、Java EE 7 ではオプションとなりました。JAX-RPC は 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 をデプロイする必要がありました。

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

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

Apache CXF インターセプター

JBossWS 記述子は、クライアントエンドポイントコードを編集せずにインターセプターを宣言できる新しい設定オプションを提供します。cxf.interceptors.in および cxf.interceptors.out プロパティーのインターセプタークラス名のリストを指定して、事前定義されたクライアントおよびエンドポイント設定内でインターセプターを宣言します。

以下は、これらのプロパティーを使用してインターセプターを宣言する jaxws-endpoint-config.xml ファイルの例です。

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

Apache CXF の機能

JBossWS 記述子を使用すると、cxf.features プロパティーの機能クラス名のリストを指定して、事前定義のクライアントおよびエンドポイント設定内で機能を宣言できます。

以下は、このプロパティーを使用して機能を宣言する jaxws-endpoint-config.xml ファイルの例です。

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

Apache CXF HTTP トランスポート

Apache CXF では、org.apache.cxf.transport.http.HTTPConduit オプションを指定すると HTTP トランスポートの設定を実行できます。JBossWS の統合により、以下のように Apache CXF API を使用して conduit がプログラム的に編集されます。

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

また、システムプロパティーを設定すると Apache CXF HTTPConduit のデフォルト値を制御および上書きできます。

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 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.49、1.51、またはそれ以降のバージョンを使用する必要があります。

コンテナー内で実行されているクライアントのデフォルトのバス選択ストラテジーが 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 はこの要件を隠さないようになりました。そのため、コンテナーによってインジェクトされたユーザー提供のサービスクラスが、WebServiceFeature 引数が 1 つ以上含まれる javax.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 ディレクトリーに置くことで、デプロイされたアプリケーションすべてがライブラリーを利用できるメカニズムです。

アプリケーションが Apache CXF の JBossWS 実装を使用する場合、JBoss EAP 7 では必要な依存関係が正しい順序で追加されるため、この変更による影響はないはずです。アプリケーションが 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 では、jboss-webservices.xml デプロイメント記述子ファイルを EAR アーカイブの META-INF/ ディレクトリーで設定できるようになりました。jboss-webservices.xml ファイルが EAR アーカイブと JAR (または WAR) アーカイブの両方で見つかった場合、JAR または WAR の jboss-webservices.xml ファイルにある設定データによって EAR 記述子ファイルの対応するデータが上書きされます。

ネーミングパターン -jms.xml によって識別されたプロプライエタリーの HornetQ メッセージングリソースデプロイメント記述子ファイルは JBoss EAP 7 では動作しません。以下は、JBoss EAP 6 の Jakarta Messaging リソースデプロイメント記述子ファイルの例になります。

<?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 Jakarta Messaging デプロイメント記述子をアプリケーションで使用した場合、Jakarta EE Platform の EE.5.18 で指定されたとおりに標準のデプロイメント記述子を使用するようアプリケーションを変換するか、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 7 は Jakarta Messaging 1.1 API をサポートするため、コードを変更する必要はありません。

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

migrate 操作を使用してサーバー設定を移行する場合、これまでの設定は保持され、PROVIDER_URL を更新する必要はありません。しかし、新しい JBoss EAP 7 のデフォルト設定を使用して実行する場合は、新しい http-remoting://localhost:8080 設定を使用するよう PROVIDER_URL を変更する必要があります。詳細は リモートネーミングクライアントコードの移行 を参照してください。

Jakarta Messaging 2.0 API を使用するためにコードを移行する計画がある場合は、作業例を helloworld-jms クイックスタートで確認してください。

JBoss EAP 6 には org.hornetq モジュールが含まれ、これによりアプリケーションソースコードで HornetQ API が使用できました。

JBoss EAP 7 では HornetQ が Apache ActiveMQ Artemis に置き換えられたため、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.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 の JAX-RS 対応インターセプターファシリティーに置き換えられました。関係するインターフェイスは、 jaxrs-api モジュールの javax.ws.rs.ext パッケージに定義されます。

インターセプターの詳細情報は、JBoss EAPWeb サービスアプリケーションの開発の RESTEasy インターセプター を参照してください。

新しい代替の API は、RESTEasy JAX-RS 3.9.0.Final API を参照してください。

クライアント 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 では非推奨になりました。この機能は JAX-RS の jax.ws.rs.ext.ParamConverterProvider クラスを使用して置き換えできます。

ResteasyProviderFactory Add メソッド

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

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

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

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

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

YAML プロバイダーの設定変更

以前のリリースの JBoss EAP では、RESTEasy YAML プロバイダー設定はデフォルトで有効になっていました。これは JBoss EAP 7 で変更になりました。YAML プロバイダーがデフォルトで無効化されるようになりました。アンマーシャリングで RESTEasy によって使用される SnakeYAML ライブラリーにセキュリティー上の問題があるため、YAML プロバイダーの使用はサポートされず、アプリケーションで明示的に有効にする必要があります。アプリケーションで YAML プロバイダーを有効にし、Maven 依存関係を追加する方法は、JBoss EAPWeb サービスアプリケーションの開発の 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 EAPWeb サービスアプリケーションの開発の テキストメディアタイプおよび文字セット を参照してください。

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

リソースメソッドアルゴリズムの切り替え

3.0.25.Final より前の RESTEasy 3.0.x バージョンで使用されたリソースメソッド一致アルゴリズムでバグが見つかりました。このバグにより、リクエストの応答時に RESTEasy は余分なリソースメソッドを返しました。

一致アルゴリズムには 3 つの手順があります。

JAX-RS 2.0 仕様によると、潜在的なリソースメソッドセットのソート後に最大要素のみを手順 3 に渡す必要があります。しかし、RESTEasy 3.0.25 より前の RESTEasy 3.0.x 実装はすべてのメソッドを手順 3 に渡しました。JBoss EAP 7.1.0 に含まれる RESTEasy 3.0.24 は、この不適切な動作を実行します。

JBoss EAP 7.1.1 に含まれる RESTEasy 3.0.25 は、JAX-RS 2.0 仕様に準拠するために手順 3 に渡すメソッドを制限する修正を提供します。厳格でない動作が望ましい場合もあるため、RESTEasy 3.0.25 にはこれまでの動作を有効にできる context-param 設定オプションの resteasy.loose.step2.request.matching も導入されました。これはデフォルトで false に設定されています。

JBoss EAP サーバーを 7.1.0 から 7.1.1 に更新し、これまでの動作を維持して潜在的なリソースメソッドをすべて手順 3 に渡す場合は、resteasy.loose.step2.request.matching オプションを true に設定します。

一致アルゴリズムは、一致したすべてのリソースメソッドを手順 3 に渡すよう JAX-RS 2.1 で変更になりました。JBoss EAP 7.4 に含まれている RESTEasy 3.9.0 は、JAX-RS 2.0 仕様で定義されている厳格な動作を維持する jaxrs.2.0.request.matching オプションを提供します。

アプリケーションを JBoss EAP 7.1.0 から 7.2.x に移行した場合、リソースメソッドの一致アルゴリズムの動作は変更されません。アプリケーションを JBoss EAP 7.1.1 から 7.2.x 以降に移行し、JAX-RS 2.0 仕様に定義されている厳格な動作を維持したい場合は、jaxrs.2.0.request.matching オプションを true に変更します。

SPI 例外

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

InjectorFactory および Registry

InjectorFactory および Registry SPI が変更されました。ドキュメントに従ってサポートされるように RESTEasy を使用する場合は、問題はありません。

JBoss EAP に含まれる Jackson のバージョンは変更されました。JBoss EAP の以前のリリースに含まれていた Jackson は 1.9.9 でした。JBoss EAP 7 には Jackson 2.6.3 またはそれ以降が含まれています。このため、Jackson プロバイダーが resteasy-jackson-provider から resteasy-jackson2-provider に変更されました。

resteasy-jackson2-provider へのアップグレードにはいくつかのパッケージ変更が必要になります。たとえば、Jackson アノテーションパッケージは org.codehaus.jackson.annotate から com.fasterxml.jackson.annotation に変更されました。

JBoss EAP の以前のリリースに含まれていたデフォルトのプロバイダーを使用するようにアプリケーションを切り替えるには、JBoss EAPWeb サービスアプリケーションの開発の デフォルトの Jackson プロバイダーの切り替え を参照してください。

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開発ガイドの デプロイメントへの明示的なモジュール依存関係の追加 を参照してください。

JBoss EAP 7.3 は MicroProfile REST クライアントのバージョン 1.3.x をサポートします。以前のバージョンの MicroProfile REST クライアントを使用していた場合は、コードに更新をいくつか行う必要があります。

org.jboss.resteasy.client.microprofile.MicroprofileClientBuilderResolver クラスは org.eclipse.microprofile.rest.client.RestClientBuilder に置き換えられました。以下に例を示します。

@Path("resource")
public interface TestResourceIntf {

   @Path("test")
   @GET
   public String test();
}

TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .build(TestResourceIntf.class);
String s = service.test();

MicroProfile REST クライアントの詳細は、JBoss EAPWeb サービスアプリケーションの開発の MicroProfile REST クライアント を参照してください。

MicroProfile Config は、開発者がアプリケーションとマイクロサービスを設定して、それらのアプリケーションを変更または再パッケージ化することなく、複数の環境で実行できるようにするために使用できる仕様の名前です。以前は、MicroProfile Config はテクノロジープレビューとして JBoss EAP で利用可能でしたが、その後削除されました。MicroProfile Config は、JBoss EAP XP でのみ使用できるようになりました。

JBoss EAP 6.4 の Hibernate ORM 3 を簡単に使用できるようにする統合クラスは JBoss EAP 7 から削除されました。膨大な作業を行わないと JBoss EAP で Hibernate ORM 3 を実行できなくなったため、アプリケーションが Hibernate ORM 3 ライブラリーを使用する場合は、アプリケーションを移行して Hibernate ORM 5 を使用するようにすることが強く推奨されます。Hibernate ORM 5 へ移行できない場合は、Hibernate ORM 3 JAR のカスタム JBoss モジュールを定義し、アプリケーションから Hibernate ORM 5 のクラスを除外する必要があります。

アプリケーションに対して 2 次キャッシュを有効にする必要がある場合、nfinispan 8.x が Hibernate ORM 5.0 と統合されたことに注意してください。Infinispan を Hibernate の 2 次キャッシュプロバイダーとして使用するためのサポートは、Hibernate ORM 5.3 の Infinispan プロジェクトに移されました。 そのため、hibernate-infinispan モジュールは本リリースより削除されました。

Hibernate ORM 4.x で作成されたアプリケーションは Hibernate ORM 4.x を引き続き使用できます。Hibernate ORM 4.x JAR のカスタム JBoss モジュールを定義し、アプリケーションから Hibernate ORM 5 クラスを排除する必要があります。しかし、Hibernate ORM 5 を使用するようにアプリケーションコードを書き直すことが強く推奨されます。Hibernate ORM 5 への移行に関する情報は、Hibernate ORM 5 への移行 を参照してください。

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 が含まれていました。ここでは、この 2 つの違いと、Hibernate ORM のバージョン 5.1 からバージョン 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 を参照してください。

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

migrate 操作を使用してサーバー設定を移行した場合は、旧設定は保持されるためこの変更を行う必要はありません。しかし、新しい JBoss EAP 7 のデフォルト設定で実行する場合は以下の変更を行う必要があります。

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 EJB クライアント 2.1.4 が同梱されていましたが、JBoss EAP 7.1 以上には JBoss EJB クライアント 4.0.x が同梱され、API に複数の変更が追加されました。

JBoss EAP 7.2 では org.apache.santuario.xmlsec モジュールが 2.0.8 から 2.1.1 にアップグレードされ、PicketLinkSTS のリモーティングで回帰が発生します。この問題により以下のランタイム例外が発生します。

java.lang.IllegalArgumentException: ELY05131: Invalid ASCII control "0xA"

これは、アサーションの生成された SignatureValue のフォーマットの変更が原因です。これまでのリリースでは、生成された値は以下の例と似ていました。

<dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">cUNpFJIZlLYrBDZtQSTDrq2K6PbnAHyg2qbx/D5FuB4XMjdQ5oxQjkMejLyelnA7s4GFusoLhahlqlTOT8UrOyxrR4yYAmJ/e5s+f4gys926+tbiraT/3/wG8wM/Lvcjvk5Ap69zODuRYpypsWfA4jrI7TTBXVPGy8g4KUdnFviUiTuFTc2Ghgxp53AmUuLis/THyP28jE7+28//q8bi/bQrFwHC6tWX67+NK1duFCOcQ6IPIKeVrePZz55Ivgl+WWdkF6uYCz5IdMzurhzmeQ3K8DAMIxz/MG67VWJIOnuGNWF7nmdye5zd9AFcRsr1XadvZJCbGNfuc89AL5inCg==</dsig:SignatureValue>

JBoss EAP 7.2 では、生成された値に無効な非表示の ASCII 0xD キャリッジリターンおよび 0xD ラインフィード制御文字のインスタンスが含まれます。

<dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">cUNpFJIZlLYrBDZtQSTDrq2K6PbnAHyg2qbx/D5FuB4XMjdQ5oxQjkMejLyelnA7s4GFusoLhahl&#13;
qlTOT8UrOyxrR4yYAmJ/e5s+f4gys926+tbiraT/3/wG8wM/Lvcjvk5Ap69zODuRYpypsWfA4jrI&#13;
7TTBXVPGy8g4KUdnFviUiTuFTc2Ghgxp53AmUuLis/THyP28jE7+28//q8bi/bQrFwHC6tWX67+N&#13;
K1duFCOcQ6IPIKeVrePZz55Ivgl+WWdkF6uYCz5IdMzurhzmeQ3K8DAMIxz/MG67VWJIOnuGNWF7&#13;
nmdye5zd9AFcRsr1XadvZJCbGNfuc89AL5inCg==</dsig:SignatureValue>

上記のランタイム例外が発生した場合はクライアントコードを更新し、発生した非表示の ASCII 文字を返されたアサーション文字列から削除する必要があります。たとえば、現在のコードが以下の例と同様であるとします。

WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
                "http://localhost:8080/picketlink-sts/PicketLinkSTS", new WSTrustClient.SecurityInfo(username, password));
Element assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);

// Return the assertion as a string
String assertionString = DocumentUtil.getNodeAsString(assertion);
...
properties.put("remote.connection.main.password", assertionString);

コードを 1 行追加して、以下のように無効な非表示の ASCII 0xD キャリッジリターンおよび 0xA ラインフィード文字を削除する必要があります。

WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
                "http://localhost:8080/picketlink-sts/PicketLinkSTS", new WSTrustClient.SecurityInfo(username, password));
Element assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);

// Return the assertion as a string, stripping the invalid hidden ASCII characters
String assertionString = DocumentUtil.getNodeAsString(assertion).replace(String.valueOf((char) 0xA), "").replace(String.valueOf((char) 0xD), "");
...
properties.put("remote.connection.main.password", assertionString);

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

SSO の SAML v2 設定で必要となる変更の情報は、JBoss EAPSAML v2 での SSO のセットアップ方法の JBoss EAP の以前のバージョンからの変更 を参照してください。

Kerberos による SSO 設定についての相違点は、JBoss EAPKerberos による SSO のセットアップ方法の これまでのバージョンの JBoss EAP とは異なる設定 を参照してください。

以下のリストは、アプリケーションを JBoss EAP 6 から JBoss EAP 7 へ移行するときに注意する必要がある新しいクラスターリング機能の一部を示しています。

本セクションの残りの部分では、クラスターリングの変更がアプリケーションの JBoss EAP 7 への移行に及ぼす可能性のある影響について説明します。

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 サブシステムで使用される設定と同じに見えます。

<?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開発ガイドの クラスターリングサービスのパブリック API を参照してください。

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

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

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

レガシー security サブシステムの使用を継続する場合、vault データを編集または更新する必要はないはずです。しかし、アプリケーションを移行して Elytron を使用する計画がある場合、既存の vault をクレデンシャルストアに変換し、elytron サブシステムが処理できるようにする必要があります。クレデンシャルストアに関する詳細は、サーバーセキュリティーの設定方法の クレデンシャルストア を参照してください。

WildFly Elytron Tool を使用した vault データの移行

JBoss EAP に同梱されている WildFly Elytron Tool は、vault の内容をクレデンシャルストアに移行するのに便利な vault コマンドを提供します。EAP_HOME/bin ディレクトリーにある elytron-tool スクリプトを実行してツールを実行します。

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

java -jar コマンドを実行してツールを実行することもできます。

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

以下のコマンドを使用すると、使用できるすべての引数の説明を表示できます。

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

以下の移行オプションの 1 つを選択します。

単一のセキュリティー vault をクレデンシャルストアに移行

以下は、単一のセキュリティー vault をクレデンシャルストアに変換するために使用されるコマンドの例になります。

$ 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 をクレデンシャルストアに変換し、変換に使用された管理 CLI コマンドの概要を出力します。

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

複数のセキュリティー vault を一括でクレデンシャルストアに移行

--bulk-convert 引数を使用して一括変換記述子ファイルを示し、複数の vault をクレデンシャルストアに変換することができます。

ここで使用する例では、以下の一括変換記述子ファイルを使用します。

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

新しい keystore: 行ごとに変換が新たに開始されます。salt、iteration、および properties 以外のオプションはすべて必須です。

一括変換を実行し、管理 CLI コマンドをフォーマットする出力を生成するには、以下のコマンドを実行します。

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

このコマンドは、ファイルに指定されたすべてのセキュリティー vault をクレデンシャルストアに変換し、変換に使用された管理 CLI コマンドの概要を出力します。

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 として定義されていることを仮定します。

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

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

ファイルシステムベースのレルムは、ユーザー ID を保存するための、Elytron で使用されるファイルシステムベースのアイデンティティーストアです。filesystem-realm コマンドは、properties-realm ファイルを filesystem-realm に変換します。また、このレリムとセキュリティードメインを elytron サブシステムに追加するためのコマンドも生成します。

プロパティーベースの認証をファイルシステムベースの認証に移行する手順は次のとおりです。

ここでは、情報をアイデンティティー属性として管理できるようにするために、レガシー LDAP 認証を移行する方法について説明します。特に、セキュリティードメインおよび認証ファクトリーの定義方法と認証のためにこれらをマップする方法に関しては、プロパティーベースの認証および承認の Elytron への移行 に記載されている多くの情報がここでも適用されます。ここでは、同じ手順は再度説明しないため、プロパティーベースの認証および承認の 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 への移行 に記載されている多くの情報がここでも適用されます。ここでは、同じ手順は再度説明しないため、プロパティーベースの認証および承認の 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 サーバーは環境からの設定情報に依存でき、システムプロパティーを使用してキー設定を指定することも可能です。ここでは、Kerberos HTTP および Kerberos SASL 認証の移行方法を説明します。

ここで使用する例では、以下のシステムプロパティーを使用して Kerberos が設定されたことを仮定します。これらのシステムプロパティーは、レガシー設定と移行された 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>

以下の移行オプションの 1 つを選択します。

Kerberos HTTP 認証の移行

レガシーのセキュリティー設定では、セキュリティーレルムを定義して以下のように HTTP 管理インターフェイスの SPNEGO 認証を有効にできます。

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

また、2 つのレガシーセキュリティードメインを定義して、アプリケーションが Kerberos HTTP 認証を使用できるようにすることも可能です。

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

セキュリティーアプリケーションは、SPNEGO セキュリティードメインを参照してデプロイされ、SPNEGO によってセキュア化されます。

Kerberos HTTP 認証の Elytron への移行

セキュリティーレルムと Kerberos セキュリティーファクトリーを使用すると、管理インターフェイスとアプリケーションの両方をセキュアにすることができます。

Kerberos リモーティング SASL 認証

ネイティブ管理インターフェイスなど、リモーティング認証に使用される Kerberos / GSSAPI SASL 認証のレガシーセキュリティーレルムを定義することが可能です。

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

Kerberos リモーティング SASL 認証の Elytron への移行

同等の Elytron 設定を定義する手順は、Kerberos HTTP 認証の移行 の手順と大変似ています。

これにより、サーバー設定ファイルの elytron サブシステムの設定が以下のようになります。

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

これで、管理インターフェイスまたはリモーティングコネクターが更新され、SASL 認証ファクトリーを参照するようになりました。

ここで定義された 2 つの Elytron の例は、共有されたセキュリティードメインおよびセキュリティーレルムを使用し、各自が独自の Kerberos セキュリティーファクトリーを参照するプロトコル固有の認証ファクトリーを使用するよう組み合わせることも可能です。

ここでは、PicketBox または 複数のアイデンティティーストアを使用する レガシーセキュリティーレルム 設定を Elytron に移行する方法について説明します。PicketBox またはレガシーセキュリティーレルムを使用する場合、承認に使用される情報を 1 つのアイデンティティーストアからロードしながら別のアイデンティティーストアに対して認証を実行する設定を定義することが可能です。Elytron に移行する場合、集約セキュリティーレルムを使用してこれを実現できます。

以下の例は、example-users.properties プロパティーファイルを使用してユーザー認証を実行し、LDAP をクエリーしてグループおよびロール情報をロードします。

PicketBox 複合ストア設定

この場合の PicketBox セキュリティードメインは、以下の管理 CLI コマンドを使用して設定されます。

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

elytron サブシステムで集約セキュリティーレルムを設定してこれを実現する方法については、Elytron 集約セキュリティーレルム設定 を参照してください。

レガシーセキュリティーレルム複合ストア設定

この場合のレガシーセキュリティーレルム設定は、以下の管理 CLI コマンドを使用して設定されます。

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

elytron サブシステムで集約セキュリティーレルムを設定してこれを実現する方法については、Elytron 集約セキュリティーレルム設定 を参照してください。

Elytron 集約セキュリティーレルム設定

この場合の同等の Elytron 設定は、以下の管理 CLI コマンドを使用して設定されます。

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

elytron サブシステムでは、認証に使用するセキュリティーレルムと承認の決定に使用するセキュリティーレルムを指定するために aggregate-realm が定義されています。

PicketBox を使用する場合、セキュリティードメインを定義し、アクセスのためにインメモリーキャッシングを有効にすることが可能です。これにより、ユーザーはメモリーのアイデンティティーデータにアクセスでき、それ以外ではアイデンティティーストアへ直接アクセスできないようにします。同様の設定を Elytron で実現することができます。ここでは、Elytron 使用時のセキュリティードメインキャッシングの設定方法について説明します。

PicketBox のキャッシュ済みセキュリティードメイン設定

以下のコマンドは、キャッシングを有効にする 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>

Elytron のキャッシュ済みセキュリティードメイン設定

以下の手順に従って、Elytron の使用時にセキュリティードメインをキャッシュする同様の設定を作成します。

これらのコマンドにより、サーバー設定に以下が追加されます。

<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 はレガシー security サブシステムを使用して Jakarta Authorization ポリシープロバイダーおよびファクトリーを設定します。デフォルト設定は PicketBox から実装へマップします。

elytron サブシステムは、Jakarta Authorization 仕様をベースとした組み込みポリシープロバイダーを提供します。Elytron が Jakarta Authorization 設定およびその他のポリシーを管理できるようにするようにサーバーを設定する前に、以下の管理 CLI コマンドを使用して最初にレガシー security サブシステムで Jakarta Authorization を無効にする必要があります。

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

この作業を怠ると、次のエラーメッセージがサーバーログに出力されます: MSC000004: Failure during stop of service org.wildfly.security.policy: java.lang.StackOverflowError

Jakarta Authorization を有効にする方法や、elytron サブシステムで Jakarta Authorization ポリシープロバイダーを定義する方法の詳細は、JBoss EAP開発ガイドの elytron サブシステムを使用した Jakarta Authorization の有効化 を参照してください。

ここでは、org.jboss.naming.remote.client.InitialContextFactory クラスによってバックされる org.jboss.naming.remote.client.InitialContext クラスを使用してリモート JNDI ルックアップを実行するクライアントアプリケーションを Elytron に移行する方法について説明します。

以下の例は、ユーザークレデンシャルのプロパティーおよび接続するネーミングプロバイダーの URL のプロパティーを指定して InitialContextFactory クラスが作成されることを仮定します。

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

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

// 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 {JEB} 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 {JEB}
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 {JEB} 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);

セキュリティーレルムを使用して JBoss EAP サーバーへの HTTP 接続をセキュアにした場合、本セクションの情報を使用してその設定を Elytron に移行できます。

ここで使用する例は、以下の keystore が security-realm に設定されていることを仮定します。

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="keystore_password" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
</security-realm>

以下の手順に従って、Elytron を使用して同じ設定を実現します。

これにより、サーバー設定ファイルの elytron サブシステム設定が以下のようになります。

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

これにより、サーバー設定ファイルの undertow サブシステム設定が以下のようになります。

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

詳細は、サーバーセキュリティーの設定方法の Elytron サブシステム および 管理インターフェイスのセキュア化の方法 を参照してください。

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 つあります。

CA のみが含まれるレガシー truststore

以下の手順に従って、有効な証明書とプライベートキーを持たないユーザーが Elytron を使用してサーバーにアクセスしないようにサーバーを設定します。

これにより、サーバー設定ファイルの elytron サブシステム設定が以下のようになります。

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

これにより、サーバー設定ファイルの undertow サブシステム設定が以下のようになります。

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

レルムおよびドメイン

事前定義された Elytron ManagementDomain セキュリティードメインと ManagementRealm セキュリティーレルムを使用できるようにするため、ユーザーは標準のプロパティーファイルに格納されます。

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

セキュリティーレルムは 2 つの状況で使用されます。

そのため、すべてのクライアント証明書に対してユーザーがセキュリティーレルムに存在する必要があります。

プリンシパルデコーダー

証明書認証が使用され、セキュリティーレルムがユーザー名を許可してアイデンティティーを解決する場合、クライアント証明書から username を取得する方法の定義が必要です。

この場合、証明書サブジェクトで CN 属性が使用されます。

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

HTTP 認証ファクトリー

HTTP 接続では、以前定義したリソースを使用して HTTP 認証ファクトリーが定義されます。これは、CLIENT_CERT および DIGEST 認証をサポートするために設定されます。

プロパティーレルムはパスワードのみを検証し、クライアント証明書を検証できないため、最初に設定メカニズムのファクトリーを追加する必要があります。これは、セキュリティーレルムに対する証明書の検証を無効にします。

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

HTTP 認証は次のように作成できます。

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