mcpField
K
keycloak-administration

keycloak-administration

github.com/dauquangthanh安全17321 次安装40 周前更新
代码仓库

关于 keycloak-administration

面向运维人员和 IAM 管理员的 KeyCloak 管理指南，涵盖部署、身份配置、安全、扩展和故障排查，并按任务提供参考文档。

主要功能

  1. 01安装与部署指导
  2. 02Realm、用户和客户端管理
  3. 03SSO、身份验证与授权
  4. 04LDAP 和 AD 联合
  5. 05安全加固与运维

适用场景

  1. 01规划新的 KeyCloak 部署
  2. 02配置 Realm、用户或应用客户端
  3. 03设置 SSO、MFA 或 LDAP 同步
  4. 04加固或扩展生产集群

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dauquangthanh/hanoi-rainbow --skill keycloak-administration

安装后在 Claude Code 中输入/keycloak-administration确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
authentication-sso.md
authorization-rbac.md
client-configuration.md
ha-scalability.md
integration-examples.md
realm-management.md
security-hardening.md
troubleshooting.md
user-federation.md

详细介绍

KeyCloak 管理

概述

提供系统化的 KeyCloak 管理指南，涵盖安装、配置、域管理、安全加固和运维最佳实践。支持独立部署和集群部署，打造安全、可扩展的身份和访问管理（IAM）解决方案。

快速入门指南

选择任务并加载相应的参考资料：

  1. 全新安装 → 继续阅读安装与设置
  2. 域与用户管理 → 加载 realm-management.md
  3. 客户端配置 → 加载 client-configuration.md
  4. 身份验证与 SSO → 加载 authentication-sso.md
  5. 授权与 RBAC → 加载 authorization-rbac.md
  6. 用户联合（LDAP/AD） → 加载 user-federation.md
  7. 安全加固 → 加载 security-hardening.md
  8. 高可用与扩展 → 加载 ha-scalability.md
  9. 故障排查 → 加载 troubleshooting.md
  10. 集成示例 → 加载 integration-examples.md

安装与设置

部署选项

1. 独立模式（开发/测试）

# Download and start KeyCloak
wget https://github.com/keycloak/keycloak/releases/download/[VERSION]/keycloak-[VERSION].tar.gz
tar -xvzf keycloak-[VERSION].tar.gz
cd keycloak-[VERSION]
bin/kc.sh start-dev

# Access: http://localhost:8080
# Create initial admin user on first access

2. 使用数据库的生产模式

# Configure and build
bin/kc.sh build --db=postgres

# Set environment variables
export KC_DB=postgres
export KC_DB_URL=jdbc:postgresql://localhost/keycloak
export KC_DB_USERNAME=keycloak
export KC_DB_PASSWORD=password
export KC_HOSTNAME=keycloak.example.com

# Start production mode
bin/kc.sh start --optimized

3. Docker 部署

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

4. Kubernetes - 使用 KeyCloak Operator 或 Helm chart

初始配置步骤
  1. 管理员账户：首次访问时创建，并设置强密码（至少 12 个字符）
  2. 主机名：为生产环境配置 KC_HOSTNAME
  3. SSL/TLS：设置证书（生产环境必需）
  4. 数据库：配置 PostgreSQL 连接
  5. 电子邮件：配置用于发送通知的 SMTP
# Email settings
KC_SMTP_HOST=smtp.example.com
KC_SMTP_PORT=587
[email protected]
KC_SMTP_STARTTLS=true

核心概念

域
  • Master 域：管理域（不要用于应用）
  • 应用域：为每个应用/环境创建独立的域
  • 创建：管理控制台 → 创建域
用户与组
  • 用户：拥有凭据的个人账户
  • 组：按层级组织用户
  • 属性：自定义键值对
  • 联合：从 LDAP/AD 同步（参见 user-federation.md）
客户端
  • OIDC 客户端：现代 OAuth 2.0/OIDC 应用
  • SAML 客户端：传统企业应用
  • 类型：机密型（服务端）或公共型（SPA/移动应用）
  • 详情：参见 client-configuration.md
角色与权限
  • 域角色：适用于所有客户端的全局角色
  • 客户端角色：仅适用于单个客户端
  • 复合角色：继承多个角色
  • 详情：参见 authorization-rbac.md

常见任务

为应用配置 SSO

  1. 为应用创建 OIDC 客户端

  2. 设置重定向 URI（必须是精确 URL，不支持通配符）

  3. 配置客户端类型：

    • 机密型：服务端应用（需要客户端密钥）
    • 公共型：SPA/移动应用（使用 PKCE）

  4. 从域端点获取配置：

    https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration

  5. 将其集成到应用中（参见 integration-examples.md）

启用多因素身份验证
  1. 身份验证 → 流
  2. 复制 Browser 流
  3. 添加 OTP 或 WebAuthn 身份验证器
  4. 设置为必需或有条件
  5. 绑定到域
  6. 用户在下次登录时配置 MFA

详情：参见 authentication-sso.md

连接到 LDAP/Active Directory
  1. 用户联合 → 添加 LDAP 提供程序
  2. 配置连接（URL、绑定 DN、凭据）
  3. 设置搜索基准：ou=users,dc=example,dc=com
  4. 配置属性映射器
  5. 测试连接并同步用户

详情：参见 user-federation.md

安全的生产部署

基本安全措施：

  • SSL/TLS：所有生产流量都必须使用
  • 密码策略：至少 12 个字符，并满足复杂度要求
  • 防暴力破解：启用并设置锁定机制
  • 令牌有效期：使用较短的访问令牌有效期（5-15 分钟）
  • 管理员 MFA：为所有管理员账户启用
  • 事件日志：监控身份验证事件

完整清单：参见 security-hardening.md

设置高可用性
  1. 共享数据库：所有节点使用 PostgreSQL/MySQL
  2. 分布式缓存：配置 Infinispan
  3. 负载均衡器：使用带有粘性会话的 HAProxy/NGINX
  4. 健康检查：使用 /health/ready 和 /health/live
  5. 监控：通过 /metrics 获取 Prometheus 指标

详情：参见 ha-scalability.md

故障排除速查

用户无法登录
  • 检查用户是否已启用
  • 确认重定向 URI 完全匹配
  • 查看必需操作
  • 检查 Events → Login Events
令牌验证失败
  • 确认 Realm 公钥
  • 检查令牌是否过期
  • 验证签发者 URL
  • 确认受众声明
LDAP 同步问题
  • 测试 LDAP 连接
  • 确认绑定凭据
  • 检查用户 DN 路径
  • 手动运行同步

完整故障排除指南：参见 troubleshooting.md

基本命令

# Start modes
bin/kc.sh start-dev                    # Development
bin/kc.sh start --optimized            # Production

# Build for database
bin/kc.sh build --db=postgres

# Export/Import realm
bin/kc.sh export --dir /backup --realm my-realm
bin/kc.sh import --dir /backup

# Admin CLI
bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin
bin/kcadm.sh create realms -s realm=my-realm -s enabled=true
bin/kcadm.sh create users -r my-realm -s username=john -s enabled=true
bin/kcadm.sh set-password -r my-realm --username john --new-password secret

最佳实践总结

架构
  • 为每个应用程序/环境单独设置 Realm
  • 使用组组织结构，使用角色管理权限
  • 根据安全需求规划令牌有效期
  • 在集群中启用会话复制
安全
  • 在生产环境中始终使用 SSL/TLS
  • 为特权账户启用 MFA
  • 实施防暴力破解措施
  • 定期进行安全审计
  • 遵循最小权限原则
运维
  • 自动执行备份并测试恢复
  • 监控指标并设置警报
  • 记录配置
  • 定期更新和修补
  • 进行容量规划
开发
  • 为公共客户端使用 PKCE
  • 正确实现令牌刷新
  • 妥善处理令牌过期
  • 正确验证令牌
  • 使用适当的授权类型

参考文档

如需详细指南，请加载相应的参考文件：

其他资源

评论

支持 Markdown