Keycloak 安装、配置与使用文档
身份认证与访问控制（IAM）解决方案实战指南
适用版本：Keycloak 22+（Quarkus 发行版）
适用场景：开发 / 测试 / 私有化部署
说明：本文档系统性介绍 Keycloak 的安装、基础配置及常见使用方式。生产环境请结合安全、性能与高可用要求进行额外加固。
1️⃣ Keycloak 简介
Keycloak 是 Red Hat 开源的 身份与访问管理（IAM） 系统，提供：
- ✅ 单点登录（SSO）
- 🔐 OAuth 2.0 / OpenID Connect / SAML 2.0
- 👥 用户 / 角色 / 权限管理
- 🧩 多租户（Realm）支持
- 🔗 LDAP / Active Directory 集成
2️⃣ 环境准备
2.1 基础环境要求
- JDK：17 或以上（Keycloak 17+ 必须）
- 操作系统：Linux / macOS / Windows
- 数据库（可选，生产环境推荐）：
- PostgreSQL
- MySQL / MariaDB
- Oracle
开发环境可直接使用内置 H2 数据库。
3️⃣ Keycloak 安装
3.1 下载 Keycloak
官方下载地址：
https://www.keycloak.org/downloads
示例（Linux）：
wget https://github.com/keycloak/keycloak/releases/download/22.0.5/keycloak-22.0.5.tar.gz
tar -xzf keycloak-22.0.5.tar.gz
cd keycloak-22.0.5
3.2 创建管理员账号
首次启动前需要创建管理员：
bin/kc.sh bootstrap-admin
按提示输入：admin 用户名和密码。
3.3 启动 Keycloak（开发模式）
bin/kc.sh start-dev
默认访问地址：
- 管理控制台：
http://localhost:8080/admin - 用户端点：
http://localhost:8080
4️⃣ Keycloak 基础配置
4.1 Realm（领域）
- Realm 是 Keycloak 的逻辑隔离单元
- 一个 Realm 可包含：用户、客户端、角色、身份源
创建 Realm
- 登录 Admin Console
- 左上角 Realm 下拉框
- 点击 Create realm
4.2 用户管理（Users）
创建用户
- 进入指定 Realm
- Users → Create user
- 填写用户名、邮箱
- 保存
设置密码
- Users → Credentials
- 设置密码
- 关闭 Temporary（否则首次登录需修改密码）
4.3 角色管理（Roles）
Realm 角色
- Roles → Create role
- 示例：
admin、user
给用户分配角色
- Users → Role mapping
- 分配 Realm Roles 或 Client Roles
5️⃣ Client（客户端）配置
Client 表示受 Keycloak 保护的应用。
5.1 创建 Client
- Clients → Create client
- Client ID：如
demo-app - Client type：
OpenID Connect
5.2 常用配置项说明
基本配置
- Client authentication：
On：机密客户端（后端）Off：公共客户端（前端）
重定向 URI
http://localhost:3000/*
Web Origins
http://localhost:3000
5.3 获取 Client Secret（机密客户端）
- Clients → Credentials
- 复制 Client Secret
6️⃣ Keycloak 与应用集成
6.1 OIDC 授权码模式（Authorization Code）
登录流程
- 应用重定向至 Keycloak 登录页
- 用户认证成功
- Keycloak 回调应用并携带
code - 应用使用
code换取 Token
6.2 获取 Token 示例
POST /realms/{realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=demo-app
&client_secret=xxx
&code=xxx
&redirect_uri=http://localhost:3000/callback
返回：
- access_token
- refresh_token
- id_token
6.3 Token 校验
- JWT（RS256）签名
- 使用 Realm 的
jwks_uri公钥校验
7️⃣ 与数据库集成（生产推荐）
7.1 PostgreSQL 示例
bin/kc.sh build \
--db=postgres
bin/kc.sh start \
--db-url=jdbc:postgresql://localhost:5432/keycloak \
--db-username=keycloak \
--db-password=keycloak
8️⃣ 常用配置参数
| 参数 | 说明 |
|---|---|
--http-port | HTTP 端口 |
--hostname | 对外访问域名 |
--proxy=edge | 反向代理场景 |
--log-level | 日志级别 |
9️⃣ 安全与生产建议
- 使用 HTTPS（反向代理 + TLS）
- 关闭
start-dev，使用start - 使用外部数据库
- 定期备份 Realm 配置
- 限制 Admin Console 访问
🔟 常见问题
10.1 无法登录 Admin Console
- 检查是否已执行
bootstrap-admin - 清理 data 目录后重新初始化
10.2 重定向 URI 不匹配
- 确保 Client 中配置的 Redirect URI 完全匹配
📚 参考资料
- Keycloak 官方文档：https://www.keycloak.org/documentation
- OpenID Connect：https://openid.net/
✨ 文档结束 ✨