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

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

原文: https://fdetimes.net/zh/tools/keycloak-local-sso-testing-fde/

应用进入企业时，客户的 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` 的管理员账号。命令如下：

```bash
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.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`。路径取自当前文档，请对照你所用镜像版本的文档核实。

```yaml
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` 文件只需要一个客户端和一个测试用户。下面的示意片段只保留要点，从管理控制台实际导出的文件要长得多：

```json
{
  "realm": "mock-customer",
  "enabled": true,
  "clients": [
    {
      "clientId": "your-app",
      "publicClient": true,
      "redirectUris": ["http://localhost:3000/callback"]
    }
  ],
  "users": [
    {
      "username": "employee1",
      "email": "employee1@mock-customer.test",
      "enabled": true,
      "credentials": [{ "type": "password", "value": "test", "temporary": false }]
    }
  ]
}
```

建议的做法是：手工配置一次 realm，导出为 JSON，加入扮演客户实际用户组（普通员工、经理、管理员）的账号，再把文件和 compose 文件一起提交到仓库。此后团队里任何人运行 `docker compose up`，都能得到同一个 IdP，演示不再依赖某个人的记忆。

**要点:** 别让与客户 IT 团队开会成为你的应用第一次接触真实 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。走进会议室时，你带的是对的问题，而不是一串未知数。

**本周动手试试:**

- 按照官方入门页面用 Docker 运行 Keycloak，登录管理控制台，为你的应用创建一个 realm 和一个 OIDC 客户端。
- 把新建的 realm 导出为 .json 文件，加入几个测试账号，再用 --import-realm 从干净实例重建，确认一切都可以复现。
- 写一份简短的 README，让同事不用问你任何问题就能重新跑起这个 IdP。

## 信源

- [Docker - Keycloak](https://www.keycloak.org/getting-started/getting-started-docker)

- [Keycloak](https://www.keycloak.org/)

- [Keycloak joins CNCF as an incubating project](https://cncf.io/blog/2023/04/11/keycloak-joins-cncf-as-an-incubating-project)

- [GitHub - keycloak/keycloak: Open Source Identity and Access Management For Modern Applications and Services](https://github.com/keycloak/keycloak)

- [Importing and exporting realms - Keycloak](https://www.keycloak.org/server/importExport)

- [Setting Up SSO with Keycloak - PuppyGraph Docs](https://docs.puppygraph.com/getting-started/setting-up-sso-with-keycloak/)

- [Keycloak OIDC Setup for Local Development | Welcome to the Artemis Documentation](https://docs.artemis.tum.de/developer/keycloak-oidc-setup)

- [Test SAML SSO Locally Without an Okta or Entra Tenant](https://ssojet.com/blog/test-saml-sso-locally-without-idp-tenant)

- [Introducing Test SSO, an easier way to integrate SSO into your app](https://www.workos.com/blog/introducing-test-sso)
