当前位置：首页 > news >正文

开源身份和访问管理（IAM）解决方案:Keycloak

news 来源：原创 2025/7/29 5:32:44

一、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