Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

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>
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
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>
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
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
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 KeycloakRed 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>
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
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>
Copy to Clipboard Toggle word wrap 
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>
Copy to Clipboard Toggle word wrap

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

kc.sh start
    --hostname myFrontendUrl
Copy to Clipboard Toggle word wrap

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

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

kc.sh start --proxy-headers xforwarded
Copy to Clipboard Toggle word wrap
注記

ホスト名とプロキシー設定は、リソース 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 の証明書をトラストストアにインポートします。その後、システムのトラストストアを指定して 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>
Copy to Clipboard Toggle word wrap

Red Hat build of Keycloak は、PEM ファイル、または拡張子が .p12 および .pfx の PKCS12 ファイル形式のトラストストアをサポートしています。PKCS12 ファイルの場合は、暗号化されている証明書は使用できません。つまり、パスワードは必要ありません。JKS トラストストアを変換する必要があります。Java keytool ではパスワードの最小長が 6 文字に制限されるため、暗号化されていない PKCS12 トラストストアを作成する代わりに openssl を使用できます。

  1. 古い JKS トラストストアの内容をインポートし、keytool を使用して一時パスワードを持つ PKCS12 トラストストアを作成します。 

    keytool -importkeystore -srckeystore path/to/myTrustStore.jks \
   -destkeystore path/to/myTrustStore.p12 \
   -srcstoretype jks \
   -deststoretype pkcs12 \
   -srcstorepass password \
   -deststorepass temp-password
    Copy to Clipboard Toggle word wrap

  2. openssl を使用して、新しい PKCS12 トラストストアの内容をエクスポートします。 

    openssl pkcs12 -in path/to/myTrustStore.p12 \
   -out path/to/myTrustStore.pem \
   -nodes -passin pass:temp-password
    Copy to Clipboard Toggle word wrap

  3. openssl を使用して、暗号化されていない新しい PKCS12 トラストストアにコンテンツを再インポートします。 

    openssl pkcs12 -export -in path/to/myTrustStore.pem \
   -out path/to/myUnencryptedTrustStore.p12 \
   -nokeys -passout pass:
    Copy to Clipboard Toggle word wrap

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

kc.sh start
    --truststore-paths path/to/myUnencryptedTrustStore.p12
    --tls-hostname-verifier 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>
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
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
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>
Copy to Clipboard Toggle word wrap

以下は新しい形式です。 

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

Environment Variable

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 - エラーが発生した場合、エラースタックトレース全体を出力します。
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat