Ruby SAML

Las versiones menores y de parche de Ruby SAML pueden introducir cambios que rompan la compatibilidad. Por favor, lea UPGRADING.md para obtener orientación sobre cómo actualizar a las nuevas versiones de Ruby SAML.

Aviso de vulnerabilidad

CVE-2025-66568 y CVE-2025-66567. afecta a la versión ruby-saml < 1.18.0 (incluida la 1.12.4), actualice a la 1.18.1

CVE-2025-54572 afecta a la versión ruby-saml < 1.18.1

Existen vulnerabilidades críticas que afectan a ruby-saml < 1.18.0, dos de ellas permiten eludir la autenticación SAML (CVE-2025-25291, CVE-2025-25292, CVE-2025-25293). Por favor, actualice a una versión corregida (1.18.0)

Notificación de vulnerabilidades

Si cree que ha descubierto una vulnerabilidad de seguridad en esta gema, por favor notifíquela por correo electrónico al mantenedor: [email protected]

Patrocinadores

Gracias a los siguientes patrocinadores por asegurar el ecosistema de código abierto:

^SerpApi

^{Una API en tiempo real para acceder a los resultados de búsqueda de Google. Gestiona proxies, resuelve captchas y analiza todos los datos estructurados enriquecidos por ti}

^Github

^{La plataforma completa para desarrolladores para construir, escalar y entregar software seguro.}

^84codes

^{Simplificando las colas de mensajes y el streaming. Deje la gestión de servidores a los expertos, para que pueda centrarse en construir grandes aplicaciones.}

Descripción general

La librería Ruby SAML sirve para implementar el lado cliente de una autorización SAML, es decir, proporciona un medio para gestionar las solicitudes de inicialización y confirmación de autorización desde los proveedores de identidad.

La autorización SAML es un proceso de dos pasos y se espera que implemente soporte para ambos.

Creamos un proyecto de demostración para Rails 4 que utiliza la última versión de esta librería: ruby-saml-example

Consideraciones de seguridad

• Validación de la URL de los metadatos del IdP: Al cargar los metadatos del IdP desde una URL, Ruby SAML requiere que usted (el desarrollador/administrador) se asegure de que la URL proporcionada es correcta y proviene de una fuente de confianza. Ruby SAML no realiza ninguna validación de que la URL que ha introducido sea correcta y/o segura.
• Advertencias de seguridad falsos positivos: Algunas herramientas pueden informar incorrectamente de que Ruby SAML es una posible vulnerabilidad de seguridad, debido a su dependencia de Nokogiri. Dichas advertencias pueden ignorarse; Ruby SAML utiliza Nokogiri de forma segura, deshabilitando siempre su opción DTDLOAD y habilitando su opción NONET.
• Prevenir ataques de repetición: Un ataque de repetición ocurre cuando un atacante intercepta una aserción SAML válida y la reutiliza para obtener acceso no autorizado. La librería ruby-saml proporciona herramientas para ayudar a mitigar este riesgo, pero es su responsabilidad implementar la lógica necesaria. Consulte Preventing Replay Attacks para obtener orientación adicional.

Versiones de Ruby compatibles

Las siguientes versiones de Ruby están cubiertas por las pruebas de CI:

• Ruby (MRI) 2.1 a 4.0
• JRuby 9.1 a 9.4
• TruffleRuby (última)

Primeros pasos

Para utilizar Ruby SAML necesitará instalar la gema (ya sea manualmente o usando Bundler), y requerir la librería en su aplicación Ruby:

Usando Gemfile

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

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

Usando RubyGems

gem install ruby-saml

Es posible que necesites la gema completa Ruby SAML:

require 'onelogin/ruby-saml'

o simplemente los componentes requeridos individualmente:

require 'onelogin/ruby-saml/authrequest'

Instalación en Ruby 1.8.7

Esta gema utiliza Nokogiri como dependencia, la cual dejó de dar soporte a Ruby 1.8.x en Nokogiri 1.6. Al instalar esta gema en Ruby 1.8.7, deberás asegurarte de que se instale o especifique una versión de Nokogiri anterior a la 1.6 si aún no se ha hecho.

Usando Gemfile

gem 'nokogiri', '~> 1.5.10'

Usando RubyGems

gem install nokogiri --version '~> 1.5.10'

Configuración del registro

Al solucionar problemas de integración de SAML, le resultará extremadamente útil examinar la salida de la lógica de negocio de esta gema. De forma predeterminada, los mensajes de registro se emiten a RAILS_DEFAULT_LOGGER cuando la gema se utiliza en un contexto de Rails, y a STDOUT cuando la gema se utiliza fuera de Rails.

Para anular el comportamiento predeterminado y controlar el destino de los mensajes de registro, proporcione un objeto Logger de ruby al singleton de registro de la gema:

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

La fase de inicialización

Esta es la primera solicitud que recibirás del proveedor de identidad. Llegará a tu aplicación en una URL específica que hayas anunciado como tu punto de inicialización SAML. La respuesta a esta inicialización es una redirección de vuelta al proveedor de identidad, que puede verse algo así (ignora la llamada al método saml_settings por ahora):

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

Si el SP sabe quién debe autenticarse en el IdP, puede proporcionar esa información de la siguiente manera:

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