Ruby SAML 项目技术文档

1. 安装指南

使用 Bundler

在项目的 Gemfile 中添加以下内容：

# 最新稳定版本
gem 'ruby-saml', '~> 1.11.0'

# 或者跟踪 master 分支以获取最新功能
gem 'ruby-saml', :github => 'saml-toolkit/ruby-saml'

然后运行以下命令安装 gem：

bundle install

使用 RubyGems

直接通过 RubyGems 安装：

gem install ruby-saml

在 Ruby 1.8.7 上安装

由于 ruby-saml 依赖 Nokogiri，而 Nokogiri 在 1.6 版本后不再支持 Ruby 1.8.x。因此，在 Ruby 1.8.7 上安装时，需要确保安装的是 Nokogiri 1.6 之前的版本。

在 Gemfile 中指定 Nokogiri 版本：

gem 'nokogiri', '~> 1.5.10'

或者通过 RubyGems 安装：

gem install nokogiri --version '~> 1.5.10'

2. 项目的使用说明

概述

Ruby SAML 是一个用于实现 SAML 认证客户端的 Ruby 库。它提供了管理身份提供者（IdP）的授权初始化和确认请求的功能。SAML 认证是一个两步过程，用户需要实现这两个步骤的支持。

初始化阶段

当用户从身份提供者（IdP）收到初始化请求时，应用程序会重定向回 IdP。以下是一个示例代码：

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

如果服务提供者（SP）知道应该由哪个用户在 IdP 中进行认证，可以提供相关信息：

def init
  request = OneLogin::RubySaml::Authrequest.new
  saml_settings.name_identifier_value_requested = "[e-mail]"
  saml_settings.name_identifier_format = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
  redirect_to(request.create(saml_settings))
end

消费阶段

当 IdP 完成用户认证后，会重定向回应用程序。以下是一个消费阶段的示例代码：

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

  if response.is_valid?
     session[:userid] = response.nameid
     session[:attributes] = response.attributes
  else
    authorize_failure  # 显示错误信息
  end
end

3. 项目 API 使用文档

初始化 SAML 请求

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

处理 SAML 响应

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

if response.is_valid?
   # 认证成功，记录用户信息
   session[:userid] = response.nameid
   session[:attributes] = response.attributes
else
   # 认证失败，处理错误
end

配置 SAML 设置

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"
  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"
  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"

  settings
end

4. 项目安装方式

使用 Bundler

在 Gemfile 中添加：

gem 'ruby-saml', '~> 1.11.0'

然后运行：

bundle install

使用 RubyGems

直接安装：

gem install ruby-saml

在 Ruby 1.8.7 上安装

确保安装 Nokogiri 1.6 之前的版本：

gem 'nokogiri', '~> 1.5.10'

或者：

gem install nokogiri --version '~> 1.5.10'