Keycloak开源企业级IAM

Keycloak 是 RedHat 主导的开源企业级IAM（身份认证与访问管理） ，对标商业产品如 Oracle OAM、IBM Tivoli，是微服务/云原生架构下统一认证与SSO的首选开源中间件。

一、核心定位与价值

• 一句话：把"登录、认证、授权、用户管理"从业务系统中抽离，集中托管，应用只需要对接标准协议，不用自研账号体系。
• 适用场景：微服务/多系统SSO、企业统一账号、多端（Web/App/小程序）认证、第三方登录集成、替代商业IAM。
• 授权协议 ：Apache 2.0，完全开源免费、可商用。
• 架构：Java + Quarkus（新版），轻量高性能，支持集群与水平扩展。

二、核心功能（企业级能力）

1. 单点登录 SSO（最常用）

• 一次登录，访问所有信任应用；支持单点登出SLO。
• 协议：OpenID Connect(OIDC)、OAuth2.0、SAML2.0，全覆盖。

2. 用户与权限管理

• Realm（租户隔离）：多租户天然支持，隔离不同业务线用户与配置。
• 用户/角色/组管理、RBAC+细粒度权限、密码策略、账号锁定/过期。
• 用户联邦（User Federation）：无缝对接LDAP/AD、MySQL、第三方IdP，无需迁移用户。

3. 安全增强

• MFA多因素认证：TOTP（谷歌验证器）、短信、邮件、WebAuthn（指纹/人脸/硬件Key）。
• 社交登录：GitHub/Google/微信/支付宝等快速接入。
• JWT令牌管理：签发、过期、撤销、非对称加密验签。
• 审计日志：全链路认证/授权/操作日志，合规审计必备。

4. 企业级集成

• 适配：Spring Boot/Spring Cloud、Node.js、Python、Go、移动端。
• 网关集成：可与Spring Cloud Gateway、APISIX、Kong无缝对接，统一入口鉴权。

三、核心概念（快速理解）

• Realm：独立身份域，隔离用户、应用、权限（如企业内"内部系统""客户系统"分属不同Realm）。
• Client：接入Keycloak的应用/服务（如Web后台、App、网关）。
• User/Role/Group：用户、角色、用户组，用于权限分配。
• IdP（Identity Provider）：第三方身份源（如LDAP、GitHub、微信）。

四、与同类产品对比

产品	优势	劣势	适用场景
Keycloak	全功能、标准协议、多租户、开源免费、生态强	部署略重、配置项多	企业级统一认证、微服务SSO
Sa-Token	轻量、易集成、国产文档好	企业级能力弱（无SAML/复杂MFA）	中小项目、单体应用、简单微服务
Casdoor	轻量、UI友好、国产	成熟度与生态不及Keycloak	创业公司、内部工具

五、快速部署（Docker，5分钟）

# 启动容器
docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin123 \
  quay.io/keycloak/keycloak:26.6.0 start-dev

访问：http://localhost:8080，创建Realm、Client、用户即可接入应用。

六、企业落地建议

• 生产环境：用Quarkus原生镜像、外置数据库（PostgreSQL）、集群部署、配置HTTPS与定期备份。
• 微服务架构：网关（Spring Cloud Gateway/APISIX）统一对接Keycloak，后端服务校验JWT令牌。
• 替代商业IAM：完全替代Oracle OAM、IBM Tivoli、PingFederate等，节省百万级授权费用。

Keycloak + Spring Cloud Gateway 极简集成示例（可直接跑）

场景：网关统一鉴权，所有微服务统一 OIDC/OAuth2 登录，SSO 单点登录。

一、前置

1. 启动 Keycloak（Docker 快速启动）

docker run -d \
--name keycloak \
-p 8080:8080 \
-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=123456 \
quay.io/keycloak/keycloak:25.0 start-dev

访问：http://127.0.0.1:8080

• 新建 Realm：demo-realm
• 新建 Client：demo-gateway
• 有效重定向URI：http://localhost:9000/*
• 开启：Confidential，记录客户端秘钥

---

二、Gateway 网关依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<!-- OAuth2 / OIDC 对接 Keycloak -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

---

三、application.yml 核心配置

server:
  port: 9000

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: demo-gateway
            client-secret: 你的keycloak客户端秘钥
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
            scope: openid,profile,email
        provider:
          keycloak:
            issuer-uri: http://localhost:8080/realms/demo-realm
      # 网关作为资源服务，校验JWT
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/realms/demo-realm

  cloud:
    gateway:
      routes:
        - id: demo-service
          uri: lb://demo-service
          predicates:
            - Path=/api/**

---

四、全局安全配置（核心代码）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.oauth2.client.registration.ReactiveClientRegistrationRepository;
import org.springframework.security.oauth2.client.web.server.DefaultServerOAuth2AuthorizationRequestResolver;
import org.springframework.security.web.server.SecurityWebFilterChain;

@Configuration
@EnableWebFluxSecurity
public class SecurityConfig {

    @Bean
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http,
                                                         ReactiveClientRegistrationRepository clientRegRepo) {
        DefaultServerOAuth2AuthorizationRequestResolver resolver =
                new DefaultServerOAuth2AuthorizationRequestResolver(clientRegRepo);

        http
            .authorizeExchange(exchange -> exchange
                .pathMatchers("/public/**").permitAll()
                .anyExchange().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .authorizationRequestResolver(resolver)
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt())
            .csrf(csrf -> csrf.disable());

        return http.build();
    }
}

---

五、效果

1. 访问网关 http://localhost:9000/api/xxx
2. 自动跳转到 Keycloak 登录页
3. 登录成功自动回调网关，种下 JWT 令牌
4. 网关携带令牌转发到下游微服务
5. 下游服务可直接解析 JWT 获取用户、角色

---

六、下游微服务最简鉴权（只需要配置）

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/realms/demo-realm

直接通过 @PreAuthorize("hasRole('xxx')") 做接口权限控制。

---

七、核心优势

• 完全开源免费，替代昂贵商用 SSO/IAM
• 标准 OIDC/OAuth2，前后端、App、小程序都能接
• 统一登录、统一登出、多租户、MFA 二次认证
• 微服务/云原生架构最佳实践

需要单独部署，必须独立服务、独立端口、独立数据库，不能嵌入项目、不能集成在SpringBoot里一起跑。

---

一、为什么 Keycloak 必须单独部署

1. 定位是独立中间件
   Keycloak 是独立 IAM/SSO 身份中台，和 Redis、RocketMQ、Nacos 一个级别：

• 独立进程
• 独立域名/IP+端口
• 独立数据库
• 独立集群扩容、独立运维

2. 多系统统一登录

   公司几十个系统、网关、App、后台，全部对接同一个 Keycloak，

   如果嵌在某个业务项目里，项目挂了=全公司所有系统全部无法登录。

3. 协议与架构决定

   基于标准 OIDC/OAuth2/SAML，需要：

• 固定登录回调地址
• 统一令牌签发、过期、吊销
• 独立会话管理、单点登出
  只能单独部署。

---

二、部署形态（三种，任选）

1）Docker 部署（开发/测试最简单）

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=123456 \
  quay.io/keycloak/keycloak:25.0 start-dev

开箱即用，本地开发首选。

2）二进制安装包（虚拟机/服务器）

官方压缩包，start.sh 启动，外置数据库。

3）K8s 集群部署（生产标配）

Helm 一键部署，集群高可用、持久化、HTTPS、多副本。

---

三、能不能合并部署？（不推荐）

1. ❌ 不能打成 SpringBoot 依赖内嵌启动
2. ❌ 不能和网关、业务服务共用一个进程
3. ⚠️ 同一台服务器可以不同端口 部署（允许）
   例如：

• Gateway：9000
• Keycloak：8080
• 业务服务：8090
  同一机器、独立进程，没问题。

---

四、生产最低标配（企业使用）

1. 单独服务器/容器
2. 外置数据库（MySQL/PostgreSQL），不要内置H2
3. 开启 HTTPS
4. 多副本集群，防止单点故障
5. 定时备份用户、角色、Realm配置

---

五、和你项目的关系

• 你的 SpringCloud 网关、微服务 只做对接
• 所有登录页面、账号密码、验证码、MFA 全在 Keycloak
• 业务系统只需要校验JWT，完全不用写登录逻辑

---

六、轻量替代（如果不想单独部署）

如果嫌 Keycloak 太重、不想多维护一个中间件：

• 国产轻量替代：Sa-Token、Casdoor
• 可内嵌、部署简单、适合中小项目

---

一句话总结

1. Keycloak 是独立中间件，强制单独部署
2. 开发用 Docker 快速搭，生产独立集群+外置库
3. 多系统统一 SSO 选它；小项目嫌重就换 Sa-Token/Casdoor

简单说：Distribution powered by Quarkus = 现在的 Keycloak 官方发行版，用 Quarkus 替代了原来的 WildFly（JBoss），主打云原生、启动快、内存小、容器友好。

一、这句话是什么意思

• Distribution：就是 Keycloak 的服务器安装包（zip / tar.gz / Docker 镜像）。
• powered by Quarkus ：底层不再是旧的 WildFly 应用服务器，而是 Quarkus 框架（RedHat 出品，云原生 Java 框架）。
• 从 Keycloak 17+ 开始，默认发行版都是 Quarkus 版；旧 WildFly 版已废弃。

二、Quarkus 版和旧版（WildFly）的关键区别

特性	旧版（WildFly）	新版（Quarkus）
底层	应用服务器（重）	云原生框架（轻）
启动速度	慢（秒级）	极快（毫秒级）
内存占用	高（1--2GB）	低（200--500MB）
容器友好	一般	强（不可变镜像、K8s 友好）
默认路径	/auth	根路径 /（去掉了 /auth）
配置方式	复杂（XML + 大量配置）	简化（CLI + env + yaml）
热部署	支持	不支持（编译期优化）

简单记：Quarkus 版更适合 Docker / K8s，更省资源，启动飞快，生产必用。

三、对你的影响（实操层面）

1. 部署命令变了

   • 旧版：standalone.sh
   • 新版：kc.sh（核心脚本）

   # 开发模式（本地测试）
   ./kc.sh start-dev
   
   # 生产模式（必须构建优化）
   ./kc.sh build
   ./kc.sh start

2. 路径变了

   • 旧版：http://localhost:8080/auth
   • 新版：http://localhost:8080（直接根路径）

3. Docker 镜像就是它

   你之前用的：

   quay.io/keycloak/keycloak:25.0

   这个镜像 就是 Quarkus 发行版，不用额外选。

四、一句话总结

Distribution powered by Quarkus = 现代、轻量、云原生的 Keycloak，替代了老旧的 WildFly 版，现在安装/部署/容器化都默认用它。