$ export PATH=$PATH:$KEYCLOAK_HOME/bin $ kcreg.sh
クライアント登録 CLI は、アプリケーション開発者が Keycloak と統合する際に、セルフサービス方式で新しいクライアントを設定するためのコマンドラインインターフェース (CLI) ツールです。これは特に Keycloak クライアント登録 REST エンドポイントと対話するように設計されています。
Keycloak を使用できるようにするには、すべてのアプリケーションに対してクライアント設定を作成または取得する必要があります。通常、一意のホスト名でホストされる新しいアプリケーションごとに新しいクライアントを設定します。アプリケーションが Keycloak と対話する場合、アプリケーションはクライアント ID で自身を識別するため、Keycloak はログインページ、シングルサインオン (SSO) セッション管理、およびその他のサービスを提供できます。
クライアント登録 CLI を使用してコマンドラインからアプリケーションクライアントを設定でき、シェルスクリプトで使用できます。
特定のユーザーが `Client Registration CLI` を使用できるようにするには、Keycloak 管理者は通常、Admin Console を使用して適切なロールを持つ新しいユーザーを設定するか、新しいクライアントとクライアントシークレットを設定してクライアント登録 REST API へのアクセスを許可します。
Admin Console (たとえば、https://127.0.0.1:8080) に admin としてログインします。
管理するレルムを選択します。
既存のユーザーを使用する場合は、そのユーザーを選択して編集します。それ以外の場合は、新しいユーザーを作成します。
**ロールマッピング**、**ロールを割り当てる** を選択します。オプションリストから、**クライアントでフィルタリング** をクリックします。検索バーに `manage-clients` と入力します。ロールを選択します。または、マスターレルムにいる場合は、**NAME-realm** の名前を持つものを選択します。ここで、`NAME` はターゲットレルムの名前です。マスターレルムのユーザーに他のレルムへのアクセスを許可できます。
**割り当てる** をクリックして、クライアント管理のフルセットのアクセス許可を付与します。別のオプションは、読み取り専用の場合は **view-clients** を選択するか、新しいクライアントを作成する場合は **create-client** を選択することです。
**利用可能なロール**、**manage-client** を選択して、クライアント管理のフルセットのアクセス許可を付与します。別のオプションは、読み取り専用の場合は **view-clients** を選択するか、新しいクライアントを作成する場合は **create-client** を選択することです。
|
これらの権限により、ユーザーは初期アクセストークンまたは登録アクセストークンを使用せずに操作を実行する機能が付与されます (詳細については、クライアント登録サービス を参照してください)。 |
ユーザーに realm-management ロールを割り当てないことも可能です。その場合、ユーザーはクライアント登録 CLI でログインできますが、初期アクセストークンなしでは使用できません。トークンなしで操作を実行しようとすると、**403 Forbidden** エラーが発生します。
管理者は、Admin Console の [クライアント] 領域の [**初期アクセストークン**] タブから初期アクセストークンを発行できます。
デフォルトでは、サーバーは Client Registration CLI を admin-cli クライアントとして認識します。これは、すべての新しいレルムに対して自動的に設定されます。ユーザー名でログインする場合、追加のクライアント設定は必要ありません。
Client Registration CLI 用に個別のクライアント設定を使用する場合は、クライアント (たとえば、reg-cli) を作成します。
**標準フローを有効にする** のチェックを外します。
**クライアント認証** を **オン** に切り替えて、セキュリティを強化します。
使用するアカウントのタイプを選択します。
クライアントに関連付けられたサービスアカウントを使用する場合は、**サービスアカウントのロール** をチェックします。
通常のユーザーアカウントを使用する場合は、**ダイレクトアクセス許可** をチェックします。
**次へ** をクリックします。
**保存** をクリックします。
**認証情報** タブをクリックします。
クライアント ID とシークレット または 署名付き JWT のいずれかを設定します。
サービスアカウントロールを使用している場合は、**サービスアカウントのロール** タブをクリックします。
サービスアカウントのアクセスを設定するロールを選択します。選択するロールの詳細については、Client Registration CLI で使用するための新しい通常のユーザーの設定 を参照してください。
**保存** をクリックします。
kcreg config credentials を実行するときは、--secret オプションを使用して、設定されたシークレットを指定します。
kcreg config credentials を実行するときに、使用する clientId を指定します (たとえば、--client reg-cli)。
サービスアカウントが有効になっている場合、kcreg config credentials を実行するときにユーザーの指定を省略し、クライアントシークレットまたはキーストア情報のみを提供できます。
Client Registration CLI は Keycloak Server ディストリビューション内にパッケージ化されています。実行スクリプトは bin ディレクトリ内にあります。Linux スクリプトは kcreg.sh と呼ばれ、Windows スクリプトは kcreg.bat と呼ばれます。
ファイルシステムの任意の場所から使用するためにクライアントをセットアップするときに、Keycloak サーバーディレクトリを PATH に追加します。
例:
Linux
$ export PATH=$PATH:$KEYCLOAK_HOME/bin $ kcreg.sh
Windows
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin c:\> kcreg
KEYCLOAK_HOME は、Keycloak Server ディストリビューションが展開されたディレクトリを指します。
認証情報でログインして、認証済みセッションを開始します。
Client Registration REST エンドポイントでコマンドを実行します。
例:
Linux
$ kcreg.sh config credentials --server https://127.0.0.1:8080 --realm demo --user user --client reg-cli $ kcreg.sh create -s clientId=my_client -s 'redirectUris=["https://127.0.0.1:8980/myapp/*"]' $ kcreg.sh get my_client
Windows
c:\> kcreg config credentials --server https://127.0.0.1:8080 --realm demo --user user --client reg-cli c:\> kcreg create -s clientId=my_client -s "redirectUris=[\"https://127.0.0.1:8980/myapp/*\"]" c:\> kcreg get my_client
|
本番環境では、トークンがネットワークスニファーに公開されるのを防ぐために、Keycloak に |
サーバーの証明書が、Java のデフォルトの証明書トラストストアに含まれる信頼できる認証局 (CA) のいずれかによって発行されていない場合は、truststore.jks ファイルを準備し、Client Registration CLI にそれを使用するように指示します。
例:
Linux
$ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
Windows
c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
Client Registration CLI でログインするときは、サーバーエンドポイント URL とレルムを指定します。
ユーザー名またはクライアント ID を指定します。これにより、特別なサービスアカウントが使用されます。ユーザー名を使用する場合、指定されたユーザーのパスワードを使用する必要があります。クライアント ID を使用する場合、パスワードの代わりにクライアントシークレットまたは 署名付き JWT を使用します。
ログイン方法に関係なく、ログインするアカウントには、クライアント登録操作を実行できるように適切な権限が必要です。マスター以外のレルムのアカウントは、同じレルム内のクライアントを管理する権限のみを持つことに注意してください。異なるレルムを管理する必要がある場合は、異なるレルムに複数のユーザーを設定するか、master レルムに単一のユーザーを作成し、異なるレルムのクライアントを管理するためのロールを追加できます。
Client Registration CLI でユーザーを設定することはできません。ユーザーを設定するには、Admin Console Web インターフェースまたは Admin Client CLI を使用してください。詳細については、サーバー管理ガイド を参照してください。
kcreg が正常にログインすると、認証トークンを受信し、後続の呼び出しで使用できるように、プライベート構成ファイルに保存します。構成ファイルの詳細については、代替構成の使用 を参照してください。
Client Registration CLI の使用方法の詳細については、組み込みのヘルプを参照してください。
例:
Linux
$ kcreg.sh help
Windows
c:\> kcreg help
認証済みセッションの開始の詳細については、kcreg config credentials --help を参照してください。
デフォルトでは、Client Registration CLI は、ユーザーのホームディレクトリの下にあるデフォルトの場所 ./.keycloak/kcreg.config に構成ファイルを自動的に保持します。--config オプションを使用して、別のファイルまたは場所を指し、複数の認証済みセッションを並行して維持できます。これは、単一のスレッドから単一の構成ファイルに関連付けられた操作を実行する最も安全な方法です。
|
構成ファイルをシステムの他のユーザーに表示しないでください。構成ファイルには、プライベートに保つ必要があるアクセストークンとシークレットが含まれています。 |
不便であり、より多くのトークンリクエストが必要になりますが、すべてのコマンドで --no-config オプションを使用することで、構成ファイル内にシークレットを保存することを避けることができます。各 kcreg 呼び出しですべての認証情報を指定します。
使用したい Keycloak サーバーにアカウントが設定されていない開発者は、Client Registration CLI を使用できます。これは、レルム管理者が開発者に初期アクセストークンを発行した場合にのみ可能です。これらのトークンをいつ、どのように発行および配布するかを決定するのは、レルム管理者次第です。レルム管理者は、初期アクセストークンの最大有効期間と、それを使用して作成できるクライアントの総数を制限できます。
開発者が初期アクセストークンを取得すると、kcreg config credentials で認証せずに、それを使用して新しいクライアントを作成できます。初期アクセストークンは、構成ファイルに保存するか、kcreg create コマンドの一部として指定できます。
例:
Linux
$ kcreg.sh config initial-token $TOKEN $ kcreg.sh create -s clientId=myclient
または
$ kcreg.sh create -s clientId=myclient -t $TOKEN
Windows
c:\> kcreg config initial-token %TOKEN% c:\> kcreg create -s clientId=myclient
または
c:\> kcreg create -s clientId=myclient -t %TOKEN%
初期アクセストークンを使用すると、サーバー応答には新しく発行された登録アクセストークンが含まれます。そのクライアントに対する後続の操作は、そのトークンで認証することによって実行する必要があります。これは、そのクライアントに対してのみ有効です。
Client Registration CLI は、プライベート構成ファイルを自動的に使用して、このトークンを関連付けられたクライアントとともに保存および使用します。すべてのクライアント操作に同じ構成ファイルが使用されている限り、開発者はこの方法で作成されたクライアントを読み取り、更新、または削除するために認証する必要はありません。
初期アクセスおよび登録アクセストークンの詳細については、クライアント登録サービス を参照してください。
Client Registration CLI でトークンを設定する方法の詳細については、kcreg config initial-token --help および kcreg config registration-token --help コマンドを実行してください。
認証情報で認証するか、初期アクセストークンを構成した後の最初のタスクは、通常、新しいクライアントを作成することです。多くの場合、準備された JSON ファイルをテンプレートとして使用し、属性の一部を設定またはオーバーライドしたい場合があります。
次の例は、JSON ファイルを読み取り、含まれている可能性のあるクライアント ID をオーバーライドし、他の属性を設定し、作成が成功した後で構成を標準出力に出力する方法を示しています。
Linux
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
Windows
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 コマンドを使用して、既存のクライアントを取得できます。
例:
Linux
$ kcreg.sh get myclient
Windows
C:\> kcreg get myclient
クライアント構成をアダプター構成ファイルとして取得することもできます。これは、Web アプリケーションと一緒にパッケージ化できます。
例:
Linux
$ kcreg.sh get myclient -e install > keycloak.json
Windows
C:\> kcreg get myclient -e install > keycloak.json
kcreg get コマンドの詳細については、kcreg get --help コマンドを実行してください。
クライアント構成を更新する方法は 2 つあります。
1 つの方法は、現在の構成を取得し、ファイルに保存し、編集し、サーバーにポストバックした後で、完全な新しい状態をサーバーに送信することです。
例:
Linux
$ kcreg.sh get myclient > myclient.json $ vi myclient.json $ kcreg.sh update myclient -f myclient.json
Windows
C:\> kcreg get myclient > myclient.json C:\> notepad myclient.json C:\> kcreg update myclient -f myclient.json
2 番目の方法は、現在のクライアントを取得し、フィールドを設定または削除して、1 つのステップでポストバックすることです。
例:
Linux
$ kcreg.sh update myclient -s enabled=false -d redirectUris
Windows
C:\> kcreg update myclient -s enabled=false -d redirectUris
適用する変更のみを含むファイルを使用することもできます。これにより、引数として多くの値を指定する必要がなくなります。この場合、--merge を指定して、Client Registration CLI に、JSON ファイルを完全な新しい構成として扱うのではなく、既存の構成に適用される属性のセットとして扱うように指示します。
例:
Linux
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
Windows
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json
kcreg update コマンドの詳細については、kcreg update --help コマンドを実行してください。
クライアントを削除するには、次の例を使用します。
Linux
$ kcreg.sh delete myclient
Windows
C:\> kcreg delete myclient
kcreg delete コマンドの詳細については、kcreg delete --help コマンドを実行してください。
--no-config モードを使用して作成、読み取り、更新、および削除 (CRUD) 操作を実行する場合、Client Registration CLI は登録アクセストークンを処理できません。その場合、クライアントの最新の発行済み登録アクセストークンを見失う可能性があり、**manage-clients** 権限を持つアカウントで認証せずに、そのクライアントに対してそれ以上の CRUD 操作を実行することが不可能になります。
権限がある場合は、クライアントの新しい登録アクセストークンを発行し、標準出力に出力するか、選択した構成ファイルに保存できます。それ以外の場合は、レルム管理者にクライアントの新しい登録アクセストークンを発行して送信してもらう必要があります。その後、--token オプションを介して任意の CRUD コマンドに渡すことができます。kcreg config registration-token コマンドを使用して、新しいトークンを構成ファイルに保存し、それ以降 Client Registration CLI に自動的に処理させることができます。
kcreg update-token コマンドの詳細については、kcreg update-token --help コマンドを実行してください。