一、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，可以按照以下步骤进行：

1. 下载 Keycloak： 访问 Keycloak 官方网站下载最新版本的 Keycloak 服务器。
2. 启动 Keycloak 服务器： 按照官方文档的说明启动 Keycloak 服务器。
3. 访问管理控制台： 在浏览器中访问 Keycloak 管理控制台（通常是 http://localhost:8080/admin）。
4. 创建 Realm： 创建一个或多个 Realm 来组织你的应用程序和用户。
5. 创建 Client： 为你的应用程序注册一个或多个 Client。
6. 创建 User 和 Role： 创建用户并分配相应的角色。
7. 配置 Authentication Flow（可选）： 根据需求自定义认证流程。
8. 集成你的应用程序： 使用 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

步骤:

1. 创建 Docker Compose 文件 (可选但推荐):

   • 创建一个名为 docker-compose.yml 的文件在你的本地目录中。
   • 将以下内容粘贴到文件中：

   version: '3.8'
   services:
     keycloak:
       image: quay.io/keycloak/keycloak:latest
       environment:
         KEYCLOAK_ADMIN: admin
         KEYCLOAK_ADMIN_PASSWORD: admin
       ports:
         - "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。这适用于本地开发和测试。

2. 启动 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 docker
   
   
   docker-compose up -d
   

3. 访问 Keycloak 管理控制台:

   • 在你的浏览器中访问 http://localhost:8080/.
   • 你应该会看到 Keycloak 的欢迎页面。
   • 点击 "Administration Console"。
   • 使用你在 docker-compose.yml 文件中设置的用户名 (admin) 和密码 (admin) 登录。

4. 停止 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:15
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: 123456
    ports:
      - "5432:5432"

  keycloak:
    image: bitnami/keycloak:24
    container_name: keycloak
    depends_on:
      - postgres
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: 123456
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin123
    ports:
      - "8080:8080"
    command: start-dev

启动：

docker-compose up -d

6、首次设置 (适用于两种方法)

当你首次访问 Keycloak 管理控制台时，你需要创建一个初始的管理员用户。按照以下步骤操作：

1. 访问管理控制台: 在浏览器中打开 http://localhost:8080/admin.
2. 创建管理员用户: 你将被重定向到一个页面，要求你设置管理员用户名和密码。
3. 登录: 使用你刚刚创建的管理员用户名和密码登录。
4. 开始使用: 登录成功后，你将进入 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: myrealm
  auth-server-url: http://localhost:8080/auth
  resource: my-client
  credentials:
    secret: xxxxx
  bearer-only: true
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/auth/realms/myrealm