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

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

undefined

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

undefined

Admin REST API

管理员REST API

bash

undefined

bash

undefined

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"

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)

浏览器流程（默认）

Cookie (ALTERNATIVE)
Identity Provider Redirector (ALTERNATIVE)
Forms:
- Username/Password (REQUIRED)
- Conditional OTP (CONDITIONAL)

Cookie（备选）
身份提供商重定向器（备选）
表单：
- 用户名/密码（必填）
- 条件式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

安全最佳实践

Enable brute force protection
Require email verification
Use SSL/TLS in production (sslRequired: all)
Configure proper token lifetimes
Enable audit logging
Use PKCE for public clients
Implement MFA for admin roles

启用暴力破解防护
要求邮箱验证
生产环境使用SSL/TLS（sslRequired: all）
配置合理的令牌有效期
启用审计日志
公开客户端使用PKCE
管理员角色启用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

Troubleshooting

故障排查

bash

undefined

bash

undefined

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"

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

keycloak

Original

Translation

Keycloak Skill

Keycloak 技能

When to Use This Skill

何时使用本技能

Quick Reference

快速参考

Common Commands

常用命令

Start Keycloak in dev mode

Start Keycloak in dev mode

Export realm configuration

Export realm configuration

Import realm

Import realm

Get admin token

Get admin token

Health check

Health check

Admin REST API

管理员REST API

Base URL

Base URL

List users

List users

Create client

Create client

Get realm roles

Get realm roles

Realm Configuration

领域配置

alpha-members Realm

alpha-members 领域

Default Roles

默认角色

Client Roles (member-api)

客户端角色（member-api）

Authentication Flows

认证流程

Browser Flow (Default)

浏览器流程（默认）

Custom MFA Flow

自定义MFA流程

Client Configuration

客户端配置

member-api (Backend Service)

member-api（后端服务）

member-ui (Frontend SPA)

member-ui（前端SPA）

Token Configuration

令牌配置

OIDC Endpoints

OIDC 端点

Theme Customization

主题定制

Theme Structure

主题结构

Theme Properties

主题属性

User Federation

用户联合

LDAP Configuration

LDAP配置

Security Best Practices

安全最佳实践

Project Files

项目文件

Related Agents

相关Agent

Troubleshooting

故障排查

Check Keycloak logs

Check Keycloak logs

Test OIDC configuration

Test OIDC configuration

Validate token

Validate token