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

إعداد 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

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

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

الإعداد	القيمة
نوع التطبيق	Web / Confidential
المنح	Authorization Code
URI إعادة توجيه تسجيل الدخول	{KAZMA_PUBLIC_URL}/api/auth/oidc/callback
تسجيل الخروج (اختياري)	{KAZMA_PUBLIC_URL}/login
PKCE	مُفعَّل (S256)

Okta

1. Applications ← Create App Integration ← OIDC ← Web Application
2. إعادة توجيه تسجيل الدخول: https://your.host/api/auth/oidc/callback
3. عيّن المستخدمين/المجموعات
4. اختياري: أضف ادعاء role = admin / operator / viewer في Authorization Server

Auth0

1. Applications ← Regular Web Application
2. عناوين URL المسموحة للاستدعاء الراجع: https://your.host/api/auth/oidc/callback
3. المُصدر: https://YOUR_DOMAIN.auth0.com/
4. إجراءات اختيارية: أضف role إلى الـ ID token

Azure Entra ID

1. تسجيل التطبيق ← URI إعادة توجيه الويب
2. المُصدر: https://login.microsoftonline.com/{tenant}/v2.0
3. اعرض الأدوار أو استخدم أدوار التطبيق المُسندة إلى الرمز

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

• يعرض /login زر المتابعة عبر SSO عند تهيئة OIDC ‏(/api/auth/status → oidc: true)
• بعد الاستدعاء الراجع، تُسكّ كاظمه kazma-session معتمًا يحمل اسم المستخدم + الدور
• العلامة التجارية (الشعار، الألوان) تُهيَّأ في صفحة تسجيل دخول مزوّد الهوية — وكاظمه تعرض زر SSO محايدًا

ربط الأدوار

قيمة ادعاء مزوّد الهوية	دور كاظمه
admin، وowner، وadministrator	admin
operator، وuser، وmember، وwrite	operator
viewer، وread، وguest	viewer
(غياب)	KAZMA_OIDC_DEFAULT_ROLE

الاختبار

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