Ruby SAML

قد تُدخل الإصدارات الثانوية والتصحيحية من Ruby SAML تغييرات كاسرة. يُرجى قراءة UPGRADING.md للحصول على إرشادات حول الترقية إلى إصدارات Ruby SAML الجديدة.

إشعار الثغرات الأمنية

CVE-2025-66568 و CVE-2025-66567. تؤثر على الإصدار ruby-saml < 1.18.0 (بما في ذلك 1.12.4)، قم بالترقية إلى 1.18.1

CVE-2025-54572 تؤثر على الإصدار ruby-saml < 1.18.1

هناك ثغرات أمنية حرجة تؤثر على ruby-saml < 1.18.0، اثنتان منها تسمحان بتجاوز مصادقة SAML (CVE-2025-25291، CVE-2025-25292، CVE-2025-25293). يُرجى الترقية إلى إصدار مُصحَّح (1.18.0)

الإبلاغ عن الثغرات الأمنية

إذا كنت تعتقد أنك اكتشفت ثغرة أمنية في هذه المكتبة، يُرجى الإبلاغ عنها عبر البريد الإلكتروني إلى المشرف: [email protected]

الرعاة

شكرًا للرعاة التاليين على تأمين النظام البيئي مفتوح المصدر:

^SerpApi

^{واجهة برمجة تطبيقات في الوقت الفعلي للوصول إلى نتائج بحث Google. تتعامل مع الوكلاء، وتحل اختبارات CAPTCHA، وتحلل جميع البيانات المهيكلة الغنية نيابةً عنك}

^Github

^{منصة المطورين الكاملة لبناء وتوسيع وتسليم البرمجيات الآمنة.}

^84codes

^{تبسيط قوائم انتظار الرسائل والبث. اترك إدارة الخوادم للخبراء، حتى تتمكن من التركيز على بناء تطبيقات رائعة.}

نظرة عامة

مكتبة Ruby SAML مخصصة لتنفيذ الجانب العميل من تفويض SAML، أي أنها توفر وسيلة لإدارة طلبات تهيئة التفويض وتأكيده من مزوّدي الهوية.

تفويض SAML هو عملية من خطوتين ويُتوقع منك تنفيذ الدعم لكلتا الخطوتين.

أنشأنا مشروعًا تجريبيًا لـ Rails 4 يستخدم أحدث إصدار من هذه المكتبة: ruby-saml-example

اعتبارات أمنية

• التحقق من صحة عنوان URL لبيانات IdP الوصفية: عند تحميل بيانات IdP الوصفية من عناوين URL، يتطلب منك Ruby SAML (بصفتك المطور/المسؤول) التأكد من أن العنوان المُقدَّم صحيح ومن مصدر موثوق. لا يقوم Ruby SAML بأي تحقق من أن العنوان الذي أدخلته صحيح و/أو آمن.
• تحذيرات أمنية إيجابية كاذبة: قد تُبلغ بعض الأدوات بشكل غير صحيح عن Ruby SAML كوجود ثغرة أمنية محتملة، بسبب اعتمادها على Nokogiri. يمكن تجاهل مثل هذه التحذيرات؛ يستخدم Ruby SAML مكتبة Nokogiri بطريقة آمنة، من خلال تعطيل خيار DTDLOAD دائمًا وتمكين خيار NONET.
• منع هجمات إعادة التشغيل: تحدث هجوم إعادة التشغيل عندما يعترض المهاجم تأكيد SAML صالحًا ويعيد استخدامه للحصول على وصول غير مصرح به. توفر مكتبة ruby-saml أدوات للمساعدة في التخفيف من هذه المخاطر، لكن تقع على عاتقك مسؤولية تنفيذ المنطق اللازم. راجع منع هجمات إعادة التشغيل للحصول على إرشادات إضافية.

إصدارات Ruby المدعومة

إصدارات Ruby التالية مشمولة باختبار CI:

• Ruby (MRI) 2.1 إلى 4.0
• JRuby 9.1 إلى 9.4
• TruffleRuby (الأحدث)

البدء

لاستخدام Ruby SAML ستحتاج إلى تثبيت المكتبة (إما يدويًا أو باستخدام Bundler)، وطلب المكتبة في تطبيق Ruby الخاص بك:

باستخدام Gemfile

# latest stable
gem 'ruby-saml', '~> 1.18.0'

# or track master for bleeding-edge
gem 'ruby-saml', :github => 'saml-toolkits/ruby-saml'

استخدام RubyGems

gem install ruby-saml

قد تحتاج إلى مكتبة Ruby SAML gem بالكامل:

require 'onelogin/ruby-saml'

أو فقط المكونات المطلوبة بشكل فردي:

require 'onelogin/ruby-saml/authrequest'

التثبيت على Ruby 1.8.7

تستخدم هذه الجوهرة Nokogiri كاعتماد، وقد أوقفت دعم Ruby 1.8.x في Nokogiri 1.6. عند تثبيت هذه الجوهرة على Ruby 1.8.7، ستحتاج إلى التأكد من تثبيت إصدار من Nokogiri أقدم من 1.6 أو تحديده إذا لم يكن مثبتًا بالفعل.

استخدام Gemfile

gem 'nokogiri', '~> 1.5.10'

استخدام RubyGems

gem install nokogiri --version '~> 1.5.10'

تكوين التسجيل

عند استكشاف مشكلات تكامل SAML وإصلاحها، ستجد أنه من المفيد للغاية فحص مخرجات منطق الأعمال الخاص بهذه الجوهرة (gem). بشكل افتراضي، تُرسل رسائل السجل إلى RAILS_DEFAULT_LOGGER عند استخدام الجوهرة في سياق Rails، وإلى STDOUT عند استخدام الجوهرة خارج Rails.

لتجاوز السلوك الافتراضي والتحكم في وجهة رسائل السجل، وفّر كائن Logger بلغة Ruby إلى الوحيد (singleton) الخاص بتسجيل الجوهرة:

OneLogin::RubySaml::Logging.logger = Logger.new('/var/log/ruby-saml.log')

مرحلة التهيئة

هذا هو الطلب الأول الذي ستتلقاه من مزوّد الهوية. سيصل إلى تطبيقك على عنوان URL محدد أعلنت عنه كنقطة تهيئة SAML الخاصة بك. الاستجابة لهذه التهيئة هي إعادة توجيه إلى مزوّد الهوية، والتي قد تبدو شيئًا كهذا (تجاهل استدعاء الدالة saml_settings في الوقت الحالي):

def init
  request = OneLogin::RubySaml::Authrequest.new
  redirect_to(request.create(saml_settings))
end

إذا كان مزود الخدمة (SP) يعرف من يجب مصادقته في مزود الهوية (IdP)، فيمكنه تقديم هذه المعلومات على النحو التالي:

def init
  request = OneLogin::RubySaml::Authrequest.new
  saml_settings.name_identifier_value_requested = "[email protected]"
  saml_settings.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
  redirect_to(request.create(saml_settings))
end

بمجرد إعادة توجيهك مرة أخرى إلى مزود الهوية، سيتأكد من أن المستخدم قد تم تفويضه ويعيد التوجيه إلى تطبيقك للاستهلاك النهائي. قد يبدو هذا شيئًا كهذا (الطريقتان authorize_success و authorize_failure خاصتان بتطبيقك):

def consume
  response = OneLogin::RubySaml::Response.new(params[:SAMLResponse], :settings => saml_settings)

  # We validate the SAML Response and check if the user already exists in the system
  if response.is_valid?
     # authorize_success, log the user
     session[:userid] = response.nameid
     session[:attributes] = response.attributes
  else
    authorize_failure  # This method shows an error message
    # List of errors is available in response.errors array
  end
end

في ما سبق هناك بعض الافتراضات، أحدها أن response.nameid هو عنوان بريد إلكتروني. يتم التعامل مع كل هذا من خلال كيفية تحديد الإعدادات المعمول بها عبر طريقة saml_settings. يمكن تنفيذ ذلك على غرار هذا:

response = OneLogin::RubySaml::Response.new(params[:SAMLResponse])
response.settings = saml_settings