Ruby SAML

GitHub Gem Gem

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 に影響する重大な脆弱性が存在し、そのうち 2 つは SAML 認証バイパスを可能にします（CVE-2025-25291、CVE-2025-25292、CVE-2025-25293）。修正されたバージョン（1.18.0）にアップグレードしてください。

脆弱性の報告

この gem にセキュリティ脆弱性を発見したと思われる場合は、メンテナーまでメールで報告してください: [email protected]

スポンサー

オープンソースエコシステムを保護してくださっている以下のスポンサーに感謝します:

^SerpApi

^{Google 検索結果にアクセスするためのリアルタイム API。プロキシを処理し、キャプチャを解決し、すべてのリッチな構造化データを解析します}

^Github

^{安全なソフトウェアを構築、拡張、提供するための完全な開発者プラットフォーム。}

^84codes

^{メッセージキューイングとストリーミングを簡素化。サーバー管理は専門家に任せて、優れたアプリケーションの構築に集中できます。}

概要

Ruby SAML ライブラリは、SAML 認可のクライアント側を実装するためのものであり、つまり、アイデンティティプロバイダーからの認可の初期化および確認リクエストを管理する手段を提供します。

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 のサポートが終了しました。この gem を Ruby 1.8.7 にインストールする際は、まだインストールされていない場合は、Nokogiri の 1.6 より前のバージョンがインストールされているか、指定されていることを確認する必要があります。

Gemfile を使用する場合

gem 'nokogiri', '~> 1.5.10'

RubyGemsの使用

gem install nokogiri --version '~> 1.5.10'

ログの設定

SAML 統合の問題をトラブルシューティングする際には、この gem のビジネスロジックの出力を調べることが非常に役立ちます。デフォルトでは、gem が Rails コンテキストで使用される場合はログメッセージが RAILS_DEFAULT_LOGGER に出力され、Rails 外で使用される場合は STDOUT に出力されます。

デフォルトの動作を上書きし、ログメッセージの出力先を制御するには、Ruby の Logger オブジェクトを gem のロギングシングルトンに渡します:

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

初期化フェーズ

これはIDプロバイダーから受け取る最初のリクエストです。これは、SAML初期化ポイントとして告知した特定のURLでアプリケーションに到達します。この初期化への応答は、IDプロバイダーへのリダイレクトであり、次のようになります（今はsaml_settingsメソッド呼び出しは無視してください）：

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

IdP で誰を認証すべきかを SP が把握している場合、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

ID プロバイダーにリダイレクトして戻ると、ユーザーが認可されていることを確認し、最終的な利用のためにアプリケーションにリダイレクトして戻ります。これは次のようになります（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

上記にはいくつかの前提があり、その1つは response.nameid がメールアドレスであることです。これはすべて、saml_settings メソッドを介して指定する設定によって処理されます。それは次のような形で実装できます:

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

SAMLResponseのアサーションが暗号化されていない場合は、:settings パラメータなしで Response を初期化し、後で設定できます。SAMLResponse に暗号化されたアサーションが含まれている場合は、復号されたアサーションを取得するために initialize メソッドで設定を提供する必要があり、復号にはサービスプロバイダの秘密鍵を使用します。何が期待されるかわからない場合は、常に前者（initialize で設定をセットする）を使用してください。

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"

ruby-saml

人気