إعداد 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.
بيئة كاظمه
Section titled “بيئة كاظمه”KAZMA_PUBLIC_URL=https://kazma.example.comKAZMA_OIDC_ISSUER=https://YOUR_TENANT.okta.com # or Auth0/Entra issuerKAZMA_OIDC_CLIENT_ID=...KAZMA_OIDC_CLIENT_SECRET=...# optional overridesKAZMA_OIDC_REDIRECT_URI=https://kazma.example.com/api/auth/oidc/callbackKAZMA_OIDC_SCOPES=openid profile emailKAZMA_OIDC_ROLE_CLAIM=role # or groups / custom claimKAZMA_OIDC_DEFAULT_ROLE=operator # viewer | operator | adminKAZMA_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.comKAZMA_OIDC_ALLOWED_DOMAINS=example.comKAZMA_OIDC_ALLOWED_GROUPS=kazma-usersمن يمكنه تسجيل الدخول
Section titled “من يمكنه تسجيل الدخول”دون قائمة سماح، يمكن لكل حساب يصادق عليه المُصدر أن يسجّل الدخول
ويحصل على 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) |
- Applications ← Create App Integration ← OIDC ← Web Application
- إعادة توجيه تسجيل الدخول:
https://your.host/api/auth/oidc/callback - عيّن المستخدمين/المجموعات
- اختياري: أضف ادعاء
role=admin/operator/viewerفي Authorization Server
- Applications ← Regular Web Application
- عناوين URL المسموحة للاستدعاء الراجع:
https://your.host/api/auth/oidc/callback - المُصدر:
https://YOUR_DOMAIN.auth0.com/ - إجراءات اختيارية: أضف
roleإلى الـ ID token
Azure Entra ID
Section titled “Azure Entra ID”- تسجيل التطبيق ← URI إعادة توجيه الويب
- المُصدر:
https://login.microsoftonline.com/{tenant}/v2.0 - اعرض الأدوار أو استخدم أدوار التطبيق المُسندة إلى الرمز
تجربة تسجيل الدخول في كاظمه
Section titled “تجربة تسجيل الدخول في كاظمه”- يعرض
/loginزر المتابعة عبر SSO عند تهيئة OIDC (/api/auth/status→oidc: true) - بعد الاستدعاء الراجع، تُسكّ كاظمه
kazma-sessionمعتمًا يحمل اسم المستخدم + الدور - العلامة التجارية (الشعار، الألوان) تُهيَّأ في صفحة تسجيل دخول مزوّد الهوية — وكاظمه تعرض زر SSO محايدًا
ربط الأدوار
Section titled “ربط الأدوار”| قيمة ادعاء مزوّد الهوية | دور كاظمه |
|---|---|
| admin، وowner، وadministrator | admin |
| operator، وuser، وmember، وwrite | operator |
| viewer، وread، وguest | viewer |
| (غياب، أو لا قيمة تُربط) | KAZMA_OIDC_DEFAULT_ROLE |
يُقرأ الادعاء القائمة (groups: ["staff", "admin"]) كاملًا: يفوز أعلى دور
تُربط به أيٌّ من قيمه.
الاختبار
Section titled “الاختبار”- افتح
/login← المتابعة عبر SSO - أكمل تسجيل دخول مزوّد الهوية
- تصل إلى
/والكوكيز مضبوطة - يعيد
GET /api/auth/meالقيمتينusername+role

