自托管 Supabase 的 Studio 里 OAuth 面板是禁用的,一切都得改 docker-compose.yml。
而 Keycloak 与 Supabase 之间有两种完全不同的信任关系,选错不是改配置,是架构返工。
配套代码:https://github.com/geffzhang/supabase-keycloak
一、先决定:最终的 token 由谁签发
方案 A:Keycloak 只是身份源,Supabase Auth 换发自己的 token
浏览器 → Keycloak → GoTrue ─签发→ Supabase JWT → PostgREST
(在 auth.users 里建用户镜像)
方案 B:Keycloak 直接签发,Supabase 只验不签
浏览器 → Keycloak ─签发→ Keycloak JWT → PostgREST(用 Keycloak 公钥验签)
auth.users 保持空表
| A:GoTrue 换发 | B:直信 Keycloak | |
|---|---|---|
| token 签发方 | Supabase Auth | Keycloak |
auth.users |
有用户镜像 | 空表 |
auth.uid() / 会话 / MFA |
原生可用 | 无,登出不吊销 token |
| 密钥轮换 | GoTrue 管 | 手工重做 JWKS 并重建容器 |
| 适合 | 新项目要 RLS 全家桶 | 已有生产 Keycloak 不想迁用户 |
选择标准只有一条:用户到底归属谁。
如果目标是「用户由 Keycloak 统一管理」,A 就不成立。它会在 auth.users 留一份镜像,
Keycloak 改名不改、删用户不清。双份存储的代价就在这里。选 B。
二、信任链长什么样
一次请求带两个头,分别服务两个目的:
apikey: <ANON_KEY> ← HS256,用 JWT_SECRET 签的,证明"这是个合法客户端"
Authorization: Bearer <jwt> ← RS256,Keycloak 签的,证明"这是谁"

完整链路是:
Keycloak ──签发 RS256 token──▶ 浏览器
│ │
└──导出公钥──▶ JWKS 端点 │ 双头请求
│ ▼
│ Supabase 网关(只按 apikey 字符串比对)
│ │
▼ ▼
├──▶ PostgREST / Storage / Realtime(用合并 JWKS 验签)
│ │
│ ▼
└──▶ Postgres · RLS(auth.jwt() ->> 'sub')
三个关键点:
- 网关不验证用户 token,只做
apikey的字符串比对。验签在下游各家自己完成。 - 公钥要「导出再合并」,不能直接把 Keycloak 的 JWKS 塞给下游(原因见 4.1)。
- 验签只回答「你是谁」,RLS 才回答「你能看哪一行」。后面所有坑都从这里长出来:
两者任一环节错了,表现都是「登录成功但查不到数据」。
三、方案 B 的三个注入点
yaml
services:
rest:
environment:
PGRST_JWT_SECRET: ${KEYCLOAK_JWKS}
PGRST_APP_SETTINGS_JWT_SECRET: ${KEYCLOAK_JWKS}
storage:
environment:
JWT_JWKS: ${KEYCLOAK_JWKS}
AUTH_JWT_SECRET: ${JWT_SECRET} # 不能清空
PGRST_JWT_SECRET: ${KEYCLOAK_JWKS} # storage 也读它
realtime:
environment:
API_JWT_JWKS: ${KEYCLOAK_JWKS}
API_JWT_SECRET: ${JWT_SECRET}
漏配表现各不相同:只配 rest,能查库传不了文件;只配 storage,能传文件但订阅 401。
而 KEYCLOAK_JWKS 本身必须是合并出来的,不是 Keycloak 的公钥集。
顺带说方案 A。 如果选 A,改动小得多:只需把 Keycloak 配成 GoTrue 的一个
OIDC provider,不需要碰 rest/storage/realtime:
yaml
auth:
environment:
GOTRUE_EXTERNAL_KEYCLOAK_ENABLED: "true"
GOTRUE_EXTERNAL_KEYCLOAK_CLIENT_ID: "supabase"
GOTRUE_EXTERNAL_KEYCLOAK_SECRET: "<client secret>"
GOTRUE_EXTERNAL_KEYCLOAK_REDIRECT_URI: "https://example.com/auth/v1/callback"
GOTRUE_EXTERNAL_KEYCLOAK_URL: "https://kc.example.com/realms/supabase"
GOTRUE_EXTERNAL_KEYCLOAK_SCOPES: openid
三个必填项别漏:_URL 要用 issuer 形式(不带 /auth 前缀);_SCOPES 必须含
openid(Keycloak 22 起不传会直接失败);改完必须 --force-recreate auth,
restart 不重读环境变量。
验证方式是 curl -H 'apikey: <key>' https://.../auth/v1/settings,返回体里
external.keycloak 必须为 true。这条不过就不是前端问题。
四、六个静默失败
下面每一条都实测撞过。共同特征是:报错信息和真正原因相距很远,
或者干脆不报错。
1. JWKS 必须合并两套密钥
只放 Keycloak 公钥,anon 和 service_role 那两把 HS256 密钥就验不过了。
未登录请求 401、Studio 打不开、后端全废。现象特别像「Keycloak 配错了」,
实际是把自家的钥匙扔了。
正确做法是把 JWT_SECRET 转成 RFC 7517 的 oct 密钥,和公钥放进同一个 JWKS:
json
{"keys":[
{"kty":"RSA","alg":"RS256","use":"sig","kid":"...","n":"...","e":"AQAB"},
{"kty":"oct","k":"<base64url(JWT_SECRET)>","alg":"HS256"}
]}
务必过滤 use=enc。 Keycloak 同时导出签名密钥(RS256)和加密密钥(RSA-OAEP)。
后者混进去会让验签库因「找不到可用算法」整体拒绝。
从请求生命周期看会更清楚为什么必须合并。一次带用户身份的请求到 PostgREST,
验签器要用同一份密钥集校验两个不同来源的 token:
| 请求里的位置 | 谁签的 | 用 JWKS 里哪把 |
|---|---|---|
apikey 头 |
JWT_SECRET(HS256) |
oct 密钥 |
Authorization 头 |
Keycloak(RS256) | RSA 公钥 |
换成只放公钥,第一行就验不过了。而未登录请求、Studio 打开页面、后端用
service_role 调接口,全都只带 apikey,所以这些路径会一起挂掉。
这也是为什么 sync-jwks.sh 要读你 .env 里的 JWT_SECRET:它必须和现有密钥
完全一致,不能另生成一个。
写进 shell 环境时还有两个小坑:JWKS 里的 /、&、" 会破坏 sed 表达式,
得用脚本读改写;docker compose config 输出的 YAML 引号会骗人,
要验证实际值请用 --format json 反解。
2. Storage 需要 PGRST_JWT_SECRET,清空 AUTH_JWT_SECRET 会反复重启
直觉上想「只用 JWKS 就把旧变量清空」,结果:
Error: PGRST_JWT_SECRET is undefined
storage-api 的配置读取器强制要求这个变量存在。三个都得给(见上面 yaml)。
3. /health/ready 在 9000,不在 8080
--health-enabled=true 只让管理端口多出 /health。在 8080 探永远 404。
这个 404 看起来像「Keycloak 没起来」或「realm 导入失败」,实际只是探错了端口。
另外 Keycloak 26 基于 ubi-micro,镜像里没有 curl / wget / bash,不能写容器内
healthcheck,只能用宿主机脚本探。
4. realm 导入时内置 client scope 还不存在,sub 会丢
首次导入会刷一串 WARN Referenced client scope 'profile' doesn't exist。
这条 warning 看起来无害,但后果是 token 里没有 sub,没有任何用户标识。
原因:realm JSON 引用了 openid/profile/email 这些内置 scope,
但导入阶段它们还没被创建,引用被静默丢弃,连带里面的 base claim mapper 也没了。
解法是在自定义 scope 内显式声明 sub,不依赖内置 scope:
json
{
"name": "sub",
"protocolMapper": "oidc-sub-mapper",
"config": { "access.token.claim": "true", "id.token.claim": "true" }
}
5. db 首次启动要跑几十个 init-script,官方 healthcheck 等不及
官方是 5s × 10 ≈ 50 秒,实测需要 30 秒以上,慢机器就超时。超时后果是连锁的:
db unhealthy → 所有 depends_on 它的服务报 dependency failed to start
看上去像配置写错了。加启动宽限期:
yaml
db:
healthcheck:
start_period: 180s
retries: 20
6. 两份 .env 直接拼装会产生重复键,后者覆盖前者
官方模板和项目变量有 3 个同名键(JWT_SECRET / API_EXTERNAL_URL / SITE_URL),
而 Compose 读 .env 时后者覆盖前者:
bash
$ grep -n "^JWT_SECRET=" .env
33:JWT_SECRET=your-super-secret-... # 模板里的有效值
430:JWT_SECRET= # 追加进来的空值 ← 生效的是这个
所有请求 401,而你以为 secret 已经设过了。正确做法是逐个 sed 替换已有键,
只对模板里没有的键用 >> 追加。合并后自检:
bash
grep -oE '^[A-Z_]+=' .env | sort | uniq -d # 期望为空
五、两个「正常设计」的假故障
/rest/v1/ 返回 403 RBAC: access denied 是对的。 那是 OpenAPI root,
官方 Envoy 网关只允许 admin 级密钥,anon 必然被拒。有效探针是具体表路径:
验签通过 → 404(表不存在),验签失败 → 401。
storage.objects.owner 是 uuid 列。 migration 0017 只删了外键没改类型,
0018 另加了 owner_id text 取代它。上传时 Storage 把 sub 写进 owner,
所以 sub 必须是 UUID:
500 invalid input syntax for type uuid: "auth0|user_abc123"
Keycloak 自建用户的 sub 天生是 UUID v4;风险在导入用户或外部 user storage。
六、最小可跑 demo
不依赖仓库里没有的文件,五步走完。
1. 拿基线 + 覆盖文件
bash
mkdir sb-kc && cd sb-kc
# 官方自托管基线(不需要改它)
curl -fsSLO https://raw.githubusercontent.com/supabase/supabase/master/docker/docker-compose.yml
# 本项目的覆盖文件与脚本
git clone --depth 1 https://github.com/geffzhang/supabase-keycloak.git pkg
cp pkg/docker-compose.keycloak.yml \
pkg/docker-compose.supabase-thirdparty.yml \
pkg/.env.example .
cp -r pkg/keycloak pkg/scripts .
2. 补 env
官方 compose 需要 60+ 个变量,pkg/.env.example 只覆盖 Keycloak 侧。
从官方模板起步,但不要直接 cat >> 追加。两份文件有 3 个同名键
(JWT_SECRET / API_EXTERNAL_URL / SITE_URL),而 Compose 读 .env 时
后者覆盖前者,追加会让 pkg 里的空值把模板里的有效值覆盖掉。
正确做法是逐个替换:
bash
curl -fsSLO https://raw.githubusercontent.com/supabase/supabase/master/docker/.env.example
mv .env.example .env
JWT_SECRET=$(openssl rand -base64 48 | tr -d '\n')
KEYCLOAK_HOST=localhost:8081
# 只替换已有键,不新增行
sed -i "s|^JWT_SECRET=.*|JWT_SECRET=${JWT_SECRET}|" .env
sed -i "s|^API_EXTERNAL_URL=.*|API_EXTERNAL_URL=http://localhost:8000/auth/v1|" .env
sed -i "s|^SITE_URL=.*|SITE_URL=http://localhost:3000|" .env
# Keycloak 侧变量在模板里没有,安全追加
cat >> .env <<EOF
KEYCLOAK_HOST=${KEYCLOAK_HOST}
KEYCLOAK_REALM=supabase
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=$(openssl rand -base64 18 | tr -d '/+=')
KEYCLOAK_DB_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')
KEYCLOAK_CLIENT_ID=supabase
KEYCLOAK_JWKS=
KC_SCHEME=http
EOF
# 确认没有重复键(应为空)
grep -oE '^[A-Z_]+=' .env | sort | uniq -d
POSTGRES_PASSWORD 也建议换掉:
bash
sed -i "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')|" .env
ANON_KEY / SERVICE_ROLE_KEY 不能沿用模板里那两把。它们是示例 secret 签的,
换了 JWT_SECRET 就必然验签失败,而且网关只报 invalid apikey,很难查到根因。
用同一把 secret 重签:
bash
export JWT_SECRET=$(openssl rand -base64 48 | tr -d '\n')
python3 - <<'PY'
import base64, hashlib, hmac, json, os, time
secret = os.environ["JWT_SECRET"].encode()
b64 = lambda b: base64.urlsafe_b64encode(b).decode().rstrip("=")
def sign(role):
now = int(time.time())
h = b64(json.dumps({"alg":"HS256","typ":"JWT"}, separators=(",",":")).encode())
p = b64(json.dumps({"role":role, "iss":"supabase", "iat":now,
"exp":now+60*60*24*365*10}, separators=(",",":")).encode())
return f"{h}.{p}." + b64(hmac.new(secret, f"{h}.{p}".encode(), hashlib.sha256).digest())
print("ANON_KEY="+sign("anon"))
print("SERVICE_ROLE_KEY="+sign("service_role"))
PY
把输出的两行替换进 .env 的对应项,JWT_SECRET 也用同一个值。
3. 起 Keycloak
bash
docker compose -f docker-compose.keycloak.yml up -d keycloak-db keycloak
./scripts/wait-keycloak.sh http://localhost:9000/health/ready 180
wait-keycloak.sh 的默认参数就是 9000,直接跑也行。看到 keycloak is ready 再继续。
realm 会自动导入。进去改两处占位符:Clients → supabase → Credentials → Regenerate;
Users → demo → Credentials。
4. 合并 JWKS 再起 Supabase
bash
./scripts/sync-jwks.sh
docker compose -f docker-compose.yml -f docker-compose.supabase-thirdparty.yml up -d
sync-jwks.sh 会做三件事:拉 Keycloak 公钥、过滤掉 use=enc、把 JWT_SECRET
转成 oct 密钥一起写进 .env 的 KEYCLOAK_JWKS。跑完确认长度不为 0:
bash
grep -c '^KEYCLOAK_JWKS=.\{50,\}' .env # 期望输出 1
首次起 Supabase 要等 db 跑完初始化,约 30 秒以上。
5. 验证
bash
SUPABASE_URL=http://localhost:8000 \
SUPABASE_KEY=$(grep '^ANON_KEY=' .env | cut -d= -f2) \
KEYCLOAK_HOST=localhost:8081 \
KC_SCHEME=http \
./scripts/verify.sh b
期望看到 全部通过。verify.sh 查四层:issuer 形状、JWKS 是否非对称且带 kid、
token 里的 sub/role/preferred_username、以及 Keycloak token 能否穿过
PostgREST 和 Storage。
想连 RLS 一起验,建张探针表再跑一次:
bash
docker exec -i supabase-db psql -U postgres < pkg/sql/roles-and-rls.sql
RLS_PROBE_TABLE=notes ... ./scripts/verify.sh b # 多出「写自己 201 / 越权 403」
七、验证要有负向判据
只验「admin 能访问 admin 端点」是不够的。权限校验被整体跳过时它也会通过。
必须同时验「非 admin 被拒」:
admin → 404(业务错误:无此审批单,权限已过)
operator → 403(requires role 'admin')
只有后者也对了,前者才有意义。同理,RLS 不能只验「能写自己的」,
还要验「写别人的被拒 403」和「查列表只看到自己的」。
八、角色:进库的永远只有 authenticated
Keycloak 的 app_admin 不会 变成 Postgres 角色。写成 to app_admin 会直接报
role "app_admin" does not exist。要区分管理员得建映射表,用 RLS 去查:
sql
create policy todos_admin on public.todos
for all to authenticated
using (exists (
select 1 from public.user_roles
where subject = (select auth.jwt() ->> 'sub')
and app_role = 'admin'
));
另外不要用 auth.uid() :sub 不是合法 UUID 时它抛异常而不是返回 null,
整条请求 500。统一用 (select auth.jwt() ->> 'sub'),外层 select 让 Postgres
走 InitPlan 缓存,否则每个 policy 都要对每一行重新解析一次 json。
小结
这套集成的难点不在「怎么配」,而在默认行为是静默的:
- 密钥配错 → 401,日志只写
invalid apikey - claim 丢了 → 权限降级,两边都不报错
- health 探错端口 → 404,像服务没起来
- 属性被丢弃 → 写入返回 204,实际没存
背配置项省不了时间,给每一层配一条能红的判据才省。
上面六个坑各自对应一条断言,红了才说明配错了。
版本基线:Supabase docker@4ead4b0、Keycloak 26.0、验证于 2026-11。