18.7. レルム操作
新しいレルムの作成
realms エンドポイントで create コマンドを使用して、新しい有効なレルムを作成します。属性を realm に設定し、enabled に設定します。
$ kcadm.sh create realms -s realm=demorealm -s enabled=true
Red Hat build of Keycloak では、デフォルトでレルムが無効になっています。これを有効にすると、認証にレルムをすぐに使用できます。
新規オブジェクトの説明には、JSON 形式を使用することもできます。
$ kcadm.sh create realms -f demorealm.json
レルム属性を使用して JSON ドキュメントをファイルから直接送信するか、標準入力にドキュメントをパイプして送信できます。
以下に例を示します。
Linux:
$ kcadm.sh create realms -f - << EOF { "realm": "demorealm", "enabled": true } EOFWindows:
c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f -
既存のレルムのリスト表示
このコマンドは、すべてのレルムのリストを返します。
$ kcadm.sh get realms
Red Hat build of Keycloak は、サーバー上のレルムのリストをフィルタリングして、ユーザーのみが表示できるレルムを返します。
ほとんどのユーザーは、レルム名やレルムの有効化ステータスなどの属性のサブセットに関心があるので、すべてのレルム属性のリストは詳細にすることができます。--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 build of Keycloak では、サービス呼び出しのロギング (eventsEnabled) と、管理コンソールまたは Admin REST API (adminEventsEnabled) によってトリガーされる監査イベントのロギングを個別に制御できます。eventsExpiration イベントを期限切れにし、データベースがいっぱいにならないようにすることができます。Red Hat build of Keycloak は、eventsExpiration を秒単位で表される存続期間に設定します。
すべてのイベントを受信し、JBoss-logging でイベントをログに記録する組み込みイベントリスナーを設定できます。Red Hat build of Keycloak は org.keycloak.events ロガーを使用して、エラーイベントを 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","UPDATE_CREDENTIAL_ERROR","VERIFY_EMAIL_ERROR","REMOVE_TOTP_ERROR","REMOVE_CREDENTIAL_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\",\"UPDATE_CREDENTIAL_ERROR\",\"VERIFY_EMAIL_ERROR\",\"REMOVE_TOTP_ERROR\",\"REMOVE_CREDENTIAL_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
