客户端注册服务

使用客户端注册服务

为了使应用程序或服务能够使用 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)

以下章节将描述如何使用不同的 providers。

身份验证

要调用客户端注册服务，通常需要一个令牌。该令牌可以是 bearer token、initial access token 或 registration access token。还有另一种无需任何令牌即可注册新客户端的方法，但这需要配置客户端注册策略（见下文）。

Bearer token

Bearer token 可以代表用户或服务帐户颁发。调用端点需要以下权限（更多详情请参见 服务器管理指南）

  • create-client 或 manage-client - 用于创建客户端

  • view-client 或 manage-client - 用于查看客户端

  • manage-client - 用于更新或删除客户端

如果您使用 bearer token 创建客户端，建议使用来自仅具有 create-client 角色的服务帐户的令牌（更多详情请参见 服务器管理指南）。

Initial Access Token

注册新客户端的推荐方法是使用 initial access token。Initial access token 只能用于创建客户端，并且具有可配置的过期时间和可配置的客户端创建数量限制。

Initial access token 可以通过管理控制台创建。要创建新的 initial access token，首先在管理控制台中选择 realm，然后在左侧菜单中单击“Client”，然后在页面中显示的选项卡中单击“Initial access token”。

现在您将能够看到任何现有的 initial access token。如果您有权限，您可以删除不再需要的令牌。您只能在创建令牌时检索令牌的值。要创建新令牌，请单击“Create”。现在您可以选择添加令牌的有效期，以及可以使用该令牌创建多少个客户端。单击“Save”后，将显示令牌值。

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

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

Authorization: bearer eyJhbGciOiJSUz...

Registration Access Token

当您通过客户端注册服务创建客户端时，响应将包含 registration access token。Registration access token 提供稍后检索客户端配置的权限，以及更新或删除客户端的权限。Registration access token 的包含方式与 bearer token 或 initial access token 相同。

默认情况下，registration access token 轮换已启用。这意味着 registration access token 仅有效一次。当令牌被使用时，响应将包含一个新令牌。请注意，可以使用 客户端策略 禁用 registration access token 轮换。

如果客户端是在客户端注册服务之外创建的，则它不会有关联的 registration access token。您可以通过管理控制台创建一个。如果您丢失了特定客户端的令牌，这也可能很有用。要创建新令牌，请在管理控制台中找到客户端，然后单击“Credentials”。然后单击“Generate registration access token”。

Keycloak 表示

default 客户端注册 provider 可用于创建、检索、更新和删除客户端。它使用 Keycloak 客户端表示格式，该格式支持完全按照通过管理控制台配置客户端的方式配置客户端，例如，包括配置协议映射器。

要创建客户端，请创建客户端表示 (JSON)，然后对 /realms/<realm>/clients-registrations/default 执行 HTTP POST 请求。

它将返回一个客户端表示，其中还包括 registration access token。如果您想稍后检索配置、更新或删除客户端，则应将 registration access token 保存在某处。

要检索客户端表示，请对 /realms/<realm>/clients-registrations/default/<client id> 执行 HTTP GET 请求。

它还将返回一个新的 registration access token。

要更新客户端表示，请使用更新后的客户端表示对 /realms/<realm>/clients-registrations/default/<client id> 执行 HTTP PUT 请求。

它还将返回一个新的 registration access token。

要删除客户端表示，请对 /realms/<realm>/clients-registrations/default/<client id> 执行 HTTP DELETE 请求

Keycloak 适配器配置

installation 客户端注册 provider 可用于检索客户端的适配器配置。除了令牌身份验证之外，您还可以使用 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>]。

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

SAML 实体描述符

SAML 实体描述符端点仅支持使用 SAML v2 实体描述符创建客户端。它不支持检索、更新或删除客户端。对于这些操作，应使用 Keycloak 表示端点。创建客户端时，将返回 Keycloak 客户端表示，其中包含有关已创建客户端的详细信息，包括 registration access token。

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

使用 CURL 的示例

以下示例使用 CURL 创建 clientId 为 myclient 的客户端。您需要将 eyJhbGciOiJSUz…​ 替换为正确的 initial access token 或 bearer token。

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…​ 替换为正确的 initial access token 或 bearer token。

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”子选项卡。在这里，您将看到默认情况下为匿名请求配置了哪些策略，以及为身份验证请求配置了哪些策略。

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

目前我们有以下策略实现

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

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

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

  • 客户端 Scope 策略 - 允许将 Client Scopes 列入白名单，这些 Client Scopes 可以与新注册或更新的客户端一起使用。默认情况下，没有列入白名单的 scope；默认情况下，只有定义为“Realm Default Client Scopes”的客户端 scope 列入白名单。

  • 完全 Scope 策略 - 新注册的客户端将禁用“Full Scope Allowed”开关。这意味着它们将不具有任何 scope 的 realm 角色或其他客户端的客户端角色。

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

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

在此页
编辑本指南