Keycloakの設定

Keycloakを設定および起動する方法について理解する

このガイドでは、Keycloakの設定方法、および推奨される設定を起動および適用する方法について説明します。また、Keycloakの高速起動と低メモリフットプリントのために最適化するための設定ガイドラインも含まれています。

Keycloakの設定ソース

Keycloakは、4つのソースから設定をロードします。これらは適用順にリストされています。

  1. コマンドラインパラメータ

  2. 環境変数

  3. conf/keycloak.confファイル、またはユーザー作成の設定ファイルで定義されたオプション。

  4. ユーザー作成のJavaキーストアファイルで定義された機密オプション。

オプションが複数のソースで設定されている場合、リストの先頭にあるものがそのオプションの値を決定します。たとえば、コマンドラインパラメータで設定されたオプションの値は、同じオプションの環境変数よりも優先度が高くなります。

例：db-url-hostパラメータの設定

次の例は、db-url値が4つの設定ソースでどのように設定されているかを示しています。

ソース 形式

コマンドラインパラメータ

--db-url=cliValue

環境変数

KC_DB_URL=envVarValue

設定ファイル

db-url=confFileValue

Javaキーストアファイル

kc.db-url=keystoreValue

適用優先度に基づくと、起動時に使用される値はcliValueです。これは、コマンドラインが最も優先度が高いためです。

--db-url=cliValueが使用されなかった場合、適用される値はKC_DB_URL=envVarValueになります。コマンドラインまたは環境変数のいずれでも値が適用されなかった場合、db-url=confFileValueが使用されます。以前の値がいずれも適用されなかった場合、利用可能な設定ソースの中で最も優先度が低いため、kc.db-url=keystoreValueの値が使用されます。

設定の形式

設定はソースごとの統一形式を使用しており、キー/バリューペアをある設定ソースから別の設定ソースに簡単に変換できます。これらの形式はspiオプションにも適用されることに注意してください。

コマンドラインパラメータ形式

コマンドラインの値は、--<ダッシュ付きキー>=<値>形式を使用します。一部の値では、-<省略形>=<値>の短縮形も存在します。

環境変数形式

環境変数の値は、大文字のKC_<アンダースコア付きキー>=<値>形式を使用します。

設定ファイル形式

設定ファイルに入る値は、<ダッシュ付きキー>=<値>形式を使用します。

キーストア設定ファイル形式

キーストア設定ファイルに入る値は、kc.<ダッシュ付きキー>形式を使用します。<値>は、キーストアに格納されたパスワードになります。

各設定ガイドの最後に、関連オプションの見出しを探してください。これは、適用可能な設定形式を定義しています。すべての設定オプションについては、すべての設定を参照してください。ユースケースに適用される設定ソースと形式を選択してください。

例 - 設定ソースに基づいた代替形式

次の例は、3つの設定ソースに対するdb-url-hostの設定形式を示しています。

コマンドラインパラメータ
bin/kc.[sh|bat] start --db-url-host=mykeycloakdb
環境変数
export KC_DB_URL_HOST=mykeycloakdb
conf/keycloak.conf
db-url-host=mykeycloakdb

コマンドラインパラメータの形式

Keycloakには、設定用の多くのコマンドラインパラメータが同梱されています。利用可能な設定形式を確認するには、次のコマンドを入力します。

bin/kc.[sh|bat] start --help

または、すべてのサーバーオプションについては、すべての設定を参照してください。

環境変数の形式

keycloak.confファイル内で環境変数から環境固有の値を解決するために、プレースホルダーを使用できます。${ENV_VAR}構文を使用します。

db-url-host=${MY_DB_HOST}

環境変数を解決できない場合は、フォールバック値を指定できます。mydbの前にここに示されているように:（コロン）を使用します。

db-url-host=${MY_DB_HOST:mydb}

特定の設定ファイルを含める形式

デフォルトでは、サーバーは常にconf/keycloak.confファイルから設定オプションを取得します。新しいインストールの場合、このファイルには、本番環境で実行するときに設定したいことのアイデアとして、コメント化された設定のみが含まれています。

[-cf|--config-file]オプションを使用して、明示的な設定ファイルの場所を指定することもできます。次のコマンドを入力します。

bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start

このオプションを設定すると、Keycloakはconf/keycloak.confの代わりに指定されたファイルから設定を読み取ります。

Javaキーストアファイルを使用した機密オプションの設定

キーストア設定ソースのおかげで、[--config-keystore]および[--config-keystore-password]オプションを使用して、Javaキーストアからプロパティを直接ロードできます。オプションで、[--config-keystore-type]オプションを使用してキーストアタイプを指定できます。デフォルトでは、キーストアタイプはPKCS12です。

キーストア内のシークレットは、PBE（パスワードベースの暗号化）キーアルゴリズムを使用して格納する必要があります。ここで、キーはキーストアパスワードから派生します。次のkeytoolコマンドを使用して、そのようなキーストアを生成できます。

keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v

コマンドを実行した後、格納するパスワードを入力してくださいというプロンプトが表示されます。これは、上記のkc.db-passwordプロパティの値を表します。

キーストアが作成されたら、次のパラメータを使用してサーバーを起動できます。

bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=keystorepass --config-keystore-type=PKCS12

生のQuarkusプロパティの形式

ほとんどの場合、利用可能な設定オプションはサーバーを設定するのに十分なはずです。ただし、Keycloak設定に欠落している特定の動作または機能については、基盤となるQuarkusフレームワークのプロパティを使用できます。

可能であれば、Quarkusから直接プロパティを使用することは避けてください。これらはKeycloakではサポートされていないためです。お客様のニーズが不可欠な場合は、最初に機能拡張リクエストを開くことを検討してください。このアプローチは、お客様のニーズに合わせてKeycloakの設定を改善するのに役立ちます。

機能拡張リクエストが不可能な場合は、生のQuarkusプロパティを使用してサーバーを設定できます。

  1. confディレクトリにquarkus.propertiesファイルを作成します。

  2. そのファイルに必要なプロパティを定義します。

    Quarkusドキュメントで定義されているQuarkus拡張機能のサブセットのみを使用できます。また、Quarkusプロパティの次の違いにも注意してください。

    • QuarkusドキュメントのQuarkusプロパティのロックアイコンは、ビルド時プロパティを示しています。buildコマンドを実行して、このプロパティを適用します。buildコマンドの詳細については、Keycloakの最適化に関する後続のセクションを参照してください。

    • Quarkusガイドのプロパティにロックアイコンがない場合は、QuarkusおよびKeycloakのランタイムプロパティを示しています。

QuarkusプロパティをJavaキーストアに格納することもできます。

quarkus.http.portや同様の重要なプロパティなど、一部のQuarkusプロパティはすでにKeycloak設定にマッピングされていることに注意してください。プロパティがKeycloakで使用されている場合、quarkus.propertiesでそのプロパティキーを定義しても効果はありません。Keycloak設定値は、Quarkusプロパティ値よりも優先されます。

値での特殊文字の使用

Keycloakは、設定値の処理にQuarkusおよびMicroProfileに依存しています。値式がサポートされていることに注意してください。たとえば、${some_key}はsome_keyの値に評価されます。

式評価を無効にするには、\文字がエスケープ文字として機能します。特に、式を定義したり、繰り返されたりする場合に$文字の使用をエスケープするために使用する必要があります。たとえば、設定値my$$passwordが必要な場合は、代わりにmy\$\$passwordを使用します。\文字は、ほとんどのunixシェルを使用する場合、またはプロパティファイルに表示される場合に、追加のエスケープまたは引用符が必要になることに注意してください。たとえば、bashのシングルクォートは、単一のバックスラッシュ--db-password='my\$\$password'を保持します。また、bashのダブルクォートでは、追加のバックスラッシュ--db-password="my\\$\\$password"が必要です。同様に、プロパティファイルでは、バックスラッシュ文字もエスケープする必要があります：kc.db-password=my\\$\\$password

Windows固有の考慮事項

設定値でWindowsファイルパスを指定する場合、バックスラッシュもエスケープする必要があります。たとえば、パスC:\path\to\fileを指定する場合は、C:\\path\\to\\fileと記述する必要があります。または、エスケープする必要のないフォワードスラッシュC:/path/to/fileを使用することもできます。

PowerShellを使用しており、値にコンマなどの特殊文字が含まれている場合は、ダブルクォートをシングルクォートで囲んでください。

.\kc.bat start --log-level='"INFO,org.hibernate:debug"'

PowerShellはクォートを異なる方法で処理します。kc.batスクリプトに渡す前に、クォートされた文字列を解釈し、外側のクォート文字を削除します。したがって、値構造を保持するには、追加のクォート層が必要です。そうしないと、コンマが区切り文字として解釈されます。Windows CMDでは、ダブルクォートを直接使用できます。

Keycloakの起動

Keycloakは、開発モードまたは本番モードで起動できます。各モードは、意図された環境に対して異なるデフォルトを提供します。

開発モードでのKeycloakの起動

Keycloakを初めて試して、迅速に起動して実行するには、開発モードを使用します。このモードは、新しいKeycloakテーマの開発など、開発者にとって便利なデフォルトを提供します。

開発モードで起動するには、次のコマンドを入力します。

bin/kc.[sh|bat] start-dev
デフォルト

開発モードでは、次のデフォルト設定が設定されます。

  • HTTPが有効になっています

  • 厳密なホスト名解決が無効になっています

  • キャッシュはローカルに設定されています（高可用性に使用される分散キャッシュメカニズムはありません）

  • テーマキャッシュとテンプレートキャッシュが無効になっています

本番モードでのKeycloakの起動

本番環境でのKeycloakのデプロイには、本番モードを使用します。このモードは、デフォルトで安全の原則に従います。

本番モードで起動するには、次のコマンドを入力します。

bin/kc.[sh|bat] start

追加の設定なしでは、このコマンドはKeycloakを起動せず、代わりにエラーを表示します。この応答は意図的に行われています。Keycloakはデフォルトで安全の原則に従っているためです。本番モードでは、ホスト名が設定され、HTTPS/TLSセットアップが起動時に利用可能になることが期待されます。

デフォルト

本番モードでは、次のデフォルトが設定されます。

  • トランスポート層セキュリティ（HTTPS）が不可欠であるため、HTTPは無効になっています

  • ホスト名設定が想定されています

  • HTTPS/TLS設定が想定されています

本番環境にKeycloakをデプロイする前に、本番環境向けKeycloakの設定で概説されている手順に従ってください。

デフォルトでは、本番モードの構成オプションの例は、デフォルトのconf/keycloak.confファイルでコメントアウトされています。これらのオプションは、本番環境でKeycloakを実行する際に考慮すべき主な構成についてのアイデアを提供します。

最初の管理者ユーザーの作成

最初の管理者ユーザーは、ローカル接続（localhost）を使用してアクセスするWebフロントエンドを使用して作成できます。代わりに、環境変数を使用してこのユーザーを作成できます。最初の管理者ユーザー名にはKC_BOOTSTRAP_ADMIN_USERNAME=<ユーザー名>、最初の管理者パスワードにはKC_BOOTSTRAP_ADMIN_PASSWORD=<パスワード>を設定します。

Keycloakは、最初の起動時にこれらの値を解析して、管理者権限を持つ最初のユーザーを作成します。管理者権限を持つ最初のユーザーが存在すると、管理コンソールまたはコマンドラインツールkcadm.[sh|bat]を使用して追加のユーザーを作成できます。

最初の管理者がすでに存在し、起動時に環境変数がまだ存在する場合、最初の管理者の作成に失敗したことを示すエラーメッセージがログに表示されます。Keycloakは値を無視し、正しく起動します。

Keycloakの起動の最適化

本番環境にKeycloakをデプロイする前に、Keycloakを最適化して、起動を高速化し、メモリ消費を改善することを推奨します。このセクションでは、最高のパフォーマンスとランタイム動作のためにKeycloakの最適化を適用する方法について説明します。

最適化されたKeycloakビルドの作成

デフォルトでは、startまたはstart-devコマンドを使用すると、Keycloakは利便性のために内部でbuildコマンドを実行します。

このbuildコマンドは、起動とランタイム動作のために一連の最適化を実行します。ビルドプロセスには数秒かかる場合があります。特にKubernetesやOpenShiftなどのコンテナ化された環境でKeycloakを実行する場合、起動時間は重要です。その時間を無駄にしないように、CI/CDパイプラインの個別のステップなど、起動前に明示的にbuildを実行します。

最初のステップ：明示的にビルドを実行する

buildを実行するには、次のコマンドを入力します。

bin/kc.[sh|bat] build <build-options>

このコマンドは、入力するビルドオプションを表示します。Keycloakは、buildコマンドを実行するときに使用できるビルドオプションと、サーバーを起動するときに使用できる構成オプションを区別します。

Keycloakの非最適化起動の場合、この区別は影響を与えません。ただし、起動前にビルドを実行する場合、ビルドコマンドで使用できるオプションのサブセットのみです。この制限は、ビルドオプションが最適化されたKeycloakイメージに永続化されるためです。たとえば、db-passwordなどの資格情報の設定（構成オプション）は、セキュリティ上の理由から永続化してはなりません。

すべてのビルドオプションはプレーンテキストで永続化されます。ビルドオプションとして機密データを保存しないでください。これは、キーストア構成ソースを含む、利用可能なすべての構成ソースに当てはまります。したがって、Javaキーストアにビルドオプションを保存することも推奨しません。また、構成オプションに関しては、機密データを格納するために主にキーストア構成ソースを使用することをお勧めします。機密データ以外の場合は、残りの構成ソースを使用できます。

ビルドオプションは、すべての設定でツールアイコンでマークされています。利用可能なビルドオプションを見つけるには、ビルドオプションが選択されたすべての設定ページを参照するか、次のコマンドを入力します。

bin/kc.[sh|bat] build --help
例：起動前にデータベースをPostgreSQLに設定するためにbuildを実行する
bin/kc.[sh|bat] build --db=postgres

2番目のステップ：--optimizedを使用してKeycloakを起動する

ビルドが成功したら、Keycloakを起動し、次のコマンドを入力してデフォルトの起動動作をオフにできます。

bin/kc.[sh|bat] start --optimized <configuration-options>

--optimizedパラメータは、Keycloakに事前にビルドされた、最適化済みのKeycloakイメージが使用されていると想定するように指示します。その結果、Keycloakは起動時にビルドのチェックと実行を直接回避し、時間を節約します。

すべての構成オプションを起動時に入力できます。これらのオプションは、すべての設定でツールアイコンでマークされていないものです。

  • ビルドオプションが起動時に見つかり、buildの入力時に使用された値と等しい値を持つ場合、--optimizedパラメータを使用すると、そのオプションは暗黙的に無視されます。

  • そのオプションの値が、ビルドが入力されたときに使用された値と異なる場合、ログに警告が表示され、以前にビルドされた値が使用されます。この値を有効にするには、起動前に新しいbuildを実行します。

最適化されたビルドを作成する

次の例は、最適化されたビルドの作成に続いて、Keycloakを起動するときに--optimizedパラメータを使用する方法を示しています。

  1. buildコマンドを使用して、PostgreSQLデータベースベンダーのビルドオプションを設定します。

    bin/kc.[sh|bat] build --db=postgres

  2. conf/keycloak.confファイルでpostgresのランタイム構成オプションを設定します。

    db-url-host=keycloak-postgres
db-username=keycloak
db-password=change_me
hostname=mykeycloak.acme.com
https-certificate-file

  3. 最適化されたパラメータでサーバーを起動します。

    bin/kc.[sh|bat] start --optimized

buildコマンドを使用すると、起動とランタイム動作に対するほとんどの最適化を実現できます。また、構成ソースとしてkeycloak.confファイルを使用することで、CLI自体を初期化するなど、コマンドラインパラメータを必要とする起動時のいくつかのステップを回避できます。その結果、サーバーはさらに高速に起動します。

レルム構成でのシステム変数の使用

レルム機能の一部では、管理者はレルムとそのコンポーネントを構成するときに、環境変数やシステムプロパティなどのシステム変数を参照できます。

デフォルトでは、Keycloakはシステム変数の使用を許可しませんが、spi-admin-allowed-system-variables構成オプションを通じて明示的に指定されたもののみを許可します。このオプションを使用すると、同じキーを持つシステム変数からの値に最終的に解決されるキーのコンマ区切りリストを指定できます。

  1. サーバーを起動し、サーバーランタイムに一連のシステム変数を公開します。

    bin/kc.[sh|bat] start --spi-admin-allowed-system-variables=FOO,BAR

将来のリリースでは、この機能は削除され、レルム構成でのシステム変数の使用を完全に防止する方向になります。

基礎となる概念

このセクションでは、Keycloakが使用する基礎となる概念、特に起動の最適化に関する概念の概要を説明します。

Keycloakは、Quarkusフレームワークと再拡張/可変jarアプローチを内部で使用します。このプロセスは、buildコマンドが実行されると開始されます。

以下は、buildコマンドによって実行される最適化の一部です。

  • インストールされているプロバイダーに関する新しいクローズドワールドの仮定が作成されます。つまり、Keycloakを起動するたびにレジストリを再作成してファクトリを初期化する必要はありません。

  • 設定ファイルは事前に解析され、サーバー起動時のI/Oが削減されます。

  • データベース固有のリソースが構成され、特定のデータベースベンダーに対して実行できるように準備されます。

  • ビルドオプションをサーバーイメージに永続化することにより、サーバーは構成オプションを解釈して（再）構成するための追加の手順を実行しません。

詳細については、特定のQuarkusガイドをお読みください。

このページの内容
このガイドを編集