إنشاء المستخدم الأول

الوصول إلى لوحة التحكم

لوحة تحكم المشرف (Admin Console) هي واجهة الويب لإدارة ميثاق:

URL:        http://your-server:8080/admin
Master Realm:  master (Realm الافتراضي)
Username:     admin (من KEYCLOAK_ADMIN)
Password:     (من KEYCLOAK_ADMIN_PASSWORD)

إنشاء مستخدم جديد عبر الويب

1. سجّل الدخول إلى Admin Console باستخدام حساب admin
2. اختر الـ Realm من القائمة العلوية (أو أنشئ realm جديد)
3. اذهب إلى Users ← انقر Add user
4. أدخل البيانات:
   • Username: اسم المستخدم (فريد)
   • Email: البريد الإلكتروني
   • First Name: الاسم الأول
   • Last Name: اسم العائلة
   • Email Verified: فعّل إذا كان البريد مؤكد
   • User Enabled: تأكد أنه مفعّل
5. انقر Save
6. بعد الحفظ، اذهب إلى tab Credentials
7. انقر Set password — أدخل كلمة المرور واختر Temporary: OFF
8. انقر Save

تعيين الأدوار (Roles)

1. في صفحة المستخدم، اذهب إلى tab Role Mappings
2. اختر Client Roles ← realm-management
3. اختر الأدوار المطلوبة:
   • admin — مسؤول كامل (للمشرفين)
   • create-realm — إنشاء realms جديدة
   • view-users — عرض المستخدمين
   • manage-users — إدارة المستخدمين
   • view-realm — عرض إعدادات Realm
   • manage-clients — إدارة العملاء
4. انقر Add selected

عبر سطر الأوامر (kcadm)

kcadm هو أداة سطر أوامر ميثاق لإدارة الموارد برمجياً:

# التنصيب (ضمن تثبيت ميثاق)
export PATH=$PATH:/path/to/methaq/bin

# تسجيل الدخول
kcadm config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin \
  --password YOUR_PASSWORD

# إنشاء مستخدم
kcadm create users -r methaq \
  -s username=newuser \
  -s email=newuser@company.com \
  -s firstName=John \
  -s lastName=Doe \
  -s enabled=true \
  -s emailVerified=true

# تعيين كلمة مرور
kcadm set-password -r methaq \
  --username newuser \
  --new-password 'SecurePass123!' \
  --temporary off

# منح دور admin
kcadm add-roles -r methaq \
  --username newuser \
  --rolepath /realms/methaq/roles/admin

# عرض المستخدمين
kcadm get users -r methaq --offset 0 --limit 100

عبر REST API

Useful for automation, CI/CD pipelines, and programmatic user provisioning:

# 1. الحصول على Access Token
curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=YOUR_PASSWORD"

# Response:
# {
#   "access_token": "eyJhbG...",
#   "token_type": "Bearer",
#   "expires_in": 300
# }

# 2. Create user
curl -X POST http://localhost:8080/admin/realms/methaq/users \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","enabled":true,"email":"newuser@company.com"}'

# 3. Get user ID
# Use Admin REST API to list users and find the new user's UUID
curl -s http://localhost:8080/admin/realms/methaq/users \
  -H "Authorization: Bearer ACCESS_TOKEN" | \
  jq -r '.[] | select(.username=="newuser") | .id'
# Output: 7d3b97f4-5c3b-4a1c-b3e2-d8f6c1a9e4b2

# 4. Assign admin role (replace USER_ID with actual UUID)
curl -X POST "http://localhost:8080/admin/realms/methaq/users/USER_ID/role-mappings/realm" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"name":"admin"}]'

استعادة الوصول عند نسيان كلمة المرور

الطريقة 1: via Keycloak CLI

# Set new password directly (requires server access)
kcadm config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin \
  --password OLD_PASSWORD

kcadm set-password -r master \
  --username admin \
  --new-password 'NewSecurePassword!' \
  --temporary off

الطريقة 2: via Database (PostgreSQL)

# Hash the password using Keycloak's hashing
# Connect to PostgreSQL:
psql -h localhost -U methaq -d methaq

# Update admin password (bcrypt hash)
UPDATE user_entity
SET value = '$2a$N$10$...hashed_password...'
WHERE username = 'admin';

# Or disable login for recovery:
UPDATE user_entity
SET totp = 0, credentials = '[]'
WHERE username = 'admin';

الطريقة 3: Recovery Codes (للإنتاج)

Before lockout, generate recovery codes:

# Admin Console → Users → [admin] → Credentials
# Click "Setup recovery authentication methods"
# Download recovery codes and store securely
Recovery Codes: 8-character codes, store in password manager
Use one code → reset password → codes become invalid

إعداد البريد لاسترداد كلمات المرور

لتفعيل رابط "نسيت كلمة المرور" على صفحة تسجيل الدخول:

1. Admin Console ← Realm Settings ← tab Email
2. أدخل إعدادات SMTP:

   Host:     smtp.gmail.com (أو مزود البريد الخاص بك)
   Port:     587 (STARTTLS) أو 465 (SSL)
   From:     noreply@methaq.org
   From Display Name:  Methaq IAM
   Username: your-smtp-username
   Password: your-smtp-password

3. اختبر الاتصال: انقر Test connection
4. تفعيل Forgot Password في Realm Settings ← Login

Gmail SMTP (للتطوير فقط)

# تحتاج تفعيل "App Passwords" في حساب Google
# Google Account → Security → 2-Step Verification → App Passwords
Host: smtp.gmail.com
Port: 587
Use TLS: Yes
Username: your@gmail.com
Password: xxxx xxxx xxxx xxxx

للتطوير المحلي (MailHog)

# استخدم MailHog لالتقاط emails محلياً
docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog

# Then in Methaq SMTP config:
Host: host.docker.internal
Port: 1025
# Access Web UI at http://localhost:8025