1.2. 設定用の形式

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

bin/kc.[sh|bat] start --db-url-host=mykeycloakdb

export KC_DB_URL_HOST=mykeycloakdb

db-url-host=mykeycloakdb

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

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

もしくは、すべての設定 ですべてのサーバーオプションを確認できます。

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

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

このオプションを設定すると、Red Hat build of Keycloak は conf/keycloak.conf ではなく指定されたファイルから設定を読み取ります。

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

KeyStore 内のシークレットは、PBE (パスワードベースの暗号化) キーアルゴリズムを使用して保存する必要があります。この場合のキーは、KeyStore のパスワードから導出します。次の keytool コマンドを使用して、このような KeyStore を生成できます。

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

コマンドを実行すると、Enter the password to be stored というプロンプトが表示されます。これは、上記の kc.db-password プロパティーの値を表します。

KeyStore が作成されると、次のパラメーターを使用してサーバーを起動できます。

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

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

可能であれば、Quarkus から直接プロパティーを使用することは避けてください。それらは Red Hat build of Keycloak でサポートされていません。どうしても必要な場合は、まず 機能拡張リクエスト を作成することを検討してください。このアプローチは、ニーズに合わせて Red Hat build of Keycloak の設定を改善するのに役立ちます。

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

同様に、Quarkus プロパティーを Java KeyStore に保存することもできます。

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

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

式の評価を無効にするには、\ 文字をエスケープ文字として使用します。特に、$ で式を定義する場合や $ が繰り返し現れる場合、\ によって $ の使用をエスケープする必要があります。たとえば、設定値 my$$password が必要な場合は、代わりに my\$\$password を使用します。ほとんどの Unix シェルを使用する場合、またはプロパティーファイルに現れる場合は、\ 文字を追加でエスケープするか、引用符で囲む必要があることに注意してください。たとえば、bash で一重引用符を使用すると、単一のバックスラッシュ --db-password='my\$\$password' が保持されます。また、bash で二重引用符を使用する場合は、バックスラッシュがもう 1 つ --db-password="my\\$\\$password" が必要です。同様に、プロパティーファイルでも、バックスラッシュ文字をエスケープする必要があります (kc.db-password=my\\$\\$password)。