2.4. 設定の移行

Red Hat build of Keycloak サーバーを設定する統一された方法として、設定オプションが新しく導入されました。Red Hat Single Sign-On 7.6 の設定メカニズム (standalone.xml、jboss-cli など) は使用できなくなりました。

各オプションは、次の設定ソースを通じて定義できます。

CLI パラメーター
環境変数
設定ファイル
Java KeyStore ファイル

同じ設定オプションが別々の設定ソースで指定されている場合は、上記のリストの最初のソースが使用されます。

すべての設定オプションは、さまざまな設定ソースすべてで使用できますが、主な違いはキーの形式です。たとえば、データベースのホスト名を設定する 4 つの方法を次に示します。

Expand

ソース	フォーマット
CLI パラメーター	--db-url-host cliValue
環境変数	KC_DB_URL_HOST=envVarValue
設定ファイル	db-url-host=confFileValue
Java KeyStore ファイル	kc.db-url-host=keystoreValue

kc.sh --help コマンドおよび Red Hat build of Keycloak ドキュメントに、使用可能なすべての設定オプションの詳細なリストが記載されています。オプションはキャッシュ、データベースなどのカテゴリーごとにグループ化されています。また、データベースの設定の章など、設定する領域ごとに個別の章があります。

2.4.1. データベース設定の移行
リンクのコピー

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>

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

注記

データベース認証情報は、セキュアな KeyStore 設定ソースに保存することを検討してください。

2.4.2. HTTP および TLS 設定の移行
リンクのコピー

実稼働モード (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>

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

2.4.3. クラスタリングとキャッシュ設定の移行
リンクのコピー

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

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

Expand

Red Hat build of Keycloak	Red Hat Single Sign-On 7.6
./kc.sh start --cache=local	./standalone.sh
./kc.sh start [--cache=ispn]	./standalone.sh --server-config=standalone-ha.xml

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

local - start-dev コマンドの実行時
ispn - start コマンドの実行時

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>

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

注記

ドメインクラスターモードは、Red Hat build of Keycloak ではサポートされていません。

トランスポートスタック

Red Hat build of Keycloak のデフォルトおよびカスタム JGroups トランスポートスタックを移行する必要はありません。

唯一の改善点は、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>

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

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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

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

2.4.4. ホスト名とプロキシー設定の移行
リンクのコピー

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>

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

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

Red Hat build of Keycloak では、リバースプロキシーの背後でクラスターを実行するときに HTTP ヘッダー転送を簡単に有効にするために、プロキシーの TLS Termination モードに応じて、さまざまなプロキシーモードを設定できます。

none (デフォルト)
edge
passthrough
reencrypt

edge または reencrypt を設定すると、プロキシーによって設定された HTTP Forwarded および X-Forwarded-* ヘッダーを Red Hat build of Keycloak が認識できるようになります。クラスターを公開する前に、プロキシーがこれらのヘッダーをオーバーライドしていることを確認する必要があります。

注記

ホスト名とプロキシー設定は、リソース URL (リダイレクト URI、CSS および JavaScript リンク、OIDC の既知のエンドポイントなど) を決定するために使用され、受信要求を積極的にブロックするために使用されるわけではありません。ホスト名/プロキシーオプションは、Red Hat build of Keycloak サーバーがリッスンする実際のバインディングアドレスやポートを変更しません。これは HTTP/TLS オプションの役割です。Red Hat Single Sign-On 7.6 では、ホスト名の設定が強く推奨されていましたが、強制はされていませんでした。Red Hat build of Keycloak では、start コマンドを使用する場合にホスト名の設定が必須になりました。ただし、--hostname-strict=false オプションで明示的に無効にした場合を除きます。

2.4.5. トラストストア設定の移行
リンクのコピー

トラストストアは、HTTPS 要求や LDAP サーバーなどの外部 TLS 通信に使用します。トラストストアを使用するには、リモートサーバーまたは CA の証明書をトラストストアにインポートします。その後、トラストストアの SPI を指定して 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>

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

Copy to Clipboard

Toggle word wrap

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

kc.sh start
  --spi-truststore-file-file /path/to/myTrustStore.jks
  --spi-truststore-file-password password
  --spi-truststore-file-hostname-verification-policy WILDCARD

kc.sh start
  --spi-truststore-file-file /path/to/myTrustStore.jks
  --spi-truststore-file-password password
  --spi-truststore-file-hostname-verification-policy WILDCARD

Copy to Clipboard

Toggle word wrap

2.4.6. Vault 設定の移行
リンクのコピー

キーストア 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>

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

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

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

2.4.7. JVM 設定の移行
リンクのコピー

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

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

Copy to Clipboard

Toggle word wrap

2.4.8. SPI プロバイダー設定の移行
リンクのコピー

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

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

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

Copy to Clipboard

Toggle word wrap

以下は新しい形式です。

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

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

Copy to Clipboard

Toggle word wrap

Expand

ソース	フォーマット
CLI	./kc.sh start --spi-connections-http-client-default-connection-pool-size 10
環境変数	KC_SPI_CONNECTIONS_HTTP_CLIENT_DEFAULT_CONNECTION_POOL_SIZE=10
設定ファイル	spi-connections-http-client-default-connection-pool-size=10
Java キーストアファイル	kc.spi-connections-http-client-default-connection-pool-size=10

2.4.9. 設定のトラブルシューティング
リンクのコピー

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

kc.sh show-config - 特定のプロパティーのロード元である設定ソースとその値を表示します。プロパティーとその値が正しく伝播されているかどうかを確認できます。
kc.sh --verbose start - エラーが発生した場合、エラースタックトレース全体を出力します。

トップに戻る

2.4. 設定の移行

2.4.1. データベース設定の移行
リンクのコピー

2.4.2. HTTP および TLS 設定の移行
リンクのコピー

2.4.3. クラスタリングとキャッシュ設定の移行
リンクのコピー

2.4.4. ホスト名とプロキシー設定の移行
リンクのコピー

2.4.5. トラストストア設定の移行
リンクのコピー

2.4.6. Vault 設定の移行
リンクのコピー

2.4.7. JVM 設定の移行
リンクのコピー

2.4.8. SPI プロバイダー設定の移行
リンクのコピー

2.4.9. 設定のトラブルシューティング
リンクのコピー

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4. 設定の移行

2.4.1. データベース設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.2. HTTP および TLS 設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.3. クラスタリングとキャッシュ設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.4. ホスト名とプロキシー設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.5. トラストストア設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.6. Vault 設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.7. JVM 設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.8. SPI プロバイダー設定の移行リンクのコピーリンクがクリップボードにコピーされました!

2.4.9. 設定のトラブルシューティングリンクのコピーリンクがクリップボードにコピーされました!

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4.1. データベース設定の移行
リンクのコピー

2.4.2. HTTP および TLS 設定の移行
リンクのコピー

2.4.3. クラスタリングとキャッシュ設定の移行
リンクのコピー

2.4.4. ホスト名とプロキシー設定の移行
リンクのコピー

2.4.5. トラストストア設定の移行
リンクのコピー

2.4.6. Vault 設定の移行
リンクのコピー

2.4.7. JVM 設定の移行
リンクのコピー

2.4.8. SPI プロバイダー設定の移行
リンクのコピー

2.4.9. 設定のトラブルシューティング
リンクのコピー