README.md in rails-auth-0.0.1 vs README.md in rails-auth-0.1.0
- old
+ new
@@ -1,16 +1,22 @@
-# Rails::Auth
+Rails::Auth
+===========
+[](http://rubygems.org/gems/rails-auth)
+[](https://travis-ci.org/square/rails-auth)
+[](https://codeclimate.com/github/square/rails-auth)
+[](https://coveralls.io/github/square/rails-auth?branch=master)
+[](https://github.com/square/rails-auth/blob/master/LICENSE)
Modular resource-based authentication and authorization for Rails/Rack
## Description
Rails::Auth is a flexible library designed for both authentication (AuthN) and
authorization (AuthZ) using Rack Middleware. It splits the AuthN and AuthZ
steps into separate middleware classes, using AuthN middleware to first verify
-request client identities, or "principals", then authorizing the request
-via separate AuthZ middleware that consumes these principals, e.g. access
+credentials (such as X.509 certificates or cookies), then authorizing the request
+via separate AuthZ middleware that consumes these credentials, e.g. access
control lists (ACLs).
Rails::Auth can be used to authenticate and authorize end users using browser
cookies, service-to-service requests using X.509 client certificates, or any
other clients with credentials that have proper authenticating middleware.
@@ -37,11 +43,11 @@
middleware for your app.
Rails::Auth ships with the following middleware:
* **AuthN**: `Rails::Auth::X509::Middleware`: support for authenticating
- principals by their SSL/TLS client certificates.
+ clients by their SSL/TLS client certificates.
* **AuthZ**: `Rails::Auth::ACL::Middleware`: support for authorizing requests
using Access Control Lists (ACLs).
Documentation of these middleware and how to use them is provided below.
@@ -102,11 +108,11 @@
```ruby
app = MyRackApp.new
acl = Rails::Auth::ACL.from_yaml(
File.read("/path/to/my/acl.yaml"),
- matchers: { allow_claims: MyClaimsPredicate }
+ matchers: { allow_claims: MyClaimsMatcher }
)
acl_auth = Rails::Auth::ACL::Middleware.new(app, acl: acl)
run acl_auth
@@ -125,18 +131,18 @@
method. The full Rack environment is passed to `#match`. The corresponding
object from the ACL definition is passed to the class's `#initialize` method.
Here is an example of a simple custom predicate matcher:
```ruby
-class MyClaimsPredicate
+class MyClaimsMatcher
def initialize(options)
@options = options
end
def match(env)
- claims = Rails::Auth.principals(env)["claims"]
- return false unless principal
+ claims = Rails::Auth.credentials(env)["claims"]
+ return false unless credential
@options["groups"].any? { |group| claims["groups"].include?(group) }
end
end
@@ -221,13 +227,13 @@
```ruby
cert_filters: { 'X-SSL-Client-Cert' => proc { |pem| OpenSSL::X509::Certificate.new(pem) } }
```
-When certificates are recognized and verified, an `Rails::Auth::X509::Principal`
-object will be added to the Rack environment under `env["rails-auth.principals"]["x509"]`.
-This middleware will never add any certificate to the environment's principals
+When certificates are recognized and verified, a `Rails::Auth::X509::Certificate`
+object will be added to the Rack environment under `env["rails-auth.credentials"]["x509"]`.
+This middleware will never add any certificate to the environment's credentials
that hasn't been verified against the configured CA bundle.
## RSpec integration
Rails::Auth includes built-in matchers that allow you to write tests for your
@@ -241,29 +247,29 @@
Below is an example of how to write an ACL spec:
```ruby
RSpec.describe "example_acl.yml", acl_spec: true do
- let(:example_principals) { x509_principal_hash(ou: "ponycopter") }
+ 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(principals: example_principals) }
+ it { is_expected.to permit get_request(credentials: example_credentials) }
it { is_expected.not_to permit get_request) }
end
end
```
The following helper methods are available:
-* `x509_principal`, `x509_principal_hash`: create instance doubles of Rails::Auth::X509::Principals
+* `x509_certificate`, `x509_certificate_hash`: create instance doubles of Rails::Auth::X509::Certificate
* Request builders: The following methods build requests from the described path:
* `get_request`
* `head_request`
* `put_request`
* `post_request`
@@ -273,10 +279,47 @@
* `link_request`
* `unlink_request`
The following matchers are available:
-* `allow_request`: allows a request with the given Rack environment, and optional principals
+* `allow_request`: allows a request with the given Rack environment, and optional credentials
+
+### Error Page Middleware
+
+When an authorization error occurs, the `Rails::Auth::NotAuthorizedError`
+exception is raised up the middleware chain. However, it's likely you would
+prefer to show an error page than have an unhandled exception.
+
+You can write your own middleware that catches `Rails::Auth::NotAuthorizedError`
+if you'd like. However, a default one is provided which renders a 403 response
+with a static page body if you find that helpful.
+
+To use it, add `Rails::Auth::ErrorPage::Middleware` to your app:
+
+```ruby
+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
+```
## Contributing
Any contributors to the master *rails-auth* repository must sign the
[Individual Contributor License Agreement (CLA)]. It's a short form that covers