6.4. クライアント登録 CLI の使用

ログイン方法に関係なく、ログインするアカウントには、クライアント登録操作を実行するための適切な権限が必要です。マスター以外のレルムのアカウントには、同じレルム内のクライアントを管理するためのパーミッションのみを持つことができる点に注意してください。異なるレルムを管理する必要がある場合は、異なるレルムで複数のユーザーを設定するか、master レルムで 1 つのユーザーを作成し、異なるレルムでクライアントを管理するロールを追加できます。

クライアント登録 CLI を使用してユーザーを設定することはできません。管理コンソールの Web インターフェイスまたは Admin Client CLI を使用してユーザーを設定します。詳細は、サーバー管理ガイド を参照してください。

kcreg が 正常にログインすると、認可トークンを受け取り、プライベート設定ファイルに保存します。これにより、後続の呼び出しにトークンを使用できます。設定ファイルの詳細については、「代替設定の使用」 を参照してください。

クライアント登録 CLI の使用方法についての詳細は、組み込みヘルプを参照してください。

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

$ kcreg.sh help

c:\> kcreg help

認証セッションの開始に関する詳細は、kcreg config credentials --help を参照してください。

デフォルトでは、クライアント登録 CLI は、ユーザーのホームディレクトリーにあるデフォルトの場所 (./.keycloak/kcreg.config) で設定ファイルを自動的に維持します。--config オプションを使用して異なるファイルまたは場所を指定し、複数の認証セッションを並行して管理することができます。単一のスレッドから、単一の設定ファイルに関連付けられる操作を実行するための最も安全な方法です。

すべてのコマンドで --no-config オプションを使用すると、シークレットを設定ファイル内に格納しないようにすることができます。各 kcreg 呼び出しですべての認証情報を指定します。

使用する Red Hat build of Keycloak サーバーでアカウントを設定していない開発者は、クライアント登録 CLI を使用できます。これは、レルム管理者が開発者に初期アクセストークンを発行した場合にのみ可能です。これらのトークンを発行および配布する方法と時期を決定するのは、レルム管理者の責任になります。レルム管理者は、初期アクセストークンの最大有効期間と、それを使用して作成できるクライアントの総数を制限できます。

開発者に初期アクセストークンがある場合、開発者は kcreg config credentials で認証せずにこれを使用して新規クライアントを作成することができます。初期アクセストークンは、設定ファイルに保存するか、kcreg create コマンドの一部として指定できます。

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

$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient

または、以下を実行します。

$ kcreg.sh create -s clientId=myclient -t $TOKEN

c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient

または、以下を実行します。

c:\> kcreg create -s clientId=myclient -t %TOKEN%

初期アクセストークンを使用する場合、サーバーの応答には、新しく発行された登録アクセストークンが含まれます。そのクライアントの後続の操作は、そのトークンで認証することで実行する必要があります。これは、そのクライアントに対してのみ有効です。

クライアント登録 CLI は、プライベート設定ファイルを自動的に使用して、このトークンを保存し、関連付けられたクライアントで使用します。同じ設定ファイルがすべてのクライアント操作に使用される限り、開発者はこの方法で作成されたクライアントの読み取り、更新、または削除を行うために認証する必要はありません。

初期アクセスおよび登録アクセストークンの詳細は、クライアント登録 を参照してください。

クライアント登録 CLI でトークンを設定する方法についての詳細は、kcreg config initial-token --help コマンドおよび kcreg config registration-token --help コマンドを実行してください。

通常、認証情報を使用して認証するか、初期アクセストークンを設定した後の最初のタスクは、新しいクライアントを作成することです。多くの場合、準備した JSON ファイルをテンプレートとして使用し、一部の属性を設定したり、上書きすることを推奨します。

以下の例は、JSON ファイルの読み取り、含まれる可能性のあるクライアント ID の上書き、その他の属性の設定、正常な作成後に設定を標準出力に出力する方法を示しています。

$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o

C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o

kcreg create コマンドの詳細は、kcreg create --help を実行します。

kcreg attrs を使用して利用可能な属性をリスト表示できます。多くの設定属性は、有効性または一貫性についてチェックされないことに注意してください。適切な値を指定することが推奨されます。テンプレートに id フィールドを使用せず、kcreg create コマンドに引数として指定しないでください。

kcreg get コマンドを使用して、既存のクライアントを取得できます。

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

$ kcreg.sh get myclient

C:\> kcreg get myclient

クライアント設定をアダプター設定ファイルとして取得することもできます。これは Web アプリケーションでパッケージ化できます。

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

$ kcreg.sh get myclient -e install > keycloak.json

C:\> kcreg get myclient -e install > keycloak.json

kcreg get コマンドの詳細は、kcreg get --help コマンドを実行してください。

クライアント設定の更新方法は 2 つあります。

1 つの方法は、現在の設定を取得してファイルに保存し、編集してサーバーにポストバックした後に、完全に新しい状態をサーバーに送信することです。

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

$ kcreg.sh get myclient > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json

C:\> kcreg get myclient > myclient.json
C:\> notepad myclient.json
C:\> kcreg update myclient -f myclient.json

2 つ目の方法は、現在のクライアントをフェッチし、そのクライアントのフィールドを設定または削除して、1 つのステップでポストバックします。

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

$ kcreg.sh update myclient -s enabled=false -d redirectUris

C:\> kcreg update myclient -s enabled=false -d redirectUris

適用する変更のみを含むファイルを使用することもできるため、引数として値を多く指定する必要はありません。この場合は、--merge を指定して、JSON ファイルを完全かつ新規の設定として処理するのではなく、既存の設定に適用する属性セットとして処理する必要があることをクライアント登録 CLI に指示します。

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

$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json

C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json

kcreg update コマンドの詳細は、kcreg update --help コマンドを実行してください。

クライアントを削除するには、以下の例を使用します。

$ kcreg.sh delete myclient

C:\> kcreg delete myclient

kcreg delete コマンドの詳細は、kcreg delete --help コマンドを実行してください。

--no-config モードを使用して作成、読み取り、更新、および削除 (CRUD) 操作を実行すると、クライアント登録 CLI はユーザーの登録アクセストークンを処理できません。この場合、クライアントに対して最近発行した Registration Access Token の追跡できなくなる可能性があり、manage-clients パーミッションを持つアカウントで認証を行わずに、そのクライアントでの CRUD 操作を追加で実行できなくなります。

パーミッションがある場合は、クライアントの新しい登録アクセストークンを発行し、標準出力に出力したり、任意の設定ファイルに保存したりできます。それ以外の場合は、レルム管理者に、クライアント用の新しい登録アクセストークンを発行して送信するよう依頼する必要があります。--token オプションを使用して、これをすべての CRUD コマンドに渡すことができます。kcreg config registration-token コマンドを使用して新規トークンを設定ファイルに保存し、クライアント登録 CLI にこの時点から自動的に処理させることもできます。

kcreg update-token コマンドの詳細は、kcreg update-token --help コマンドを実行してください。