Ruby SAML

GitHub Gem Gem

Versões menores e de patch do Ruby SAML podem introduzir alterações que quebram a compatibilidade. Por favor, leia UPGRADING.md para orientações sobre como atualizar para novas versões do Ruby SAML.

Aviso de Vulnerabilidade

CVE-2025-66568 e CVE-2025-66567. afetam a versão ruby-saml < 1.18.0 (incluindo 1.12.4), atualize para 1.18.1

CVE-2025-54572 afeta a versão ruby-saml < 1.18.1

Existem vulnerabilidades críticas que afetam o ruby-saml < 1.18.0, duas delas permitem o bypass de autenticação SAML (CVE-2025-25291, CVE-2025-25292, CVE-2025-25293). Por favor, atualize para uma versão corrigida (1.18.0)

Relato de Vulnerabilidades

Se você acredita ter descoberto uma vulnerabilidade de segurança nesta gem, por favor reporte-a por e-mail ao mantenedor: [email protected]

Patrocinadores

Agradecemos aos seguintes patrocinadores por protegerem o ecossistema de código aberto:

^SerpApi

^{Uma API em tempo real para acessar resultados de pesquisa do Google. Ela lida com proxies, resolve captchas e analisa todos os dados estruturados ricos para você}

^Github

^{A plataforma completa para desenvolvedores criarem, escalarem e entregarem software seguro.}

^84codes

^{Simplificando o Enfileiramento de Mensagens e Streaming. Deixe o gerenciamento de servidores para os especialistas, para que você possa focar em construir ótimas aplicações.}

Visão Geral

A biblioteca Ruby SAML serve para implementar o lado cliente de uma autorização SAML, ou seja, ela fornece um meio de gerenciar a inicialização e confirmação de requisições de autorização a partir de provedores de identidade.

A autorização SAML é um processo de duas etapas e espera-se que você implemente suporte para ambas.

Criamos um projeto de demonstração para Rails 4 que usa a versão mais recente desta biblioteca: ruby-saml-example

Considerações de Segurança

Validação da URL de Metadados do IdP: Ao carregar Metadados do IdP a partir de URLs, o Ruby SAML exige que você (o desenvolvedor/administrador) garanta que a URL fornecida está correta e é de uma fonte confiável. O Ruby SAML não realiza nenhuma validação de que a URL que você inseriu está correta e/ou é segura.
Avisos de Segurança Falso-Positivos: Algumas ferramentas podem relatar incorretamente o Ruby SAML como uma potencial vulnerabilidade de segurança, devido à sua dependência do Nokogiri. Tais avisos podem ser ignorados; o Ruby SAML usa o Nokogiri de forma segura, sempre desabilitando sua opção DTDLOAD e habilitando sua opção NONET.
Prevenção de ataques de Replay: Um ataque de replay ocorre quando um atacante intercepta uma asserção SAML válida e a reutiliza para obter acesso não autorizado. A biblioteca ruby-saml fornece ferramentas para ajudar a mitigar esse risco, mas é sua responsabilidade implementar a lógica necessária. Consulte Prevenção de Ataques de Replay para orientações adicionais.

Versões do Ruby Suportadas

As seguintes versões do Ruby são cobertas por testes de CI:

Ruby (MRI) 2.1 a 4.0
JRuby 9.1 a 9.4
TruffleRuby (mais recente)

Primeiros Passos

Para usar o Ruby SAML você precisará instalar a gem (manualmente ou usando o Bundler), e requerer a biblioteca em sua aplicação 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

Você pode precisar da gem Ruby SAML completa:

require 'onelogin/ruby-saml'

ou apenas os componentes necessários individualmente:

require 'onelogin/ruby-saml/authrequest'

Instalação no Ruby 1.8.7

Esta gem usa o Nokogiri como dependência, que deixou de oferecer suporte ao Ruby 1.8.x no Nokogiri 1.6. Ao instalar esta gem no Ruby 1.8.7, você precisará garantir que uma versão do Nokogiri anterior à 1.6 esteja instalada ou especificada, caso ainda não esteja.

Usando Gemfile

gem 'nokogiri', '~> 1.5.10'

Usando RubyGems

gem install nokogiri --version '~> 1.5.10'

Configurando o Logging

Ao solucionar problemas de integração SAML, será extremamente útil examinar a saída da lógica de negócios desta gem. Por padrão, as mensagens de log são emitidas para RAILS_DEFAULT_LOGGER quando a gem é usada em um contexto Rails, e para STDOUT quando a gem é usada fora do Rails.

Para substituir o comportamento padrão e controlar o destino das mensagens de log, forneça um objeto Logger ruby para o singleton de logging da gem:

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

A Fase de Inicialização

Esta é a primeira requisição que você receberá do provedor de identidade. Ela atingirá sua aplicação em uma URL específica que você anunciou como seu ponto de inicialização SAML. A resposta a esta inicialização é um redirecionamento de volta ao provedor de identidade, que pode parecer algo assim (ignore a chamada do método saml_settings por enquanto):

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

Se o SP sabe quem deve ser autenticado no IdP, pode fornecer essa informação da seguinte forma:

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

Mais Populares