Menu Close

18.6. レルム操作

新しいレルムの作成

realms エンドポイントで create コマンドを使用して、新しい有効なレルムを作成します。属性を realm に設定し、enabled に設定します。

$ kcadm.sh create realms -s realm=demorealm -s enabled=true

Red Hat Single Sign-On は、デフォルトでレルムを無効にします。これを有効にすると、認証にレルムをすぐに使用できます。

新規オブジェクトの説明には、JSON 形式を使用することもできます。

$ kcadm.sh create realms -f demorealm.json

レルム属性を使用して JSON ドキュメントをファイルから直接送信するか、または標準入力にドキュメントをパイプして送信できます。

以下に例を示します。

  • Linux:
$ kcadm.sh create realms -f - << EOF
{ "realm": "demorealm", "enabled": true }
EOF
  • Windows:
c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f -

既存のレルムの一覧表示

このコマンドは、すべてのレルムの一覧を返します。

$ kcadm.sh get realms
注記

Red Hat Single Sign-On は、サーバー上のレルムのリストをフィルターリングして、ユーザーがのみ表示できるレルムを返します。

ほとんどのユーザーは、レルム名やレルムの有効化ステータスなどの属性のサブセットに関心があるので、すべてのレルム属性のリストは詳細にすることができます。--fields オプションを使用して、返す属性を指定できます。

$ kcadm.sh get realms --fields realm,enabled

結果をコンマ区切りの値として表示することができます。

$ kcadm.sh get realms --fields realm --format csv --noquotes

特定のレルムの取得

レルム名をコレクション URI に追加し、個別のレルムを取得します。

$ kcadm.sh get realms/master

レルムの更新

  1. レルムの属性すべてを変更しない場合に、-s オプションを使用して属性に新しい値を設定します。

    以下に例を示します。

    $ kcadm.sh update realms/demorealm -s enabled=false
  2. 書き込み可能な属性をすべて新しい値に設定する場合は、以下のようになります。

    1. get コマンドを実行します。
    2. JSON ファイルの現在の値を編集します。
    3. 再度送信します。

      以下に例を示します。

      $ kcadm.sh get realms/demorealm > demorealm.json
      $ vi demorealm.json
      $ kcadm.sh update realms/demorealm -f demorealm.json

レルムの削除

以下のコマンドを実行してレルムを削除します。

$ kcadm.sh delete realms/demorealm

レルムのすべてのログインページオプションをオンにする

特定のケイパビリティーを制御する属性を true に設定します。

以下に例を示します。

$ kcadm.sh update realms/demorealm -s registrationAllowed=true -s registrationEmailAsUsername=true -s rememberMe=true -s verifyEmail=true -s resetPasswordAllowed=true -s editUsernameAllowed=true

レルムキーの一覧表示

ターゲットレルムの keys エンドポイントで get 操作を使用します。

$ kcadm.sh get keys -r demorealm

新しいレルムキーの生成

  1. 新しい RSA 生成鍵のペアを追加する前に、ターゲットレルムの ID を取得します。

    以下に例を示します。

    $ kcadm.sh get realms/demorealm --fields id --format csv --noquotes
  2. kcadm.sh get keys -r demorealm によって明らかになったように、既存のプロバイダーよりも優先度の高い新規キープロバイダーを追加します。

    以下に例を示します。

    • Linux:

      $ kcadm.sh create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keySize=["2048"]'
    • Windows:

      c:\> kcadm create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keySize=[\"2048\"]"
  3. parentId 属性をターゲットレルムの ID の値に設定します。

    kcadm.sh get keys -r demorealm で示されるように、新しく追加されたキーがアクティブなキーになります。

Java キーストアファイルから新しいレルムキーの追加

  1. 新しいキープロバイダーを追加して、JKS ファイルとして新しいキーペアを事前に追加します。

    たとえば、以下のようになります。

    • Linux:

      $ kcadm.sh create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keystore=["/opt/keycloak/keystore.jks"]' -s 'config.keystorePassword=["secret"]' -s 'config.keyPassword=["secret"]' -s 'config.keyAlias=["localhost"]'
    • Windows:

      c:\> kcadm create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keystore=[\"/opt/keycloak/keystore.jks\"]" -s "config.keystorePassword=[\"secret\"]" -s "config.keyPassword=[\"secret\"]" -s "config.keyAlias=[\"localhost\"]"
  2. 特定のキーストアに一致するように、keystorekeystorePasswordkeyPassword、および alias 属性値を変更するようにしてください。
  3. parentId 属性をターゲットレルムの ID の値に設定します。

鍵のパッシブの作成または鍵の無効化

  1. パッシブを作成する鍵を特定します。

    $ kcadm.sh get keys -r demorealm
  2. キーの providerId 属性を使用して、components/PROVIDER_ID などのエンドポイント URI を作成します。
  3. update を実行します。

    以下に例を示します。

    • Linux:

      $ kcadm.sh update components/PROVIDER_ID -r demorealm -s 'config.active=["false"]'
    • Windows:

      c:\> kcadm update components/PROVIDER_ID -r demorealm -s "config.active=[\"false\"]"

      他のキー属性を更新できます。

  4. 新しい enabled 値を設定してキーを無効にします(例: config.enabled=["false"])。
  5. 新規の priority の値を設定し、キーの優先度を変更します (例: config.priority=["110"])。

古いキーの削除

  1. 削除するキーがアクティブでなくなり、無効になっていることを確認します。このアクションは、アプリケーションおよびユーザーが保持する既存のトークンが失敗しないようにするためです。
  2. 削除するキーを特定します。

    $ kcadm.sh get keys -r demorealm
  3. キーの providerId を使用して削除を実行します。

    $ kcadm.sh delete components/PROVIDER_ID -r demorealm

レルムのイベントロギングの設定

events/config エンドポイントで update コマンドを使用します。

eventsListeners 属性には、イベントを受信するすべてのイベントリスナーを指定する EventListenerProviderFactory ID の一覧が含まれます。組み込みイベントストレージを制御する属性を利用できるため、管理 REST API を使用して過去のイベントをクエリーできます。Red Hat Single Sign-On では、サービス呼び出しのロギング (eventsEnabled) と、管理コンソールまたは Admin REST API (adminEventsEnabled) によってトリガーされる監査イベントのロギングを個別に制御します。eventsExpiration イベントを期限切れにし、データベースがいっぱいにならないようにすることができます。Red Hat Single Sign-On は、eventsExpiration を秒単位で表される存続時間に設定します。

すべてのイベントを受信し、JBoss-logging でイベントをログに記録する組み込みイベントリスナーを設定できます。org.keycloak.events ロガーを使用して、Red Hat Single Sign-On はエラーイベントを WARN としてログに記録し、その他のイベントを DEBUG としてログに記録します。

以下に例を示します。

  • Linux:
$ kcadm.sh update events/config -r demorealm -s 'eventsListeners=["jboss-logging"]'
  • Windows:
c:\> kcadm update events/config -r demorealm -s "eventsListeners=[\"jboss-logging\"]"

以下に例を示します。

監査イベントを除く、利用可能なすべての ERROR イベントのストレージを 2 日間オンにして、Admin REST を使用してイベントを取得できるようします。

  • Linux:
$ kcadm.sh update events/config -r demorealm -s eventsEnabled=true -s 'enabledEventTypes=["LOGIN_ERROR","REGISTER_ERROR","LOGOUT_ERROR","CODE_TO_TOKEN_ERROR","CLIENT_LOGIN_ERROR","FEDERATED_IDENTITY_LINK_ERROR","REMOVE_FEDERATED_IDENTITY_ERROR","UPDATE_EMAIL_ERROR","UPDATE_PROFILE_ERROR","UPDATE_PASSWORD_ERROR","UPDATE_TOTP_ERROR","VERIFY_EMAIL_ERROR","REMOVE_TOTP_ERROR","SEND_VERIFY_EMAIL_ERROR","SEND_RESET_PASSWORD_ERROR","SEND_IDENTITY_PROVIDER_LINK_ERROR","RESET_PASSWORD_ERROR","IDENTITY_PROVIDER_FIRST_LOGIN_ERROR","IDENTITY_PROVIDER_POST_LOGIN_ERROR","CUSTOM_REQUIRED_ACTION_ERROR","EXECUTE_ACTIONS_ERROR","CLIENT_REGISTER_ERROR","CLIENT_UPDATE_ERROR","CLIENT_DELETE_ERROR"]' -s eventsExpiration=172800
  • Windows:
c:\> kcadm update events/config -r demorealm -s eventsEnabled=true -s "enabledEventTypes=[\"LOGIN_ERROR\",\"REGISTER_ERROR\",\"LOGOUT_ERROR\",\"CODE_TO_TOKEN_ERROR\",\"CLIENT_LOGIN_ERROR\",\"FEDERATED_IDENTITY_LINK_ERROR\",\"REMOVE_FEDERATED_IDENTITY_ERROR\",\"UPDATE_EMAIL_ERROR\",\"UPDATE_PROFILE_ERROR\",\"UPDATE_PASSWORD_ERROR\",\"UPDATE_TOTP_ERROR\",\"VERIFY_EMAIL_ERROR\",\"REMOVE_TOTP_ERROR\",\"SEND_VERIFY_EMAIL_ERROR\",\"SEND_RESET_PASSWORD_ERROR\",\"SEND_IDENTITY_PROVIDER_LINK_ERROR\",\"RESET_PASSWORD_ERROR\",\"IDENTITY_PROVIDER_FIRST_LOGIN_ERROR\",\"IDENTITY_PROVIDER_POST_LOGIN_ERROR\",\"CUSTOM_REQUIRED_ACTION_ERROR\",\"EXECUTE_ACTIONS_ERROR\",\"CLIENT_REGISTER_ERROR\",\"CLIENT_UPDATE_ERROR\",\"CLIENT_DELETE_ERROR\"]" -s eventsExpiration=172800

保存されたイベントタイプは、利用可能なすべてのイベントタイプ にリセットできます。値を空のリストに設定すると、すべてを列挙することと同じです。

$ kcadm.sh update events/config -r demorealm -s enabledEventTypes=[]

監査イベントのストレージを有効にできます。

$ kcadm.sh update events/config -r demorealm -s adminEventsEnabled=true -s adminEventsDetailsEnabled=true

過去 100 件のイベントを取得できます。イベントは新しいものから古いものの順に並べられています。

$ kcadm.sh get events --offset 0 --limit 100

保存されたすべてのイベントを削除できます。

$ kcadm delete events

キャッシュのフラッシュ

  1. 以下のエンドポイントのいずれかで create コマンドを使用して、キャッシュを消去します。

    • clear-realm-cache
    • clear-user-cache
    • clear-keys-cache
  2. realm をターゲットレルムと同じ値に設定します。

    以下に例を示します。

    $ kcadm.sh create clear-realm-cache -r demorealm -s realm=demorealm
    $ kcadm.sh create clear-user-cache -r demorealm -s realm=demorealm
    $ kcadm.sh create clear-keys-cache -r demorealm -s realm=demorealm

エクスポートされた .json ファイルからのレルムのインポート

  1. partialImport エンドポイントで create コマンドを使用します。
  2. ifResourceExistsFAILSKIP、または OVERWRITE に設定します。
  3. -f を使用して、エクスポートしたレルムの .json ファイルを送信します。

    以下に例を示します。

    $ kcadm.sh create partialImport -r demorealm2 -s ifResourceExists=FAIL -o -f demorealm.json

    レルムが存在しない場合は、最初に作成します。

    以下に例を示します。

    $ kcadm.sh create realms -s realm=demorealm2 -s enabled=true