17.5. 基本操作およびリソース URI

管理 CLI は、特定のタスクを単純化する追加のコマンドを使用して、管理 REST API エンドポイントに対して CRUD 操作を汎用的に実行できます。

主な使用方法パターンを以下に示します。

$ kcadm.sh create ENDPOINT [ARGUMENTS]
$ kcadm.sh get ENDPOINT [ARGUMENTS]
$ kcadm.sh update ENDPOINT [ARGUMENTS]
$ kcadm.sh delete ENDPOINT [ARGUMENTS]

create、get、update、および delete コマンドは HTTP 動詞である POST、GET、PUT、DELETE にそれぞれマップします。ENDPOINT はターゲットリソース URI であり、絶対 URI (http: または https: で始まる) または相対 URI にすることができます。Red Hat build of Keycloak は、次の形式で絶対 URL を設定するためにこれを使用します。

SERVER_URI/admin/realms/REALM/ENDPOINT

たとえば、サーバー http://localhost:8080 に対して認証し、レルムが master である場合は、users を ENDPOINT として使用すると http://localhost:8080/admin/realms/master/users のリソース URL となります。

ENDPOINT を clients に設定する場合、有効なリソース URI は http://localhost:8080/admin/realms/master/clients になります。

Red Hat build of Keycloak には、レルムのコンテナーである realms エンドポイントがあります。以下に対して解決します。

SERVER_URI/admin/realms

Red Hat build of Keycloak には、serverinfo エンドポイントがあります。このエンドポイントはレルムとは独立しています。

realm-admin 権限を持つユーザーとして認証する場合は、複数のレルムでコマンドを実行する必要がある場合があります。その場合は、 -r オプションを指定して、コマンドを明示的に実行するレルムを CLI に指示します。kcadm.sh config credentials の --realm オプションで指定された REALM を使用する代わりに、コマンドは TARGET_REALM を使用します。

SERVER_URI/admin/realms/TARGET_REALM/ENDPOINT

以下に例を示します。

$ kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
$ kcadm.sh create users -s username=testuser -s enabled=true -r demorealm

この例では、master レルムで admin ユーザーとして認証されたセッションを開始します。次に、リソース URL http://localhost:8080/admin/realms/demorealm/users に対して POST 呼び出しを実行します。

create および update コマンドは、JSON ボディーをサーバーに送信します。-f FILENAME を使用して、ファイルから既製のドキュメントを読み取ることができます。-f - オプションを使用できる場合、Red Hat build of Keycloak は標準入力からメッセージボディーを読み取ります。ユーザーの作成 の例にあるように、個別の属性とその値を指定できます。Red Hat build of Keycloak は、属性を JSON ボディーにしてサーバーに送信します。

Red Hat build of Keycloak では、update コマンドを使用してリソースを更新するための方法がいくつかあります。まず、リソースの現在の状態を決定してファイルに保存し、そのファイルを編集して更新のためにサーバーに送信できます。

以下に例を示します。

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

このメソッドは、送信された JSON ドキュメントの属性でサーバーのリソースを更新します。

別のオプションとして、-s, --set オプションを使用してオンザフライで更新を実行し、新しい値を設定することもできます。

以下に例を示します。

$ kcadm.sh update realms/demorealm -s enabled=false

このメソッドは、enabled 属性を false に設定します。

デフォルトでは、update コマンドは get を実行し、新しい属性値を既存の値とマージします。エンドポイントが PUT コマンドをサポートするかもしれませんが、GET コマンドではない場合もあります。-n オプションを使用して no-merge 更新を実行できます。これは、GET コマンドを最初に実行せずに PUT コマンドを実行します。