开源身份和访问管理（IAM）解决方案:Keycloak
一、Keycloak介绍
1、什么是 Keycloak？
Keycloak 是一个开源的身份和访问管理（Identity and Access Management - IAM）解决方案。它旨在为现代应用程序和服务提供安全保障，简化身份验证和授权过程。Keycloak 提供了集中式的用户管理、单点登录（Single Sign-On - SSO）、身份联合、社交登录等功能，帮助开发者专注于业务逻辑，而无需从头开始构建复杂的安全系统。
-
名称：Keycloak
-
开源地址：https://github.com/keycloak/keycloak
-
官方网站：Keycloak
-
开发语言：Java（基于 WildFly 或 Quarkus 构建）
-
协议：Apache License 2.0
Keycloak 由 Red Hat 领导开发，是 Red Hat SSO 商业版的上游项目。
2、核心概念
理解 Keycloak 的核心概念对于有效使用它至关重要：
- Realm（域）： Realm 是 Keycloak 中最高级别的组织单元，用于隔离不同的环境、组织或租户。每个 Realm 拥有自己独立的用户、角色、客户端和配置。你可以将不同的应用程序或部门放在不同的 Realm 中进行管理。例如，你可以创建一个用于开发环境的 Realm，一个用于生产环境的 Realm，或者为不同的客户创建独立的 Realm。
- Client（客户端）： Client 代表需要 Keycloak 保护的应用程序或服务。可以是 Web 应用程序、移动应用程序、API 等。每个 Client 都需要在 Keycloak 中注册，并配置其访问权限和认证方式。Keycloak 支持多种客户端类型，例如：
- Confidential: 需要密钥进行认证的客户端，通常用于后端服务或服务器端 Web 应用。
- Public: 不需要密钥进行认证的客户端，通常用于浏览器端 Web 应用或移动应用。
- Bearer-only: 仅用于接收和验证 Bearer 令牌的客户端，通常用于受保护的 API。
- User（用户）： User 代表需要访问受保护应用程序或服务的个人或实体。Keycloak 提供用户管理功能，包括创建、删除、更新用户，以及管理用户的凭据（密码、证书等）。用户可以属于一个或多个 Realm。
- Role（角色）： Role 定义了用户在应用程序或服务中拥有的权限。角色可以在 Realm 级别定义（Realm Roles），也可以在特定客户端级别定义（Client Roles）。通过将角色分配给用户，可以控制用户可以执行的操作。例如，可以定义 "admin"、"user"、"editor" 等角色。
- Group（组）： Group 是用户的集合，用于简化角色分配和权限管理。可以将一组用户添加到组中，然后将角色分配给整个组，而不是单独分配给每个用户。组可以形成层级结构。
- Identity Provider（身份提供者）： Identity Provider 是外部的身份验证系统，Keycloak 可以与之集成，实现身份联合。这意味着用户可以使用他们在其他系统（例如：Google、Facebook、GitHub、LDAP、SAML IdP 等）中的凭据登录到受 Keycloak 保护的应用程序。
- Authentication Flow（认证流）： Authentication Flow 定义了用户进行身份验证时需要经历的步骤。Keycloak 提供了灵活的认证流配置，可以根据需求自定义认证过程，例如添加多因素认证（MFA）、CAPTCHA 验证等。
- Protocol Mapper（协议映射器）： Protocol Mapper 用于将 Keycloak 中的用户信息（例如：角色、属性）映射到特定协议（例如：OAuth 2.0、SAML）的令牌声明中。这使得应用程序可以从令牌中获取用户的相关信息。
3、主要功能和特点
Keycloak 提供了丰富的功能，使其成为一个强大的 IAM 解决方案：
- 单点登录（SSO）： 用户只需要登录一次 Keycloak，就可以访问所有受其保护的应用程序和服务，无需为每个应用单独登录。支持标准协议：OpenID Connect（OIDC）、OAuth 2.0、SAML 2.0
- 身份联合（Identity Federation）： 可以集成现有的身份验证系统（例如：LDAP、Active Directory、社交登录提供商），允许用户使用已有的凭据进行登录。
- 社交登录（Social Login）： 支持通过常见的社交媒体账户（例如：Google、Facebook、Twitter、GitHub）进行身份验证，提升用户体验。
- 用户管理： 提供用户创建、删除、更新、密码管理、用户属性管理等功能。
- 角色和权限管理： 支持细粒度的角色定义和权限控制，可以基于角色或组来管理用户对应用程序和资源的访问权限。通过 Role-based Access Control（RBAC） 和 Attribute-based Access Control（ABAC） 管理访问权限。可与 Keycloak Authorization Services 配合进行细粒度控制。
- 多因素认证（MFA）： 可以配置多种 MFA 机制，例如基于时间的一次性密码（TOTP）、短信验证码等，提高安全性。
- OAuth 2.0 和 OpenID Connect 支持： 遵循行业标准协议，方便与各种现代应用程序和服务集成。
- SAML 2.0 支持： 支持与传统的企业应用程序集成。
- 细粒度的授权策略： 提供基于属性、角色、时间等多种因素的授权策略，实现更复杂的访问控制。
- 管理控制台： 提供基于 Web 的管理界面，方便管理员进行配置和管理。
- RESTful API： 提供丰富的 RESTful API，允许通过编程方式进行管理和集成。
- 可扩展性： 支持水平扩展，可以处理大量的用户和请求。
- 自定义性： 允许自定义主题、认证流程、用户属性等。
- 审计日志： 记录用户的登录、登出、权限变更等操作，方便进行安全审计。
4、架构
Keycloak 的核心是一个服务器，通常部署在一个或多个实例中以实现高可用性。其主要组件包括：
- Keycloak Server: 负责处理所有的身份验证和授权请求，管理用户、角色、客户端等信息。
- Database: 用于存储 Keycloak 的配置数据、用户信息、会话信息等。Keycloak 支持多种数据库，例如：PostgreSQL、MySQL、MariaDB、Oracle、SQL Server 等。
- Admin Console: 基于 Web 的管理界面，用于配置和管理 Keycloak 服务器。
- Client Adapters: 针对不同编程语言和框架提供的客户端库，简化了应用程序与 Keycloak 的集成。例如：Keycloak Spring Boot Adapter、Keycloak Node.js Adapter 等。
5、使用场景
Keycloak 可以应用于各种场景，包括但不限于：
- 保护 Web 应用程序： 实现用户身份验证和授权，防止未经授权的访问。
- 保护 RESTful API： 使用 OAuth 2.0 协议保护后端 API，确保只有授权的客户端可以访问。
- 单点登录（SSO）： 为多个相关的应用程序提供统一的登录体验。
- 身份联合： 将内部用户目录与外部身份提供者集成，方便用户使用现有账户登录。
- 微服务安全： 为微服务架构提供统一的身份验证和授权解决方案。
- SaaS 应用程序： 为多租户 SaaS 应用程序提供安全的身份和访问管理。
- 物联网（IoT）： 管理和认证物联网设备的身份。
6、优势
使用 Keycloak 的主要优势包括：
- 简化开发： 开发者无需从头开始构建复杂的安全系统，可以专注于业务逻辑。
- 提高安全性： 提供标准的身份验证和授权机制，降低安全风险。
- 统一管理： 集中管理用户、角色和权限，方便维护和管理。
- 提升用户体验： 提供单点登录和社交登录等功能，改善用户体验。
- 标准化： 基于行业标准协议（OAuth 2.0、OpenID Connect、SAML），易于集成。
- 开源免费： 可以免费使用，并拥有活跃的社区支持。
- 高度可定制： 可以根据需求进行定制和扩展。
7、缺点和注意事项
虽然 Keycloak 功能强大，但也需要注意一些方面：
- 学习曲线： 对于初学者来说，理解其复杂的概念和配置可能需要一定的学习成本。
- 部署和维护： 需要一定的运维知识来部署、配置和维护 Keycloak 服务器。
- 性能考虑： 在高并发场景下，需要合理配置和优化 Keycloak 以保证性能。
- 依赖性： 应用程序需要依赖 Keycloak 进行身份验证和授权，如果 Keycloak 服务不可用，可能会影响应用程序的功能。
8、入门
要开始使用 Keycloak，可以按照以下步骤进行：
- 下载 Keycloak： 访问 Keycloak 官方网站下载最新版本的 Keycloak 服务器。
- 启动 Keycloak 服务器： 按照官方文档的说明启动 Keycloak 服务器。
- 访问管理控制台： 在浏览器中访问 Keycloak 管理控制台（通常是
http://localhost:8080/admin）。 - 创建 Realm： 创建一个或多个 Realm 来组织你的应用程序和用户。
- 创建 Client： 为你的应用程序注册一个或多个 Client。
- 创建 User 和 Role： 创建用户并分配相应的角色。
- 配置 Authentication Flow（可选）： 根据需求自定义认证流程。
- 集成你的应用程序： 使用 Keycloak 提供的客户端适配器或 SDK 将你的应用程序与 Keycloak 集成。
Keycloak 是一个功能强大且灵活的开源 IAM 解决方案，可以帮助你构建安全可靠的应用程序和服务。通过理解其核心概念和功能，你可以有效地利用 Keycloak 来管理用户身份、控制访问权限并提升整体安全性。
二、与相关产品的对比
1、与其他系统对比
| 功能/系统 | Keycloak | Auth0 | Okta | Firebase Auth |
|---|---|---|---|---|
| 开源/本地部署 | ✅ | ❌ | ❌ | ❌ |
| 多协议支持 | ✅ | ✅ | ✅ | 部分支持 |
| 多租户 | ✅ | ✅ | ✅ | ❌ |
| 企业集成能力 | 强 | 强 | 强 | 弱 |
| 社区活跃度 | 高 | 高 | 高 | 高2 |
2、与IBM ISVA对比
Keycloak 与 IBM Security Verify Access（ISVA，原 IBM Access Manager）都是强大的身份和访问管理解决方案，但它们在定位、架构、功能深度、开源性、部署方式等方面有显著区别。
下面从多个维度来详细对比 Keycloak 与 IBM ISVA：
1.产品定位与背景
| 维度 | Keycloak | IBM ISVA |
|---|---|---|
| 厂商背景 | Red Hat（开源），社区主导；Red Hat SSO 为商业支持版 | IBM，成熟商业产品，定位中大型企业 |
| 开源/商业 | 100% 开源（Apache 2.0）；Red Hat SSO 为付费支持版本 | 商业授权，闭源；按用户/部署数收费 |
| 主要用户群体 | 开发者、云原生团队、SaaS 平台、DevOps | 大型企业、政企客户、安全审计严格行业（金融、政府） |
| 支持平台 | 任意平台（Kubernetes、Docker、物理机） | IBM Cloud、VM、硬件设备、传统基础设施为主 |
2.架构与部署方式
| 维度 | Keycloak | IBM ISVA |
|---|---|---|
| 部署灵活性 | 非常高，支持容器化、Kubernetes、OpenShift | 较为复杂，推荐配合 WebSeal 网关、Appliance 运行 |
| 云原生支持 | 完善，支持 Operator、Helm、K8s | 有一定支持，但更多是传统部署方式 |
| 组件结构 | 轻量级单体（Quarkus/WildFly）+ 可插拔 SPI | 模块化复杂（AAC、WGA、WebSeal、Policy Server） |
| 运维难度 | 中等（开源文档齐全，需 DevOps 能力） | 较高（依赖 IBM 专业服务，配置复杂） |
3.功能对比
| 功能模块 | Keycloak | IBM ISVA |
|---|---|---|
| 身份认证协议支持 | OAuth2, OIDC, SAML2 | OAuth2, OIDC, SAML2, WS-Fed |
| SSO（单点登录） | ✅ 全面支持 | ✅ 深度支持 |
| 身份联合（Federation） | ✅ 通过 IdP/SAML/OIDC 实现 | ✅ 更强，支持复杂身份桥接 |
| 多因素认证（MFA） | ✅ 支持 TOTP/SMS/WebAuthn | ✅ 支持丰富硬件/软件 MFA |
| LDAP/AD 集成 | ✅ 原生支持 | ✅ 强大支持（可多源、同步、映射） |
| 授权服务（RBAC/ABAC） | ✅ 基于角色 + 资源策略 | ✅ 支持细粒度规则、策略引擎（JAVASCRIPT、XACML） |
| API 保护 | ✅ OAuth2 Bearer Token | ✅ 支持 Token、网关策略、多层保护 |
| SOC/审计支持 | 中等（事件系统可拓展） | 非常强（支持 SIEM 对接、详尽审计） |
| 密码策略 | 支持自定义规则 | 更加严谨、可配复杂策略 |
| 高级功能 | 插件自定义灵活，支持 SPI 开发 | 强大的访问网关（WebSeal）、风险引擎、访问控制链路 |
4.扩展性与集成能力
| 维度 | Keycloak | IBM ISVA |
|---|---|---|
| 插件扩展能力 | 非常强（SPI 架构） | 强，但需 IBM 工具和语言 |
| 集成常见 SaaS 应用 | 支持 SAML/OIDC 标准化接入 | 提供大量模板和企业应用连接器 |
| 与企业 IT 架构整合能力 | 偏向新架构（微服务、K8s） | 对传统 IT（SOA、WAS、Portal）支持更好 |
5.成本对比
| 项目 | Keycloak | IBM ISVA |
|---|---|---|
| 软件授权 | 免费 | 商业授权，按用户/服务计费 |
| 技术支持 | 社区支持；可选 Red Hat SSO 商业支持 | IBM 官方支持；费用较高 |
| 运维成本 | 相对较低；需 DevOps 技能 | 较高；建议专业团队维护 |
| 总体 TCO（总拥有成本） | 低 | 高，但适合合规严格场景 |
6.使用场景总结
| 场景 | 更推荐 Keycloak | 更推荐 IBM ISVA |
|---|---|---|
| 微服务、容器云 | ✅ | ❌ |
| 企业微信/钉钉/OIDC 集成 | ✅ | ✅ |
| 多租户 SaaS 平台 | ✅（Realm 多租户） | ❌ |
| 高安全级别访问控制 | 中等支持 | ✅ 强大策略系统 |
| 传统大型企业安全体系 | ❌ | ✅ |
| 快速开发、灵活定制 | ✅ | ❌（开发成本高） |
7.总结一句话：
Keycloak 适合快速集成、云原生环境、开源爱好者与 SaaS 项目；而 IBM ISVA 更适合复杂企业架构、高安全/合规需求、传统 IT 系统整合。
3、Keycloak和IBM ISVA的重点差异
和 IBM ISVA 相比，Keycloak 在“后台审计”和“后台授权”这两个企业级关键能力上相对较弱。我们来具体拆解一下这两个点：
1.Keycloak 的后台审计功能：基本够用，但不够“企业级”
✅ Keycloak 的优势：
-
支持基本事件记录（例如登录成功/失败、用户创建、密码更改等）；
-
可配置事件监听器（Event Listener SPI），将事件导出到：
-
日志文件（stdout、file）；
-
Syslog；
-
Kafka、数据库、自定义 webhook；
-
-
能够通过外部工具（如 ELK、Prometheus/Grafana）做二次整合和可视化。
❌ 相对较弱的地方：
-
无内建的 审计策略引擎（如 ISVA 的 audit framework）；
-
缺乏基于审计事件的风险响应机制（如异常行为触发阻断/预警）；
-
审计事件粒度有限，尤其在访问控制链路、Token 使用路径上不够详细；
-
不原生支持合规性框架映射（如 GDPR、ISO 27001、SOC 2 等）。
2.Keycloak 的后台授权功能：适合中等复杂度，难胜任高安全场景
✅ Keycloak 的能力：
-
支持 RBAC（基于角色）授权：配置用户 → 角色 → 客户端；
-
支持 资源级访问控制（需启用 Authorization Services）：
-
定义资源、策略、权限；
-
支持 JS-based 规则、时间、IP、用户属性等；
-
-
提供 REST API 用于动态授权校验。
❌ 相对 ISVA 来说的劣势：
| 项目 | Keycloak | ISVA |
|---|---|---|
| 授权模型深度 | 中（RBAC/简单 ABAC） | 强（复杂 ABAC、XACML） |
| 风险引擎 | 无 | 有（支持行为分析、IP 黑名单等） |
| 细粒度策略管理 | 有限（资源/作用域维度） | 强（URL 模式、应用上下文、设备状态） |
| 执行性能 | 好（适合轻量级微服务） | 高（适合关键核心系统） |
| 动态上下文响应 | 手动定制 | 内建风险评估引擎 |
举例来说，ISVA 可以实现下面这种访问策略：
「当用户使用海外 IP 并且访问敏感资源（如工资系统）时，要求双因素认证且操作记录写入 SIEM。」
而 Keycloak 本体是很难做到这样的上下文感知授权判断的，除非做大量自定义插件开发。
3.总结一句话
Keycloak 擅长轻量级认证与基础授权，适合现代应用快速集成；ISVA 擅长深度授权与合规审计，适合对安全性要求极高的核心系统。
4.建议使用策略（基于场景）：
| 场景 | 推荐用 Keycloak | 推荐用 ISVA |
|---|---|---|
| 前端登录认证、移动 App、SPA 接入 | ✅ | ❌ |
| 对外 SSO、OAuth2 登录联邦 | ✅ | ✅ |
| 复杂后台权限校验（设备、行为、IP 等） | ⚠️（需扩展） | ✅ |
| 合规性强审计（金融、政务） | ⚠️（需外接 ELK） | ✅ |
| 异常行为识别、动态授权响应 | ❌ | ✅ |
如果你已经用 Keycloak 接入了新系统，但还在用 ISVA 守护传统系统，可以考虑采用混合架构 —— Keycloak 做前端认证分发，ISVA 做后端审计授权，达到“前轻后重”的最佳效果。
4、Keycloak + IBM ISVA 联合使用的混合身份架构图
下面是一个典型的 Keycloak + IBM ISVA 联合使用的混合身份架构图，满足以下目标：
-
✅ Keycloak 负责现代系统接入、OIDC/SAML 登录、前端认证体验；
-
✅ ISVA 负责核心系统保护、高安全授权、合规审计；
-
✅ 用户通过 Keycloak 登录，部分场景联合跳转至 ISVA；
-
✅ 可选：共用统一企业 LDAP/AD。
🧭 架构说明：
┌─────────────────────────────┐
│ 用户 / 客户端 │
└────────────┬────────────────┘│ 1. 访问前端 / App▼┌──────────────────┐│ Keycloak │ ◄──────────────────────────────────────────────┐│ （统一登录入口） │ │└──────┬───────────┘ ││ │┌─────▼───────────────┐ ┌─────────────▼────────────┐│ OIDC/SAML 登录认证 │ │ ISVA 身份认证网关 ││（外部 IdP / AD 联合）│ ──▶▶ SAML/OIDC Federation ──▶│ WebSeal + AAC 模块 │└─────┬───────────────┘ └─────────────┬────────────┘│ │┌──────▼───────────────┐ ││ Keycloak 授权 Token │ ││ （JWT / AccessToken） │ │└──────┬───────────────┘ │▼ ▼┌────────────────────┐ ┌────────────────────────┐│ 新应用系统 / API网关 │ │ 核心系统（工资、合同、审批） ││ （基于 OIDC 接入） │ │ （基于 WebSeal 防护） │└────────────────────┘ └────────────────────────┘共用统一 LDAP/AD 目录作为身份源┌─────────────────────────────────────────────┐│ 企业 AD / LDAP / HR 系统（身份主目录） │└─────────────────────────────────────────────┘Keycloak 与 ISVA 可接入统一 SIEM / ELK 审计系统┌─────────────────────────────────────────────┐│ 审计平台（SIEM、ELK、Qradar、Splunk） │└─────────────────────────────────────────────┘
🔍 关键要点解析：
| 模块 | 说明 |
|---|---|
| Keycloak | 作为统一身份认证入口，支持 OIDC/SAML 多协议，兼容现代应用。可自定义登录页、支持多租户、多 IdP 联合登录。 |
| ISVA | 对于需要高安全审计和复杂授权的应用，通过联合认证（Federation）接入 ISVA，由其完成二次身份校验与行为控制。 |
| 统一身份源 | Keycloak 与 ISVA 可共同对接统一 LDAP / AD，实现用户同步与一致性。 |
| SIEM / 审计系统 | 审计日志可分别收集 Keycloak 登录事件与 ISVA 安全事件，汇总进统一平台，增强审计与合规能力。 |
📌 可选增强项：
-
可在 Keycloak 启用 事件监听器插件，将事件实时推送至 Kafka / Elastic；
-
ISVA 可配置 风险评估策略，如地理位置 / 异常行为自动触发 MFA；
-
两者之间的联合登录可通过 SAML2 或 OIDC 联邦桥接方式实现；
-
可增加 API Gateway（如 Kong、APISIX、3scale）对接 Keycloak 做 API 授权。
三、本地安装部署Keycloak
1、方法一：使用 Docker (推荐用于本地开发和测试)
Docker 是一个容器化平台，可以让你轻松地运行 Keycloak 而无需担心依赖项和环境配置。
前提条件:
- 安装 Docker: 确保你的计算机上已经安装了 Docker 和 Docker Compose。你可以从 Docker 官方网站下载并安装：Docker Desktop: The #1 Containerization Tool for Developers | Docker
步骤:
-
创建 Docker Compose 文件 (可选但推荐):
- 创建一个名为
docker-compose.yml的文件在你的本地目录中。 - 将以下内容粘贴到文件中：
version: '3.8' services:keycloak:image: quay.io/keycloak/keycloak:latestenvironment:KEYCLOAK_ADMIN: adminKEYCLOAK_ADMIN_PASSWORD: adminports:- "8080:8080"command: ["start-dev"]- 解释:
version: '3.8': 指定 Docker Compose 文件的版本。services:: 定义要运行的服务。keycloak:: 定义名为keycloak的服务。image: quay.io/keycloak/keycloak:latest: 指定要使用的 Keycloak Docker 镜像。latest标签表示使用最新稳定版本。你也可以指定特定的版本号，例如quay.io/keycloak/keycloak:24.0.0.environment:: 设置 Keycloak 的环境变量。KEYCLOAK_ADMIN: admin: 设置初始管理员用户的用户名。你可以修改为你想要的用户名。KEYCLOAK_ADMIN_PASSWORD: admin: 设置初始管理员用户的密码。强烈建议在生产环境中使用更安全的密码。
ports:: 将容器的 8080 端口映射到主机的 8080 端口。这样你就可以通过主机的 8080 端口访问 Keycloak。command: ["start-dev"]: 使用开发模式启动 Keycloak。这适用于本地开发和测试。
- 创建一个名为
-
启动 Keycloak:
- 打开你的终端或命令提示符，导航到包含
docker-compose.yml文件的目录。 - 运行以下命令：
-d参数表示在后台运行容器。
#配置加速 sudo mkdir -p /etc/docker cat <<EOF | sudo tee /etc/docker/daemon.json {"registry-mirrors": ["https://dockerproxy.com","https://registry.docker-cn.com","https://mirror.baidubce.com"] } EOF sudo systemctl daemon-reexec sudo systemctl restart dockerdocker-compose up -d - 打开你的终端或命令提示符，导航到包含
-
访问 Keycloak 管理控制台:
- 在你的浏览器中访问
http://localhost:8080/. - 你应该会看到 Keycloak 的欢迎页面。
- 点击 "Administration Console"。
- 使用你在
docker-compose.yml文件中设置的用户名 (admin) 和密码 (admin) 登录。
- 在你的浏览器中访问
-
停止 Keycloak:
- 在终端或命令提示符中，导航到包含
docker-compose.yml文件的目录。 - 运行以下命令：
docker-compose down- 这会停止并删除 Keycloak 容器。
- 在终端或命令提示符中，导航到包含
2、方法二：直接从发行版运行 (Standalone)
这种方法需要你手动下载 Keycloak 的发行版并运行。
前提条件:
- 安装 Java Development Kit (JDK): Keycloak 需要 Java 11 或更高版本。确保你的计算机上安装了兼容的 JDK，并且
JAVA_HOME环境变量已正确配置。你可以从 Oracle 或 OpenJDK 下载。
wget https://download.oracle.com/java/21/latest/jdk-21_linux-x64_bin.deb
sudo dpkg -i jdk-21_linux-x64_bin.deb
sudo apt-get install -f
java -version步骤:
1.下载 Keycloak 发行版:
- 访问 Keycloak 官方下载页面：downloads - Keycloak
- 下载 "Server" 部分的 ZIP 文件 (例如：
keycloak-26podm.0.0.zip)。
2.解压发行版:
- 将下载的 ZIP 文件解压到你想要安装 Keycloak 的本地目录中。
- 配置数据库：在keycloak-26.2.0/conf目录下nano keycloak.conf
- 确保安装了数据库，修改之后运行：./bin/kc.sh build
- 然后创建管理员：./kc.sh bootstrap-admin user
3.运行 Keycloak:
./kc.sh start-dev
- 打开你的终端或命令提示符，导航到解压后的 Keycloak 目录。
- 进入
bin目录。 - 运行以下命令来启动 Keycloak 的开发模式：
- 在 Windows 上，使用
kc.bat start-dev。
4.访问 Keycloak 管理控制台:
- 在你的浏览器中访问
http://localhost:8080/. - 你应该会看到 Keycloak 的欢迎页面。
- 点击 "Administration Console"。
- 由于这是首次运行，你需要创建一个初始的管理员用户。按照屏幕上的提示设置用户名和密码。
5.停止 Keycloak:
- 在运行 Keycloak 的终端或命令提示符中，按下
Ctrl + C来停止服务器。
6.配置SSL
生成自签名证书
openssl req -newkey rsa:2048 -nodes -keyout keycloak.key -x509 -days 365 -out keycloak.crt 找到 Keycloak 配置文件 conf/keycloak.conf 或 conf/application.properties，然后添加：
hostname=your-domain.com
http-enabled=false
https-port=443
https-certificate-file=/path/to/keycloak.crt
https-certificate-key-file=/path/to/keycloak.key启动
./bin/kc.sh start配置Nginx或Apahce反向代理
server {listen 443 ssl;server_name your-domain.com;ssl_certificate /path/to/keycloak.crt;ssl_certificate_key /path/to/keycloak.key;location / {proxy_pass http://localhost:8080;proxy_set_header Host $host;proxy_set_header X-Forwarded-Proto https;}
}7.配置用户登录
如果新建的用户无法登录，下图两个不要选择。或者使用有效的TLS证书，如：使用 Let's Encrypt 或其他受信任的证书颁发机构（CA）来配置 HTTPS，而不是自签名证书。
3、方法三：配置带数据库
Step 1：使用国内源拉取 Keycloak 镜像
官方默认是 quay.io/keycloak/keycloak，国内可以用阿里云、DockerHub 镜像加速：
docker pull docker.io/bitnami/keycloak:24
或者配置镜像加速：
sudo mkdir -p /etc/docker
cat <<EOF | sudo tee /etc/docker/daemon.json
{"registry-mirrors": ["https://dockerproxy.com","https://registry.docker-cn.com","https://mirror.baidubce.com"]
}
EOF
sudo systemctl daemon-reexec
sudo systemctl restart docker
Step 2：准备数据库（PostgreSQL）
Keycloak 不推荐用 H2 数据库，建议搭配 PostgreSQL：
docker run -d --name keycloak-db \-e POSTGRES_DB=keycloak \-e POSTGRES_USER=keycloak \-e POSTGRES_PASSWORD=123456 \-p 5432:5432 \postgres:15
Step 3：启动 Keycloak（带数据库）
以下命令适配 Keycloak 21+，使用了 Quarkus 模式（默认方式）：
docker run -d --name keycloak \-e KC_DB=postgres \-e KC_DB_URL=jdbc:postgresql://host.docker.internal:5432/keycloak \-e KC_DB_USERNAME=keycloak \-e KC_DB_PASSWORD=123456 \-e KEYCLOAK_ADMIN=admin \-e KEYCLOAK_ADMIN_PASSWORD=admin123 \-p 8080:8080 \bitnami/keycloak:24 \start-dev
💡 注意：如果用的是 Linux，需要用
172.17.0.1或宿主机 IP 替代host.docker.internal。这个写法在 Windows/macOS 上是成立的，因为 Docker Desktop 对这些系统做了额外处理，让host.docker.internal指向宿主机。在 Linux 上，host.docker.internal是无效的！在容器内，Keycloak 只要访问：172.17.0.1:5432，就等于访问宿主机上开的数据库端口。宿主机（Linux） | |-- Docker bridge 网络：172.17.0.0/16||-- 宿主机网关 IP：172.17.0.1 （容器眼中的宿主机）||-- 容器1（PostgreSQL）：172.17.0.2|-- 容器2（Keycloak）： 172.17.0.3
Step 4：访问管理界面
浏览器打开：http://localhost:8080
账号：admin
密码：admin123
进入后台后你可以：
-
创建 Realm、用户、客户端；
-
配置 SSO、OAuth2；
-
汉化界面（导入中文包）；
-
启用 SAML/OIDC、Identity Provider。
国内如果下载慢：
sudo nano /etc/docker/daemon.json
添加如下内容（或合并已有的配置）：
{"registry-mirrors": ["https://registry.docker-cn.com","https://docker.mirrors.ustc.edu.cn","https://hub-mirror.c.163.com","https://mirror.baidubce.com"]
}
重启Docker服务
sudo systemctl daemon-reexec
sudo systemctl restart docker
4、一键启动脚本（Keycloak + PG）【可直接复制运行】
#!/bin/bash# 启动 PostgreSQL
docker run -d --name keycloak-db \-e POSTGRES_DB=keycloak \-e POSTGRES_USER=keycloak \-e POSTGRES_PASSWORD=123456 \-p 5432:5432 \postgres:15# 启动 Keycloak
docker run -d --name keycloak \-e KC_DB=postgres \-e KC_DB_URL=jdbc:postgresql://host.docker.internal:5432/keycloak \-e KC_DB_USERNAME=keycloak \-e KC_DB_PASSWORD=123456 \-e KEYCLOAK_ADMIN=admin \-e KEYCLOAK_ADMIN_PASSWORD=admin123 \-p 8080:8080 \bitnami/keycloak:24 \start-dev
5、Bonus：使用 docker-compose 快速部署
version: '3.8'
services:postgres:image: postgres:15container_name: keycloak-dbenvironment:POSTGRES_DB: keycloakPOSTGRES_USER: keycloakPOSTGRES_PASSWORD: 123456ports:- "5432:5432"keycloak:image: bitnami/keycloak:24container_name: keycloakdepends_on:- postgresenvironment:KC_DB: postgresKC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloakKC_DB_USERNAME: keycloakKC_DB_PASSWORD: 123456KEYCLOAK_ADMIN: adminKEYCLOAK_ADMIN_PASSWORD: admin123ports:- "8080:8080"command: start-dev
启动：
docker-compose up -d
6、首次设置 (适用于两种方法)
当你首次访问 Keycloak 管理控制台时，你需要创建一个初始的管理员用户。按照以下步骤操作：
- 访问管理控制台: 在浏览器中打开
http://localhost:8080/admin. - 创建管理员用户: 你将被重定向到一个页面，要求你设置管理员用户名和密码。
- 登录: 使用你刚刚创建的管理员用户名和密码登录。
- 开始使用: 登录成功后，你将进入 Keycloak 管理控制台，可以在这里创建 Realm、Client、User、Role 等。
7、重要注意事项:
- 开发模式 vs. 生产模式: 上述命令 (
start-dev和 Docker Compose 中的配置) 都是用于开发模式。在生产环境中，你需要使用不同的启动命令和配置，以确保安全性和性能。请参考 Keycloak 的官方文档获取生产环境的部署指南。 - 端口冲突: 如果你的计算机上已经有其他服务占用了 8080 端口，Keycloak 可能会启动失败。你可以尝试修改 Docker Compose 文件或 Keycloak 的配置文件来更改端口。
- 数据持久化 (Docker): 在上面的 Docker Compose 配置中，Keycloak 的数据不会持久化。这意味着当你停止并删除容器后，所有数据都会丢失。如果你需要在本地持久化数据，你需要配置 Docker 卷。
- 数据库配置 (Standalone): 默认情况下，Standalone 模式使用内嵌的 H2 数据库，这不适合生产环境。你可以配置 Keycloak 使用更可靠的外部数据库，例如 PostgreSQL、MySQL 等。
8、简单集成示例（Spring Boot + Keycloak）
# application.yml 示例
keycloak:realm: myrealmauth-server-url: http://localhost:8080/authresource: my-clientcredentials:secret: xxxxxbearer-only: true
spring:security:oauth2:resourceserver:jwt:issuer-uri: http://localhost:8080/auth/realms/myrealm