2.4. 設定の移行

Red Hat Single Sign-On 7.6 とは対照的に、Red Hat build of Keycloak には、サポート対象データベースのサポートが組み込まれているため、データベースドライバーを手動でインストールして設定する必要がありません。例外は Oracle と Microsoft SQL Server です。これらについては、ドライバーを手動でインストールする必要があります。

設定に関しては、Red Hat Single Sign-On 7.6 の既存インストールのデータソースサブシステムを考慮し、その設定を、Red Hat build of Keycloak のデータベース設定カテゴリーで利用可能なオプションにマッピングします。たとえば、以前の設定として、次のようなものがあるとします。

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="true">
    <connection-url>jdbc:postgresql://mypostgres:5432/mydb?currentSchema=myschema</connection-url>
    <driver>postgresql</driver>
    <pool>
        <min-pool-size>5</min-pool-size>
        <max-pool-size>50</max-pool-size>
    </pool>
    <security>
        <user-name>myuser</user-name>
        <password>myuser</password>
    </security>
</datasource>

Red Hat build of Keycloak では、CLI パラメーターを使用した同等の設定は、次のようなものになります。

kc.sh start
   --db postgres
   --db-url-host mypostgres
   --db-url-port 5432
   --db-url-database mydb
   --db-schema myschema
   --db-pool-min-size 5 --db-pool-max-size 50
   --db-username myser --db-password myuser

実稼働モード (start オプションで表される) を使用する場合は常に、HTTP が無効になり、TLS 設定がデフォルトで必要になります。

--http-enabled=true 設定オプションを使用すると、HTTP を有効にできます。ただし、Red Hat build of Keycloak サーバーが完全に分離されたネットワーク内にあり、内部または外部の攻撃者がネットワークトラフィックを監視できるリスクがない場合を除き、このオプションの使用は推奨されません。

Red Hat build of Keycloak インスタンスは、サーバーのルートを使用するため、異なるコンテキストルート (URL パス) を持ちます。一方、Red Hat Single Sign-On 7.6 はデフォルトで /auth を追加します。以前の動作を再現するには、--http-relative-path=/auth 設定オプションを使用できます。デフォルトのポートは同じままです。ただし、--http-port および --https-port オプションによって変更することもできます。

TLS を設定するには 2 つの方法があります。PEM 形式のファイルを使用するか、Java キーストアを使用します。たとえば、Java キーストアによる以前の設定として、次のようなものがあるとします。

<tls>
	<key-stores>
            <key-store name="applicationKS">
                 <credential-reference
		 clear-text="password"/>
		 <implementation type="JKS"/>
                 <file
   path="/path/to/application.keystore”/>
            </key-store>
     </key-stores>
     <key-managers>
        <key-manager name="applicationKM"
         key-store="applicationKS">
               <credential-reference
          clear-text="password"/>
        </key-manager>
     </key-managers>
     <server-ssl-contexts>
         <server-ssl-context name="applicationSSC"
     key-manager="applicationKM"/>
     </server-ssl-contexts>
</tls>

Red Hat build of Keycloak では、CLI パラメーターを使用した同等の設定は、次のようなものになります。

kc.sh start
   --https-key-store-file /path/to/application.keystore
   --https-key-store-password password

Red Hat build of Keycloak では、次のように PEM 形式の証明書を指定することで TLS を設定できます。

kc.sh start
   --https-certificate-file /path/to/certfile.pem
   --https-certificate-key-file /path/to/keyfile.pem

Red Hat Single Sign-On 7.6 は、サーバーをスタンドアロン、スタンドアロンクラスター、およびドメインクラスターとして実行するための個別の動作モードを備えていました。これらのモードは、起動スクリプトと設定ファイルが異なります。Red Hat build of Keycloak では、単一の起動スクリプト kc.sh を使用したシンプルな方法を利用できます。

サーバーをスタンドアロンまたはクラスター化されたスタンドアロンとして実行するには、kc.sh スクリプトを使用します。

--cache パラメーターのデフォルト値は、起動モードを認識します。

Red Hat Single Sign-On 7.6 では、クラスタリングとキャッシュの設定を Infinispan サブシステムを通じて行っていました。一方、Red Hat build of Keycloak では、設定の大部分を、別の Infinispan 設定ファイルを通じて行います。たとえば、Infinispan の以前の設定として、次のようなものがあるとします。

<subsystem xmlns="urn:jboss:domain:infinispan:13.0">
<cache-container name="keycloak" marshaller="JBOSS" modules="org.keycloak.keycloak-model-infinispan">
                <local-cache name="realms">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="users">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="sessions"/>
                <local-cache name="authenticationSessions"/>
                <local-cache name="offlineSessions"/>
			...
</cache-container>
</subsystem>

Red Hat build of Keycloak では、デフォルトの Infinispan 設定ファイルは conf/cache-ispn.xml ファイルにあります。独自の Infinispan 設定ファイルを用意し、次のように CLI パラメーターを使用して指定できます。

kc.sh start --cache-config-file my-cache-file.xml

唯一の改善点は、CLI オプションのキャッシュスタックを指定することで、キャッシュ設定ファイルで定義されたスタックをオーバーライドできることです。指定すると、そのキャッシュスタックが優先されます。カスタム JGroups トランスポートスタックを使用した上記の Infinispan 設定ファイル my-cache-file.xml の一部として、次のようなものがあるとします。

keycloak キャッシュコンテナーのトランスポートスタックが tcp に設定されていますが、次のように CLI オプションを使用してこのスタックをオーバーライドできます。

<jgroups>
	<stack name=”my-encrypt-udp” extends=”udp”>
		…
	</stack>
</jgroups>

<cache-container name=”keycloak”>
	<transport stack=”tcp”/>
	…
</cache-container>

kc.sh start
   --cache-config-file my-cache-file.xml
   --cache-stack my-encrypt-udp

上記のコマンドを実行すると、my-encrypt-udp トランスポートスタックが使用されます。

Red Hat build of Keycloak では、ホスト名 SPI の設定が必須です。これは、ユーザーをリダイレクトするとき、またはユーザーのクライアントと通信するときに、サーバーによってフロントエンド URL とバックエンド URL をどのように作成するかを設定するために必要です。

たとえば、Red Hat Single Sign-On 7.6 インストールに次のような設定があるとします。

<spi name="hostname">
      <default-provider>default</default-provider>
      <provider name="default" enabled="true">
           <properties>
              <property name="frontendUrl" value="myFrontendUrl"/>
              <property name="forceBackendUrlToFrontendUrl" value="true"/>
           </properties>
      </provider>
</spi>

Red Hat build of Keycloak では、これは次のような設定オプションに変換できます。

kc.sh start
    --hostname-url myFrontendUrl
    --hostname-strict-backchannel true

hostname-url 設定オプションを使用すると、クラスターの前で実行されているイングレス層からクラスターをパブリックに公開する場所となるベース URL を設定できます。hostname-admin-url 設定オプションを設定して、管理リソースの URL を設定することもできます。

Red Hat build of Keycloak を使用すると、どのリバースプロキシーヘッダーを反映するかを設定できます。Forwarded ヘッダーまたは X-Forwarded-* ヘッダーのセットのいずれかを使用できます。以下に例を示します。

kc.sh start --proxy-headers xforwarded

トラストストアは、HTTPS 要求や LDAP サーバーなどの外部 TLS 通信に使用します。トラストストアを使用するには、リモートサーバーまたは CA の証明書をトラストストアにインポートします。その後、システムのトラストストアを指定して Red Hat build of Keycloak サーバーを起動できます。

たとえば、以前の設定として、次のようなものがあるとします。

<spi name="truststore">
    <provider name="file" enabled="true">
        <properties>
            <property name="file" value="path/to/myTrustStore.jks"/>
            <property name="password" value="password"/>
            <property name="hostname-verification-policy" value="WILDCARD"/>
        </properties>
    </provider>
</spi>

Red Hat build of Keycloak は、PEM ファイル、または拡張子が .p12 および .pfx の PKCS12 ファイル形式のトラストストアをサポートしています。PKCS12 ファイルの場合は、暗号化されている証明書は使用できません。つまり、パスワードは必要ありません。JKS トラストストアを変換する必要があります。以下に例を示します。

keytool -importkeystore -srckeystore path/to/myTrustStore.jks \
   -destkeystore path/to/myTrustStore.p12 \
   -srcstoretype jks \
   -deststoretype pkcs12
   -srcstorepass password
   -deststorepass “”

この例では、結果の CLI パラメーターは次のようになります。

kc.sh start
    --truststore-paths path/to/myTrustStore.p12
    --tls-hostname-verifier WILDCARD

キーストア Vault は Vault SPI の実装であり、ベアメタルインストールにシークレットを保存するのに役立ちます。この Vault は、Red Hat Single Sign-On 7.6 の Elytron 認証情報ストアに代わるものです。

<spi name="vault">
     <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="path/to/keystore.p12"/>
             <property name="secret" value="password"/>
     </properties>
   </provider>
</spi>

Red Hat build of Keycloak では、CLI パラメーターを使用した同等の設定は、次のようなものになります。

kc.sh start
   --vault keystore
   --vault-file /path/to/keystore.p12
   --vault-pass password

Vault に保存されたシークレットには、管理コンソール内の複数の場所からアクセスできます。既存の Elytron Vault から新しい Java KeyStore ベースの Vault への移行に関しては、レルム設定の変更は必要ありません。新しく作成された Java キーストアに同じシークレットが含まれている場合は、既存のレルム設定が機能するはずです。

デフォルトの REALM_UNDERSCORE_KEY キーリゾルバーを使用すると、以前と同じ方法で ${vault.realm-name_alias} によって (たとえば、LDAP ユーザーフェデレーション設定内で) シークレットにアクセスできます。

Red Hat build of Keycloak での JVM 設定方法は、Red Hat Single Sign-On 7.6 の方法と似ています。引き続き特定の環境変数を設定する必要がありますが、/bin フォルダーに standalone.conf などの設定ファイルが含まれません。

Red Hat build of Keycloak は、さまざまなデフォルトの JVM 引数を提供します。これは、メモリー割り当てと CPU オーバーヘッドの面で優れたスループットと効率を実現するため、ほとんどのデプロイメントに適していることが判明しています。また、他のデフォルトの JVM 引数は、Red Hat build of Keycloak インスタンスをスムーズに実行するためのものであり、ユースケースに合わせて引数を変更する場合は注意が必要です。

JVM 引数または GC 設定を変更するには、Java オプションとして指定する特定の環境変数を設定します。これらの設定を完全にオーバーライドするには、JAVA_OPTS 環境変数を指定します。

特定の Java プロパティーの追加のみが必要な場合は、JAVA_OPTS_APPEND 環境変数を指定します。JAVA_OPTS 環境変数が指定されていない場合は、./kc.sh スクリプト内にあるデフォルトの Java プロパティーが使用されます。

たとえば、次のように特定の Java オプションを指定できます。

export JAVA_OPTS_APPEND=-XX:+HeapDumpOnOutOfMemoryError
kc.sh start

SPI プロバイダーの設定は、新しい設定システムを通じて行います。以下は古い形式です。

<spi name="<spi-id>">
    <provider name="<provider-id>" enabled="true">
        <properties>
            <property name="<property>" value="<value>"/>
        </properties>
    </provider>
</spi>

以下は新しい形式です。

spi-<spi-id>-<provider-id>-<property>=<value>

トラブルシューティングには次のコマンドを使用します。