keycloak

Keycloak スキル

Alpha Members Platform 向けに、包括的な Keycloak のアイデンティティおよびアクセス管理機能を提供します。

このスキルを使用するタイミング

次の作業を行う際に、このスキルを有効にしてください。

• Keycloak レルムの設定
• クライアントのセットアップと管理
• 認証フロー（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"

レルム設定

alpha-members レルム

{
  "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. Identity Provider Redirector（ALTERNATIVE）
3. Forms:
   • ユーザー名／パスワード（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. 管理者ロールには MFA を導入する

プロジェクトファイル

• レルム設定：keycloak/realm-config/alpha-realm.json
• Docker：docker/docker-compose.yml（keycloak サービス）
• テーマ：keycloak/themes/alpha/

関連エージェント

• keycloak-realm-admin - レルムとクライアントの管理
• 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"