客户端注册服务

使用客户端注册服务

为了让应用程序或服务使用 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 角色的服务帐户的令牌（有关更多详细信息，请参阅 服务器管理指南）。

初始访问令牌

注册新客户端的推荐方法是使用初始访问令牌。初始访问令牌只能用于创建客户端，并且具有可配置的过期时间以及可配置的创建客户端数量限制。

可以通过管理控制台创建初始访问令牌。要创建新的初始访问令牌，请先在管理控制台中选择域，然后单击左侧菜单中的 Client，然后单击页面中显示的选项卡中的 Initial access token。

您现在将能够看到任何现有的初始访问令牌。如果您有权限，您可以删除不再需要的令牌。您只能在创建令牌时检索令牌的值。要创建新令牌，请单击 Create。您现在可以选择添加令牌的有效期，还可以添加使用令牌可以创建的客户端数量。单击 Save 后，将显示令牌值。

重要的是，您现在要复制/粘贴此令牌，因为您以后无法检索它。如果您忘记复制/粘贴它，请删除令牌并创建另一个令牌。

令牌值用作调用客户端注册服务时的标准承载令牌，方法是在请求中将其添加到授权标头中。例如

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 请求。

它还会返回一个新的注册访问令牌。

要更新客户端表示，请对以下地址执行 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)

要检索适配器配置，请对 /realms/<realm>/clients-registrations/install/<client id> 执行 HTTP GET 请求。

公共客户端不需要身份验证。这意味着对于 JavaScript 适配器，您可以直接从 Keycloak 使用上面的 URL 加载客户端配置。

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 客户端表示，其中包含有关已创建客户端的详细信息，包括注册访问令牌。

要创建客户端，请对 /realms/<realm>/clients-registrations/saml2-entity-descriptor 执行包含 SAML 实体描述符的 HTTP POST 请求。

使用 CURL 的示例

以下示例使用 CURL 创建一个名为 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<。

有关使用客户端注册的完整说明，请参阅 JavaDoc。以下是如何创建客户端的示例。您需要将 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 当前支持两种方式，通过客户端注册服务注册新客户端。

  • 经过身份验证的请求 - 注册新客户端的请求必须包含如上所述的 Initial Access Token 或 Bearer Token。

  • 匿名请求 - 注册新客户端的请求根本不需要包含任何令牌

匿名客户端注册请求是一个非常有趣且功能强大的功能，但是您通常不希望任何人能够在没有任何限制的情况下注册新客户端。因此，我们有 Client Registration Policy SPI，它提供了一种限制谁可以注册新客户端以及在哪些条件下注册新客户端的方式。

在 Keycloak 管理控制台中，您可以单击 Client Registration 选项卡，然后单击 Client Registration Policies 子选项卡。在这里，您将看到为匿名请求配置了哪些策略，以及为经过身份验证的请求配置了哪些策略。

匿名请求（没有任何令牌的请求）仅允许创建（注册）新客户端。因此，当您通过匿名请求注册新客户端时，响应将包含注册访问令牌，该令牌必须用于特定客户端的读取、更新或删除请求。但是，使用来自匿名注册的此注册访问令牌将受匿名策略约束！这意味着例如，如果存在 Trusted Hosts 策略，更新客户端的请求也需要来自受信任的主机。例如，它不允许在更新客户端时禁用 Consent Required，以及当存在 Consent Required 策略时等。

我们目前有以下策略实现

  • 受信任的主机策略 - 您可以配置受信任主机和受信任域的列表。仅可以从这些主机或域发送对客户端注册服务的请求。从某些不受信任的 IP 发送的请求将被拒绝。新注册客户端的 URL 也必须仅使用这些受信任主机或域。例如，不允许设置指向某些不受信任主机的客户端 Redirect URI。默认情况下，没有列入白名单的主机，因此匿名客户端注册实际上已禁用。

  • 同意必需策略 - 新注册的客户端将启用 Consent Allowed 开关。因此，在成功身份验证后，用户始终会在需要批准权限（客户端范围）时看到同意屏幕。这意味着客户端将无法访问任何个人信息或用户的权限，除非用户批准它。

  • 协议映射器策略 - 允许配置列入白名单的协议映射器实现列表。如果新客户端包含某些未列入白名单的协议映射器，则无法注册或更新该客户端。请注意，此策略也用于经过身份验证的请求，因此即使对于经过身份验证的请求，也有一些限制，即可以使用哪些协议映射器。

  • 客户端范围策略 - 允许将 Client Scopes 列入白名单，这些范围可用于新注册的或已更新的客户端。默认情况下，没有列入白名单的范围；默认情况下，仅将定义为 Realm Default Client Scopes 的客户端范围列入白名单。

  • 完整范围策略 - 新注册的客户端将禁用 Full Scope Allowed 开关。这意味着它们不会拥有任何范围的域角色或其他客户端的客户端角色。

  • 最大客户端策略 - 如果领域中当前的客户端数量等于或大于指定的限制，则拒绝注册。对于匿名注册，默认值为 200。

  • 客户端禁用策略 - 新注册的客户端将被禁用。这意味着管理员需要手动批准并启用所有新注册的客户端。即使对于匿名注册，此策略默认情况下也不会使用。

在本页
编辑本指南