Ruby SAML

GitHub Gem Gem

Le versioni minor e patch di Ruby SAML possono introdurre modifiche incompatibili. Consulta UPGRADING.md per indicazioni sull'aggiornamento alle nuove versioni di Ruby SAML.

Avviso di vulnerabilità

CVE-2025-66568 e CVE-2025-66567. interessano la versione ruby-saml < 1.18.0 (inclusa la 1.12.4), aggiorna alla 1.18.1

CVE-2025-54572 interessa la versione ruby-saml < 1.18.1

Esistono vulnerabilità critiche che interessano ruby-saml < 1.18.0, due delle quali consentono il bypass dell'autenticazione SAML (CVE-2025-25291, CVE-2025-25292, CVE-2025-25293). Si prega di aggiornare a una versione corretta (1.18.0)

Segnalazione di vulnerabilità

Se ritieni di aver scoperto una vulnerabilità di sicurezza in questa gem, segnalala via email al maintainer: [email protected]

Grazie ai seguenti sponsor per aver messo in sicurezza l'ecosistema open source:

^SerpApi

^{Un'API in tempo reale per accedere ai risultati di ricerca di Google. Gestisce proxy, risolve captcha e analizza tutti i dati strutturati avanzati per te}

^Github

^{La piattaforma completa per sviluppatori per creare, scalare e distribuire software sicuro.}

^84codes

^{Semplificare il Message Queuing e lo Streaming. Lascia la gestione del server agli esperti, così puoi concentrarti sulla creazione di ottime applicazioni.}

Panoramica

La libreria Ruby SAML serve per implementare il lato client di un'autorizzazione SAML, ovvero fornisce un mezzo per gestire le richieste di inizializzazione e conferma dell'autorizzazione da parte degli identity provider.

L'autorizzazione SAML è un processo in due fasi e ci si aspetta che tu implementi il supporto per entrambe.

Abbiamo creato un progetto demo per Rails 4 che utilizza l'ultima versione di questa libreria: ruby-saml-example

Considerazioni sulla sicurezza

Validazione dell'URL dei metadati IdP: Quando carichi i metadati IdP da un URL, Ruby SAML richiede a te (sviluppatore/amministratore) di assicurarti che l'URL fornito sia corretto e provenga da una fonte attendibile. Ruby SAML non esegue alcuna validazione che l'URL inserito sia corretto e/o sicuro.
Avvisi di sicurezza falsi positivi: Alcuni strumenti potrebbero segnalare erroneamente Ruby SAML come potenziale vulnerabilità di sicurezza, a causa della sua dipendenza da Nokogiri. Tali avvisi possono essere ignorati; Ruby SAML utilizza Nokogiri in modo sicuro, disabilitando sempre la sua opzione DTDLOAD e abilitando la sua opzione NONET.
Prevenire gli attacchi di replay: Un attacco di replay si verifica quando un attaccante intercetta un'asserzione SAML valida e la riutilizza per ottenere accesso non autorizzato. La libreria ruby-saml fornisce strumenti per aiutare a mitigare questo rischio, ma è tua responsabilità implementare la logica necessaria. Consulta Prevenire gli attacchi di replay per ulteriori indicazioni.

Versioni di Ruby supportate

Le seguenti versioni di Ruby sono coperte dai test CI:

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

Per iniziare

Per utilizzare Ruby SAML dovrai installare la gem (manualmente o usando Bundler), e richiedere la libreria nella tua applicazione 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'

Utilizzo di RubyGems

gem install ruby-saml

Potresti aver bisogno dell'intero gem Ruby SAML:

require 'onelogin/ruby-saml'

o solo i componenti richiesti individualmente:

require 'onelogin/ruby-saml/authrequest'

Installazione su Ruby 1.8.7

Questa gem utilizza Nokogiri come dipendenza, che ha abbandonato il supporto per Ruby 1.8.x in Nokogiri 1.6. Quando si installa questa gem su Ruby 1.8.7, sarà necessario assicurarsi che una versione di Nokogiri precedente alla 1.6 sia installata o specificata, se non lo è già stata.

Utilizzando Gemfile

gem 'nokogiri', '~> 1.5.10'

Utilizzo di RubyGems

gem install nokogiri --version '~> 1.5.10'

Configurazione del Logging

Quando si risolvono problemi di integrazione SAML, sarà estremamente utile esaminare l'output della logica di business di questa gem. Per impostazione predefinita, i messaggi di log vengono emessi su RAILS_DEFAULT_LOGGER quando la gem viene utilizzata in un contesto Rails, e su STDOUT quando la gem viene utilizzata al di fuori di Rails.

Per sovrascrivere il comportamento predefinito e controllare la destinazione dei messaggi di log, fornire un oggetto Logger ruby al singleton di logging della gem:

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

La fase di inizializzazione

Questa è la prima richiesta che riceverai dal provider di identità. Colpirà la tua applicazione a un URL specifico che hai annunciato come punto di inizializzazione SAML. La risposta a questa inizializzazione è un reindirizzamento verso il provider di identità, che può apparire più o meno così (ignora per ora la chiamata al metodo saml_settings):

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

Se lo SP sa chi dovrebbe essere autenticato nell'IdP, può fornire tali informazioni come segue:

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

Più Popolari