クライアント登録サービス

クライアント登録サービスの使用

アプリケーションまたはサービスがKeycloakを利用するためには、Keycloakにクライアントを登録する必要があります。管理者は管理コンソール（または管理RESTエンドポイント）を通じてこれを行うことができますが、クライアントはKeycloakクライアント登録サービスを通じて自身を登録することもできます。

クライアント登録サービスは、Keycloakクライアント表現、OpenID Connectクライアントメタデータ、およびSAMLエンティティ記述子の組み込みサポートを提供します。クライアント登録サービスのエンドポイントは/realms/<realm>/clients-registrations/<provider>です。

組み込みでサポートされているprovidersは次のとおりです。

  • default - Keycloakクライアント表現 (JSON)

  • install - Keycloakアダプター構成 (JSON)

  • openid-connect - OpenID Connectクライアントメタデータ記述 (JSON)

  • saml2-entity-descriptor - SAMLエンティティ記述子 (XML)

以下のセクションでは、さまざまなプロバイダーの使用方法について説明します。

認証

クライアント登録サービスを呼び出すには、通常、トークンが必要です。トークンは、ベアラートークン、初期アクセストークン、または登録アクセストークンです。トークンなしで新しいクライアントを登録する代替手段もありますが、その場合はクライアント登録ポリシーを設定する必要があります（下記参照）。

ベアラートークン

ベアラートークンは、ユーザーまたはサービスアカウントの代わりに発行できます。エンドポイントを呼び出すには、次の権限が必要です（詳細については、サーバー管理ガイドを参照してください）。

  • create-client または manage-client - クライアントを作成する場合

  • view-client または manage-client - クライアントを表示する場合

  • manage-client - クライアントを更新または削除する場合

ベアラートークンを使用してクライアントを作成する場合は、create-clientロールのみを持つサービスアカウントからのトークンを使用することをお勧めします（詳細については、サーバー管理ガイドを参照してください）。

初期アクセストークン

新しいクライアントを登録する推奨アプローチは、初期アクセストークンを使用することです。初期アクセストークンはクライアントの作成にのみ使用でき、設定可能な有効期限と、作成できるクライアント数の設定可能な制限があります。

初期アクセストークンは、管理コンソールを通じて作成できます。新しい初期アクセストークンを作成するには、まず管理コンソールでレルムを選択し、左側のメニューのクライアントをクリックし、ページに表示されるタブの初期アクセストークンをクリックします。

これで、既存の初期アクセストークンを確認できます。アクセス権があれば、不要になったトークンを削除できます。トークンの値は、作成時にのみ取得できます。新しいトークンを作成するには、作成をクリックします。トークンの有効期間と、トークンを使用して作成できるクライアント数をオプションで追加できます。保存をクリックすると、トークン値が表示されます。

後で取得できなくなるため、このトークンを今すぐコピー/ペーストすることが重要です。コピー/ペーストを忘れた場合は、トークンを削除して別のトークンを作成してください。

トークン値は、クライアント登録サービスを呼び出すときに標準のベアラートークンとして使用され、リクエストのAuthorizationヘッダーに追加されます。例：

Authorization: bearer eyJhbGciOiJSUz...

登録アクセストークン

クライアント登録サービスを通じてクライアントを作成すると、応答に登録アクセストークンが含まれます。登録アクセストークンは、後でクライアント構成を取得したり、クライアントを更新または削除したりするためのアクセスを提供します。登録アクセストークンは、ベアラートークンまたは初期アクセストークンと同じ方法でリクエストに含まれます。

デフォルトでは、登録アクセストークンのローテーションが有効になっています。これは、登録アクセストークンが一度だけ有効であることを意味します。トークンが使用されると、応答に新しいトークンが含まれます。登録アクセストークンのローテーションは、クライアントポリシーを使用することで無効にできることに注意してください。

クライアント登録サービス以外でクライアントが作成された場合、それに関連付けられた登録アクセストークンはありません。管理コンソールを通じて作成できます。これは、特定のクライアントのトークンを紛失した場合にも役立ちます。新しいトークンを作成するには、管理コンソールでクライアントを見つけて、認証情報をクリックします。次に、登録アクセストークンを生成をクリックします。

Keycloak表現

defaultクライアント登録プロバイダーは、クライアントの作成、取得、更新、および削除に使用できます。これは、管理コンソールを通じて構成できるのとまったく同じようにクライアントを構成するためのサポートを提供するKeycloakクライアント表現形式を使用します。たとえば、プロトコルマッパーの構成などです。

クライアントを作成するには、クライアント表現（JSON）を作成し、HTTP POSTリクエストを/realms/<realm>/clients-registrations/defaultに実行します。

登録アクセストークンも含むクライアント表現が返されます。後で構成を取得したり、クライアントを更新または削除したりする場合は、登録アクセストークンをどこかに保存する必要があります。

クライアント表現を取得するには、HTTP GETリクエストを/realms/<realm>/clients-registrations/default/<client id>に実行します。

新しい登録アクセストークンも返されます。

クライアント表現を更新するには、更新されたクライアント表現を使用してHTTP PUTリクエストを/realms/<realm>/clients-registrations/default/<client id>に実行します。

新しい登録アクセストークンも返されます。

クライアント表現を削除するには、HTTP DELETEリクエストを/realms/<realm>/clients-registrations/default/<client id>に実行します。

Keycloakアダプター構成

installationクライアント登録プロバイダーは、クライアントのアダプター構成を取得するために使用できます。トークン認証に加えて、HTTP基本認証を使用してクライアント認証情報で認証することもできます。これを行うには、リクエストに次のヘッダーを含めます。

Authorization: basic BASE64(client-id + ':' + client-secret)

アダプター構成を取得するには、HTTP GETリクエストを/realms/<realm>/clients-registrations/install/<client id>に実行します。

パブリッククライアントには認証は不要です。これは、JavaScriptアダプターの場合、上記のURLを使用してKeycloakから直接クライアント構成をロードできることを意味します。

OpenID Connect動的クライアント登録

Keycloakは、OpenID Connect動的クライアント登録を実装しており、これはOAuth 2.0動的クライアント登録プロトコルおよびOAuth 2.0動的クライアント登録管理プロトコルを拡張したものです。

これらの仕様を使用してKeycloakにクライアントを登録するためのエンドポイントは、/realms/<realm>/clients-registrations/openid-connect[/<client id>]です。

このエンドポイントは、レルムのOpenID Connectディスカバリーエンドポイント/realms/<realm>/.well-known/openid-configurationにもあります。

SAMLエンティティ記述子

SAMLエンティティ記述子エンドポイントは、SAML v2エンティティ記述子を使用してクライアントを作成することのみをサポートしています。クライアントの取得、更新、または削除はサポートしていません。これらの操作には、Keycloak表現エンドポイントを使用する必要があります。クライアントを作成すると、作成されたクライアントに関する詳細（登録アクセストークンを含む）を含むKeycloakクライアント表現が返されます。

クライアントを作成するには、SAMLエンティティ記述子を使用してHTTP POSTリクエストを/realms/<realm>/clients-registrations/saml2-entity-descriptorに実行します。

CURLを使用した例

次の例は、CURLを使用してclientId myclientを持つクライアントを作成します。eyJhbGciOiJSUz…​を適切な初期アクセストークンまたはベアラートークンに置き換える必要があります。

curl -X POST \
    -d '{ "clientId": "myclient" }' \
    -H "Content-Type:application/json" \
    -H "Authorization: bearer eyJhbGciOiJSUz..." \
    https://127.0.0.1:8080/realms/master/clients-registrations/default

Javaクライアント登録APIを使用した例

クライアント登録Java APIを使用すると、Javaを使用してクライアント登録サービスを簡単に使用できます。使用するには、Mavenから依存関係org.keycloak:keycloak-client-registration-api:>VERSION<を含めます。

クライアント登録の使用に関する完全な手順については、JavaDocsを参照してください。以下は、クライアントを作成する例です。eyJhbGciOiJSUz…​を適切な初期アクセストークンまたはベアラートークンに置き換える必要があります。

String token = "eyJhbGciOiJSUz...";

ClientRepresentation client = new ClientRepresentation();
client.setClientId(CLIENT_ID);

ClientRegistration reg = ClientRegistration.create()
    .url("https://127.0.0.1:8080", "myrealm")
    .build();

reg.auth(Auth.token(token));

client = reg.create(client);

String registrationAccessToken = client.getRegistrationAccessToken();

クライアント登録ポリシー

現在の計画では、クライアント登録ポリシーはサーバー管理ガイドで説明されているクライアントポリシーに置き換えられる予定です。クライアントポリシーはより柔軟性があり、より多くのユースケースをサポートしています。

Keycloakは現在、クライアント登録サービスを通じて新しいクライアントを登録する2つの方法をサポートしています。

  • 認証済みリクエスト - 新しいクライアントを登録するリクエストには、上記の初期アクセストークンまたはベアラートークンのいずれかが含まれている必要があります。

  • 匿名リクエスト - 新しいクライアントを登録するリクエストには、トークンがまったく含まれている必要はありません。

匿名クライアント登録リクエストは非常に興味深く強力な機能ですが、通常は誰でも制限なしに新しいクライアントを登録できることを望ましくありません。したがって、誰が新しいクライアントを登録できるか、およびどのような条件下で登録できるかを制限する方法を提供するクライアント登録ポリシーSPIがあります。

Keycloak管理コンソールで、クライアント登録タブ、次にクライアント登録ポリシーサブタブをクリックできます。ここでは、匿名リクエストに対してデフォルトで構成されているポリシーと、認証済みリクエストに対して構成されているポリシーが表示されます。

匿名リクエスト（トークンなしのリクエスト）は、新しいクライアントの作成（登録）のみが許可されています。したがって、匿名リクエストを通じて新しいクライアントを登録すると、応答には登録アクセストークンが含まれます。これは、特定のクライアントの読み取り、更新、または削除リクエストに使用する必要があります。ただし、この匿名登録からの登録アクセストークンの使用も、匿名ポリシーの対象になります！これは、たとえば、信頼できるホストポリシーがある場合、クライアントの更新リクエストも信頼できるホストから送信される必要があることを意味します。また、たとえば、クライアントの更新時、および同意が必要ポリシーが存在する場合に同意が必要を無効にすることは許可されません。

現在、これらのポリシー実装があります。

  • 信頼できるホストポリシー - 信頼できるホストと信頼できるドメインのリストを設定できます。クライアント登録サービスへのリクエストは、これらのホストまたはドメインからのみ送信できます。信頼できないIPから送信されたリクエストは拒否されます。新しく登録されたクライアントのURLも、これらの信頼できるホストまたはドメインのみを使用する必要があります。たとえば、信頼できないホストを指すクライアントのリダイレクトURIを設定することは許可されません。デフォルトでは、ホワイトリストに登録されたホストはないため、匿名クライアント登録は事実上無効になっています。

  • 同意が必要ポリシー - 新しく登録されたクライアントには、同意を許可スイッチが有効になっています。したがって、認証が成功した後、ユーザーが許可（クライアントスコープ）を承認する必要がある場合、常に同意画面が表示されます。これは、ユーザーが承認しない限り、クライアントがユーザーの個人情報や許可にアクセスできないことを意味します。

  • プロトコルマッパーポリシー - ホワイトリストに登録されたプロトコルマッパー実装のリストを設定できます。新しいクライアントは、ホワイトリストに登録されていないプロトコルマッパーが含まれている場合、登録または更新できません。このポリシーは認証済みリクエストにも使用されるため、認証済みリクエストであっても、使用できるプロトコルマッパーにはいくつかの制限があることに注意してください。

  • クライアントスコープポリシー - 新しく登録または更新されたクライアントで使用できるクライアントスコープをホワイトリストに登録できます。デフォルトでは、ホワイトリストに登録されたスコープはありません。レルムのデフォルトクライアントスコープとして定義されているクライアントスコープのみがデフォルトでホワイトリストに登録されています。

  • フルスコープポリシー - 新しく登録されたクライアントには、フルスコープ許可スイッチが無効になります。これは、それらがスコープ付きレルムロールまたは他のクライアントのクライアントロールを持たないことを意味します。

  • 最大クライアント数ポリシー - レルム内の現在のクライアント数が指定された制限以上の場合、登録を拒否します。匿名登録の場合、デフォルトで200です。

  • クライアント無効化ポリシー - 新しく登録されたクライアントは無効になります。これは、管理者が新しく登録されたすべてのクライアントを手動で承認して有効にする必要があることを意味します。このポリシーは、匿名登録であってもデフォルトでは使用されません。

このページについて
このガイドを編集