第16章 エクスポートおよびインポート

Red Hat Single Sign-On は、データベース全体をエクスポートおよびインポートする機能があります。これは、Red Hat Single Sign-On データベース全体をある環境から別の環境に移行する場合や、別のデータベース (MySQL から Oracle など) に移行する場合に役立ちます。エクスポートとインポートはサーバーの起動時にトリガーされ、そのパラメーターは Java システムプロパティーを使用して渡されます。インポートとエクスポートはサーバーの起動時に発生するため、サーバーやデータベースではその他のアクションが行われないため注意してください。

データベースを以下のようにエクスポート/インポートすることができます。

  • ローカルファイルシステムのディレクトリー
  • ファイルシステムの単一 JSON ファイル

ディレクトリーストラテジーを使用してインポートする場合は、ファイルは以下で指定された命名規則に従う必要があることに注意してください。以前にエクスポートされたファイルをインポートする場合、ファイルはすでにこの規則に従います。

  • <REALM_NAME>-realm.json (例: 「acme-roadrunner-affairs」という名前のレルムの場合は「acme-roadrunner-affairs-realm.json」)
  • <REALM_NAME>-users-<INDEX>.json (例: 「acme-roadrunner-affairs」という名前のレルムにおける最初のユーザーファイルの場合は「acme-roadrunner-affairs-users-0.json」)

ディレクトリーへエクスポートする場合には、各 JSON ファイルに保存されているユーザー数を指定することもできます。

注記

データベースにユーザー数が多い場合は (500 以上)、単一のファイルではなくディレクトリーにエクスポートすることを強く推奨します。1 つのファイルにエクスポートすると、非常に大きなファイルが発生する可能性があります。また、ディレクトリープロバイダーは各「ページ」(ユーザーと共にファイル) に別のトランザクションを使用するため、パフォーマンスが向上します。ファイルごとのユーザーのデフォルト数 (およびトランザクション) は 50 で、最良のパフォーマンスが得られますが、上書きが可能です (下記参照)。単一ファイルへのエクスポートでは、エクスポート全体とインポートごとに 1 つのトランザクションが使用され、ユーザーが大量のパフォーマンスが低下します。

暗号化されていないディレクトリーにエクスポートするには、以下を使用できます。 

bin/standalone.sh -Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=<DIR TO EXPORT TO>

単一の JSON ファイルにエクスポートするには、以下を使用できます。 

bin/standalone.sh -Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO EXPORT TO>

同様に、インポートには export の代わりに -Dkeycloak.migration.action=import を使用します。以下は、インポート例です。 

bin/standalone.sh -Dkeycloak.migration.action=import
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO IMPORT>
-Dkeycloak.migration.strategy=OVERWRITE_EXISTING

その他の利用可能なオプションは以下のとおりです。

-Dkeycloak.migration.realmName
このプロパティーは、all ではなく、指定したレルムだけをエクスポートする場合に使用されます。指定されていない場合は、すべてのレルムがエクスポートされます。
-Dkeycloak.migration.usersExportStrategy

このプロパティーは、ユーザーのエクスポートされる場所を指定するために使用されます。以下の値が使用できます。

  • DIFFERENT_FILES: ファイルごとのユーザーの最大数に応じて、ユーザーは異なるファイルにエクスポートされます。これはデフォルト値です。
  • SKIP: ユーザーのエクスポートは完全にスキップされます。
  • REALM_FILE: すべてのユーザーはレルム設定で同じファイルにエクスポートされます。(結果は、レルムデータとユーザーの両方を持つ「foo-realm.json」などのファイルになります。)
  • SAME_FILE: すべてのユーザーは、同じファイルにエクスポートされますが、レルムファイルとは異なります。(結果は、レルムデータを含む「foo-realm.json」および「foo-users.json」などのファイルとなります。)
-Dkeycloak.migration.usersPerFile
このプロパティーは、ファイルごとにユーザー数 (および DB トランザクションごと) を指定するために使用されます。デフォルトで 50 になります。これは、usersExportStrategy が DIFFERENT_FILES である場合にのみ使用されます。
-Dkeycloak.migration.strategy

このプロパティーは、インポート中に使用されます。同じ名前のレルムがデータをインポートするデータベースに存在する場合に、続行する方法を指定できます。以下の値が使用できます。

  • IGNORE_EXISTING: この名前のレルムがすでに存在する場合には、インポートを無視します。
  • OVERWRITE_EXISTING: 既存のレルムを削除して、JSON ファイルから新しいデータでインポートします。1 つの環境を別の環境に完全移行して、新しい環境に同じデータが含まれていることを確認する場合は、これを指定できます。

これまでにエクスポートされなかったレルムファイルをインポートする場合、keycloak.import オプションを使用できます。複数のレルムファイルをインポートする必要がある場合は、ファイル名のコンマ区切りリストを指定できます。これは、マスターレルムが初期化された後にのみ行われるため、前のケースよりも適しています。例:

  • -Dkeycloak.import=/tmp/realm1.json
  • -Dkeycloak.import=/tmp/realm1.json,/tmp/realm2.json

16.1. 管理コンソールのエクスポート/インポート

ほとんどのリソースのインポートは、管理コンソールから実行したり、ほとんどのリソースをエクスポートすることもできます。ユーザーのエクスポートはサポートされていません。

注記

シークレットまたはプライベート情報を含む属性はエクスポートファイルでマスクされます。そのため、管理コンソールから取得したファイルのエクスポートファイルは、バックアップやサーバー間のデータ転送には適していません。ブートタイムエクスポートのみが適切です。

また、「startup」エクスポート中に作成されたファイルを使用して、管理 UI からインポートすることもできます。これにより、あるレルムから別のレルムにエクスポートして、別のレルムにインポートできます。または、あるサーバーからエクスポートして、別のサーバーにインポートできます。

注記

管理コンソールのエクスポート/インポートでは、ファイルごとに 1 つのレルムのみが許可されます。

警告

管理コンソールのインポートにより、選択した場合はリソースを「上書き」することができます。特に本番環境ではこの機能を使用してください。通常、Admin Console Export 操作から .json ファイルはシークレットの無効な値が含まれるため、データのインポートには適切ではありません。

警告

管理コンソールのエクスポートを使用すると、クライアント、グループ、およびロールをエクスポートできます。レルムにこれらのアセットが多数ある場合は、操作が完了するのに時間がかかる場合があります。この間、サーバーがユーザーリクエストに応答しなくなることがあります。特に本番環境ではこの機能を使用してください。