Keycloak on IDaaS Book

Keycloak 细粒度权限与授权策略实战 — Groups vs Roles、Authorization Services | IDaaS Book

Thu, 09 Jul 2026 00:00:00 +0800

场景

你已经在 Keycloak 里配好了 Realm、Client 和用户，SSO 登录也跑通了。现在业务方提了三个需求：

“这个 API 只有管理员能调，普通用户不行”
“同一个 API，部门 A 的人能写、部门 B 的人只能读”
“用户可以查看自己的订单，但不能看别人的”

你在 Keycloak 的 Groups、Roles、Composite Roles、Authorization Services 之间绕晕了——到底该用哪个？配了半天 Policy Evaluation 还是不通过。

适用与不适用

适用	不适用
需要对单个资源做细粒度控制（按 HTTP 方法、URI、资源属性）	只需要简单的「已登录/未登录」判断
多个应用共用 Keycloak，授权规则各不相同	授权规则完全由应用内部代码管理
需要 ABAC/ReBAC 混合模型	只需要 OAuth 2.0 Scope 就够了
有管理后台需要按角色区分菜单可见性	你的应用根本不区分角色

核心概念速览

在深入配置之前，先理清几个最容易混淆的概念：

Group vs Role

	Group	Role
本质	用户的组织归属	用户的权限标签
典型值	`engineering`、`sales`、`cn-team`	`admin`、`viewer`、`order-manager`
能嵌套吗	✅ 支持子 Group	✅ 通过 Composite Role 嵌套
适合干什么	按部门/团队分组、LDAP 映射	授予具体权限、做 RBAC
不适合干什么	直接做权限判断	表达部门层级关系

简单原则：Group 说「你是谁的人」，Role 说「你能干什么」。一个用户可以有多个 Group 和多个 Role。

Keycloak + oauth2-proxy 保护内部应用：Ingress 与 ForwardAuth 配置清单

Sat, 04 Jul 2026 00:00:00 +0800

一份面向内部应用的 Keycloak + oauth2-proxy 网关层 SSO 配置清单，覆盖 NGINX Ingress、Traefik ForwardAuth、常见报错和回滚。

Keycloak 直连 Kubernetes OIDC 认证 — API Server 集成与 RBAC 绑定 | IDaaS Book

Sat, 11 Jul 2026 00:00:00 +0800

场景

你有一个 Kubernetes 集群，团队成员目前用证书或静态 token 认证，管理起来既麻烦又不安全。组织已经在用 Keycloak 管理用户和组，你想把 K8s 集群的认证直接委托给 Keycloak，用 Keycloak 里的组来控制谁有集群管理员权限、谁只能看 Pod 日志。

与 Dex + Keycloak 联邦方案不同，这里不需要额外的 Dex 代理层——Keycloak 本身就是标准的 OIDC Provider，Kubernetes API Server 原生支持 OIDC 认证。

一句话：Keycloak 告诉 K8s「这个人是谁、属于哪些组」，K8s RBAC 决定「这些组能做什么」。

适用与不适用

适用	不适用
单集群或少量集群，用户都在 Keycloak 里	几十个集群需要统一管理（建议加 Dex，参考联邦方案）
Keycloak 是唯一的用户身份源	需要同时接受 GitHub、LDAP、Google 等多源认证（用 Dex 做聚合）
团队规模中等（几十到几百用户）	上千用户且需要动态 RBAC 同步
已有 Keycloak 部署，不想引入新组件	Keycloak 还没部署（先部署 Keycloak，参考生产部署指南）

架构

 sequenceDiagram
 participant User as kubectl / kubelogin
 participant K8s as K8s API Server
 participant KC as Keycloak

 User->>K8s: kubectl get pods
 K8s->>User: 401 + OIDC redirect URL
 User->>KC: 浏览器打开 Keycloak 登录页
 Note over User,KC: OIDC Authorization Code + PKCE
 KC->>User: 登录成功，返回 id_token + refresh_token
 User->>K8s: kubectl get pods (Authorization: Bearer &lt;id_token&gt;)
 K8s->>K8s: 验证 JWT 签名 + issuer + aud + exp
 K8s->>K8s: 提取 sub、groups → 匹配 RBAC
 K8s->>User: Pod 列表

流程要点：