Back to Details

keycloak

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Keycloak Skill

Keycloak 技能

Provides comprehensive Keycloak identity and access management capabilities for the Alpha Members Platform.
为Alpha会员平台提供全面的Keycloak身份与访问管理能力。

When to Use This Skill

何时使用本技能

Activate this skill when working with:
  • Keycloak realm configuration
  • Client setup and management
  • Authentication flows (MFA, OTP, WebAuthn)
  • User federation (LDAP, Active Directory)
  • Identity providers (SAML, OIDC, social login)
  • Theme customization
  • Role-based access control
在处理以下场景时启用本技能：
  • Keycloak领域（Realm）配置
  • 客户端设置与管理
  • 认证流程（MFA、OTP、WebAuthn）
  • 用户联合（LDAP、Active Directory）
  • 身份提供商（SAML、OIDC、社交登录）
  • 主题定制
  • 基于角色的访问控制

Quick Reference

快速参考

Common Commands

常用命令

bash
undefined
bash
undefined

Start Keycloak in dev mode

Start Keycloak in dev mode

docker-compose up keycloak keycloak-db -d
docker-compose up keycloak keycloak-db -d

Export realm configuration

Export realm configuration

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

Import realm

Import realm

docker exec keycloak /opt/keycloak/bin/kc.sh import
--dir /opt/keycloak/data/import
docker exec keycloak /opt/keycloak/bin/kc.sh import
--dir /opt/keycloak/data/import

Get admin token

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"
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

Health check

curl http://localhost:8080/health/ready
undefined
curl http://localhost:8080/health/ready
undefined

Admin REST API

管理员REST API

bash
undefined
bash
undefined

Base URL

Base URL

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

List users

List users

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

Create client

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}'
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

Get realm roles

curl -H "Authorization: Bearer $TOKEN"
"$KEYCLOAK_URL/admin/realms/$REALM/roles"
undefined
curl -H "Authorization: Bearer $TOKEN"
"$KEYCLOAK_URL/admin/realms/$REALM/roles"
undefined

Realm Configuration

领域配置

alpha-members Realm

alpha-members 领域

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

Default Roles

默认角色

  • admin - Full administrative access
  • member - Standard member access
  • guest - Limited guest access
  • admin - 完整管理员权限
  • member - 标准会员权限
  • guest - 受限访客权限

Client Roles (member-api)

客户端角色（member-api）

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

Authentication Flows

认证流程

Browser Flow (Default)

浏览器流程（默认）

  1. Cookie (ALTERNATIVE)
  2. Identity Provider Redirector (ALTERNATIVE)
  3. Forms:
    • Username/Password (REQUIRED)
    • Conditional OTP (CONDITIONAL)
  1. Cookie（备选）
  2. 身份提供商重定向器（备选）
  3. 表单：
    • 用户名/密码（必填）
    • 条件式OTP（条件触发）

Custom MFA Flow

自定义MFA流程

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

Client Configuration

客户端配置

member-api (Backend Service)

member-api（后端服务）

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

member-ui (Frontend SPA)

member-ui（前端SPA）

json
{
  "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"
  }
}
json
{
  "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"
  }
}

Token Configuration

令牌配置

yaml
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)
yaml
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 Endpoints

OIDC 端点

yaml
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
yaml
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

Theme Customization

主题定制

Theme Structure

主题结构

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

Theme Properties

主题属性

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

User Federation

用户联合

LDAP Configuration

LDAP配置

yaml
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
yaml
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

Security Best Practices

安全最佳实践

  1. Enable brute force protection
  2. Require email verification
  3. Use SSL/TLS in production (sslRequired: all)
  4. Configure proper token lifetimes
  5. Enable audit logging
  6. Use PKCE for public clients
  7. Implement MFA for admin roles
  1. 启用暴力破解防护
  2. 要求邮箱验证
  3. 生产环境使用SSL/TLS（sslRequired: all）
  4. 配置合理的令牌有效期
  5. 启用审计日志
  6. 公开客户端使用PKCE
  7. 管理员角色启用MFA

Project Files

项目文件

  • Realm Config: 
    keycloak/realm-config/alpha-realm.json
  • Docker: 
    docker/docker-compose.yml
    (keycloak service)
  • Themes: 
    keycloak/themes/alpha/
  • 领域配置：
    keycloak/realm-config/alpha-realm.json
  • Docker配置：
    docker/docker-compose.yml
    （keycloak服务）
  • 主题文件：
    keycloak/themes/alpha/

Related Agents

相关Agent

  • keycloak-realm-admin - Realm and client management
  • keycloak-theme-developer - Theme customization
  • keycloak-identity-specialist - Federation and SSO
  • keycloak-auth-flow-designer - Authentication flows
  • keycloak-security-auditor - Security review
  • keycloak-realm-admin - 领域与客户端管理
  • keycloak-theme-developer - 主题定制
  • keycloak-identity-specialist - 联合身份与SSO
  • keycloak-auth-flow-designer - 认证流程设计
  • keycloak-security-auditor - 安全审核

Troubleshooting

故障排查

bash
undefined
bash
undefined

Check Keycloak logs

Check Keycloak logs

docker logs keycloak -f --tail=100
docker logs keycloak -f --tail=100

Test OIDC configuration

Test OIDC configuration

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

Validate token

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"
undefined
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"
undefined