什么是 Keycloak？如何一步步安装它？

最后更新： 08/01/2026
作者： 艾萨克
  • Keycloak 是一个开源身份提供商，它使用 OAuth 2.0、OpenID Connect 和 SAML 为多个应用程序集中进行身份验证、授权和 SSO。
  • 其领域、用户、组和角色模型允许灵活管理身份和权限，包括与 LDAP、Active Directory 或 Azure AD 等外部目录进行联合。
  • 它可以部署在 Docker、Kubernetes 或机器上。 Linux 使用 PostgreSQL，并通过反向代理和负载均衡器（如 Nginx 和 Keepalived）实现高可用性扩展。
  • Keycloak 颁发的 JWT 令牌可以使用映射器进行自定义，从而实现易于集成到现代 API 和应用程序中的精细安全模型。

Keycloak身份和访问管理

几乎在你每天使用的任何现代应用程序中 （电子邮件、社交媒体、企业内网、客户仪表盘等等）在后台，有一个系统决定着你的身份以及你可以访问哪些内容。当公司开始积累大量的应用程序、服务和API时，手动管理用户、密码、权限和会话就成了一件非常棘手的事情。

Keycloak及时出现，解决了这场混乱。Keycloak 是一个身份和访问管理平台，它集中管理多个应用程序的身份验证、授权和单点登录。无需每个应用程序自行实现登录、角色和密码恢复系统，Keycloak 会处理所有这些事务，应用程序只需使用 OAuth 2.0、OpenID Connect 或 SAML 2.0 等标准信任它即可。

Keycloak是什么？它在身份和访问管理（IAM）安全中扮演什么角色？

Keycloak 是一个开源的身份提供商 (IdP)。该软件采用 Java 编写，由 Red Hat（前身为 JBoss）维护，并以 Apache 2.0 许可证发布，因此即使在商业环境中也可以免费使用和修改。虽然存在名为 Red Hat Single Sign-On 的付费企业级版本，但其核心功能相同。

此身份服务器提供单点登录、联合身份验证和多租户功能。它允许用户登录一次并访问多个应用程序，这些应用程序将身份验证委托给 Keycloak，用户、组、属性和权限的管理集中完成，而无需在每个项目中重新实现相同的功能。

Keycloak 在其他身份和访问管理 (IAM) 解决方案中脱颖而出。 选择解决方案时，应考虑其成熟度、普及程度以及与标准协议的兼容性（免费、开源或专有）。即便如此，每个组织的最佳解决方案仍取决于其具体需求（商业支持、服务级别协议、特定功能、本地部署还是SaaS部署等）。

Keycloak 的优势之一 它结合了多个组件：基于 OAuth 2.0 和 OpenID Connect 的身份验证、SAML 2.0 支持、社交登录（Google, Facebook（例如 GitHub 等），与 LDAP 和 Active Directory 集成，通过 Web 控制台、CLI 和 REST API 进行管理，以及灵活的用户、组和角色模型，这些模型反映在为应用程序颁发的令牌中。

Keycloak 服务器和连接的应用程序

必备基础知识：OAuth 2.0、OpenID Connect 和 JWT

要充分理解 Keycloak 的功能，首先需要明确三个概念。OAuth 2.0、OpenID Connect (OIDC) 和 JSON Web Tokens (JWT)。你不需要成为专家，但你需要了解基本概念，因为一切都围绕它们展开。

OAuth 2.0 作为一种授权框架

OAuth 2.0 是一个标准的 API 授权框架它被谷歌、Facebook、微软、GitHub 和 LinkedIn 等巨头广泛使用，其主要功能是允许应用程序（客户端）在获得用户明确许可的情况下，访问用户在另一个应用程序或 API 中的资源，而无需不断共享凭据。

无需在每次请求中发送用户名和密码OAuth 2.0 引入了访问令牌的概念：一种有效期很短的访问令牌，通过 HTTP 调用发送到 API 并由 API 进行验证。身份提供商（例如 Keycloak）在验证用户身份和授权后颁发此令牌。

该标准定义了几种授权流程（授权类型）。 根据客户端类型调整流程：安全后端应用程序、基于浏览器的单页应用程序 (SPA) 应用 移动设备、受限设备、机器对机器通信等。每个流程都标记了每个步骤中交换的内容（授权码、令牌、凭证等）。

OAuth 2.0 的四个基本角色 是：

  • 资源所有者：通常是指您想要查阅或修改其数据的用户。
  • 客户应用程序（网页、移动端、 IoT（后端……）想要代表用户执行操作。
  • 资源服务器：公开数据并验证访问令牌的 API。
  • 授权服务器：对用户进行身份验证并颁发令牌的身份提供商（Keycloak）。

此外，OAuth 2.0 引入了作用域的概念。这些定义了用户授予应用程序的权限范围：读取电子邮件、在社交网络上发帖、访问基本个人资料等。颁发的令牌编码了实际授予客户端的权限。

OpenID Connect：OAuth 2.0 之上的身份层

OpenID Connect (OIDC) 为 OAuth 2.0 添加身份验证功能OAuth 处理的是授权（应用程序可以做什么），而 OIDC 处理的是以标准化的方式识别已认证用户的身份以及如何获取其基本数据。

  隐藏 IP 地址的 9 种方法

OIDC 定义了众所周知的端点和元数据例如，在路线上发布的发现文件 /.well-known/openid-configuration 其中，提供商指定授权 URL、令牌、公钥、用户信息等。这使得应用程序几乎可以自动配置。

它还提供了 UserInfo 端点。此功能用于使用有效的访问令牌从已认证用户（姓名、电子邮件等）检索信息。在基于 Keycloak 的集成中，通常会在登录后读取这些数据，以填充应用程序中的用户个人资料。

访问令牌和 JSON Web 令牌 (JWT)

在许多现代实现中，access_token 是一个 JWT。 （JSON Web Token）。这是一个标准（RFC 7519），用于将声明表示为数字签名的 JSON，分为三个部分，以句点分隔：标头、有效负载和签名，全部以 Base64URL 编码。

头部信息包含有关令牌的技术信息。 （签名算法、令牌类型，以及通常使用的密钥标识符， kid有效载荷包含以下声明，例如：

  • EXP： 截止日期。
  • IAT：播出时间。
  • 国际空间站：发卡方，通常是身份提供商 URL。
  • 分：唯一用户标识符。
  • 澳元代币的目标受众。
  • JTI：令牌的唯一标识符。

签名是用私钥或秘密密钥生成的。因此，对令牌的任何修改都会破坏签名，并在验证过程中被检测到。API 通过该属性从身份提供商 (IdP) 获取公钥。 jwks_uri 根据发现文档，该文档指向一个 JSON 文件，其中包含公钥列表及其 kid.

Keycloak还允许自定义颁发的令牌。可以根据用户属性、用户组、用户角色，甚至固定值添加额外的声明。这是通过为每个客户端或客户端范围配置的映射器实现的，从而使 API 能够轻松获取所需的确切信息。

OAuth2 OpenID Connect 和 JWT 架构

Keycloak架构：领域、用户、组和角色

Keycloak 在 Realms 中组织其配置这些就像单个安装环境中的“虚拟身份服务器”。其他厂商将类似的东西称为租户或目录。每个域都有自己独立的用户、组、客户端、策略和设置。

默认情况下，存在一个名为 master 的特殊领域。此账号应仅用于全局管理任务，例如创建和管理其他服务器。管理员用户可以从同一控制台管理多个服务器，而无需为每个服务器使用不同的账号登录。

本地用户可以在一个领域内定义。通过分配自定义属性、分组以及将对象与角色关联，该模型经过精心设计，确保相关信息最终能够反映在应用程序使用的令牌中（角色、组、配置文件数据、安全标志等）。

群组允许用户按层级结构进行组织。一个群组可以拥有子群组（子群组），用户继承其所属所有群组（包括其父群组）的属性和角色。这使得授权模型非常灵活，无需为每个用户重复配置。

就角色而言，主要分为两个层级。:

  • 领域角色：领域内的全局变量，常用于跨属性权限。
  • 客户角色：针对特定应用程序，允许对每项服务进行精细控制。

Keycloak 支持复合角色也就是说，角色之间可以包含其他角色。这有助于对权限进行分组，并一次性将所有权限分配给用户或用户组，但最好不要过度使用此功能，以免使管理复杂化或影响性能。

在开发模式下安装 Keycloak：Docker、Kubernetes 和虚拟机

使用 Keycloak 设置实验室环境 有几种简单的选择：Docker 容器、在 Kubernetes 上部署（例如使用 Minikube）或在具有 Linux 和 OpenJDK 的虚拟机上进行经典安装。

Docker 中的 Keycloak

启动 Keycloak 进行测试的最快方法 这包括运行一个使用官方镜像的容器，暴露 8080 端口，并通过环境变量传递管理员用户名和密码，然后启动进入模式。 start-dev （不使用 HTTPS，并嵌入 H2 数据库）：

只需一条 Docker 命令 获得了一台功能齐全的服务器 http://localhost:8080足以对管理控制台进行调整，创建领域、用户、客户端并测试基本集成。

在 Kubernetes 中使用 Minikube 部署 Keycloak

如果您已经在使用 Kubernetes，则可以轻松部署 Keycloak。 使用官方存储库中的示例清单，您可以创建一个 Deployment 和一个 Service，然后使用 Minikube 打开一个隧道，以便从您的机器访问该服务，通常也是通过 8080 端口。

  CPI 文件 – 定义、特征、用途、兼容程序

这种方法非常适合模拟更接近生产环境的情况。 （包括 pod、服务、外部配置等）并尝试在 K8s 集群上对 Keycloak 进行受控部署、扩展和升级。

在 Ubuntu 上使用 OpenJDK 和 PostgreSQL 的 Keycloak（高级开发模式）

另一种方法是在 Ubuntu 虚拟机上安装 Keycloak。 使用 OpenJDK 和本地 PostgreSQL 数据库，并配置了自签名证书和自定义主机名。虽然目前仍处于测试阶段，但已越来越接近生产环境。

典型步骤包括:

  • 更新操作系统并安装 Java（例如，OpenJDK 11 或更高版本）。
  • 安装 PostgreSQL（理想情况下安装在单独的服务器上，但在实验室环境中可以安装在同一台机器上）。
  • 为 Keycloak 创建特定用户和数据库，并授予相应的权限。
  • 创建一个没有权限的系统用户（例如， keycloak）运行该服务。
  • 下载官方 Keycloak 发行版，并将其解压缩到 /opt/keycloak 并调整权限。
  • 使用以下命令生成自签名 X.509 证书 openssl的 并设置在 keycloak.conf 以及PostgreSQL连接参数和 hostname 期望。
  • 定义一个单位 systemd 要在系统启动时以开发模式启动 Keycloak，请通过环境变量设置管理员凭据。

服务启动并运行后通常情况下，可以通过配置的主机名，使用 8443 端口上的 HTTPS 协议进行访问。如果使用自签名证书，则需要在浏览器中信任该证书（通过将 CA 或证书本身导入到计算机的受信任证书存储区中）。

Keycloak的安装和部署

高级部署：高可用性、PostgreSQL 和反向代理

当我们从实验室走向生产时情况发生了变化：你必须考虑高可用性、强大的数据持久性、有效的证书，而且通常还需要一个集中管理 HTTPS 访问和负载均衡的反向代理。

一种相当常见的模式是部署多个 Keycloak 节点 系统部署在负载均衡器（例如 Nginx）之后，并使用高可用性 (HA) 模式的 PostgreSQL 数据库作为持久化后端。目标是消除应用层和数据层的单点故障。

在这种架构中，通常会遵循以下步骤：:

  • 准备已更新的Linux服务器（Debian/Ubuntu）并安装依赖项： unzip, wget, openjdk, openssl等等。
  • 创建系统用户 keycloak 拥有家 /opt/keycloak 且不具备特权交互式登录权限。
  • 下载所需版本的 Keycloak，解压缩，并将所有权分配给指定用户。
  • 在 PostgreSQL 中创建一个特定的数据库，并设置相应的用户和权限，同时调整模式所有者和表的默认权限。
  • 为 Keycloak 节点生成自签名证书（或使用来自内部 CA 的证书），并在应用程序服务器上配置 HTTPS。
  • 正义者 keycloak.conf 要连接到 PostgreSQL VIP，请定义 HTTP/HTTPS 端口、证书、代理参数、主机名、集群堆栈（例如 UDP）和日志级别。
  • 定义一项服务 systemd 简单的 引导 钥匙斗篷 kc.sh start o kc.sh start --optimized管理故障时的自动重启。

Nginx 通常部署在发布和负载均衡层之上。 作为 HTTPS 反向代理，它有自己的 TLS 证书和指向其后端端口（如果 TLS 在 Nginx 中终止，则通常为 8080）上 Keycloak 节点的上游配置。

为了消除平衡器中的单点故障使用 Keepalived 配置两个 Nginx 节点以实现高可用性是一种常见做法。该工具管理一个浮动虚拟 IP (VIP)，该 IP 地址会通告给其中一台服务器作为主节点，并在主节点发生故障时切换到备用节点，从而保持服务连续性。

设置领域、用户和应用程序（客户端）注册

一旦 Keycloak 启动并运行起来，下一步合乎逻辑的做法就是 它涉及为我们的用户和应用程序创建一个领域，并从中定义用户、组、角色和客户端（将身份验证委托给 Keycloak 的应用程序）。

通过管理控制台创建一个新的领域。 只需输入它的名称即可。从那时起，我们将拥有一个独立的空间，并拥有自己的设置。在最初的调整中，以下几项通常很有用：

  • 配置 SMTP 以发送电子邮件（电子邮件验证、密码恢复、通知）。
  • 根据需要启用 声明式用户配置文件它允许您以声明的方式定义用户将拥有哪些属性、应用哪些验证以及用户是否可以编辑这些属性。
  • 调整登录参数：允许或禁止自助注册、记住浏览器重启后的会话、允许密码恢复等。

在域中创建用户就像填写表单一样简单。 您需要提供用户名、电子邮件地址、姓名（包括姓和名）。然后，您可以在“凭据”选项卡中设置密码（临时密码或永久密码）。之后，您可以分配组、角色和其他属性。

  修复 TSL 握手失败错误

Keycloak 为最终用户提供专用的帐户控制台。用户可在此处查看和修改个人资料、更改密码、查看活动会话或管理其他身份验证因素。这是一种非常便捷的方式，可以将一些基本的帐户管理操作委托给用户。

冒充是另一个有趣的特性。拥有权限的管理员可以从控制台“模拟”用户，以重现问题、验证权限等，而无需用户的密码。

要使用 Keycloak 作为身份提供商 (IdP) 的应用程序必须将其注册为客户端。在“客户端”部分，创建一个新的客户端 ID，类型指定为 OpenID Connect（除非要使用 SAML），并选择允许的 OAuth 2.0 流程：标准流程（授权码）、直接访问授权（密码）、隐式授权、客户端凭据（服务帐户）、设备代码、CIBA 等。

客户端配置也决定了这一点。 如果需要客户端身份验证（客户端密钥或证书），则需要确定哪些重定向 URI 有效，以及允许哪些 Web 源（这在单页应用程序 (SPA) 中尤为重要，因为存在 CORS 策略）。之后，应用程序可以使用官方或第三方库，通过 OIDC 将身份验证委托给 Keycloak。

与外部目录和其他身份提供商集成

Keycloak 可以作为本地身份源。 （在其自身数据库中定义的用户、组和角色）或者它可以充当一个或多个外部提供商的身份代理。

一种非常常见的集成方式是与 Azure Active Directory 集成。Azure AD 存储企业用户和组，Keycloak 作为 OIDC 客户端连接以下载身份和组，并将它们映射到本地用户和角色。这样可以避免跨多个站点重复创建身份和管理任务。

一般来说，要使用 Azure AD 作为外部身份提供商 (IdP) 完成以下工作：

  • 在 Azure AD 中注册应用程序，获取其客户端 ID 并创建客户端密钥。
  • 在 Azure AD 中配置重定向 URI 到 Keycloak（相应域中的 OIDC 代理终结点）。
  • 调整 Azure AD 应用程序中令牌中将颁发的声明，例如，通过包含用户组。
  • 在 Keycloak 中，创建一个指向 Azure 终结点（授权、令牌、注销、用户信息）的 OpenID Connect 身份提供程序，并配置客户端 ID、客户端密钥和所需的登录参数。

一旦他们之间建立了信任当用户通过 Azure AD 登录时，Keycloak 会在本地创建（或同步）该用户，并可以使用高级映射器将 Azure 组映射到 Keycloak 角色。例如，Azure 中的“开发人员”组可以转换为 Keycloak 中的“开发人员”角色，然后将该角色部署到集成的应用程序和服务（例如 Jenkins）。

除了 Azure AD，Keycloak 还支持与以下系统进行身份联合： LDAP、经典 Active Directory、其他 OIDC IdP、社交提供商（Google、Facebook、GitHub 等）等等，能够在同一领域内同时混合多个来源。

额外的安全措施：机器人、验证码和最佳实践

尽管 Keycloak 大大增强了身份验证安全性 （多因素身份验证、密码策略、帐户锁定、会话控制等），登录、注册和密码恢复页面仍然是机器人和自动化攻击的明显目标。

为了减轻这类威胁建议将 Keycloak 与反机器人机制（例如符合 GDPR 标准的 CAPTCHA 解决方案）结合使用，这些方案能够在不影响用户体验的前提下区分人类流量和自动化流量。这些解决方案通常集成到登录和注册表单中，从而增加一层额外的防御，防止撞库攻击、批量创建账户或滥用密码恢复流程。

除了验证码之外，其他良好做法还包括 监控 日志 对于访问权限，设置失败尝试异常激增的警报，定期审查已颁发的令牌及其有效期，确保只有必要的端点暴露给外部，并使 Keycloak 及其依赖项保持最新安全补丁的更新。

整个功能生态系统 （SSO、多租户、与外部目录集成、可配置令牌、高可用性部署和机器人保护）使 Keycloak 成为集中管理现代应用程序身份验证和授权的非常强大的工具，帮助公司在不牺牲用户体验或不断重新发明身份管理的情况下加强其安全态势。