自定义 Keycloak 的登录页面

1、概览

Keycloak 是第三方授权服务器，用于管理 Web 或移动应用的身份验证和授权。它为用户提供了一个默认的登录页面。

本文将带你了解如何自定义 Keycloak 服务器的登录页面。

本文在 《自定义 Keycloak 主题》 基础上进行实现。

2、独立 Keycloak 服务器

继续以 custom 主题为例，先看看独立服务器。

2.1、管理控制台设置

进入 Keycloak 目录，然后在 bin 文件夹中运行如下命令，启动服务器：

kc.[sh|bat] start-dev --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false

使用上述命令启动服务器后，只需刷新页面，就能看到更改。

现在，在 themes/custom 目录中新建一个名为 login 的文件夹。为了简单起见，先将 themes/keycloak/login 目录中的所有内容复制到这里。这是默认的登录页面主题。

然后，进入管理控制台（http://localhost:8080/admin/master/console），使用 initial1/zaq1!QAZ 凭证登录，并进入 Realm 的 “Themes” 选项卡：

为 Login Theme 选择 custom，然后保存更改。

现在就可以尝试一些自定义功能了。不过在此之前，先来看看默认登录页面：

2.2、添加自定义内容

现在，假设我们需要更改背景。

打开 login/resources/css/login.css 并更改 class 定义：

.login-pf body {
    background: #39a5dc;
    background-size: cover;
    height: 100%;
}

刷新页面即可看到效果：

接下来，尝试更改用户名和密码的标签。

为此，需要在 theme/login/messages 文件夹中创建一个新文件 messages_en.properties。该文件中的属性将覆盖 Message Bundle 中的默认属性：

usernameOrEmail=Enter Username:
password=Enter Password:

再次刷新页面，查看效果：

如果我们想更改整个 HTML 或其中的一部分，则需要覆盖 Keycloak 默认使用的 freemarker 模板。登录页面的默认模板保存在 base/login 目录中。

比方说，我们想用 WELCOME TO BAELDUNG 代替 SPRINGBOOTKEYCLOAK。

为此，需要将 base/login/template.ftl 复制到 custom/login 文件夹。

在复制的文件中，把下面一行：

<div id="kc-header-wrapper" class="${properties.kcHeaderWrapperClass!}">
    ${kcSanitize(msg("loginTitleHtml",(realm.displayNameHtml!'')))?no_esc}
</div>

改为：

<div id="kc-header-wrapper" class="${properties.kcHeaderWrapperClass!}">
    WELCOME TO BAELDUNG
</div>

现在，登录页面显示的是我们的自定义信息，而不是 Realm 名称。

3、嵌入式 Keycloak 服务器

首先，将在独立服务器中更改的所有文件添加到嵌入式授权服务器的源代码中。

在 src/main/resources/themes/custom 中创建一个包含这些内容的新文件夹 login：

现在需要做的就是在 Realm 定义文件 baeldung-realm.json 中添加指令，以使用 custom 作为登录主题类型：

"loginTheme": "custom",

由于已经配置了 “重定向到 custom 主题目录”，服务器已经知道从哪里获取登录页面的主题文件。

点击登录页面，测试效果：

如你所见，之前为独立服务器所做的所有定制，如背景、标签名称和页面标题，都会在这里出现。

4、绕过 Keycloak 登录页面

从技术上讲，我们可以通过使用 密码或直接访问授权 模式完全绕过 Keycloak 登录页面。不过，强烈建议不要使用这种授权模式。

在这种情况下，没有中间步骤获取授权码，然后交换获得 Access Token。相反，可以通过 REST API 调用直接发送用户凭据，并在响应中获取 Access Token。

这实际上意味着，可以使用登录页面来收集用户的 ID 和密码，并连同客户端 ID 和 secret，通过 POST 发送到 Keycloak 的 token 端点。

Keycloak 已经提供了丰富的登录选项功能，如记住我、密码重置和 MFA 等，因此几乎没有理由绕过它。

5、总结

本文介绍了如何更改 Keycloak 的默认登录页面并添加自定义设置。

Ref：https://www.baeldung.com/keycloak-custom-login-page