第四部分：实现与实践 on IDaaS Book

Keycloak IAM 架构深度解析 — 核心组件、部署架构与扩展机制 | IDaaS Book

Mon, 01 Apr 2024 00:00:00 +0800

14.1 Keycloak 的设计哲学

Keycloak 是 Red Hat 主导开源的 IAM 解决方案。它的设计哲学可概括为：

开箱即用：快速部署，即可使用完整 SSO、社交登录、MFA
标准优先：完整实现 OAuth 2.0、OIDC、SAML 2.0
可扩展：SPI（Service Provider Interface）机制允许深度定制
云原生：支持容器化、Kubernetes、Operator 部署

14.2 架构全景

┌─────────────────────────────────────────────────────────────┐
│ Keycloak Server │
│ │
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Admin Console │ │ Account │ │ Login/Register │ │
│ │ (管理控制台) │ │ Console │ │ Themes (登录页) │ │
│ │ Angular SPA │ │ (用户自助) │ │ FTL Templates │ │
│ └───────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │ │
│ ┌───────┴─────────────────┴────────────────────┴─────────┐ │
│ │ REST API Layer │ │
│ │ (JAX-RS + Admin REST + Realms Admin) │ │
│ └──────────────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴──────────────────────────────┐ │
│ │ Service Layer │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │ │
│ │ │Auth Flow │ │Identity │ │User │ │Client │ │ │
│ │ │Executor │ │Provider │ │Federation│ │Manager │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │ │
│ └───────────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴──────────────────────────────┐ │
│ │ SPI Layer (扩展点) │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌─────────┐ │ │
│ │ │User │ │Auth │ │Event │ │Theme │ │Required │ │ │
│ │ │Storage │ │Flow │ │Listener│ │ │ │Action │ │ │
│ │ └────────┘ └────────┘ └────────┘ └──────┘ └─────────┘ │ │
│ └───────────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴──────────────────────────────┐ │
│ │ Infinispan (缓存层) │ │
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────────┐ │ │
│ │ │User Cache │ │Realm Cache │ │Auth Session Cache│ │ │
│ │ └────────────┘ └────────────┘ └──────────────────┘ │ │
│ └───────────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴──────────────────────────────┐ │
│ │ Persistence (持久层) │ │
│ │ JPA (Hibernate) → PostgreSQL / MySQL │ │
│ │ Liquibase (数据库迁移管理) │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

14.3 核心概念

Realm（域）

Realm 是 Keycloak 中最核心的隔离单位。一个 Realm 管理一组用户、凭证、角色和组。不同 Realm 之间完全隔离。

第15章：Apereo CAS — 开源企业级 SSO 与 CAS 协议详解 | IDaaS Book

Tue, 02 Apr 2024 00:00:00 +0800

15.1 CAS 简介

Apereo CAS（Central Authentication Service）是教育和技术社区最古老、最广泛使用的开源 SSO 解决方案之一。始于耶鲁大学（2002年），现由 Apereo 基金会维护。

CAS 的定位是：专注于 Web SSO 的认证服务器，提供了丰富的协议支持和现代的身份管理能力。

15.2 CAS 与 Keycloak 的定位差异

维度	CAS	Keycloak
起源	教育领域（耶鲁大学）	企业领域（Red Hat）
设计哲学	高度可配置，Assembly Line	开箱即用，约定优于配置
扩展方式	依赖注入，丰富的模块	SPI 机制
用户管理	委派给外部源	自有用户存储 + 联合
协议支持	CAS 协议、SAML 2.0、OIDC、OAuth 2.0、WS-Federation	OIDC、OAuth 2.0、SAML 2.0（不原生支持 WS-Fed）
文档质量	一般	好
社区	教育+研究机构为主	更广泛的企业社区
容器化友好度	需要定制构建	原生支持

选型建议：

如果你的环境主要是 Java 生态，需要高度定制化 → CAS
如果你需要快速部署，开箱即用 → Keycloak
如果你在教育领域，已有 CAS 基础设施 → 继续用 CAS

15.3 CAS 架构

核心设计：Assembly Line

CAS 使用"装配线"模式处理认证请求：

第16章：Dex 身份代理 — Kubernetes 原生 OIDC 联邦方案 | IDaaS Book

Wed, 03 Apr 2024 00:00:00 +0800

16.1 Dex 的设计定位

Dex 最初由 CoreOS 开发，现由 dexidp 社区维护（CNCF 生态相关），专门为 Kubernetes 生态设计。它的定位非常精准：

Dex 不是一个完整的 IAM 系统，它是一个 OIDC 身份代理。

Dex 不做的事：

不存储用户（用户数据在外部 IdP）
不提供用户管理 UI
不提供授权管理（RBAC 由 Kubernetes 的 RBAC 处理）

Dex 做的事：

连接各种上游 IdP（LDAP、AD、GitHub、Google、SAML 等）
统一输出为 OIDC
为 Kubernetes 提供 OIDC 认证

什么时候用 Dex？

你的 Kubernetes 集群需要对接企业 AD/LDAP 进行认证
你只需要一个轻量级的 OIDC 桥接
你不想部署完整的 Keycloak

什么时候不用 Dex？

你需要用户管理界面
你需要丰富的授权策略
你需要支持多种下游协议（如 SAML）
你需要自定义认证流程

16.2 Dex 架构

 ┌─────────────────────────┐
 │ Dex Server │
 │ │
 │ ┌───────────────────┐ │
 │ │ Connectors │ │
 │ │ ┌──────┐┌──────┐ │ │
 │ │ │ LDAP ││ OIDC │ │ │
 │ │ └──────┘└──────┘ │ │
 │ │ ┌──────┐┌──────┐ │ │
 │ │ │ SAML ││GitHub│ │ │
 │ │ └──────┘└──────┘ │ │
 │ │ ┌──────┐┌──────┐ │ │
 │ │ │Google││ AD │ │ │
 │ │ └──────┘└──────┘ │ │
 │ └───────────────────┘ │
 │ │
 │ 统一输出：OIDC Provider │
 └───────────┬─────────────┘
 │
 ┌───────────────┼───────────────┐
 ▼ ▼ ▼
 [Kubernetes] [Grafana] [Istio]

16.3 Dex 配置

基本配置结构

# config.yaml
issuer: https://dex.example.com

storage:
 type: kubernetes
 config:
 inCluster: true

web:
 http: 0.0.0.0:5556
 # TLS 配置在生产环境必须

# OIDC 客户端配置
staticClients:
 - id: kubernetes
 redirectURIs:
 - 'http://localhost:8000'
 name: 'Kubernetes'
 secret: 'generated-client-secret'

# 上游连接器
connectors:
 - type: ldap
 id: ldap
 name: LDAP
 config:
 host: ldap.example.com:636
 insecureNoSSL: false
 bindDN: cn=admin,dc=example,dc=com
 bindPW: admin-password
 userSearch:
 baseDN: ou=users,dc=example,dc=com
 filter: "(objectClass=inetOrgPerson)"
 username: uid
 idAttr: uid
 emailAttr: mail
 nameAttr: displayName
 groupSearch:
 baseDN: ou=groups,dc=example,dc=com
 filter: "(objectClass=groupOfNames)"
 userMatchers:
 - userAttr: DN
 groupAttr: member
 nameAttr: cn

 - type: github
 id: github
 name: GitHub
 config:
 clientID: $GITHUB_CLIENT_ID
 clientSecret: $GITHUB_CLIENT_SECRET
 redirectURI: https://dex.example.com/callback
 orgs:
 - name: my-org
 teams:
 - platform-team

连接器类型

Dex 支持的连接器：

第17章：IDaaS 方案全景对比 — Keycloak vs CAS vs Dex 选型决策框架 | IDaaS Book

Thu, 04 Apr 2024 00:00:00 +0800

17.1 IDaaS 市场格局

当前 IDaaS 市场可分为以下几个阵营：

 │ 云原生产品
 Okta │ Auth0 (Okta) 自建/私有化
 Entra ID │ Ping Identity Keycloak
 Google CI │ ForgeRock Janssen
 腾讯云IDaaS│ JumpCloud Casdoor
 │

 商业 SaaS ←──────────────→ 开源自建
 (快) (可控)

注：ForgeRock 已于 2023 年被 Ping Identity 收购，二者现同属一家；Microsoft 已将 Azure AD 更名为 Entra ID。

17.2 开源方案对比

Keycloak

类型：完整 IAM / IDaaS 平台语言：Java (Quarkus) 许可证：Apache 2.0

核心优势：

功能最全面的开源 IAM
Red Hat 背书，社区活跃、长期演进
丰富的协议支持（OIDC、SAML 2.0、OAuth 2.0）
活跃的社区和生态
SPI 机制支持深度定制
文档相对完善

不足：

第18章：IDaaS 集成模式与实践 — 网关、BFF 与 Sidecar 架构模式 | IDaaS Book

Fri, 05 Apr 2024 00:00:00 +0800

18.1 集成模式概览

将 IDaaS 集成到应用架构中有多种模式，选择正确的模式取决于应用类型、安全要求和技术栈：

模式	适用场景	复杂度	安全性
网关模式	传统 Web 应用、API	低	中
BFF 模式	SPA、移动端	中	高
Sidecar 模式	微服务/服务网格	中	高
SDK/库模式	任何应用	低	取决于实现
直接集成	自定义应用	中	取决于实现

18.2 网关模式

API 网关认证

在 API 网关层统一处理认证，后端服务不感知身份：

客户端 → [API 网关] → [后端服务]
 │
 │ Token 验证
 ▼
 [IDaaS Server]

优点：

后端服务零改动
集中管理认证策略
网关层统一的限流、日志、监控

缺点：

网关层成为性能瓶颈
细粒度授权在网关层实现困难
后端服务不知道"谁"在访问

Nginx + OAuth2 代理

使用 oauth2-proxy 为任何 HTTP 应用添加 OAuth 2.0 保护。完整配置指南、生产排错与回滚方案见 Keycloak + oauth2-proxy 集成实战指南，本节给出快速参考。

第19章：Keycloak IAM Kubernetes 生产环境部署 — Helm、Operator 与高可用 | IDaaS Book

Sat, 06 Apr 2024 00:00:00 +0800

19.1 部署方式选择

在 Kubernetes 上部署 IDaaS（以 Keycloak 为例），有三种主流方式：

方式	适用场景	优点	缺点
Helm Chart	一般场景	简单、社区维护	定制受限
Keycloak Operator	生产环境	云原生、自动管理	学习曲线
手动 YAML	特殊需求	完全控制	运维负担大

推荐：生产环境优先使用 Keycloak Operator（原生支持 Quarkus 发行版，建议跟随当前稳定版）。如果组织已经有成熟 Helm 交付体系，可以使用 Helm，但要把数据库、反向代理、健康检查、监控和升级回滚纳入同一套发布流程。

生产部署快速决策表

问题	推荐做法	风险提示
Operator 还是 Helm？	长期运行、需要自动化滚动升级和 CRD 管理时优先 Operator；短期 PoC 或已有 Helm 平台可选 Helm	不要同时用 Operator 和 Helm 管理同一个 Keycloak 实例，控制面会打架
数据库放哪里？	使用外部 PostgreSQL 或云数据库，独立备份与监控	Operator 不负责创建和维护生产数据库；把数据库塞进同一个无状态发布包，迟早会在恢复演练里交学费
TLS 在哪里终结？	通常在 Ingress/LB 终结 TLS，Keycloak 仅解析可信代理头	`proxy.headers: xforwarded` 只应信任受控代理；不要把 management 端口暴露到公网
版本如何选择？	Keycloak 镜像、Operator 资源和 CRD 使用同一稳定版本，并先在预发环境演练升级	跳版本升级前先读 release notes 和迁移指南，准备数据库备份与回滚窗口

19.2 使用 Keycloak Operator

版本提示：Keycloak 官方下载页与 GitHub Release 显示当前稳定版为 26.7.0（2026-07-11 检查）；官方 Operator 安装文档同样提供 26.7.0 的 keycloak-k8s-resources 示例。Keycloak 迭代很快，部署时请到 keycloak.org/downloads、 Keycloak Releases 与 Operator 安装文档复核当前最新稳定版，并保持 Operator 版本与 Keycloak 镜像一致。

Casdoor 深度解读 — AI-First 开源 IAM 的架构、部署与选型指南 | IDaaS Book

Wed, 08 Jul 2026 00:00:00 +0800

Casdoor 简介

Casdoor 是 Casbin 社区推出的开源身份与访问管理（IAM）平台，截至 2026 年 7 月最新稳定版为 v3.108.0（Apache 2.0 许可证），GitHub 约 13,900 星。

一句话定位：UI-first、支持多协议、内置 Casbin 授权的轻量级 IAM 服务器。它在 2025-2026 年逐步引入 MCP Gateway 和 A2A 协议支持，转向 “AI-First” 路线——这意味着 Casdoor 不仅能做人应用的认证中心，也在尝试成为 AI Agent 之间的身份与授权网关。

维度	信息
项目	github.com/casdoor/casdoor
语言	Go (后端) + React (前端)
数据库	MySQL、PostgreSQL、SQLite（快速试用）
缓存	可选 Redis
许可证	Apache 2.0
文档	casdoor.ai
在线 Demo	door.casdoor.com（只读）/ demo.casdoor.com（可写，约 5 分钟重置）

核心架构

 graph TB
 subgraph "外部系统"
 User[用户/应用]
 AI[AI Agent]
 SP[第三方 IDP<br/>Google/GitHub/企业微信]
 end

 subgraph "Casdoor"
 UI[React Web UI]
 API[RESTful API Server<br/>Go + Beego]
 AuthN[认证引擎<br/>OAuth/OIDC/SAML/CAS/LDAP]
 AuthZ[授权引擎<br/>Casbin]
 Store[(数据存储<br/>MySQL/PostgreSQL)]
 MCP[MCP Gateway<br/>A2A Protocol]
 end

 subgraph "下游应用"
 App1[Web 应用]
 App2[移动 App]
 App3[AI Agent 工具]
 end

 User --> UI
 User --> API
 AI --> MCP
 MCP --> API
 SP --> AuthN
 API --> AuthN
 API --> AuthZ
 AuthN --> Store
 AuthZ --> Store
 AuthN --> App1
 AuthN --> App2
 AuthZ --> App3

Casdoor 采用前后端分离架构：

Authentik — Python 生态的开源 IAM 平台详解 | IDaaS Book

Wed, 08 Jul 2026 00:00:00 +0800

Authentik 是一个用 Python/Django 编写的开源身份验证与授权平台，2020 年由 Jens Langhammer 创建，当前最新稳定版为 2026.5.3（2026 年 6 月发布），GitHub 22k+ star。它的核心差异点在于：用**可视化流程构建器（Flow Builder）**替代硬编码的认证逻辑，用 Outpost 代理 将认证能力延伸到任意网络边界，同时保持 Python 生态的灵活性和可编程性。

核心设计思路

Authentik 的设计围绕三个核心概念展开：

Flow（流程）：一切认证行为——登录、注册、MFA 验证、密码重置、用户设置——都是可拖拽编排的流程。你可以像搭积木一样组合"用户名密码验证 → TOTP 验证 → 用户信息确认"形成一条完整的登录流水线。
Outpost（前哨）：Authentik 核心不直接面向外部流量，而是通过 Go 编写的轻量 Outpost 代理（LDAP Outpost、Proxy Outpost、Radius Outpost）部署在目标网络内，作为认证网关。
Policy / Binding（策略与绑定）：权限控制通过表达式策略实现，支持 Python 表达式、用户属性、IP 范围等条件，策略可绑定到 Flow、应用、属性映射等任何资源上。

架构全景

 flowchart TB
 subgraph "用户侧"
 U[用户浏览器]
 APP[下游应用]
 end

 subgraph "Authentik 核心"
 WS[Web Server\nDjango + Channels]
 DB[(PostgreSQL)]
 REDIS[(Redis\n缓存 + WebSocket)]
 CELERY[Celery Worker\n后台任务]
 end

 subgraph "Outpost 层"
 PO[Proxy Outpost\nGo 反向代理]
 LO[LDAP Outpost\nGo LDAP 服务器]
 RO[Radius Outpost]
 end

 U -->|HTTPS| PO
 U -->|登录页面| WS
 APP -->|LDAP 认证| LO
 PO -->|OAuth2/OIDC/SAML| WS
 LO -->|内部 API| WS
 RO -->|内部 API| WS
 WS --> DB
 WS --> REDIS
 WS --> CELERY

 style WS fill:#4a90d9,color:#fff
 style PO fill:#e67e22,color:#fff
 style LO fill:#e67e22,color:#fff

核心（Django + PostgreSQL + Redis）负责策略决策、用户管理和流程编排；Outpost 负责协议转换和流量代理。两者通过内部 API 通信，Outpost 可部署在完全不同的网络区域。

SuperTokens — 开发者友好的开源用户认证与会话管理 | IDaaS Book

Fri, 10 Jul 2026 00:00:00 +0800

SuperTokens 是一个开源的、面向开发者的用户认证与会话管理方案，由 SuperTokens 团队于 2020 年创建，当前最新稳定版为 v11.4.5（2026 年 6 月发布），GitHub 15k+ star。核心用 Java 编写，提供 Node.js、Go、Python、React、React Native、Vanilla JS 等前端/后端 SDK，定位是 Auth0 / Firebase Auth / AWS Cognito 的开源替代品。

SuperTokens 的核心理念：把认证做得像你自己写的一样可控，但省掉从头搭建的时间和安全风险。 和 Keycloak 这类完整 IAM 平台不同，SuperTokens 选择做减法——只关注用户认证和会话管理，不涉及用户联邦、复杂协议代理或企业级身份编排。

核心设计思路

三层架构抽象：Frontend SDK（管理 session token + 渲染登录 UI）→ Backend SDK（提供 sign-up/sign-in/session refresh API）→ Core HTTP 服务（核心认证逻辑 + 数据库操作）。每一层都可以独立替换。
协议隐藏而非暴露：开发者不需要理解 OAuth 2.0 的 grant type、PKCE 或 Token 结构。调用 signUp()/signIn() 即可，SuperTokens 在后端 SDK 中处理所有协议细节。
最小供应商锁定：用户数据存在你自己的数据库中，切换 SuperTokens 不需要强制用户重新登录、重置密码或重新注册。
功能解耦：你可以只使用 SuperTokens 的登录功能，或只使用会话管理，甚至可以将会话管理与 Auth0 等其他登录提供商组合使用。

架构全景

 flowchart TB
 subgraph "用户侧"
 BROWSER[浏览器<br/>React / Vanilla JS]
 MOBILE[移动端<br/>React Native / Flutter]
 SPA[SPA 应用]
 end

 subgraph "SuperTokens 体系"
 direction TB
 FE_SDK[Frontend SDK<br/>管理 Token 与 UI]
 BE_SDK[Backend SDK<br/>Node.js / Go / Python]
 CORE[SuperTokens Core<br/>Java HTTP 服务]
 DB[(PostgreSQL<br/>或 MySQL)]
 end

 subgraph "你的应用"
 API[业务 API]
 end

 BROWSER -->|登录/注册| FE_SDK
 MOBILE -->|登录/注册| FE_SDK
 SPA -->|登录/注册| FE_SDK
 FE_SDK -->|调用 signIn/signUp API| BE_SDK
 BE_SDK -->|认证逻辑与 DB 操作| CORE
 CORE --> DB
 BE_SDK -->|session 验证中间件| API
 API -->|验证 session| BE_SDK

 style CORE fill:#4a90d9,color:#fff
 style FE_SDK fill:#e67e22,color:#fff
 style BE_SDK fill:#27ae60,color:#fff

三层各自职责：

Zitadel 深度解读 — 事件驱动、多租户原生的开源 IAM 平台 | IDaaS Book

Wed, 08 Jul 2026 00:00:00 +0800

Zitadel 简介

Zitadel 是一个用 Go 编写的开源身份与访问管理平台，截至 2026 年 7 月最新稳定版为 v4.15.3（AGPL-3.0 许可证），GitHub 约 14,300 星。项目的核心理念是"Identity infrastructure, simplified for you"——通过事件驱动架构和原生多租户设计，把身份基础设施的复杂性封装成简洁的 API 和管理界面。

一句话定位：事件溯源架构 + CQRS + 原生多租户的开源 IAM，适合需要完整审计追踪和多租户隔离的服务型平台。

维度	信息
项目	github.com/zitadel/zitadel
语言	Go (后端) + TypeScript/Angular (前端)
数据库	PostgreSQL（推荐）或 CockroachDB
许可证	AGPL-3.0
文档	zitadel.com/docs
在线 SaaS	zitadel.cloud

核心设计哲学

Zitadel 的设计和其他 IAM 有一个根本性的不同：它把"发生了什么"当作一等公民存储，而不是只存"当前状态是什么"。这来自于三个核心选择：

Event Sourcing（事件溯源）：不存储用户/项目的"当前快照"。每个操作——创建用户、修改密码、变更角色——都记录为不可变事件。当前状态是重放所有事件计算出来的。这意味着任何时间点的状态都可以追溯，任何变更都有完整审计线索。
CQRS（命令查询职责分离）：写操作（命令）和读操作（查询）走不同的数据路径。命令生成事件，事件被投影到查询优化的视图。这让 Zitadel 可以独立扩展读写能力，尤其适合读多写少的身份场景。
原生多租户：从数据库 Schema 到 API 路由，多租户不是后加的特性，而是骨子里的设计。每个"Instance"（实例）可以有多个"Organization"（组织），每个 Organization 有独立的用户、项目、应用、授权策略。

架构全景

 flowchart TB
 subgraph "用户与应用"
 U[用户浏览器]
 APP[下游应用 / API]
 MGMT[管理员]
 end

 subgraph "Zitadel 核心"
 direction TB
 API_L["API Layer<br/>REST + gRPC"]
 
 subgraph "Command Side (写)"
 CMD[Command Handler<br/>命令处理器]
 ES[(Event Store<br/>事件存储<br/>PostgreSQL)]
 end
 
 subgraph "Query Side (读)"
 PROJ[Projections<br/>查询投影]
 QV[(Query Views<br/>查询视图)]
 end
 
 AUTHN[认证引擎<br/>OIDC / OAuth2 / SAML]
 AUTHZ[授权引擎<br/>RBAC + IAM Policy]
 end

 subgraph "存储层"
 PG[(PostgreSQL<br/>事件存储 + 查询视图)]
 end

 subgraph "通知与任务"
 JOB[后台任务<br/>通知/生命周期]
 end

 U -->|登录/注册| AUTHN
 APP -->|Token 验证| AUTHN
 APP -->|API 调用| API_L
 MGMT -->|管理操作| API_L
 
 API_L --> CMD
 CMD --> ES
 ES --> PROJ
 PROJ --> QV
 API_L -.->|查询| QV
 
 AUTHN --> CMD
 AUTHN -.->|验证| QV
 AUTHZ -.->|策略评估| QV
 
 CMD --> JOB

这个架构有几个值得展开的要点：