SSO عبر SAML 2.0

SAML 2.0 معيار مبني على XML لتبادل بيانات المصادقة والتفويض بين IdP (مزود الهوية) وSP (مزود الخدمة). لو المؤسسة تستخدم Okta أو Azure AD أو أي IdP يدعم SAML، الموظفون يسجّلون دخولهم لتطبيقك بدون كلمة مرور منفصلة -- الـ IdP يتكفّل بالمصادقة.

Ithbat يعمل كـ SP. الـ IdP يصادق المستخدم ويرسل SAML Assertion موقّع لـ Ithbat. بعدها Ithbat يتحقق من الـ Assertion، يبحث عن حساب المستخدم أو ينشئه، ويصدر Session Token.

آلية عمل SAML

SP-Initiated Flow -- الأكثر شيوعًا

المستخدم يحاول الوصول لتطبيقك، يتم Redirect لـ Ithbat، ثم Redirect للـ IdP للمصادقة.

sequenceDiagram
    participant User
    participant App as Your Application
    participant Ithbat as Ithbat IAM (SP)
    participant IdP as Corporate IdP

    User->>App: Access protected resource
    App->>Ithbat: Redirect to /auth/saml/{tenant_id}/login
    Ithbat->>Ithbat: Generate AuthnRequest + RelayState
    Ithbat->>IdP: HTTP redirect with SAMLRequest
    IdP->>User: Prompt for credentials
    User->>IdP: Submit credentials
    IdP->>IdP: Authenticate user, sign assertion
    IdP->>Ithbat: POST SAMLResponse to ACS URL
    Ithbat->>Ithbat: Validate signature, extract attributes
    Ithbat->>Ithbat: Create or update user, issue tokens
    Ithbat->>App: Return access_token + refresh_token
    App->>User: Session established

IdP-Initiated Flow

المستخدم يبدأ من بوابة الـ IdP (مثل لوحة Okta) ويُرسَل مباشرةً لـ ACS Endpoint في Ithbat بدون AuthnRequest مسبق.

ملاحظة

الـ IdP-initiated flows أكثر عرضة لـ replay attacks. Ithbat يتحقق من الـ Assertion Signature وشرط NotOnOrAfter في كلا الـ flows. في الـ SP-initiated flow، الـ RelayState مطلوب ويُتحقق منه عبر server-side cache بمدة 10 دقائق.

SP Endpoints لإعداد الـ IdP

عند إعداد الـ IdP، تحتاج ثلاث قيم من Ithbat. استبدل {tenant_id} بـ UUID المستفيد.

الحقل	القيمة
SP Entity ID (Audience URI)	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata`
ACS URL (Assertion Consumer Service)	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs`
SP Metadata URL	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata`
Binding	HTTP-POST
NameID Format	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`

لتنزيل الـ SP Metadata مباشرةً:

curl https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata

إعداد SAML من لوحة تحكم المسؤول

الخيار 1 -- استيراد IdP Metadata (الطريقة المُوصى بها)

انتقل إلى الإعدادات > المصادقة > SAML.
انقر إضافة اتصال.
الصق رابط الـ IdP Metadata أو ارفع ملف XML.
أدخل اسم للاتصال (مثل Okta Corporate، Azure AD).
انقر حفظ. Ithbat يحلّل الـ XML ويستخرج EntityID وعنوان SSO وشهادة التوقيع تلقائيًا.

الخيار 2 -- الإعداد اليدوي

لو الـ IdP لا ينشر Metadata URL، أدخل القيم يدويًا:

الحقل	الوصف
الاسم	تسمية لهذا الاتصال
Entity ID	IdP Entity ID (Issuer)
SSO URL	الـ `SingleSignOnService` Endpoint للـ IdP
SLO URL	اختياري. الـ `SingleLogoutService` Endpoint للـ IdP
الشهادة	شهادة X.509 للـ IdP (بصيغة PEM)
NameID Format	اتركه فارغًا لاستخدام الافتراضي
Signing Method	اتركه فارغًا لاستخدام الافتراضي
مفعّل	زر التبديل لتفعيل الاتصال

Attribute Mapping

الـ SAML Assertions تحمل بيانات المستخدم. Ithbat يربط هذه البيانات بالملف الشخصي عبر Attribute names قابلة للتخصيص. الـ Mapping الافتراضي يستخدم Microsoft WS-Federation URI scheme ويعمل مباشرةً مع Azure AD و Okta و ADFS.

حقل Ithbat	SAML Attribute الافتراضي
`email`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
`firstName`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
`lastName`	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`
`groups`	`http://schemas.xmlsoap.org/claims/Group`

لتخصيص الـ Mapping، مرّر attributeMapping عند إنشاء الإعداد عبر API (راجع مرجع API أدناه).

أدلة إعداد الـ IdP

Okta

الخطوة 1 -- إنشاء تطبيق SAML

في Okta، انتقل إلى Applications > Applications > Create App Integration.
اختر SAML 2.0 وانقر Next.
سمّ التطبيق (مثل Ithbat IAM) وانقر Next.

الخطوة 2 -- إعداد SAML

أدخل القيم التالية:

حقل Okta	القيمة
Single sign-on URL	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs`
Audience URI (SP Entity ID)	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata`
Name ID format	`EmailAddress`
Application username	`Email`

الخطوة 3 -- Attribute Statements

في قسم Attribute Statements، انقر Add Another وأضف:

الاسم	تنسيق الاسم	القيمة
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`	URI Reference	`user.email`
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`	URI Reference	`user.firstName`
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`	URI Reference	`user.lastName`

الخطوة 4 -- IdP Metadata

أكمل المعالج وانتقل إلى تبويب Sign On.
انقر View SAML setup instructions أو انسخ Metadata URL.
في لوحة تحكم Ithbat، الصق الرابط في حقل الاستيراد من رابط.

الخطوة 5 -- تعيين المستخدمين

انتقل إلى تبويب Assignments وعيّن المستخدمين أو المجموعات.

Azure AD (Entra ID)

الخطوة 1 -- إنشاء Enterprise Application

في Azure Portal، انتقل إلى Entra ID > Enterprise applications > New application.
انقر Create your own application، سمّه (مثل Ithbat IAM)، واختر Integrate any other application you don't find in the gallery.
انقر Create.

الخطوة 2 -- إعداد SSO

افتح التطبيق، انتقل إلى Single sign-on، واختر SAML.
انقر Edit في قسم Basic SAML Configuration:

الحقل	القيمة
Identifier (Entity ID)	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata`
Reply URL (ACS URL)	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs`
Sign on URL	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/login`

احفظ.

الخطوة 3 -- Claims و Attributes

في قسم Attributes & Claims، انقر Edit وأضف:

اسم الـ Claim	Source Attribute
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`	`user.mail`
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`	`user.givenname`
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`	`user.surname`

الـ Unique User Identifier (Name ID) يجب يشير لـ user.mail بتنسيق Email address.

الخطوة 4 -- تنزيل Metadata

في قسم SAML Signing Certificate، انسخ App Federation Metadata Url. الصقه في حقل الـ Metadata URL في لوحة تحكم Ithbat.

الخطوة 5 -- تعيين المستخدمين والمجموعات

ضمن Users and groups، أضف المستخدمين أو الـ Security Groups.

Google Workspace

الخطوة 1 -- إنشاء تطبيق SAML

في Google Admin console، انتقل إلى Apps > Web and mobile apps > Add App > Add custom SAML app.
سمّ التطبيق وانقر Continue.
في شاشة Google IdP Information، نزّل الـ Metadata أو دوّن SSO URL وEntity ID وCertificate.

الخطوة 2 -- SP Details

الحقل	القيمة
ACS URL	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/acs`
Entity ID	`https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata`
Name ID	Primary email
Name ID Format	`EMAIL`

الخطوة 3 -- Attribute Mapping

في قسم Attribute mapping:

Google Directory Attribute	App Attribute
First name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
Last name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`
Primary email	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`

الخطوة 4 -- الإعداد في Ithbat

في لوحة تحكم Ithbat، أنشئ اتصال SAML يدويًا باستخدام القيم من الخطوة 1: SSO URL و Entity ID والشهادة (Base64 PEM).

الخطوة 5 -- تفعيل للمستخدمين

في Google Admin، انتقل إلى التطبيق وانقر User access > ON for everyone (أو وحدات تنظيمية محددة).

اختبار الاتصال

بعد حفظ إعداد SAML:

افتح نافذة Incognito.
انتقل إلى https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/login.
المفروض يتم Redirect لصفحة تسجيل دخول الـ IdP.
سجّل الدخول بحساب اختبار.
عند النجاح، Ithbat يرجع access_token وrefresh_token بصيغة JSON.

لو فشل تسجيل الدخول، راجع سجل التدقيق في لوحة تحكم المسؤول.

JIT Provisioning

عند أول مصادقة SAML لمستخدم، Ithbat تلقائيًا:

يتحقق هل البريد الإلكتروني موجود في المستفيد.
لو موجود -- يربط الـ SAML Identity بالحساب القائم.
لو غير موجود -- ينشئ حساب جديد بحالة emailVerified: true ويفعّله مباشرةً.

الاسم الأول واسم العائلة يُملأ من الـ SAML Assertion. لو الـ Assertion ما يتضمن Attributes للاسم، يُستخدم البريد الإلكتروني كبديل.

المستخدمون المزوّدون عبر JIT يخضعون لحد المقاعد في المستفيد. لو بلغ الحد الأقصى، تسجيل الدخول عبر SAML يرجع خطأ.

استكشاف الأخطاء

"SAML not configured for this tenant"

لا يوجد إعداد SAML مفعّل لهذا المستفيد. أنشئ إعدادًا في الإعدادات > المصادقة > SAML وفعّل زر مفعّل.

"Invalid or expired relay state"

الـ RelayState Token انتهت صلاحيته (10 دقائق) أو استُهلك. يحدث عندما المستخدم يترك النافذة مفتوحة فترة طويلة قبل المصادقة. اطلب منه يبدأ Flow جديد.

"Invalid SAML response: signature verification failed"

الـ Signature لا يتطابق مع الشهادة المُعدّة. الأسباب الشائعة:

الشهادة في Ithbat قديمة -- الـ IdP دوّر شهادة التوقيع. نزّل Metadata جديد وحدّث الإعداد.
الـ IdP يوقّع الـ Response بدل الـ Assertion (أو كليهما). راجع إعدادات التوقيع في الـ IdP.
الـ ACS URL في الـ Assertion لا يتطابق مع ACS URL في Ithbat. يجب يكونوا متطابقين تمامًا، بما في ذلك الـ trailing slash.

"Email not found in SAML assertion"

الـ Assertion لا يتضمن Attribute للبريد الإلكتروني في المسار المُعدّ. تأكد أن الـ Attribute Statement names في الـ IdP تتطابق مع attributeMapping.email في إعداد Ithbat.

Clock Skew

الـ SAML Assertions تتضمن NotBefore وNotOnOrAfter timestamps. إذا اختلفت ساعة الخادم عن الـ IdP بأكثر من بضع دقائق، تُرفض الـ Assertions. تأكد أن كلا الخادمين متزامنين مع NTP.

"Tenant is not active"

المستفيد موقوف. تواصل مع مسؤول منصة Ithbat.

مرجع API

جميع SAML Management Endpoints تتطلب Bearer Token بصلاحية settings:read أو settings:write، بالإضافة إلى Header X-Tenant-ID.

سرد SAML Configs

GET /api/v1/tenant/saml/configs
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

جلب SAML Config

GET /api/v1/tenant/saml/configs/{id}
Authorization: Bearer {token}

إنشاء SAML Config

POST /api/v1/tenant/saml/configs
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "name": "Okta Corporate",
  "entityId": "http://www.okta.com/exkABC123",
  "ssoUrl": "https://company.okta.com/app/saml/exkABC123/sso/saml",
  "sloUrl": "https://company.okta.com/app/saml/exkABC123/slo/saml",
  "certificate": "MIIC...base64...==",
  "nameIdFormat": "",
  "signingMethod": "",
  "attributeMapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
    "groups": "http://schemas.xmlsoap.org/claims/Group"
  },
  "enabled": true
}

استيراد من URL أو XML

POST /api/v1/tenant/saml/configs/import-metadata
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "name": "Azure AD",
  "metadataUrl": "https://login.microsoftonline.com/{directory_id}/federationmetadata/2007-06/federationmetadata.xml"
}

أو استيراد XML مباشرةً:

POST /api/v1/tenant/saml/configs/import-metadata
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "name": "Google Workspace",
  "metadataXml": "<?xml version=\"1.0\"?>..."
}

تحديث SAML Config

PUT /api/v1/tenant/saml/configs/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Okta Corporate",
  "enabled": false
}

حذف SAML Config

DELETE /api/v1/tenant/saml/configs/{id}
Authorization: Bearer {token}

جلب SP Metadata (عام، بدون مصادقة)

GET /api/v1/auth/saml/{tenant_id}/metadata

يرجع XML.

الخطوات التالية

SCIM 2.0 -- أتمتة Provisioning للمستخدمين مع SAML SSO
مزامنة الدليل -- Sync المستخدمين من AD/LDAP
سجل التدقيق -- مراقبة أحداث SAML Login

آلية عمل SAML​

SP-Initiated Flow -- الأكثر شيوعًا​

IdP-Initiated Flow​

SP Endpoints لإعداد الـ IdP​

إعداد SAML من لوحة تحكم المسؤول​

الخيار 1 -- استيراد IdP Metadata (الطريقة المُوصى بها)​

الخيار 2 -- الإعداد اليدوي​

Attribute Mapping​

أدلة إعداد الـ IdP​

Okta​

الخطوة 1 -- إنشاء تطبيق SAML​

الخطوة 2 -- إعداد SAML​

الخطوة 3 -- Attribute Statements​

الخطوة 4 -- IdP Metadata​

الخطوة 5 -- تعيين المستخدمين​

Azure AD (Entra ID)​

الخطوة 1 -- إنشاء Enterprise Application​

الخطوة 2 -- إعداد SSO​

الخطوة 3 -- Claims و Attributes​

الخطوة 4 -- تنزيل Metadata​

الخطوة 5 -- تعيين المستخدمين والمجموعات​

Google Workspace​

الخطوة 1 -- إنشاء تطبيق SAML​

الخطوة 2 -- SP Details​

الخطوة 3 -- Attribute Mapping​

الخطوة 4 -- الإعداد في Ithbat​

الخطوة 5 -- تفعيل للمستخدمين​

اختبار الاتصال​

JIT Provisioning​

استكشاف الأخطاء​

"SAML not configured for this tenant"​

"Invalid or expired relay state"​

"Invalid SAML response: signature verification failed"​

"Email not found in SAML assertion"​

Clock Skew​

"Tenant is not active"​

مرجع API​

سرد SAML Configs​

جلب SAML Config​

إنشاء SAML Config​

استيراد من URL أو XML​

تحديث SAML Config​

حذف SAML Config​

جلب SP Metadata (عام، بدون مصادقة)​

الخطوات التالية​

آلية عمل SAML

SP-Initiated Flow -- الأكثر شيوعًا

IdP-Initiated Flow

SP Endpoints لإعداد الـ IdP

إعداد SAML من لوحة تحكم المسؤول

الخيار 1 -- استيراد IdP Metadata (الطريقة المُوصى بها)

الخيار 2 -- الإعداد اليدوي

Attribute Mapping

أدلة إعداد الـ IdP

Okta

الخطوة 1 -- إنشاء تطبيق SAML

الخطوة 2 -- إعداد SAML

الخطوة 3 -- Attribute Statements

الخطوة 4 -- IdP Metadata

الخطوة 5 -- تعيين المستخدمين

Azure AD (Entra ID)

الخطوة 1 -- إنشاء Enterprise Application

الخطوة 2 -- إعداد SSO

الخطوة 3 -- Claims و Attributes

الخطوة 4 -- تنزيل Metadata

الخطوة 5 -- تعيين المستخدمين والمجموعات

Google Workspace

الخطوة 1 -- إنشاء تطبيق SAML

الخطوة 2 -- SP Details

الخطوة 3 -- Attribute Mapping

الخطوة 4 -- الإعداد في Ithbat

الخطوة 5 -- تفعيل للمستخدمين

اختبار الاتصال

JIT Provisioning

استكشاف الأخطاء

"SAML not configured for this tenant"

"Invalid or expired relay state"

"Invalid SAML response: signature verification failed"

"Email not found in SAML assertion"

Clock Skew

"Tenant is not active"

مرجع API

سرد SAML Configs

جلب SAML Config

إنشاء SAML Config

استيراد من URL أو XML

تحديث SAML Config

حذف SAML Config

جلب SP Metadata (عام، بدون مصادقة)

الخطوات التالية