第5章 クライアント登録サービスの使用
アプリケーションまたはサービスが Red Hat build of Keycloak を使用するには、Red Hat build of Keycloak でクライアントを登録する必要があります。管理者は管理コンソール (または管理 REST エンドポイント) でこれを実行できますが、クライアントは Red Hat build of Keycloak クライアント登録サービスを介して登録することもできます。
クライアント登録サービスは、Red Hat build of Keycloak Client Representations、OpenID Connect Client Meta Data および SAML Entity Descriptors のビルトインサポートを提供します。クライアント登録サービスのエンドポイントは /realms/<realm>/clients-registrations/<provider> です。
サポートされているビルトイン providers は以下のとおりです。
- default - Red Hat build of Keycloak Client Representation (JSON)
- install - Red Hat build of Keycloak Adapter Configuration (JSON)
- openid-connect - OpenID Connect Client Metadata Description (JSON)
- saml2-entity-descriptor - SAML Entity Descriptor (XML)
以下のセクションでは、異なるプロバイダーを使用する方法を説明します。
5.1. Authentication
クライアント登録サービスを呼び出すには、通常トークンが必要です。トークンは、ベアラートークン、初期アクセストークン、または登録アクセストークンにすることができます。トークンなしで新しいクライアントを登録する別の方法もありますが、その場合はクライアント登録ポリシーを設定する必要があります (以下を参照)。
5.1.1. ベアラートークン
ベアラートークンは、ユーザーまたは Service Account の代わりに発行できます。エンドポイントを呼び出すには、以下のパーミッションが必要です (詳細は サーバー管理ガイド を参照)。
- create-client または manage-client - クライアントを作成するため
- view-client または manage-client - クライアントを表示するため
- manage-client - クライアントを更新または削除する
ベアラートークンを使用してクライアントを作成する場合は、create-client ロールのみを持つサービスアカウントのトークンを使用することを推奨します (詳細は サーバー管理ガイド を参照)。
5.1.2. 初期アクセストークン
新しいクライアントを登録するための推奨されるアプローチは、初期アクセストークンを使用することです。初期アクセストークンは、クライアントの作成にのみ使用でき、有効期限を設定できるほか、作成できるクライアントの数に制限を設定できます。
初期アクセストークンは管理コンソールを使用して作成できます。新しい初期アクセストークンを作成するには、最初に管理コンソールでレルムを選択し、左側のメニューで Client をクリックし、ページに表示されるタブの Initial access token をクリックします。
これで、既存の初期アクセストークンを確認できるようになります。アクセスがあれば、不要になったトークンを削除できます。トークンの作成時にのみ、トークンの値を取得できます。新規トークンを作成するには、Create をクリックします。オプションで、トークンの有効期間を追加できるようになりました。また、トークンを使用して作成できるクライアントの数も追加できます。Save をクリックすると、トークンの値が表示されます。
このトークンは後で取得できないため、今すぐこのトークンをコピーして貼り付けることが重要です。コピー/貼り付けを忘れた場合は、このトークンを削除して別のトークンを作成してください。
トークン値は、クライアント登録サービスを呼び出すときに、リクエストの Authorization ヘッダーに追加することにより、標準のベアラートークンとして使用されます。以下に例を示します。
Authorization: bearer eyJhbGciOiJSUz...
5.1.3. 登録アクセストークン
クライアント登録サービス経由でクライアントを作成する場合、応答には登録アクセストークンが含まれます。登録アクセストークンは、後でクライアント設定を取得するアクセスを提供しますが、クライアントを更新または削除するためのアクセスも提供します。登録アクセストークンは、ベアラートークンまたは初期アクセストークンと同じ方法でリクエストに含まれます。
デフォルトでは、登録アクセストークンのローテーションは有効になっています。これは、登録アクセストークンが 1 回だけ有効であることを意味します。トークンが使用されると、レスポンスには新しいトークンが含まれます。登録アクセストークンのローテーションは、クライアントポリシー を使用して無効化できます。
クライアント登録サービスの外部でクライアントが作成された場合、それに関連付けられた登録アクセストークンはありません。管理コンソールから作成できます。これは、特定のクライアントのトークンを失った場合にも便利です。新しいトークンを作成するには、管理コンソールでクライアントを見つけ、Credentials をクリックします。次に、Generate registration access token をクリックします。
