Back to Details

keycloak-administration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

KeyCloak Administration

KeyCloak 管理指南

Overview

概述

Provides systematic KeyCloak administration guidance covering installation, configuration, realm management, security hardening, and operational best practices. Supports both standalone and clustered deployments for secure, scalable identity and access management (IAM) solutions.
提供系统化的KeyCloak管理指南，涵盖安装、配置、领域管理、安全加固及运维最佳实践。支持独立部署和集群部署，助力构建安全、可扩展的身份与访问管理（IAM）解决方案。

Quick Start Guide

快速入门指南

Choose your task and load the appropriate reference:
  1. New Installation → Continue to Installation & Setup
  2. Realm & User Management → Load realm-management.md
  3. Client Configuration → Load client-configuration.md
  4. Authentication & SSO → Load authentication-sso.md
  5. Authorization & RBAC → Load authorization-rbac.md
  6. User Federation (LDAP/AD) → Load user-federation.md
  7. Security Hardening → Load security-hardening.md
  8. High Availability & Scaling → Load ha-scalability.md
  9. Troubleshooting → Load troubleshooting.md
  10. Integration Examples → Load integration-examples.md
选择你的任务并加载对应的参考文档：
  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

Installation & Setup

安装与设置

Deployment Options

部署选项

1. Standalone Mode (Development/Testing)
bash
undefined
1. 独立模式（开发/测试）
bash
undefined

Download and start KeyCloak

下载并启动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
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

访问地址: http://localhost:8080

Create initial admin user on first access

首次访问时创建初始管理员用户


**2. Production Mode with Database**

```bash

**2. 带数据库的生产模式**

```bash

Configure and build

配置并构建

bin/kc.sh build --db=postgres
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
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 Deployment**

```bash
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 - Use KeyCloak Operator or Helm charts
bin/kc.sh start --optimized

**3. Docker部署**

```bash
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

Initial Configuration Steps

初始配置步骤

  1. Admin Account: Create on first access with strong password (12+ chars)
  2. Hostname: Configure 
    KC_HOSTNAME
    for production
  3. SSL/TLS: Set up certificates (required for production)
  4. Database: Configure PostgreSQL connection
  5. Email: Configure SMTP for notifications
properties
undefined
  1. 管理员账户：首次访问时创建，使用强密码（12位以上）
  2. 主机名：为生产环境配置
    KC_HOSTNAME
  3. SSL/TLS：配置证书（生产环境必需）
  4. 数据库：配置PostgreSQL连接
  5. 邮件：配置SMTP用于发送通知
properties
undefined

Email settings

邮件设置

KC_SMTP_HOST=smtp.example.com KC_SMTP_PORT=587 KC_SMTP_FROM=noreply@example.com KC_SMTP_STARTTLS=true
undefined
KC_SMTP_HOST=smtp.example.com KC_SMTP_PORT=587 KC_SMTP_FROM=noreply@example.com KC_SMTP_STARTTLS=true
undefined

Core Concepts

核心概念

Realms

领域（Realms）

  • Master realm: Administrative realm (don't use for apps)
  • Application realms: Separate realms per app/environment
  • Create: Admin Console → Create Realm
  • 主领域（Master realm）：管理用领域（不要用于业务应用）
  • 应用领域（Application realms）：每个应用/环境使用独立领域
  • 创建方式：管理控制台 → 创建领域

Users & Groups

用户与组

  • Users: Individual accounts with credentials
  • Groups: Organize users hierarchically
  • Attributes: Custom key-value pairs
  • Federation: Sync from LDAP/AD (see user-federation.md)
  • 用户：带凭证的独立账户
  • 组：层级化组织用户
  • 属性：自定义键值对
  • 联合：从LDAP/AD同步用户（详见 user-federation.md）

Clients

客户端

  • OIDC clients: Modern OAuth 2.0/OIDC applications
  • SAML clients: Legacy enterprise applications
  • Types: Confidential (server-side) or Public (SPA/mobile)
  • Details: See client-configuration.md
  • OIDC客户端：基于现代OAuth 2.0/OIDC的应用
  • SAML客户端：传统企业级应用
  • 类型：机密型（服务端应用）或公开型（SPA/移动应用）
  • 详情：查看 client-configuration.md

Roles & Permissions

角色与权限

  • Realm roles: Global across all clients
  • Client roles: Specific to one client
  • Composite roles: Inherit multiple roles
  • Details: See authorization-rbac.md
  • 领域角色：对所有客户端全局生效
  • 客户端角色：仅对单个客户端生效
  • 复合角色：继承多个角色的权限
  • 详情：查看 authorization-rbac.md

Common Tasks

常见任务

Configure SSO for Applications

为应用配置SSO

  1. Create OIDC client for your application
  2. Set redirect URIs (exact URLs, no wildcards)
  3. Configure client type:
    • Confidential: Server-side apps (need client secret)
    • Public: SPAs/mobile apps (use PKCE)
  4. Obtain configuration from realm endpoint:
    https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration
  5. Integrate with your app (see integration-examples.md)
  1. 为应用创建OIDC客户端
  2. 设置重定向URI（精确URL，不支持通配符）
  3. 配置客户端类型：
    • 机密型：服务端应用（需要客户端密钥）
    • 公开型：SPA/移动应用（使用PKCE）
  4. 从领域端点获取配置：
    https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration
  5. 与应用集成（详见 integration-examples.md）

Enable Multi-Factor Authentication

启用多因素认证（MFA）

  1. Authentication → Flows
  2. Duplicate Browser flow
  3. Add OTP or WebAuthn authenticator
  4. Set as Required or Conditional
  5. Bind to realm
  6. Users configure MFA on next login
Details: See authentication-sso.md
  1. 认证 → 流程
  2. 复制浏览器认证流程
  3. 添加OTP或WebAuthn认证器
  4. 设置为必填或条件触发
  5. 绑定到目标领域
  6. 用户下次登录时将配置MFA
详情：查看 authentication-sso.md

Connect to LDAP/Active Directory

连接LDAP/Active Directory

  1. User Federation → Add LDAP Provider
  2. Configure connection (URL, bind DN, credentials)
  3. Set search base: 
    ou=users,dc=example,dc=com
  4. Configure mappers for attributes
  5. Test connection and sync users
Details: See user-federation.md
  1. 用户联合 → 添加LDAP提供商
  2. 配置连接信息（URL、绑定DN、凭证）
  3. 设置搜索基准：
    ou=users,dc=example,dc=com
  4. 配置属性映射器
  5. 测试连接并同步用户
详情：查看 user-federation.md

Secure Production Deployment

生产环境安全加固

Essential security measures:
  • SSL/TLS: Required for all production traffic
  • Password policy: 12+ chars, complexity requirements
  • Brute force protection: Enable with lockout
  • Token lifespans: Short access tokens (5-15 min)
  • Admin MFA: Enable for all admin accounts
  • Event logging: Monitor authentication events
Complete checklist: See security-hardening.md
核心安全措施：
  • SSL/TLS：生产环境所有流量必须启用
  • 密码策略：12位以上，满足复杂度要求
  • 暴力破解防护：启用账户锁定
  • 令牌有效期：设置较短的访问令牌有效期（5-15分钟）
  • 管理员MFA：为所有管理员账户启用
  • 事件日志：监控认证事件
完整检查清单：查看 security-hardening.md

Set Up High Availability

搭建高可用性集群

  1. Shared database: PostgreSQL/MySQL for all nodes
  2. Distributed caching: Configure Infinispan
  3. Load balancer: HAProxy/NGINX with sticky sessions
  4. Health checks: Use 
    /health/ready
    and 
    /health/live
  5. Monitoring: Prometheus metrics at 
    /metrics
Details: See ha-scalability.md
  1. 共享数据库：所有节点使用PostgreSQL/MySQL
  2. 分布式缓存：配置Infinispan
  3. 负载均衡器：使用HAProxy/NGINX并启用会话粘性
  4. 健康检查：使用
    /health/ready
    和
    /health/live
    端点
  5. 监控：通过
    /metrics
    获取Prometheus指标
详情：查看 ha-scalability.md

Troubleshooting Quick Reference

故障排查速查

Users Can't Login

用户无法登录

  • Check user enabled status
  • Verify redirect URIs match exactly
  • Review required actions
  • Check Events → Login Events
  • 检查用户是否启用
  • 验证重定向URI是否完全匹配
  • 查看必填操作要求
  • 检查事件 → 登录事件

Token Validation Fails

令牌验证失败

  • Verify realm public key
  • Check token expiration
  • Validate issuer URL
  • Confirm audience claim
  • 验证领域公钥
  • 检查令牌有效期
  • 验证发行者URL
  • 确认受众声明

LDAP Sync Issues

LDAP同步问题

  • Test LDAP connection
  • Verify bind credentials
  • Check user DN path
  • Run manual sync
Full troubleshooting guide: See troubleshooting.md
  • 测试LDAP连接
  • 验证绑定凭证
  • 检查用户DN路径
  • 执行手动同步
完整故障排查指南：查看 troubleshooting.md

Essential Commands

常用命令

bash
undefined
bash
undefined

Start modes

启动模式

bin/kc.sh start-dev # Development bin/kc.sh start --optimized # Production
bin/kc.sh start-dev # 开发模式 bin/kc.sh start --optimized # 生产模式

Build for database

针对数据库构建

bin/kc.sh build --db=postgres
bin/kc.sh build --db=postgres

Export/Import realm

导出/导入领域

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

Admin CLI

管理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
undefined
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
undefined

Best Practices Summary

最佳实践总结

Architecture

架构

  • Separate realms per application/environment
  • Use groups for structure, roles for permissions
  • Plan token lifespans based on security needs
  • Enable session replication in clusters
  • 每个应用/环境使用独立领域
  • 用组管理结构，用角色分配权限
  • 根据安全需求规划令牌有效期
  • 集群中启用会话复制

Security

安全

  • Always use SSL/TLS in production
  • Enable MFA for privileged accounts
  • Implement brute force protection
  • Regular security audits
  • Principle of least privilege
  • 生产环境始终使用SSL/TLS
  • 为特权账户启用MFA
  • 实施暴力破解防护
  • 定期开展安全审计
  • 遵循最小权限原则

Operations

运维

  • Automate backups and test restores
  • Monitor metrics and set alerts
  • Document configurations
  • Regular updates and patching
  • Capacity planning
  • 自动化备份并测试恢复流程
  • 监控指标并设置告警
  • 记录配置信息
  • 定期更新与补丁
  • 做好容量规划

Development

开发

  • Use PKCE for public clients
  • Implement proper token refresh
  • Handle token expiration gracefully
  • Validate tokens correctly
  • Use appropriate grant types
  • 公开客户端使用PKCE
  • 实现正确的令牌刷新机制
  • 优雅处理令牌过期
  • 正确验证令牌
  • 使用合适的授权类型

Reference Documentation

参考文档

For detailed guidance, load the appropriate reference file:
  • realm-management.md - Realm configuration, users, groups
  • client-configuration.md - OIDC/SAML clients, scopes, mappers
  • authentication-sso.md - Auth flows, MFA, social login, IdP
  • authorization-rbac.md - Roles, permissions, fine-grained auth
  • user-federation.md - LDAP/AD integration, custom providers
  • security-hardening.md - Security policies, monitoring, auditing
  • ha-scalability.md - Clustering, performance, backup, DR
  • troubleshooting.md - Common issues, logging, diagnostics
  • integration-examples.md - Spring Boot, Node.js, React, Python, Docker, K8s
如需详细指南，加载对应的参考文件：
  • realm-management.md - 领域配置、用户、组
  • client-configuration.md - OIDC/SAML客户端、作用域、映射器
  • authentication-sso.md - 认证流程、MFA、社交登录、身份提供商
  • authorization-rbac.md - 角色、权限、细粒度认证
  • user-federation.md - LDAP/AD集成、自定义提供商
  • security-hardening.md - 安全策略、监控、审计
  • ha-scalability.md - 集群、性能、备份、容灾
  • troubleshooting.md - 常见问题、日志、诊断
  • integration-examples.md - Spring Boot、Node.js、React、Python、Docker、K8s集成

Additional Resources

额外资源