Ruby SAML

Ruby SAML의 마이너 및 패치 버전은 호환성을 깨뜨리는 변경 사항을 도입할 수 있습니다. 새로운 Ruby SAML 버전으로 업그레이드하는 방법에 대한 안내는 UPGRADING.md를 읽어보세요.

취약점 공지

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)으로 업그레이드하세요.

취약점 신고

이 gem에서 보안 취약점을 발견했다고 생각되면 유지 관리자에게 이메일로 신고해 주세요: [email protected]

스폰서

오픈 소스 생태계를 보호해 주신 다음 스폰서분들께 감사드립니다:

^SerpApi

^{Google 검색 결과에 접근하기 위한 실시간 API입니다. 프록시를 처리하고, 캡차를 해결하며, 모든 풍부한 구조화 데이터를 파싱해 드립니다}

^Github

^{안전한 소프트웨어를 구축, 확장 및 제공하기 위한 완벽한 개발자 플랫폼입니다.}

^84codes

^{메시지 큐잉과 스트리밍을 단순화합니다. 서버 관리는 전문가에게 맡기고 훌륭한 애플리케이션 구축에 집중하세요.}

개요

Ruby SAML 라이브러리는 SAML 인증의 클라이언트 측을 구현하기 위한 것으로, 즉 ID 공급자(identity provider)로부터의 인증 초기화 및 확인 요청을 관리하는 수단을 제공합니다.

SAML 인증은 2단계 프로세스이며, 두 단계 모두에 대한 지원을 구현해야 합니다.

이 라이브러리의 최신 버전을 사용하는 Rails 4용 데모 프로젝트를 만들었습니다: ruby-saml-example

보안 고려 사항

• IdP 메타데이터 URL 검증: URL에서 IdP 메타데이터를 로드할 때, Ruby SAML은 개발자/관리자인 여러분이 제공된 URL이 올바르고 신뢰할 수 있는 출처인지 확인할 것을 요구합니다. Ruby SAML은 입력한 URL이 올바르고 안전한지에 대한 어떠한 검증도 수행하지 않습니다.
• 오탐 보안 경고: 일부 도구는 Nokogiri에 대한 의존성 때문에 Ruby SAML을 잠재적 보안 취약점으로 잘못 보고할 수 있습니다. 이러한 경고는 무시해도 됩니다. Ruby SAML은 항상 DTDLOAD 옵션을 비활성화하고 NONET 옵션을 활성화하여 Nokogiri를 안전하게 사용합니다.
• 재전송 공격 방지: 재전송 공격은 공격자가 유효한 SAML 어설션을 가로채어 무단 접근을 얻기 위해 재사용할 때 발생합니다. ruby-saml 라이브러리는 이러한 위험을 완화하는 데 도움이 되는 도구를 제공하지만, 필요한 로직을 구현하는 것은 여러분의 책임입니다. 추가 안내는 재전송 공격 방지를 참조하세요.

지원되는 Ruby 버전

다음 Ruby 버전은 CI 테스트로 검증됩니다:

• Ruby (MRI) 2.1 ~ 4.0
• JRuby 9.1 ~ 9.4
• TruffleRuby (최신)

시작하기

Ruby SAML을 사용하려면 gem을 설치하고(수동 또는 Bundler 사용), Ruby 애플리케이션에서 라이브러리를 require해야 합니다:

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 gem이 필요할 수 있습니다:

require 'onelogin/ruby-saml'

또는 필요한 구성 요소만 개별적으로:

require 'onelogin/ruby-saml/authrequest'

Ruby 1.8.7에서 설치

이 gem은 Nokogiri를 의존성으로 사용하는데, Nokogiri 1.6에서 Ruby 1.8.x 지원이 중단되었습니다. Ruby 1.8.7에서 이 gem을 설치할 때는, 아직 설치되지 않았다면 1.6 이전 버전의 Nokogiri를 설치하거나 명시해야 합니다.

Gemfile 사용

gem 'nokogiri', '~> 1.5.10'

RubyGems 사용

gem install nokogiri --version '~> 1.5.10'

로깅 구성

SAML 통합 문제를 해결할 때, 이 gem의 비즈니스 로직 출력을 검토하는 것이 매우 유용합니다. 기본적으로 이 gem이 Rails 컨텍스트에서 사용될 때는 로그 메시지가 RAILS_DEFAULT_LOGGER로 출력되고, Rails 외부에서 사용될 때는 STDOUT으로 출력됩니다.

기본 동작을 재정의하고 로그 메시지의 대상을 제어하려면, gem의 로깅 싱글톤에 ruby Logger 객체를 제공하세요:

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

초기화 단계

이것은 아이덴티티 제공자로부터 받게 될 첫 번째 요청입니다. 이 요청은 SAML 초기화 지점으로 공지한 특정 URL에서 애플리케이션에 도달합니다. 이 초기화에 대한 응답은 아이덴티티 제공자로 다시 리디렉션되며, 다음과 같이 보일 수 있습니다(지금은 saml_settings 메서드 호출은 무시하세요):

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

IdP에서 누가 인증되어야 하는지 SP가 알고 있다면, 다음과 같이 해당 정보를 제공할 수 있습니다:

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

다시 identity provider로 리디렉션되면, 해당 provider는 사용자가 인가되었는지 확인한 후 최종 사용을 위해 애플리케이션으로 다시 리디렉션합니다. 이는 다음과 같이 보일 수 있습니다 (authorize_success 및 authorize_failure 메서드는 애플리케이션에 특화되어 있습니다):

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

  # We validate the SAML Response and check if the user already exists in the system
  if response.is_valid?
     # authorize_success, log the user
     session[:userid] = response.nameid
     session[:attributes] = response.attributes
  else
    authorize_failure  # This method shows an error message
    # List of errors is available in response.errors array
  end
end

위 내용에는 몇 가지 가정이 있는데, 그중 하나는 response.nameid가 이메일 주소라는 것입니다. 이는 모두 saml_settings 메서드를 통해 적용되는 설정을 어떻게 지정하느냐에 따라 처리됩니다. 이는 다음과 같은 방식으로 구현할 수 있습니다:

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

SAMLResponse의 assertion이 암호화되지 않은 경우, :settings 매개변수 없이 Response를 초기화한 후 나중에 설정할 수 있습니다. SAMLResponse에 암호화된 assertion이 포함된 경우, 복호화된 assertion을 얻기 위해 initialize 메서드에서 settings를 제공해야 하며, 복호화를 위해 서비스 제공자 개인 키를 사용합니다. 무엇을 예상해야 할지 모르겠다면, 항상 전자(initialize에서 settings 설정)를 사용하세요.

def saml_settings
  settings = OneLogin::RubySaml::Settings.new

  settings.assertion_consumer_service_url = "http://#{request.host}/saml/consume"
  settings.sp_entity_id                   = "http://#{request.host}/saml/metadata"
  settings.idp_entity_id                  = "https://app.onelogin.com/saml/metadata/#{OneLoginAppId}"
  settings.idp_sso_service_url            = "https://app.onelogin.com/trust/saml2/http-post/sso/#{OneLoginAppId}"
  settings.idp_sso_service_binding        = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" # or :post, :redirect
  settings.idp_slo_service_url            = "https://app.onelogin.com/trust/saml2/http-redirect/slo/#{OneLoginAppId}"
  settings.idp_slo_service_binding        = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" # or :post, :redirect
  settings.idp_cert_fingerprint           = OneLoginAppCertFingerPrint
  settings.idp_cert_fingerprint_algorithm = "http://www.w3.org/2000/09/xmldsig#sha1"
  settings.name_identifier_format         = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"