第17章 Web サーバーの設定 (Undertow)

17.1. Undertow サブシステムの概要

重要

JBoss EAP 7 では、JBoss EAP 6 の web サブシステムの代わりに undertow サブシステムが使用されます。

undertow サブシステムは、Web サーバーおよびサーブレットコンテナーの設定を可能にします。Jakarta Servlet 4.0 Specification や WebSocket を実装します。HTTP のアップグレードや、サーブレットデプロイメントでの高パフォーマンスな非ブロッキングハンドラーの使用もサポートします。undertow サブシステムは、mod_cluster をサポートする高パフォーマンスなリバースプロキシーとして動作することも可能です。

undertow サブシステム内で設定する主なコンポーネントは 5 つあります。

注記

JBoss EAP には、これらの各コンポーネントの設定を更新する機能がありますが、デフォルト設定は妥当なパフォーマンスの設定を提供し、ほとんどのユースケースに適しています。

デフォルトの 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>
重要

また、undertow サブシステムは io サブシステムに依存して XNIO ワーカーやバッファープールを提供します。io サブシステムは個別に設定され、ほとんどの場合で最適なパフォーマンスを得られるデフォルト設定を提供します。

注記

JBoss EAP 6 の web サブシステムと比較すると、JBoss EAP 7 の undertow サブシステムでは HTTP メソッドのデフォルト動作 が異なります。

Undertow サブシステムでの Elytron の使用

web アプリケーションがデプロイされると、そのアプリケーションが必要なセキュリティードメインの名前が特定されます。これは、デプロイメント内からで、デプロイメントにセキュリティードメインがない場合は undertow サブシステムで定義された default-security-domain が仮定されます。デフォルトでは、セキュリティードメインがレガシー security サブシステムで定義された PicketBox にマップすることが仮定されます。しかし、アプリケーションが必要なセキュリティードメインの名前から適切な Elytron 設定にマッピングする undertow サブシステムに application-security-domain リソースを追加することができます。

例: マッピングの追加

/subsystem=undertow/application-security-domain=ApplicationDomain:add(security-domain=ApplicationDomain)

マッピングの追加に成功すると、以下のような結果が出力されます。

<subsystem xmlns="urn:jboss:domain:undertow:10.0" ... default-security-domain="other">
...
    <application-security-domains>
        <application-security-domain name="ApplicationDomain" security-domain="ApplicationDomain"/>
    </application-security-domains>
...
</subsystem>

注記
  • この時点でデプロイメントがすでにデプロイされている場合は、アプリケーションサーバーをリロードして、アプリケーションセキュリティードメインマッピングを有効にする必要があります。
  • 現在の Web サービス/Elytron 統合では、Web サービスエンドポイントと Elytron セキュリティードメイン名をセキュアにするために指定されたセキュリティードメインの名前が同じである必要があります。

この簡単な例は、BASICCLIENT_CERTDIGESTFORM など、デプロイメントがサーブレット仕様内で定義された標準の HTTP メカニズムを使用する場合に適しています。この場合、認証は ApplicationDomain セキュリティードメインに対して実行されます。このフォームは、アプリケーションが認証メカニズムを使用せず、代わりにプログラムによる認証を使用したり、デプロイメントに関連する SecurityDomain を取得して直接使用したりする場合にも適しています。

例: 高度なマッピング

/subsystem=undertow/application-security-domain=MyAppSecurity:add(http-authentication-factory=application-http-authentication)

高度なマッピングに成功すると、以下のような結果が出力されます。

<subsystem xmlns="urn:jboss:domain:undertow:10.0" ... default-security-domain="other">
...
    <application-security-domains>
        <application-security-domain name="MyAppSecurity" http-authentication-factory="application-http-authentication"/>
    </application-security-domains>
...
</subsystem>

このような設定では、セキュリティードメインを参照する代わりに、http-authentication-factory が参照されます。これは、認証メカニズムのインスタンスの取得に使用されるファクトリーで、セキュリティードメインと関連付けられます。

カスタム HTTP 認証メカニズムを使用する場合や、プリンシパルトランスフォーマー、認証情報ファクトリー、メカニズムレルムなどのメカニズムに追加の設定を定義する必要がある場合など、http-authentication-factory 属性を参照する必要があります。また、Servlet 仕様に記載されている 4 つのメカニズム以外を使用する場合は、http-authentication-factory 属性を参照した方がよいでしょう。

高度なマッピングが使用される場合、別の設定オプション override-deployment-config を使用できます。参照された http-authentication-factory は認証メカニズムの完全セットを返すことができます。デフォルトでは、アプリケーションによってリクエストされたメカニズムと一致するするためにフィルターされます。このオプションが true に設定された場合、ファクトリーによって提供されたメカニズムは、アプリケーションによってリクエストされたメカニズムをオーバーライドします。

application-security-domain リソースには追加のオプション enable-jacc もあります。これを true に設定すると、このマッピングに一致するすべてのデプロイメントに対して Jakarta Authorization が有効になります。

ランタイム情報

application-security-domain マッピングが使用されている場合、このマッピングに対してデプロイメントが想定どおり一致していることを再度確認すると便利です。リソースが include-runtime=true で読み取りされた場合、マッピングに関連するデプロイメントは以下のように表示されます。

/subsystem=undertow/application-security-domain=MyAppSecurity:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "enable-jacc" => false,
        "http-authentication-factory" => undefined,
        "override-deployment-config" => false,
        "referencing-deployments" => ["simple-webapp.war"],
        "security-domain" => "ApplicationDomain",
        "setting" => undefined
    }
}

この出力の referencing-deployments 属性は、simple-webapp.war デプロイメントがマッピングを使用してデプロイされたことを示しています。