Supabase 自托管接 Keycloak:两条路线与六个静默失败

自托管 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')

三个关键点:

  1. 网关不验证用户 token,只做 apikey 的字符串比对。验签在下游各家自己完成。
  2. 公钥要「导出再合并」,不能直接把 Keycloak 的 JWKS 塞给下游(原因见 4.1)。
  3. 验签只回答「你是谁」,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。