keycloak

Keycloak 技能

为 Alpha Members Platform 提供全面的身份与访问管理功能。

何时使用此技能

在处理以下事项时启用此技能：

• Keycloak realm 配置
• 客户端设置与管理
• 身份验证流程（MFA、OTP、WebAuthn）
• 用户联合（LDAP、Active Directory）
• 身份提供商（SAML、OIDC、社交登录）
• 主题自定义
• 基于角色的访问控制

快速参考

常用命令

# Start Keycloak in dev mode
docker-compose up keycloak keycloak-db -d

# Export realm configuration
docker exec keycloak /opt/keycloak/bin/kc.sh export \
  --realm alpha-members \
  --dir /tmp/export \
  --users realm_file

# Import realm
docker exec keycloak /opt/keycloak/bin/kc.sh import \
  --dir /opt/keycloak/data/import

# Get admin token
curl -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=admin" \
  -d "grant_type=password"

# Health check
curl http://localhost:8080/health/ready

Admin REST API

# Base URL
KEYCLOAK_URL="http://localhost:8080"
REALM="alpha-members"

# List users
curl -H "Authorization: Bearer $TOKEN" \
  "$KEYCLOAK_URL/admin/realms/$REALM/users"

# Create client
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$KEYCLOAK_URL/admin/realms/$REALM/clients" \
  -d '{"clientId": "new-client", "enabled": true}'

# Get realm roles
curl -H "Authorization: Bearer $TOKEN" \
  "$KEYCLOAK_URL/admin/realms/$REALM/roles"

Realm 配置

alpha-members Realm

{
  "realm": "alpha-members",
  "enabled": true,
  "sslRequired": "external",
  "registrationAllowed": true,
  "registrationEmailAsUsername": true,
  "verifyEmail": true,
  "bruteForceProtected": true,
  "failureFactor": 5,
  "maxFailureWaitSeconds": 900
}

默认角色

• admin - 完整的管理权限
• member - 标准成员权限
• guest - 受限的访客权限

客户端角色（member-api）

• members:read
• members:write
• members:delete
• members:admin

身份验证流程

浏览器流程（默认）

1. Cookie（ALTERNATIVE）
2. 身份提供商重定向器（ALTERNATIVE）
3. 表单：
   • 用户名/密码（REQUIRED）
   • 条件 OTP（CONDITIONAL）

自定义 MFA 流程

alpha-mfa-flow:
  - Username Password Form (REQUIRED)
  - Conditional OTP:
    - Condition: User Role (admin)
    - OTP Form (REQUIRED)

客户端配置

member-api（后端服务）

{
  "clientId": "member-api",
  "enabled": true,
  "clientAuthenticatorType": "client-secret",
  "serviceAccountsEnabled": true,
  "directAccessGrantsEnabled": true,
  "publicClient": false,
  "protocol": "openid-connect"
}

member-ui（前端 SPA）

{
  "clientId": "member-ui",
  "enabled": true,
  "publicClient": true,
  "standardFlowEnabled": true,
  "implicitFlowEnabled": false,
  "directAccessGrantsEnabled": false,
  "redirectUris": ["http://localhost:3000/*"],
  "webOrigins": ["+"],
  "protocol": "openid-connect",
  "attributes": {
    "pkce.code.challenge.method": "S256"
  }
}

令牌配置

Access Token Lifespan: 1 hour (3600s)
Implicit Flow Lifespan: 15 minutes (900s)
SSO Session Idle: 30 minutes (1800s)
SSO Session Max: 10 hours (36000s)
Offline Session Idle: 30 days (2592000s)

OIDC 端点

Authorization: /realms/alpha-members/protocol/openid-connect/auth
Token: /realms/alpha-members/protocol/openid-connect/token
UserInfo: /realms/alpha-members/protocol/openid-connect/userinfo
Logout: /realms/alpha-members/protocol/openid-connect/logout
JWKS: /realms/alpha-members/protocol/openid-connect/certs
Discovery: /realms/alpha-members/.well-known/openid-configuration

主题自定义

主题结构

keycloak/themes/alpha/
├── theme.properties
├── login/
│   ├── theme.properties
│   ├── resources/css/login.css
│   └── messages/messages_en.properties
├── account/
└── email/

主题属性

parent=keycloak
import=common/keycloak
styles=css/login.css
locales=en

用户联合

LDAP 配置

Vendor: Active Directory
Connection URL: ldaps://ldap.corporate.com:636
Users DN: OU=Users,DC=corporate,DC=com
Username Attribute: sAMAccountName
Edit Mode: READ_ONLY
Sync Mode: IMPORT

安全最佳实践

1. 启用暴力破解防护
2. 要求验证电子邮件
3. 在生产环境中使用 SSL/TLS（sslRequired: all）
4. 配置适当的令牌有效期
5. 启用审计日志记录
6. 对公共客户端使用 PKCE
7. 为 admin 角色实施 MFA

项目文件

• Realm 配置：keycloak/realm-config/alpha-realm.json
• Docker：docker/docker-compose.yml（keycloak 服务）
• 主题：keycloak/themes/alpha/

相关 Agent

• keycloak-realm-admin - Realm 与客户端管理
• keycloak-theme-developer - 主题自定义
• keycloak-identity-specialist - 联合与 SSO
• keycloak-auth-flow-designer - 身份验证流程
• keycloak-security-auditor - 安全审查

故障排除

# Check Keycloak logs
docker logs keycloak -f --tail=100

# Test OIDC configuration
curl http://localhost:8080/realms/alpha-members/.well-known/openid-configuration

# Validate token
curl -X POST "http://localhost:8080/realms/alpha-members/protocol/openid-connect/token/introspect" \
  -d "client_id=member-api" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "token=$ACCESS_TOKEN"