见客户 IT 之前,先在本机跑通企业 SSO
一个 Keycloak 容器加一份 realm JSON 文件,就能带着跑通的登录流程去开会。
要点速览
- Keycloak 是采用 Apache 2.0 许可证的开源 IAM 软件,自 2023 年 4 月起成为 CNCF 孵化项目。
- 它可以在笔记本上充当替身 IdP,从 JSON 文件加载 realm,端到端测试 SSO 流程。
- Keycloak 的行为是 Keycloak 的行为,而不是 Okta 或 Entra 的,上线前仍需对照客户真实的 IdP 核验一次。
应用进入企业时,客户的 IT 团队迟早会问:他们的用户要通过哪套身份系统登录,怎么登录?
如果这时你才第一次打开 OpenID Connect(OIDC)文档,会议就变成了一堂课。有了 Keycloak,你可以带着一套已经在自己笔记本上跑通的登录流程赴会。
这并不是什么小众工具。Keycloak 是采用 Apache 2.0 许可证的开源 IAM 项目。2023 年 4 月,云原生计算基金会(CNCF)技术监督委员会投票接纳它为孵化项目。
前线部署工程师(FDE)需要它,原因却在别处。WorkOS 指出,用传统方式测试单点登录(SSO),需要一个身份提供方(IdP)账号和若干测试用户,准备起来并不轻松。对 FDE 来说,这个账号通常归客户的 IT 团队管,项目启动时未必已经开通,而你仍然得证明应用能够完成集成。
Keycloak 在现场能帮你做什么?
Keycloak 官网给自己定的目标,是以最小的工作量为应用加上身份认证。对 FDE 更重要的是,它建立在标准协议之上:OpenID Connect、OAuth 2.0 和 SAML,与客户 IdP 使用的协议相同。
正因如此,许多团队把它当作练习场。PuppyGraph 的文档在本地运行 Keycloak 作为替身 IdP,事先配好一个 OIDC 客户端和一个测试用户,读者无需生产环境的 IdP 就能走完整个 SSO 流程。
慕尼黑工业大学(TUM)的 Artemis 平台也是这样做的:用一个 Keycloak 容器加载现成的 realm,替代学校生产环境的 OIDC 提供方。
设想你要为一家使用 Entra 的银行部署内部工具。开会之前,你已经清楚应用需要哪个重定向 URI、从哪些 claim 读取邮箱和用户组、token 过期时哪里会出错。你带给 IT 的问题会具体得多。
一条命令,在本机跑起一个 IdP
官方 Docker 入门页面以开发模式运行 Keycloak,并创建一个用户名和密码都是 admin 的管理员账号。命令如下:
docker run -p 127.0.0.1:8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
<keycloak-image-from-official-guide> start-dev
<keycloak-image-from-official-guide> 这部分需要你自己填写。打开 keycloak.org/getting-started/getting-started-docker,在启动 Keycloak 的那一步找到 docker run 命令,复制紧挨在 start-dev 前面、带版本标签的完整镜像名。管理员环境变量的名称也要对照页面核实,不同版本之间可能有变化。
接着打开管理控制台,为“模拟客户”创建一个 realm,为你的应用创建一个 OIDC 客户端和几个用户,把应用指向这个 realm,然后试着登录。
到这一步,你手里只有一个手工搭建的 IdP。下次启动,或者同事想运行它时,管理控制台里的每一次点击都得从头再来。
把 IdP 变成人人都能重建的文件
Keycloak 用 realm 导入解决这个问题。官方文档说明,可以在服务器启动时用 --import-realm 选项加载 realm,容器中的导入目录是 /opt/keycloak/data/import。
Artemis 是个值得照搬的例子。它在 compose 文件中固定了 Keycloak 版本,每次启动都从仓库里的 JSON 文件加载 realm。
同样思路的最简版本可以写成下面这样。关键在于:把仓库的 realms/ 目录挂载到容器的导入目录,并在启动命令中加上 --import-realm。路径取自当前文档,请对照你所用镜像版本的文档核实。
services:
keycloak:
image: ${KEYCLOAK_IMAGE} # 镜像名 + 固定版本,取自 Keycloak 的 Docker 页面
command: start-dev --import-realm
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: admin
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./realms:/opt/keycloak/data/import # 请对照所用版本的文档核实此路径
要让这个文件跑起来,在 compose 文件旁边新建一个 .env 文件,只写一行:KEYCLOAK_IMAGE=,后面接你从 Docker 页面复制的镜像名和标签。这个 .env 文件也要提交:正是固定的标签,让同事能搭出和你完全一样的 IdP,而不是行为不同的新版本。
试运行时,realms/mock-customer.json 文件只需要一个客户端和一个测试用户。下面的示意片段只保留要点,从管理控制台实际导出的文件要长得多:
{
"realm": "mock-customer",
"enabled": true,
"clients": [
{
"clientId": "your-app",
"publicClient": true,
"redirectUris": ["http://localhost:3000/callback"]
}
],
"users": [
{
"username": "employee1",
"email": "[email protected]",
"enabled": true,
"credentials": [{ "type": "password", "value": "test", "temporary": false }]
}
]
}
建议的做法是:手工配置一次 realm,导出为 JSON,加入扮演客户实际用户组(普通员工、经理、管理员)的账号,再把文件和 compose 文件一起提交到仓库。此后团队里任何人运行 docker compose up,都能得到同一个 IdP,演示不再依赖某个人的记忆。
初次搭建容易犯的三个错误
搭建本地 IdP 时,大部分时间不是耗在 Keycloak 本身,而是耗在几个小细节上。下表列出登录不成功时应当先检查的地方。
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
| 登录成功,但返回应用时被拒绝 | 客户端中声明的重定向 URI 与应用实际调用的地址不一致 | 逐字符比对:协议、端口、路径、末尾的 / |
| 修改了 realm JSON 文件,重启后没有变化 | 服务器上已存在该 realm,导入步骤被跳过 | 从干净实例重建,或在导入前删除旧 realm |
| Keycloak 启动了,但没有加载任何 realm | 漏写了 --import-realm,或卷没有指向正确的导入目录 |
对照所用版本的文档检查启动命令和挂载路径 |
第一个错误是 OIDC 的通病,到了客户环境还会再遇到。第二个直接源于 Keycloak 的规则:realm 已存在时,导入会被跳过。把这两条写进 README,免得同事白白耗掉一个下午。
笔记本替代不了客户的 IdP
第一个局限就在启动命令里。使用 admin/admin 的开发模式只适合本机,绝不能让这套配置混进任何客户环境。
第二个局限是根本性的。SSOJet 说得很直接:Keycloak 一条 docker run 命令就能在本地跑起来,但它的行为是 Keycloak 的行为,而不是 Okta 或 Entra 的。claim 名称、用户组配置和策略,在不同 IdP 之间都可能不同。
SSOJet 还介绍了许多团队采用的节奏:开发阶段和持续集成(CI)中使用模拟 IdP,上线前再对照客户真实的 IdP 测试一次。规划时就该这样分工:笔记本用来确认应用能正确处理标准流程,与 IT 的会面留给客户环境的特有细节。
所以不必一上来就学遍 Keycloak 的所有功能。先把 OIDC 的基本流程吃透:realm、客户端、重定向 URI、token 和 claim。在 Keycloak 上弄懂这些之后,读任何企业 IdP 的文档都会更快。
收尾练习:“managers”用户组真的进了 token 吗?
大多数企业应用不仅要知道“谁登录了”,还要知道“这个人属于哪个组”。在宣告环境搭好之前,先做完这个练习。
在 mock-customer realm 中创建 managers 用户组,分配给一个新的测试账号,比如 manager1。配置客户端,让 token 中包含用户组信息,然后依次以 employee1 和 manager1 登录。解码两个用户各自的 ID token 并对比:只有 manager1 的 token 应当带有 managers 用户组的 claim。
看到这个 claim 之后,让应用读取它来放行或拦截某个管理页面,再重新导出 realm,让新用户组也保存在 JSON 文件里。这时你手里就有了问客户 IT 团队最具体的问题:他们的 IdP 把用户组信息放在哪个 claim 里,名称是什么?
一个小仓库,胜过技能清单上的一行字
一个包含示例应用、compose 文件和带现成测试用户的 realm JSON 的仓库,是 FDE 招聘方可以亲手运行的证据。写进简历时,要写成成果:搭建了可复现的 SSO 环境,在接入客户 IdP 之前测试 OIDC 集成。
下次日历上出现“与 IT 的启动会”,提前花一个晚上折腾 Keycloak。走进会议室时,你带的是对的问题,而不是一串未知数。
这篇文章对你有帮助吗?
感谢你的反馈!
9 个信源
- Docker - Keycloak
- Keycloak
- Keycloak joins CNCF as an incubating project · 2023-04-11
- GitHub - keycloak/keycloak: Open Source Identity and Access Management For Modern Applications and Services
- Importing and exporting realms - Keycloak
- Setting Up SSO with Keycloak - PuppyGraph Docs
- Keycloak OIDC Setup for Local Development | Welcome to the Artemis Documentation
- Test SAML SSO Locally Without an Okta or Entra Tenant · 2026-10-26
- Introducing Test SSO, an easier way to integrate SSO into your app · 2024-02-26