Ruby SAML

GitHub Gem Gem

Минорные и патч-версии 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

^{API в реальном времени для доступа к результатам поиска Google. Он обрабатывает прокси, решает капчи и парсит все структурированные данные за вас}

^Github

^{Полная платформа для разработчиков для создания, масштабирования и доставки безопасного программного обеспечения.}

^84codes

^{Упрощение очередей сообщений и потоковой передачи. Оставьте управление серверами экспертам, чтобы вы могли сосредоточиться на создании отличных приложений.}

Обзор

Библиотека Ruby SAML предназначена для реализации клиентской стороны SAML-авторизации, то есть она предоставляет средства для управления запросами инициализации и подтверждения авторизации от провайдеров идентификации.

SAML-авторизация — это двухэтапный процесс, и предполагается, что вы реализуете поддержку обоих этапов.

Мы создали демонстрационный проект для Rails 4, использующий последнюю версию этой библиотеки: ruby-saml-example

Вопросы безопасности

Проверка URL метаданных IdP: При загрузке метаданных IdP по URL-адресам Ruby SAML требует, чтобы вы (разработчик/администратор) убедились, что предоставленный URL-адрес корректен и получен из доверенного источника. Ruby SAML не выполняет никакой проверки того, что URL-адрес, который вы ввели, корректен и/или безопасен.
Ложноположительные предупреждения о безопасности: Некоторые инструменты могут ошибочно сообщать о Ruby SAML как о потенциальной уязвимости безопасности из-за его зависимости от Nokogiri. Такие предупреждения можно игнорировать; Ruby SAML использует Nokogiri безопасным способом, всегда отключая опцию DTDLOAD и включая опцию NONET.
Предотвращение атак повторного воспроизведения: Атака повторного воспроизведения происходит, когда злоумышленник перехватывает действительный SAML-assertion и повторно использует его для получения несанкционированного доступа. Библиотека 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:

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 вам будет крайне полезно изучить вывод бизнес-логики этого гема. По умолчанию сообщения журнала отправляются в RAILS_DEFAULT_LOGGER, когда гем используется в контексте Rails, и в STDOUT, когда гем используется вне Rails.

Чтобы переопределить поведение по умолчанию и управлять назначением сообщений журнала, предоставьте объект Logger из Ruby синглтону логирования гема:

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

ruby-saml

Популярное