FDE Times 数据在招 FDE 职位 873▼9 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 181支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

工具

见客户 IT 之前,先在本机跑通企业 SSO

一个 Keycloak 容器加一份 realm JSON 文件,就能带着跑通的登录流程去开会。

分享微博

要点速览

  • Keycloak 是采用 Apache 2.0 许可证的开源 IAM 软件,自 2023 年 4 月起成为 CNCF 孵化项目。
  • 它可以在笔记本上充当替身 IdP,从 JSON 文件加载 realm,端到端测试 SSO 流程。
  • Keycloak 的行为是 Keycloak 的行为,而不是 Okta 或 Entra 的,上线前仍需对照客户真实的 IdP 核验一次。
本地运行 Keycloak 时三类常见错误的诊断树。返回应用时被拒绝:逐字符比对重定向 URI(这个错误在客户环境中还会出现,以强调色标出)。修改了 JSON 文件但重启后没有变化:从干净实例重建。没有加载任何 realm:把 .json 文件直接放在 data/import 目录下。
登录失败时,先看现象,再直奔对应的解决办法。重定向 URI 错误是 OIDC 的通用问题,在客户环境中还会再遇到;另外两个源于 Keycloak 导入 realm 的方式。

应用进入企业时,客户的 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 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力留给客户的 API 测试套件,几个文本文件就够了Hurl 既能在你的笔记本上跑,也能放进客户的 CI 流水线,对方团队每一行都看得懂。