用戶端註冊服務

使用用戶端註冊服務

為了讓應用程式或服務能夠使用 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 角色的服務帳戶令牌（有關詳細資訊，請參閱伺服器管理指南）。

初始存取令牌

建議註冊新用戶端的方法是使用初始存取令牌。初始存取令牌只能用於建立用戶端，並且具有可配置的到期時間，以及可以建立的用戶端數量的可配置限制。

初始存取令牌可以透過管理控制台建立。要建立新的初始存取令牌，請先在管理控制台中選擇 realm，然後按一下左側選單中的 Client，然後按一下頁面中顯示的索引標籤中的 Initial access token。

現在您可以查看任何現有的初始存取令牌。如果您有存取權，則可以刪除不再需要的令牌。您只能在建立令牌時檢索令牌的值。要建立新令牌，請按一下 Create。您現在可以選擇性地新增令牌應有效的時間長度，以及可以使用令牌建立的用戶端數量。按一下 Save 後，會顯示令牌值。

請務必立即複製/貼上此令牌，因為您之後將無法檢索它。如果您忘記複製/貼上，請刪除令牌並建立另一個令牌。

當調用用戶端註冊服務時，令牌值會用作標準持有人令牌，方法是將其新增至請求中的 Authorization 標頭。例如

Authorization: bearer eyJhbGciOiJSUz...

註冊存取令牌

當您透過用戶端註冊服務建立用戶端時，回應將包含註冊存取令牌。註冊存取令牌提供稍後檢索用戶端設定的權限，也可以更新或刪除用戶端。註冊存取令牌與持有人令牌或初始存取令牌以相同方式包含在請求中。

預設情況下，會啟用註冊存取令牌輪換。這表示註冊存取令牌僅有效一次。當使用令牌時，回應將包含一個新令牌。請注意，可以使用 用戶端原則 停用註冊存取令牌輪換。

如果用戶端是在用戶端註冊服務之外建立的，則它不會有與其關聯的註冊存取令牌。您可以透過管理控制台建立一個。如果您遺失了特定用戶端的令牌，這也會很有用。要建立新令牌，請在管理控制台中找到用戶端，然後按一下 Credentials。然後按一下 Generate registration access token。

Keycloak 表示法

default 用戶端註冊提供者可用於建立、檢索、更新和刪除用戶端。它使用 Keycloak 用戶端表示法格式，該格式提供對用戶端進行配置的支援，就像它們可以透過管理控制台配置一樣，包括例如配置協定對應程式。

若要建立用戶端，請建立用戶端表示法 (JSON)，然後對 /realms/<realm>/clients-registrations/default 執行 HTTP POST 請求。

它將傳回一個用戶端表示法，其中也包含註冊存取令牌。如果您想要稍後檢索配置、更新或刪除用戶端，則應將註冊存取令牌儲存在某個位置。

若要檢索用戶端表示法，請對 /realms/<realm>/clients-registrations/default/<client id> 執行 HTTP GET 請求。

它也會傳回一個新的註冊存取令牌。

若要更新用戶端表示法，請對 /realms/<realm>/clients-registrations/default/<client id> 執行 HTTP PUT 請求，並使用更新的用戶端表示法。

它也會傳回一個新的註冊存取令牌。

若要刪除用戶端表示法，請對 /realms/<realm>/clients-registrations/default/<client id> 執行 HTTP DELETE 請求。

Keycloak 轉接器設定

installation 用戶端註冊提供者可用於檢索用戶端的轉接器設定。除了令牌驗證之外，您還可以使用 HTTP 基本驗證與用戶端憑證進行驗證。若要執行此操作，請在請求中包含以下標頭

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

若要檢索轉接器設定，請對 /realms/<realm>/clients-registrations/install/<client id> 執行 HTTP GET 請求。

公用用戶端不需要驗證。這表示對於 JavaScript 轉接器，您可以使用上述 URL 直接從 Keycloak 載入用戶端設定。

OpenID Connect 動態用戶端註冊

Keycloak 實作 OpenID Connect 動態用戶端註冊，它擴展了 OAuth 2.0 動態用戶端註冊協定 和 OAuth 2.0 動態用戶端註冊管理協定。

使用這些規範在 Keycloak 中註冊用戶端的端點為 /realms/<realm>/clients-registrations/openid-connect[/<client id>]。

此端點也可以在 realm 的 OpenID Connect Discovery 端點中找到，/realms/<realm>/.well-known/openid-configuration。

SAML 實體描述符

SAML 實體描述符端點僅支援使用 SAML v2 實體描述符來建立用戶端。它不支援檢索、更新或刪除用戶端。對於這些操作，應使用 Keycloak 表示法端點。建立用戶端時，會傳回 Keycloak 用戶端表示法，其中包含有關所建立用戶端的詳細資訊，包括註冊存取令牌。

若要建立用戶端，請對 /realms/<realm>/clients-registrations/saml2-entity-descriptor 執行 HTTP POST 請求，並使用 SAML 實體描述符。

使用 CURL 的範例

以下範例使用 CURL 建立用戶端 ID 為 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 目前支援兩種透過用戶端註冊服務註冊新用戶端的方式。

  • 已驗證的請求 - 註冊新用戶端的請求必須包含如上所述的 初始存取令牌 或 持有人令牌。

  • 匿名請求 - 註冊新用戶端的請求根本不需要包含任何令牌

匿名用戶端註冊請求是一個非常有趣且強大的功能，但是您通常不希望任何人都能不受任何限制地註冊新用戶端。因此，我們有 用戶端註冊原則 SPI，它提供了一種限制誰可以註冊新用戶端以及在哪些條件下的方法。

在 Keycloak 管理控制台中，您可以按一下 Client Registration 索引標籤，然後按一下 Client Registration Policies 子索引標籤。在這裡，您將看到預設為匿名請求設定的原則，以及為已驗證的請求設定的原則。

匿名請求（不包含任何令牌的請求）僅允許用於建立（註冊）新用戶端。因此，當您透過匿名請求註冊新用戶端時，回應將包含註冊存取令牌，該令牌必須用於特定用戶端的讀取、更新或刪除請求。但是，使用來自匿名註冊的此註冊存取令牌也將受到匿名原則的約束！這表示，例如，如果具有 Trusted Hosts 原則，則更新用戶端的請求也需要來自受信任的主機。此外，例如，當存在 Consent Required 原則時，不允許在更新用戶端時停用 Consent Required 等。

目前我們有以下原則實作

  • 信任主機政策 - 您可以設定信任主機和信任網域的列表。只有來自這些主機或網域的要求才能發送到用戶端註冊服務。來自不受信任 IP 的請求將被拒絕。新註冊用戶端的 URL 也必須僅使用這些信任的主機或網域。例如，不允許將用戶端的 Redirect URI 設定為指向某些不受信任的主機。預設情況下，沒有任何加入白名單的主機，因此實際上已停用匿名用戶端註冊。

  • 需要同意政策 - 新註冊的用戶端將啟用 允許同意 開關。因此，在成功身份驗證後，當使用者需要批准權限（用戶端範圍）時，將始終看到同意畫面。這表示，除非使用者批准，否則用戶端將無法存取任何個人資訊或使用者權限。

  • 協定對應器政策 - 允許設定加入白名單的協定對應器實作列表。如果新的用戶端包含某些未加入白名單的協定對應器，則無法註冊或更新該用戶端。請注意，此政策也適用於已驗證的要求，因此即使是已驗證的要求，也對可以使用哪些協定對應器存在一些限制。

  • 用戶端範圍政策 - 允許將 用戶端範圍 加入白名單，這些範圍可以用於新註冊或更新的用戶端。預設情況下，沒有加入白名單的範圍；只有定義為 領域預設用戶端範圍 的用戶端範圍才會預設加入白名單。

  • 完整範圍政策 - 新註冊的用戶端將停用 允許完整範圍 開關。這表示他們將不會擁有任何範圍的領域角色或其他用戶端的用戶端角色。

  • 最大用戶端數政策 - 如果領域中目前的用戶端數量與指定的限制相同或更大，則拒絕註冊。對於匿名註冊，預設值為 200。

  • 用戶端停用政策 - 新註冊的用戶端將被停用。這表示管理員需要手動批准並啟用所有新註冊的用戶端。即使是匿名註冊，預設也不會使用此政策。

本頁內容
編輯本指南