تخطَّ إلى المحتوى
kazma.
البحث في كاظمه والتوثيق
EN

إعداد OIDC لمزوّد الهوية

إعداد OIDC / IdP ‏(Okta، وAuth0، وEntra، وKeycloak)

Section titled “إعداد OIDC / IdP ‏(Okta، وAuth0، وEntra، وKeycloak)”

تستخدم كاظمه OpenID Connect القياسي (رمز تفويض + PKCE).

مغلق عند الفشل (fail-closed): الاستدعاء الراجع يتحقق من id_token (‏JWKS لـ RS/ES/PS، وسر العميل لـ HS*). خطأ JWKS، أو alg: none، أو جمهور خاطئ، أو توقيع سيئ يعني 400 — كاظمه لا تُسكّ جلسة أبدًا من JWT غير مُتحقَّق. لا تُستخدم UserInfo إلا عندما يحذف مزوّد الهوية id_token.

نافذة طرفيّة
KAZMA_PUBLIC_URL=https://kazma.example.com
KAZMA_OIDC_ISSUER=https://YOUR_TENANT.okta.com # or Auth0/Entra issuer
KAZMA_OIDC_CLIENT_ID=...
KAZMA_OIDC_CLIENT_SECRET=...
# optional overrides
KAZMA_OIDC_REDIRECT_URI=https://kazma.example.com/api/auth/oidc/callback
KAZMA_OIDC_SCOPES=openid profile email
KAZMA_OIDC_ROLE_CLAIM=role # or groups / custom claim
KAZMA_OIDC_DEFAULT_ROLE=operator # viewer | operator | admin
KAZMA_OIDC_TENANT_CLAIM=org # optional: claim naming the user's Kazma tenant
# who may sign in (set at least one; see below)
KAZMA_OIDC_ALLOWED_EMAILS=owner@example.com
KAZMA_OIDC_ALLOWED_DOMAINS=example.com
KAZMA_OIDC_ALLOWED_GROUPS=kazma-users

دون قائمة سماح، يمكن لكل حساب يصادق عليه المُصدر أن يسجّل الدخول ويحصل على KAZMA_OIDC_DEFAULT_ROLE؛ وتسجّل كاظمه تحذيرًا عند بدء التشغيل يقول ذلك. وهذا صحيح فقط لمُصدر كل حساباته لك. أما مع مُصدر عام (Google، أو مستأجر Auth0 مشترك) فسمِّ من يُسمح له:

  • KAZMA_OIDC_ALLOWED_EMAILS: عناوين بعينها، مفصولة بفواصل.
  • KAZMA_OIDC_ALLOWED_DOMAINS: نطاقات بريد، مفصولة بفواصل.
  • KAZMA_OIDC_ALLOWED_GROUPS: أسماء مجموعات أو أدوار موجودة في groups أو roles أو KAZMA_OIDC_ROLE_CLAIM داخل الرمز.

عند ضبط أيٍّ منها، يُرفض الحساب الذي لا يسمّيه أيٌّ منها. والبريد الذي يضع عليه مزوّد الهوية email_verified: false لا يطابق أي قائمة سماح أبدًا، ويُرفض حين يكون هو اسم المستخدم أو معرّفه (لا sub، أو لا preferred_username). ومزوّد الهوية الذي لا يرسل email_verified يُؤخذ بكلامه.

ويرسل كل تسجيل دخول أيضًا nonce، ويجب أن يعيده id_token. ويخضع /api/auth/oidc/start لتحديد المعدل لكل عنوان عميل (الدلو oidc_start، ‏10 في الدقيقة؛ ويغيّره api.rate_limit.oidc_start_per_minute).

KAZMA_OIDC_TENANT_CLAIM مطفأ افتراضيًا، وحينها يشترك كل مستخدم OIDC في المستأجر default. عند ضبطه، يُخزَّن الادعاء المسمّى (slug من حروف وأرقام و. و_ و-؛ وتُقبل قائمة بعنصر واحد) في جلسة المستخدم ويعمل كل طلب تحت ذلك المستأجر: أسراره وذاكرته وجلساته وخيوطه. القيمة المشوهة تُتجاهَل وتُسجَّل. المستخدمون المحليون يحصلون على الربط نفسه من tenant_id عند POST /api/saas/users.

تسجيل التطبيق لدى مزوّد الهوية

Section titled “تسجيل التطبيق لدى مزوّد الهوية”
الإعدادالقيمة
نوع التطبيقWeb / Confidential
المنحAuthorization Code
URI إعادة توجيه تسجيل الدخول{KAZMA_PUBLIC_URL}/api/auth/oidc/callback
تسجيل الخروج (اختياري){KAZMA_PUBLIC_URL}/login
PKCEمُفعَّل (S256)
  1. Applications ← Create App Integration ← OIDC ← Web Application
  2. إعادة توجيه تسجيل الدخول: https://your.host/api/auth/oidc/callback
  3. عيّن المستخدمين/المجموعات
  4. اختياري: أضف ادعاء role = admin / operator / viewer في Authorization Server
  1. Applications ← Regular Web Application
  2. عناوين URL المسموحة للاستدعاء الراجع: https://your.host/api/auth/oidc/callback
  3. المُصدر: https://YOUR_DOMAIN.auth0.com/
  4. إجراءات اختيارية: أضف role إلى الـ ID token
  1. تسجيل التطبيق ← URI إعادة توجيه الويب
  2. المُصدر: https://login.microsoftonline.com/{tenant}/v2.0
  3. اعرض الأدوار أو استخدم أدوار التطبيق المُسندة إلى الرمز

تجربة تسجيل الدخول في كاظمه

Section titled “تجربة تسجيل الدخول في كاظمه”
  • يعرض /login زر المتابعة عبر SSO عند تهيئة OIDC ‏(/api/auth/status → oidc: true)
  • بعد الاستدعاء الراجع، تُسكّ كاظمه kazma-session معتمًا يحمل اسم المستخدم + الدور
  • العلامة التجارية (الشعار، الألوان) تُهيَّأ في صفحة تسجيل دخول مزوّد الهوية — وكاظمه تعرض زر SSO محايدًا
قيمة ادعاء مزوّد الهويةدور كاظمه
admin، وowner، وadministratoradmin
operator، وuser، وmember، وwriteoperator
viewer، وread، وguestviewer
(غياب، أو لا قيمة تُربط)KAZMA_OIDC_DEFAULT_ROLE

يُقرأ الادعاء القائمة (groups: ["staff", "admin"]) كاملًا: يفوز أعلى دور تُربط به أيٌّ من قيمه.

  1. افتح /login ← المتابعة عبر SSO
  2. أكمل تسجيل دخول مزوّد الهوية
  3. تصل إلى / والكوكيز مضبوطة
  4. يعيد GET /api/auth/me القيمتين username + role