描述

导轨::验证是一个灵活的库专为使用Rack中间件两种身份验证（AuthN）可以和授权（AuthZ的）。它拆分AuthN和AuthZ的步骤到单独的中间件类，使用AuthN中间件首先验证凭据（如X.509证书或饼干），然后授权通过单独的authz中间件消耗这些凭据，如访问控制列表的请求（访问控制列表） 。

导轨::验证可用于验证和使用浏览器cookie授权最终用户，使用X.509客户端证书，或任何其他客户与有适当的身份验证凭据的中间件服务到服务请求。

安装

该行添加到您的应用程序的Gemfile：

gem 'rails-auth'

然后执行：

$ bundle

或自行安装为：

$ gem install rails-auth

用法

要使用Rails的::验证，您将需要配置相关AuthN和AuthZ的中间件为您的应用程序。

轨::验证附带以下中间件：

• AuthN：导轨::验证:: X509 ::中间件：通过他们的SSL / TLS客户端证书验证客户端的支持。
• AuthZ的：导轨::验证:: ACL ::中间件：对于授权使用访问控制列表（ACL）请求支持。

这些中间件和如何使用它们的文档提供如下。

访问控制列表（ACL）

ACL是主要工具的Rails ::验证提供AuthZ的。ACL使用一组路由由路由匹配器来控制访问特定资源。不像一些Rails的AuthZ的框架，这种宝石授予/拒绝访问控制器动作，而不是帮助你提供不同的内容，不同的角色或不同的允许，说的参数，更新操作。

导轨::验证鼓励使用YAML文件，用于存储ACL定义，虽然使用YAML的不是强制性的，并从输出相应的对象结构YAML.load可以替代地通过。以下是一个YAML ACL定义的例子：

- --
 - resources:
   - method:  ALL 
    path:  /foo/bar/.* 
  allow_x509_subject: 
    ou:  ponycopter 
  allow_claims: 
    groups:  ["example"]
 - resources:
   - method:  ALL 
    path:  /_admin/.* 
  allow_claims: 
    groups:  ["admins"]
 - resources:
   - method:  GET 
    path:  /internal/frobnobs/.* 
  allow_x509_subject: 
    ou:  frobnobber
 - resources:
   - method:  GET 
    path:  / 
  allow_all:  true

ACL由保护表达式，每个都包含资源列表和一组可授权访问这些资源谓词的列表中。任何匹配谓词将授权访问任何一个给定的表达式中所列的资源。

资源由下面的约束定义：

• 方法：请求的HTTP方法，或“ALL”允许任何方法
• 路径：一个正则表达式匹配的路径\ A和\ Z默认情况下，在开头的正则表达式的末尾添加，以保证整个路径，而不是一个子字符串匹配。

一旦你定义了ACL，则需要在Ruby中创建一个相应的ACL对象和中间件授权使用ACL请求。添加以下代码的任何地方，你可以修改中间件链（如config.ru）：

app = MyRackApp.new

acl = Rails::Auth::ACL.from_yaml(
  File.read("/path/to/my/acl.yaml"),
  matchers: { allow_claims: MyClaimsMatcher }
)

acl_auth = Rails::Auth::ACL::Middleware.new(app, acl: acl)

run acl_auth

你需要在对应于ACL的按键谓词的匹配的哈希值传递。请参阅以下如何配置中间件为“X.509客户端证书”部分allow_x509_subject。

以下谓词匹配器是内置的和随时可用：

• ALLOW_ALL：（选择：真或假的）总是允许请求给定的资源（只要真正将作为选项传递）

自定义谓词匹配器可以是响应任何Ruby类#match 方法。完整的机架环境中传递给#match。从ACL定义相应的对象被传递到类的#initialize方法。下面是一个简单的自定义谓词匹配的例子：

class MyClaimsMatcher
  def initialize(options)
    @options = options
  end

  def match(env)
    claims = Rails::Auth.credentials(env)["claims"]
    return false unless credential

    @options["groups"].any { |group| claims["groups"].include(group) }
  end
end

X.509客户端证书

一个添加的Rails ::验证:: X509 ::中间件对象添加到您Rack中间件链来验证X.509客户端证书（如中config.ru）：

app = MyRackApp.new

acl = Rails::Auth::ACL.from_yaml(
  File.read("/path/to/my/acl.yaml")
  matchers: { allow_x509_subject: Rails::Auth::X509::Matcher }
)

acl_auth = Rails::Auth::ACL::Middleware.new(app, acl: acl)

x509_auth = Rails::Auth::X509::Middleware.new(
  acl_auth,
  ca_file: "/path/to/my/cabundle.pem"
  cert_filters: { 'X-SSL-Client-Cert' => :pem },
  require_cert: true
)

run x509_auth

构造函数采用下列参数：

• 应用：链中的下一个机架中间件。您可能会想使用的Rails ::验证:: ACL ::中间件实例作为链中的下一个中间件。
• ca_file：路径的证书颁发机构（CA）软件包，用以验证客户端。这通常是用来发放X.509证书的内部服务，而不是商业CA通常使用的浏览器内部CA（S）证书。客户端证书将被忽略，除非它们可以由CAS该软件包中的一个进行验证。
• cert_filters：一个哈希它配置客户端证书如何从机架环境中提取。您需要配置Web服务器，包括在机架环境的证书。参见下面的注解了解更多详情。
• require_cert：（默认为false）要求，为了有效的客户端证书的请求来完成。这就禁止了在没有一个有效的客户端证书，谁的客户端访问您的应用程序。当启用时，中间件会提高的Rails ::验证:: X509 :: CertificateVerifyFailed例外。

当创建的Rails ::验证:: ACL ::中间件，请确保传递 的匹配：{allow_x509_subject：导轨::验证:: X509 ::匹配器}为了在你的ACL来使用此谓词。这个谓词匹配默认情况下不启用。

对于客户端证书的工作，你需要配置你的Web服务器，包括他们在您的机架环境中，并且还配置cert_filters正确地过滤和机架环境中处理它们。

例如，如果你使用的nginx +客运，你需要添加类似下面的到你的nginx的配置：

passenger_set_cgi_param的X SSL客户端证书$ ssl_client_raw_cert;

一旦客户证书是在某种形式的机架环境中，你需要配置一个过滤器对象，它可以转换它从机架环境形式到OpenSSL的:: X509 ::证书实例。有两个内置的可作为符号来做到这一点参考滤波器：

• ：PEM：从增强保密邮件格式解析证书
• ：JAVA：皈依sun.security.x509.X509CertImpl对象实例

该cert_filters参数是机架环境名称对应的过滤器映射：

cert_filters: { 'X-SSL-Client-Cert' => :pem }

除了 这些符号，滤波器可以是响应任何对象 #CALL方法，如一个PROC。以下过滤器将解析PEM证书：

cert_filters: { 'X-SSL-Client-Cert' => proc { |pem| OpenSSL::X509::Certificate.new(pem) } }

当证书的认可和验证，一个滑轨::验证:: X509 ::证书 对象将根据被添加到机架环境ENV [“轨-auth.credentials”] [“X509”]。该中间件将永远不会任何证书添加到尚未验证对配置CA束环境的凭据。

RSpec的整合

导轨::验证包括内置的匹配器，让你写你的ACL测试，以确保他们有你所期望的行为。

要启用RSpec的支持，要求如下：

require "rails/auth/rspec"

下面是如何编写ACL规范的例子：

RSpec.describe "example_acl.yml", acl_spec: true do
  let(:example_credentials) { x509_certificate_hash(ou: "ponycopter") }

  subject do
    Rails::Auth::ACL.from_yaml(
      File.read("/path/to/example_acl.yml"),
      matchers: { allow_x509_subject: Rails::Auth::X509::Matcher }
    )
  end

  describe "/path/to/resource" do
    it { is_expected.to     permit get_request(credentials: example_credentials) }
    it { is_expected.not_to permit get_request) }
  end
end

下面的辅助方法可供选择：

• x509_certificate，x509_certificate_hash：创建的Rails ::验证:: X509 ::证书实例双打
• 请求建设者：下面的方法建立从描述的路径请求：
  • get_request
  • head_request
  • put_request
  • post_request
  • delete_request
  • options_request
  • path_request
  • link_request
  • unlink_request

下面的匹配器可供选择：

• allow_request：允许与给定的机架环境的请求，以及任选的凭证

错误页面中间件

当一个授权错误发生时，Rails的::验证:: NotAuthorizedError 异常引发了中间件链。但是，很可能你宁愿显示错误页面不是有未处理的异常。

你可以写你自己的中间件，捕捉的Rails ::验证:: NotAuthorizedError ，如果你愿意的话。然而，一个默认的设置，如果你发现有帮助这使得一个静态页面体403的响应。

要使用它，添加的Rails ::验证:: ::的errorPage中间件到应用程式：

app = MyRackApp.new

acl = Rails::Auth::ACL.from_yaml(
  File.read("/path/to/my/acl.yaml")
  matchers: { allow_x509_subject: Rails::Auth::X509::Matcher }
)

acl_auth = Rails::Auth::ACL::Middleware.new(app, acl: acl)

x509_auth = Rails::Auth::X509::Middleware.new(
  acl_auth,
  ca_file: "/path/to/my/cabundle.pem"
  cert_filters: { 'X-SSL-Client-Cert' => :pem },
  require_cert: true
)

error_page = Rails::Auth::ErrorPage::Middleware.new(
  x509_auth,
  page_body: File.read("path/to/403.html")
)

run error_page

下载地址https://github.com/square/rails-auth/archive/master.zip