レルムのインポートとエクスポート

以下の export および import コマンドを使用する場合、Keycloak はレルム、クライアント、ユーザー、およびその他のエンティティに関する情報が保存されているデータベースへの接続方法を知る必要があります。Keycloak の設定 で説明されているように、その情報はコマンドラインパラメータ、環境変数、または設定ファイルとして提供できます。各コマンドの利用可能なオプションについては、--help コマンドラインオプションを使用してください。

構成オプションの一部は、ビルド時の構成オプションです。デフォルトでは、Keycloak はビルド時のパラメータの変更を検出した場合、export および import コマンドに対して自動的に再ビルドします。

Keycloak の設定 で概説されているように、build コマンドを使用して最適化されたバージョンの Keycloak をビルドした場合、--optimized コマンドラインオプションを使用して、Keycloak が起動時間の高速化のためにビルドチェックをスキップするようにします。これを行う場合は、コマンドラインからビルド時のオプションを削除し、ランタイムオプションのみを保持してください。

レルムをエクスポートするには、export コマンドを使用できます。このコマンドを呼び出すときは、Keycloak サーバーインスタンスを起動しないでください。

レルムをディレクトリにエクスポートするには、--dir <dir> オプションを使用できます。

レルムをディレクトリにエクスポートすると、サーバーはエクスポートされるレルムごとに個別のファイルを作成します。

レルムをファイルにエクスポートするには、--file <file> オプションを使用できます。

レルムをファイルにエクスポートすると、サーバーは同じファイルを使用して、エクスポートされるすべてのレルムの構成を保存します。

エクスポートする特定のレルムを指定しない場合、すべてのレルムがエクスポートされます。単一のレルムをエクスポートするには、次のように --realm オプションを使用できます。

レルムをエクスポートすると、特定のファイル名規則が使用されます。これは、ディレクトリからのインポートまたは起動時のインポートでも使用する必要があります。インポートされるレルムファイルは、<レルム名>-realm.json という名前である必要があります。レルムに関連付けられた通常およびフェデレーションユーザーファイルは、<レルム名>-users-<ファイル番号>.json および <レルム名>-federated-users-<ファイル番号>.json という名前である必要があります。この規則を使用しないと、エラーが発生したり、ユーザーファイルがインポートされなかったりする可能性があります。

レルムをインポートするには、import コマンドを使用できます。このコマンドを呼び出すときは、Keycloak サーバーインスタンスを起動しないでください。

レルムをディレクトリにエクスポートした後、--dir <dir> オプションを使用して、次のようにレルムをサーバーにインポートし直すことができます。

import コマンドを使用してレルムをインポートする場合、既存のレルムをスキップするか、新しい構成で上書きするかを設定できます。そのためには、次のように --override オプションを設定できます。

デフォルトでは、--override オプションは true に設定されているため、レルムは常に新しい構成で上書きされます。

単一のファイルに以前にエクスポートされたレルムをインポートするには、次のように --file <file> オプションを使用できます。

プレースホルダーを使用して、任意のレルム構成の環境変数から値を解決できます。

上記の例では、MY_REALM_NAME 環境変数に設定された値が、realm プロパティを設定するために使用されます。

--import-realm オプションを使用すると、サーバーの起動時にレルムをインポートすることもできます。

--import-realm オプションを設定すると、サーバーは data/import ディレクトリからレルム構成ファイルをインポートしようとします。このディレクトリから読み取られるのは .json 拡張子を使用した通常のファイルのみで、サブディレクトリは無視されます。

レルムがサーバーに既に存在する場合、インポート操作はスキップされます。この動作の主な理由は、レルムを再作成し、サーバーの再起動間で状態が失われる可能性を回避するためです。

レルムを再作成するには、サーバーを起動する前に明示的に import コマンドを実行する必要があります。

管理コンソールを使用してレルムをインポートおよびエクスポートすることもできます。この機能は、管理コンソールがレルムの部分的なエクスポート機能のみを提供するため、前のセクションで説明した他の CLI オプションとは異なります。この場合、現在のレルム設定と、クライアント、ロール、グループなどの一部のリソースをエクスポートできます。この方法では、そのレルムのユーザーをエクスポートできません。

管理コンソールを使用してレルムをエクスポートするには、次の手順を実行します。

同様の方法で、以前にエクスポートされたレルムをインポートできます。次の手順を実行します。

インポートされたリソースが既に存在する場合に Keycloak が行うべき処理を制御することもできます。これらのオプションが存在します。