Keycloak 介绍与选型指南

Keycloak 软件概述、核心架构、功能特性与 30 分钟上手路径，附 Authentik/Authelia/Auth0 实查选型对比。

KeycloakKeycloak2026/10/17

Keycloak 介绍与选型指南

‍‍​​‌​> 目标：面向"要不要用 Keycloak、怎么快速跑起来"的决策场景，给出 Keycloak 的软件定位、核心架构、功能清单、30 分钟上手路径与同代方案（Authentik / Authelia / Auth0）的选型对比，对比数据以 GitHub 实查与本机实测为准。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64，内核 6.8.0-138-generic）
  • Java：OpenJDK 21.0.12.1+1-LTS（Keycloak 26 要求 JDK 21）
  • Keycloak：26.8.1（官方发行包安装路径 /opt/keycloak）
  • 对比数据口径：GitHub API 实查（2026-10-17）、本机实测（dev 与 Postgres 两种形态各采一次内存占用）
  • 服务地址：http://localhost:8080（dev 模式默认端口）

二、软件概述

2.1 定位与发展沿革

Keycloak 是一个面向现代应用的开源身份认证与访问管理（IAM/SSO）软件：它把"用户登录、单点登录、权限角色、外部身份源联邦"这些每个应用都要做但都不该重复做的事，收敛为一个独立部署的服务。应用通过 OIDC（OpenID Connect）、OAuth 2.0 或 SAML 2.0 与它对接，用户只需在 Keycloak 登录一次，即可访问所有接入的应用。

关键节点：2014 年由 Red Hat 发起；2023 年从 Red Hat 交由 CNCF 托管（云原生计算基金会沙箱项目），社区治理与厂商中立性得到制度保障；2024 年起发布节奏固定为每月一个小版本，当前主线为 26.x（本专栏实测版本 26.8.1）；26.x 时代的服务形态为 Quarkus 底座的单二进制 + 独立管理接口（9000 端口）+ Hostname v2 配置语义。

2.2 版本与生态实测

版本核验（官方发行包自带的版本命令）：

/opt/keycloak/bin/kc.sh --version

实测回显：

Keycloak 26.8.1
JVM: 21.0.12.1 (Red Hat, Inc. OpenJDK 64-Bit Server VM 21.0.12.1+1-LTS)
OS: Linux 6.8.0-138-generic amd64

发行包实测：官方下载地址形如 https://github.com/keycloak/keycloak/releases/download/26.8.1/keycloak-26.8.1.tar.gz，本机实测下载文件 166MB、sha256sum 校验值 4e2740b181faa2ea623a1c2ecf00855935311e546046e2f857615a47ed24cbe8；发行包内含优化后的运行时（自带启动脚本 bin/kc.sh、默认配置 conf/keycloak.conf），安装解压即可用。

三、核心架构

3.1 Realm（域）：多租户的顶层边界

Realm 是最顶层的隔离单位，一个 Realm 拥有独立的用户库、客户端、角色、会话与签名密钥。安装即有 master 域（管理员专用），业务用户与业务应用放自建 Realm。Realm 之间彻底隔离：A 域签发的 token 在 B 域会被直接拒绝（实测同域 200 / 跨域 401 的对照见《Keycloak 核心原理详解》3.1）。

3.2 Client（客户端）：接入应用的注册表

Client 是"一个接入 Keycloak 的应用或服务"在 Keycloak 侧的注册项，携带回调地址、协议（openid-connect/saml）、公开/机密类型、授权流程开关等属性。实测创建一个公开客户端（Admin API 请求体核心字段）：

{"clientId":"quzuo-app","enabled":true,"protocol":"openid-connect","publicClient":true,"standardFlowEnabled":true,"directAccessGrantsEnabled":true,"redirectUris":["http://localhost:8080/callback"]}

实测回显：

HTTP/1.1 201 Created
Location: http://localhost:8080/admin/realms/quzuo-demo/clients/010343a9-ae98-4d69-b445-2d2f1d6aa626

类型约定：前端应用（SPA/移动）用公开客户端（publicClient=true，配 PKCE）；有后端的服务用机密客户端（凭 client_secret）；纯服务间调用再开服务账号（serviceAccountsEnabled）。

3.3 Role 与 Role Mapping：权限的载体

角色分两层：Realm 角色（域级，如 viewer）与 Client 角色（挂在特定客户端下，如 order-reader）。角色映射到用户后直接写入签发的 token（realm_access.roles / resource_access.<client>.roles），资源服务读 token 即可鉴权，无需回查。实测给用户分配 realm 角色后核对映射：

curl -s "http://localhost:8080/admin/realms/quzuo-demo/users/9e863c96-f97b-4d9c-989e-3088a72a8ae0/role-mappings/realm" \
  -H "Authorization: Bearer $AT" \
  | python3 -c 'import sys,json;[print(r["name"]) for r in json.load(sys.stdin)]'

实测回显：

default-roles-quzuo-demo
viewer

💡 说明：default-roles-quzuo-demo 是域默认角色组合（含 offline_access、uma_authorization 等），每个域自动生成、新用户自动携带。角色、组、属性三者可以叠加使用——组承担组织归属，角色承担权限语义，属性承担自由扩展声明。

3.4 Identity Brokering：身份联邦与协议转换

Keycloak 可以把"别的 IdP"当作自己的登录源，这是它区别于简单认证库的核心能力：社交登录（GitHub/Google 等 OIDC 登录源）、企业目录（LDAP/AD 用户联合，用户仍在目录里、密码不在 Keycloak 里）、SAML/OIDC 身份源互转（把上游 SAML IdP 包装成自己的 OIDC 能力，反之亦然）。用户首次经上游登录时，Keycloak 自动建档并可按规则合并既有账号——对存量用户表的应用而言，这是"不迁移密码也能上 SSO"的关键路径。

3.5 存储与持久化

开箱支持 H2 文件库（开发用）；生产配置 PostgreSQL、MySQL/MariaDB、Oracle、MSSQL 等关系库（--help 实测可选值：dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb）。库结构由 Keycloak 自动创建与迁移，升级版本无需手工改表。

💡 技术拓展：用户存储的三种形态对比——

形态原理/特点适用场景
内置库用户落 Keycloak 自己的库，管理最顺新建用户体系
LDAP/AD 联合用户仍在目录，Keycloak 按需拉取/缓存企业存量目录
自定义 UserStorage SPI写插件对接任意用户库特殊遗留系统

三者可并存于同一域，登录时按联合优先级匹配。

四、功能特性

4.1 认证与协议

  • 协议全：OIDC 授权码（含 PKCE）、client_credentials、refresh、device flow、SAML 2.0（IdP 与 SP 双角色）、OAuth 2.0 token 交换——两代 SSO 协议一网打尽（各流程实测见《Keycloak 核心原理详解》）。
  • 认证编排：浏览器流、直接授权流、重置凭证流均可按步骤编排，内置密码/OTP/恢复码/WebAuthn，可插拔自定义 Authenticator。
  • SSO 与登出：域级单点登录、单点登出（登出即撤会话，实测旧 token 立即 401）。

4.2 用户管理

用户全生命周期（建档/资料/凭证/组/角色）、密码策略（长度/复杂度/黑名单等可组合）、邮箱验证、临时密码（首登强制改密）、required actions（首登二步验证绑定等）、账号自助服务（Account Console，用户自己改密码/管会话）。

4.3 集成与扩展

Identity Brokering（见 3.4）、细粒度授权（Authorization Services：资源/策略/权限模型，支持 UMA 2.0）、Admin REST API（全功能管理面，实测见《Keycloak Admin API 使用详解》）、SPI 扩展（自定义 Authenticator/协议映射/事件监听等）、事件审计（登录/管理事件可落日志或外发）。

4.4 管理面与运维

Web 管理控制台（Admin Console）与 REST API 完全等价；kc.sh 子命令体系（build/start/export/import/show-config）；管理接口独立端口（9000）与业务端口隔离（26.x 默认设计）；生产模式启动硬校验（hostname/TLS/数据库三关），把配置错误拦在启动阶段。

五、快速开始

5.1 下载与安装

下载官方发行包（26.8.1，约 166MB），解压到 /opt/keycloak：

wget https://github.com/keycloak/keycloak/releases/download/26.8.1/keycloak-26.8.1.tar.gz
sha256sum keycloak-26.8.1.tar.gz
tar -xzf keycloak-26.8.1.tar.gz -C /opt && mv /opt/keycloak-26.8.1 /opt/keycloak

实测回显（校验值）：

4e2740b181faa2ea623a1c2ecf00855935311e546046e2f857615a47ed24cbe8  keycloak-26.8.1.tar.gz

5.2 启动 dev 模式

export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD=q1w2e3r4
/opt/keycloak/bin/kc.sh start-dev

实测回显（节选，约 10 秒就绪）：

Keycloak 26.8.1 on JVM (powered by Quarkus 3.40.1) started in 9.394s. Listening on: http://0.0.0.0:8080

5.3 验证与管理台登录

curl -s -o /dev/null -w 'root HTTP %{http_code}\n' http://localhost:8080/
curl -s -o /dev/null -w 'console HTTP %{http_code}\n' http://localhost:8080/admin/master/console/

实测回显：

root HTTP 302
console HTTP 200

浏览器打开 http://localhost:8080/admin/，用 admin / q1w2e3r4 登录管理控制台，即可开始建域、建客户端、建用户。后续深度动作（realm/client/用户/角色与各协议流程）的逐步实测见本专栏其余篇目。

六、适用场景与限制

6.1 适用场景

  • 多应用统一登录：一批内部/对外应用要一次登录到处可用，且协议混合（新应用 OIDC、遗留系统 SAML）；
  • 企业身份联邦：已有 LDAP/AD 或上游 IdP，要做身份聚合与协议转换；
  • B2B/租户化 SaaS：按租户（Realm）隔离用户与应用，一套部署服务多客户；
  • 需要细粒度授权：除登录外还要资源级/策略级授权（Authorization Services）。

6.2 限制与成本

  • Java 底座资源底线：JVM 堆 + 元空间决定了它比轻量网关型组件更"重"，小内存机器需要调优 JVM 参数（本机实测常驻内存约 370–410MiB，见 7.3）；
  • 生产配置硬校验：hostname/TLS/数据库三关缺一不可（真实报错：hostname is not configured、Key material not provided to setup HTTPS），首次生产化部署有学习成本；
  • HTTP 语义收缩：26.x Hostname v2 取代了大量旧版 hostname/proxy 参数，旧文档抄来的配置会静默失效，升级需对照官方迁移说明；
  • 管理端口独立：健康/指标在 9000 端口，负载均衡探活配置要跟着改；
  • 定制化要走 SPI：深度定制（自定义登录步骤、协议映射）需要写 Java 扩展并随版本维护。

6.3 上手成本与排查清单

对中小团队，建议把以下三件事纳入上线前清单：固定版本号并写明升级策略（每月小版本节奏）；生产三关（hostname/TLS 证书/持久库）在预发环境先打通一遍；管理员账号与 bootstrap 变量治理（引导变量仅在 master 域首建时生效）。做完这三件事，后续维护成本主要是常规版本升级与监控巡检。

七、选型对比

7.1 四个候选画像

  • Keycloak：功能最全的开源 IAM（CNCF 托管），OIDC/SAML 双协议 + 身份联邦 + 细粒度授权，Java 生态，社区与文档最厚，适合当"组织级认证中枢"。
  • Authentik：Python/Django 实现的全功能 IAM，UI 现代化，自带 RADIUS/代理模式等特色协议面，多组件部署相对更重，社区活跃度高。
  • Authelia：Go 单二进制的轻量认证网关，主打"反向代理伴随认证"，无用户管理后台（用户来自 YAML/LDAP），适合个人与小团队保护内网服务。
  • Auth0：Okta 旗下商业 SaaS IAM，开箱即用、全球接入、合规资质齐全，按 MAU 计费，适合不想自托管且预算充足的团队。

7.2 对比总表

维度KeycloakAuthentikAutheliaAuth0
许可（GitHub 实查）Apache-2.0其他-非开源（GNU AGPLv3）Apache-2.0商业 SaaS
治理归属CNCF 托管公司+社区公司+社区Okta
OIDC/OAuth2✅✅✅✅
SAML✅（IdP+SP）✅❌✅
LDAP/AD 联合✅✅LDAP 作后端商业版
细粒度授权✅（Authorization Services/UMA）部分❌✅
管理后台✅✅❌（YAML/LDAP）✅
自托管✅✅✅❌（SaaS）
GitHub Stars（实查）347121934824881不适用
最新版本（实查）26.8.12026.8.12.10.5SaaS
语言/底座Java（Quarkus，JDK 21）Python（Django）+Go 组件Go 单二进制不适用

7.3 实测数据表（本机 + 官方口径）

指标Keycloak（实测）AutheliaAuthentik说明
常驻内存dev 形态 411MiB / Postgres 形态 370.9MiB（实测 RSS）官方口径约 50MiB 以内官方口径多组件（服务端+worker+缓存+库），GB 级Keycloak 采样：docker stats --no-stream
冷启动到可用dev 模式约 10 秒（实测日志 started in 9.394s）秒级分钟级（多组件）同为单机空库首启
生产就绪动作hostname/TLS/持久库三关硬校验（实测报错链见专栏 C1 篇）配置文件+反向代理多组件编排—

⚠️ 注意：资源数字的口径不同（本机实测 vs 官方宣称），只做量级参考；Keycloak 的实测值对应"默认 JVM 参数 + 单域小数据量"，生产建议按并发会话数预估并预留堆余量。

7.4 选型建议

  • 要"组织级认证中枢"，协议要全（尤其 SAML）、要身份联邦、要细粒度授权 → Keycloak；
  • 要全功能但更看重现代化 UI 与二次开发体验，接受更重的多组件部署 → Authentik；
  • 只是想给内网 homelab/小规模服务加一道认证，想要极轻的单二进制 → Authelia；
  • 完全不想运维 IAM、预算允许、需要企业级 SLA 与合规背书 → Auth0。

一句话总结：Keycloak 是开源 IAM 里"功能覆盖面 × 社区厚度 × 协议完备度"的综合最优解，代价是 Java 底座的资源底线与生产配置的学习成本；越偏向"轻量网关伴随认证"的诉求，越应该看向 Authelia。

八、参考链接