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
レルムの更新
レルムの属性すべてを変更しない場合に、
-sオプションを使用して属性に新しい値を設定します。以下に例を示します。
$ kcadm.sh update realms/demorealm -s enabled=false
書き込み可能な属性をすべて新しい値に設定する場合は、以下のようになります。
-
getコマンドを実行します。 - JSON ファイルの現在の値を編集します。
再度送信します。
以下に例を示します。
$ 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
新しいレルムキーの生成
新しい RSA 生成鍵のペアを追加する前に、ターゲットレルムの ID を取得します。
以下に例を示します。
$ kcadm.sh get realms/demorealm --fields id --format csv --noquotes
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\"]"
parentId属性をターゲットレルムの ID の値に設定します。kcadm.sh get keys -r demorealmで示されるように、新しく追加されたキーがアクティブなキーになります。
Java キーストアファイルから新しいレルムキーの追加
新しいキープロバイダーを追加して、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\"]"
-
特定のキーストアに一致するように、
keystore、keystorePassword、keyPassword、およびalias属性値を変更するようにしてください。 -
parentId属性をターゲットレルムの ID の値に設定します。
鍵のパッシブの作成または鍵の無効化
パッシブを作成する鍵を特定します。
$ kcadm.sh get keys -r demorealm
-
キーの
providerId属性を使用して、components/PROVIDER_IDなどのエンドポイント URI を作成します。 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\"]"
他のキー属性を更新できます。
-
新しい
enabled値を設定してキーを無効にします (例:config.enabled=["false"])。 -
新規の
priorityの値を設定し、キーの優先度を変更します (例:config.priority=["110"])。
古いキーの削除
- 削除するキーがアクティブでなくなり、無効になっていることを確認します。このアクションは、アプリケーションおよびユーザーが保持する既存のトークンが失敗しないようにするためです。
削除するキーを特定します。
$ kcadm.sh get keys -r demorealm
キーの
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
キャッシュのフラッシュ
以下のエンドポイントのいずれかで
createコマンドを使用して、キャッシュを消去します。-
clear-realm-cache -
clear-user-cache -
clear-keys-cache
-
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 ファイルからのレルムのインポート
-
partialImportエンドポイントでcreateコマンドを使用します。 -
ifResourceExistsをFAIL、SKIP、またはOVERWRITEに設定します。 -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
