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 ドキュメントに、使用可能なすべての設定オプションの詳細なリストが記載されています。オプションはキャッシュ、データベースなどのカテゴリーごとにグループ化されています。また、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.3. 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.4. クラスタリングとキャッシュ設定の移行
リンクのコピー

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

最も関連性の高い設定オプションは設定オプションとして利用できます。たとえば、オプション cache-embedded-realms-max-count を使用して、レルムキャッシュのエントリーの最大数を設定します。

注記

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

2.4.4.1. トランスポートスタック
リンクのコピー

デフォルトのトランスポートスタックは jdbc-ping で、データベースを活用して他のノードを検出し、TCP をトランスポートとして使用し、TLS 経由で自動的に暗号化します。これは、クラウドおよび非クラウド環境で適切に機能します。

他のすべてのトランスポートスタックは非推奨になりました。キャッシュ設定を jdbc-ping に移行する必要があります。

Keycloak の Red Hat ビルドが正しいインターフェイスにバインドするように、cache-embedded-network-bind-address パラメーターを設定することを推奨します。透過的なネットワークのない環境では、パラメーター cache-embedded-network-external-port および cache-embedded-network-external-address を設定して、他のノードから Red Hat build of Keycloak ノードにアクセスする方法を指定します。

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

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 myFrontendUrl

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

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.6. トラストストア設定の移行
リンクのコピー

トラストストアは、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>

<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 を使用できます。

手順

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

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

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

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

openssl pkcs12 -in path/to/myTrustStore.p12 \
   -out path/to/myTrustStore.pem \
   -nodes -passin pass:temp-password

openssl pkcs12 -in path/to/myTrustStore.p12 \
   -out path/to/myTrustStore.pem \
   -nodes -passin pass:temp-password

Copy to Clipboard

Toggle word wrap

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

openssl pkcs12 -export -in path/to/myTrustStore.pem \
   -out path/to/myUnencryptedTrustStore.p12 \
   -nokeys -passout pass:

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

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

Copy to Clipboard

Toggle word wrap

2.4.7. 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.8. 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.9. 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
Environment Variable	KC_SPI_CONNECTIONS_HTTP_CLIENT DEFAULTCONNECTION_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.10. 設定のトラブルシューティング
リンクのコピー

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

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

トップに戻る

2.4. 設定の移行

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

2.4.2. 追加のデータソース設定の移行
リンクのコピー

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

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

2.4.4.1. トランスポートスタック
リンクのコピー

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

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

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

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

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

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

詳細情報

試用、購入および販売

コミュニティー

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

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

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4. 設定の移行

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

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

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

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

2.4.4.1. トランスポートスタックリンクのコピーリンクがクリップボードにコピーされました!

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

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

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

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

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

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

詳細情報

試用、購入および販売

コミュニティー

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

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

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

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

2.4.2. 追加のデータソース設定の移行
リンクのコピー

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

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

2.4.4.1. トランスポートスタック
リンクのコピー

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

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

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

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

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

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