Ruby SAML

Minor and patch versions of Ruby SAML may introduce breaking changes. Please read UPGRADING.md for guidance on upgrading to new Ruby SAML versions.

Vulnerability Notice

CVE-2025-66568 and CVE-2025-66567. affects version ruby-saml < 1.18.0 (including 1.12.4), upgrade to 1.18.1

CVE-2025-54572 affects version ruby-saml < 1.18.1

There are critical vulnerabilities affecting ruby-saml < 1.18.0, two of them allows SAML authentication bypass (CVE-2025-25291, CVE-2025-25292, CVE-2025-25293). Please upgrade to a fixed version (1.18.0)

Vulnerability Reporting

If you believe you have discovered a security vulnerability in this gem, please report it by email to the maintainer: [email protected]

Sponsors

Thanks to the following sponsors for securing the open source ecosystem:

^SerpApi

^{A real-time API to access Google search results. It handle proxies, solve captchas, and parse all rich structured data for you}

^Github

^{The complete developer platform to build, scale, and deliver secure software.}

^84codes

^{Simplifying Message Queuing and Streaming. Leave server management to the experts, so you can focus on building great applications.}

Overview

The Ruby SAML library is for implementing the client side of a SAML authorization, i.e. it provides a means for managing authorization initialization and confirmation requests from identity providers.

SAML authorization is a two-step process and you are expected to implement support for both.

We created a demo project for Rails 4 that uses the latest version of this library: ruby-saml-example

Security Considerations

• Validation of the IdP Metadata URL: When loading IdP Metadata from a URLs, Ruby SAML requires you (the developer/administrator) to ensure the supplied URL is correct and from a trusted source. Ruby SAML does not perform any validation that the URL you entered is correct and/or safe.
• False-Positive Security Warnings: Some tools may incorrectly report Ruby SAML as a potential security vulnerability, due to its dependency on Nokogiri. Such warnings can be ignored; Ruby SAML uses Nokogiri in a safe way, by always disabling its DTDLOAD option and enabling its NONET option.
• Prevent Replay attacks: A replay attack occurs when an attacker intercepts a valid SAML assertion and reuses it to gain unauthorized access. The ruby-saml library provides tools to help mitigate this risk, but it is your responsibility to implement the necessary logic. See Preventing Replay Attacks for additional guidance.

Supported Ruby Versions

The following Ruby versions are covered by CI testing:

• Ruby (MRI) 2.1 to 4.0
• JRuby 9.1 to 9.4
• TruffleRuby (latest)

Getting Started

In order to use Ruby SAML you will need to install the gem (either manually or using Bundler), and require the library in your Ruby application:

Using Gemfile

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

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

Using RubyGems

gem install ruby-saml

You may require the entire Ruby SAML gem:

require 'onelogin/ruby-saml'

or just the required components individually:

require 'onelogin/ruby-saml/authrequest'

Installation on Ruby 1.8.7

This gem uses Nokogiri as a dependency, which dropped support for Ruby 1.8.x in Nokogiri 1.6. When installing this gem on Ruby 1.8.7, you will need to make sure a version of Nokogiri prior to 1.6 is installed or specified if it hasn't been already.

Using Gemfile

gem 'nokogiri', '~> 1.5.10'

Using RubyGems

gem install nokogiri --version '~> 1.5.10'

Configuring Logging

When troubleshooting SAML integration issues, you will find it extremely helpful to examine the output of this gem's business logic. By default, log messages are emitted to RAILS_DEFAULT_LOGGER when the gem is used in a Rails context, and to STDOUT when the gem is used outside of Rails.

To override the default behavior and control the destination of log messages, provide a ruby Logger object to the gem's logging singleton:

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

The Initialization Phase

This is the first request you will get from the identity provider. It will hit your application at a specific URL that you've announced as your SAML initialization point. The response to this initialization is a redirect back to the identity provider, which can look something like this (ignore the saml_settings method call for now):

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

If the SP knows who should be authenticated in the IdP, it can provide that info as follows:

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

Once you've redirected back to the identity provider, it will ensure that the user has been authorized and redirect back to your application for final consumption. This can look something like this (the authorize_success and authorize_failure methods are specific to your application):

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