aker 3.0.0.pre

data/CHANGELOG.md

@@ -0,0 +1,210 @@
+Aker History
+============
+
+3.0.0
+-----
+- First open-source version.
+- Project renamed from "Bcsec" (short for Bioinformatics Core
+  security) to "Aker" (ancient Egyptian god of the horizon).
+- Bcsec contained several authorities which were specific to NUBIC;
+  those have been removed and purged from the git history for the
+  project.
+- Added :custom_form mode (#1).
+
+Bcsec History
+=============
+
+This is the history for the parts of Bcsec which remain in
+Aker. Versions that only included changes to code which has been
+removed from the open source version have been removed.
+
+2.2.0
+-----
+- Introduced the concept of "configuration slices" so that extensions
+  may add default configuration values. (#5875)
+- Introduced mode registration and authority aliases so that named
+  modes and authorities can have arbitrary class names. (#5875)
+- Introduced the ability to configure rack middleware to be installed
+  relative to bcsec (outside of modes). (#5875)
+- Bcsec now has a 30 minute session timeout.  (#5156)
+- It is now possible to customize the login and logout pages when using the
+  `form` mode.  (#5469)
+- Added a generic LDAP authority. (#5876)
+- Send a permanent redirect after a successful CAS authentication in
+  order to prevent the service ticket from showing up in the user's
+  browsing history. (#2725)
+- Extract and expose the method for determining the CAS service URL
+  for a particular request. (See `Bcsec::Cas::ServiceUrl`.)
+- Updated JRuby tested version to 1.6.2.
+
+2.1.0
+-----
+
+- ActiveRecord / ActiveSupport 3 compatibility. (#2804)
+- Fixed: user information is no longer saved in the session in
+  non-interactive modes.  (#2757)
+
+2.0.5
+-----
+
+- Updated tested platforms to JRuby 1.5.3 and Ruby 1.9.2.  (MRI 1.8.7
+  in the specific form of REE 2010.02 remains the same.)
+
+2.0.4
+-----
+
+- Changed: the #find_users method on the authorities interface now
+  accepts one or more separate criteria.  The separate criteria are
+  joined using a logical OR.  All the built-in authorities have been
+  updated to support this; custom authorities may need to be updated
+  as well.  (#4027)
+- Added: `Bcsec::Authorities::Static#load!` will now load arbitrary
+  `Bcsec::User` attributes from the YAML file, not just the username,
+  password, and authorization information. (#4297)
+- Changed: Depend on net-ldap 0.1.1 instead of ruby-net-ldap 0.0.4.
+  This new version of the net/ldap library is backwards compatible,
+  interface-wise, but it trades 1.8.6- support for 1.9+ support.
+
+2.0.3
+-----
+
+- Fixed: static authority now allows different users to have the same
+  password. (#4068)
+
+2.0.1
+-----
+
+- Added `Bcsec::Authorities::AutomaticAccess`.
+
+2.0.0
+-----
+
+- Complete rewrite: better architecture (no sole singletons); rack
+  support; better RESTful API authentication support; support for MRI
+  1.8.7, JRuby, and YARV 1.9.1; and much more.
+
+1.6.1
+-----
+
+- Correct MockAuthenticator-authorized users so that they reflect the
+  appropriate group memberships when logging in with CAS (bug #2221)
+- Prevent nil dereference in User#in_group? when the user has no groups at all
+
+1.6.0
+-----
+
+- Fix nil-sensitivity bug in Bcsec.use_cas (#1994)
+- Remove explicit `gem` invocations from library code
+- Make minor changes to allow bcsec to run under jruby 1.4.0
+
+1.5.2
+-----
+
+- Modify build layout a bit so that the source directory can be used with
+  bundler's :path option in sowsear
+
+1.5.0
+-----
+
+- Update to use open source versions of bcdatabase and
+  schema_qualified_tables.
+
+1.4.8
+-----
+
+- Configuration from use_cas now propagates to RailsCasFilter.
+
+1.4.0
+-----
+
+- Allow CAS configuration parameters to be passed to use_cas.
+  These parameters are passed directly to CASClient::Client; see
+  http://rubycas-client.rubyforge.org/ for configuration details.
+  These parameters override central configuration.
+
+1.3.0
+-----
+
+- Dev: support deploy:tag from git-svn clones
+
+1.2.6
+-----
+
+- Added Bcsec::AuthenticateOnlyAuthenticator for when you only need to
+  authenticate. It responds to allow_access? and always returns true.
+- Added ability to add authenticators with may_access? method only.
+- Added rspec-rails version to use when running specs.
+
+1.2.2
+-----
+
+- Correct _dependency_ definitions in gemspec.  (Was using _requirements_,
+  which are informational only.)  `gem install bcsec` will now install all
+  dependent gems.
+
+1.2.1
+-----
+
+- Clear the effects of use_cas in Bcsec::Configurator#clear
+
+1.2.0
+-----
+
+- Add Bcsec::portal_set? and similar to allow querying whether certain
+  config attributes are set without throwing an exception when they aren't.
+- Add adapter code in rspec_helper.rb so that rspec-rails can be used as a gem.
+
+1.1.0
+-----
+
+- Added publicly-accessible method Bcsec#amplify! to provide bcsec consumers
+  with the ability to manually invoke group data retrieval.
+
+1.0.1
+-----
+
+- Fix issue when having multiple authenticors and the first one returns no groups
+
+1.0.0
+-----
+
+- A user's security groups are cached in the current user object in the
+  session.
+- In group checks are handled in memory instead of hitting the database every
+  time.
+- Added dependency on RubyTree gem
+
+0.1.1
+-----
+
+- Fix issue where Bcsec::CentralAuthenticationParameters would sometimes not be
+  automatically resolved by applications using ActiveSupport's dependency
+  loader.
+
+0.1.0
+-----
+
+- Add CAS support
+- Add MockAuthenticator#load_credentials! to support loading test credentials
+  from a file.
+
+0.0.2
+-----
+
+- Adapt deploy task to be multi-developer friendly
+- Add separate uninstall task to return to published version
+
+0.0.1
+-----
+
+- Fix rake tasks for deploy, local install
+- Integrate ci_reporter
+- Add rudimentary environment support in order to build in hudson
+- Made site affiliate portal foreign key explicit
+
+0.0.0
+-----
+
+- Extract non-rails-specific bcsec elements from bcsec engine.
+- Convert test/unit tests moved from bcsec plugin into rspec specs.  (Shallow
+  conversion only so far.)

data/README.md

@@ -0,0 +1,282 @@
+Aker
+====
+
+Aker is a library for managing authentication and authorization in
+ruby applications (particularly Rack applications). It is designed to
+extensibly work with your existing (possibly legacy) authentication
+infrastructure.
+
+Aker is made up of **authorities** which provide user security
+information, **modes** which integrate authentication with HTTP (via
+Rack), and a **configuration** which specifies which of these to use
+and how to set them up.
+
+Reader's note: this README uses [YARD][] markup to provide links to
+Aker's API documentation. If you aren't already, consider reading it
+on [rubydoc.info][] so that the links will be followable.
+
+[YARD]: http://yardoc.org/
+[rubydoc.info]: http://rubydoc.info/github/NUBIC/aker/master/file/README.md
+
+Aker concepts
+-------------
+
+### Authorities
+
+An **authority** in Aker is the encapsulation of a mechanism for
+providing authentication and/or authorization.  The methods which an
+authority may implement (all are optional) are described in detail in
+the documentation for the {Aker::Authorities::Composite composite
+authority}.  All the included authorities are described in the
+documentation for the {Aker::Authorities} module.  See their
+documentation for more information.
+
+More than one authority can be used in a particular configuration.
+When validating credentials or performing any of the other actions
+provided by the authority interface, all the authorities will be
+consulted.  The documentation for the composite authority describes
+how the results are aggregated for each action.
+
+### Modes
+
+An Aker **mode** is a mechanism for receiving credentials in the context
+of a web application.  Aker modes come in variants that are intended
+for use in human-user-facing contexts (*UI* modes) and machine-facing
+contexts (*API* modes).  It is possible for the same mode to act in
+both capacities.
+
+An application may have zero-to-many API modes, but only one UI mode.
+API modes work within a standard [RFC2617][] HTTP Authorization
+interface, while UI modes have broad access to the Rack environment to
+prompt the user as necessary.
+
+All the included modes are described in the documentation of the
+{Aker::Modes} module. See their documentation for more information.
+If you would like to implement your own mode, see {Aker::Modes::Base}.
+
+#### API vs. UI
+
+Aker uses the following heuristic to determine whether to attempt to
+authenticate a particular request using the configured UI mode or API
+mode(s):
+
+* If there are no API modes configured, requests are always handled by
+  the UI mode.
+* If the HTTP Accept header includes `text/html` (literally includes
+  it, not matches it), the request is handled by the UI mode.
+* If the HTTP User-Agent header includes `Mozilla`, the request is
+  handled by the UI mode.
+* Otherwise, the request is handled by the API mode(s).
+
+[RFC2617]: http://www.ietf.org/rfc/rfc2617.txt
+
+### Configuration
+
+The aker **configuration** is where you define the authorities and
+modes (and their parameters) for your application.  It's a class whose
+instances can be initialized both {Aker::Configuration traditionally}
+and using a {Aker::ConfiguratorLanguage DSL}.  There's a global
+instance ({Aker.configuration}) which will be sufficient for most
+uses and which can be updated using the DSL via {Aker.configure}.
+
+Since {Aker.configure} updates the configuration (rather than
+replacing it), it is worthwhile to consider splitting up your
+configuration into environment-specific and common parts.  For
+instance, you might have the common configuration:
+
+    Aker.configure {
+      ui_mode :form
+      api_mode :http_basic
+    }
+
+And then for your development environment use:
+
+    Aker.configure {
+      authority Aker::Authorities::Static.from_file("#{Rails.root}/environments/development-users.yml")
+      central "/etc/nubic/aker-local.yml"
+    }
+
+And in your tests use:
+
+    Aker.configure {
+      authority Aker::Authorities::Static.from_file("#{Rails.root}/spec/test-users.yml")
+    }
+
+But then in production use:
+
+    Aker.configure {
+      authorities :ldap
+      central "/etc/nubic/aker-prod.yml"
+    }
+
+Using form authentication
+-------------------------
+
+Aker's {Aker::Form::Mode :form} mode provides a traditional HTML
+form for user authentication.  It works with one or more authorities
+which handle the `:user` credential kind — compatible
+authorities that ship with Aker are {Aker::Ldap::Authority
+:ldap}, and {Aker::Authorities::Static :static}.
+
+`:form` is the default UI mode.  If you want to explicitly configure
+it, do like so:
+
+    Aker.configure {
+      authorities :static # whatever is appropriate for your app
+      ui_mode :form
+    }
+
+Using CAS
+---------
+
+Aker's {Aker::Cas::ServiceMode :cas} mode provides interactive user
+authentication via an external CAS 2 server.  The
+{Aker::Cas::ProxyMode :cas_proxy} mode complements `:cas` by providing
+non-interactive authentication using CAS proxy tickets.  Each of these
+modes works with an authority which can handle the corresponding
+credential kind (i.e., `:cas` needs a `:cas`-handling authority). The
+{Aker::Cas::Authority :cas} authority handles both.  Here's an
+example configuration:
+
+    Aker.configure {
+      authority :cas
+      ui_mode :cas
+      api_mode :cas_proxy # don't include unless needed
+    }
+
+(The `:static` authority can also verify `:cas` and `:cas_proxy`
+credentials, but it is relatively awkward to set up and so is left as
+an exercise for the adventurous integrated tester.)
+
+Since the CAS server provides authentication only, you may also want
+to configure an authority to provide authorization information.
+
+Authenticating a RESTful API
+----------------------------
+
+As noted above, Aker has specific support for [RFC2617][]-style
+standard HTTP authentication.  It supports multiple simultaneous API
+authentication modes.  The most common case for multiple API modes
+will be CAS-protected APIs which also need to provide non-interactive
+API access (e.g., for cron jobs, since they are not run in the context
+of a user logged into any particular application).  Here's a sample
+configuration:
+
+    Aker.configure {
+      ui_mode :cas
+      api_mode :http_basic, :cas_proxy
+
+      authorities :cas, :ldap
+
+      central "/etc/nubic/aker-local.yml"
+    }
+
+In this case, the CAS server will be used for interactive logins and
+for CAS proxy ticket validation, while HTTP Basic-authenticated
+requests will be validated using the `:ldap` authority.
+
+Rack (and Rails) integration
+----------------------------
+
+Aker's web application integration is based on [Rack][].  This means
+it can be used with nearly any ruby web framework, including Sinatra,
+Camping, etc., in addition to Rails.
+
+In your Aker-protected Rack application, you have access to a
+`"aker.check"` key in the Rack environment.  This key will yield an
+instance of {Aker::Rack::Facade} which provides methods for
+determining who is logged in, checking permissions, requiring
+authentication, etc.  See its API documentation for more information.
+
+To configure Aker into your Rack application, use
+{Aker::Rack.use_in}.  See that method's API documentation for more
+information.
+
+#### Rails
+
+While Rack support is built into the main Aker gem, Rails support (for
+both Rails 2.3 and 3.x) is in a separate gem plugin.  See the README
+in the [`aker-rails` gem][aker-rails] for more information about it.
+
+[Rack]: http://rack.rubyforge.org/
+[aker-rails]: https://github.com/NUBIC/aker-rails
+
+Aker outside of a Rack app
+--------------------------
+
+Aker's authorities are independent of its HTTP integration, so they
+may be used in any ruby script or application.  Here's an example:
+
+    #!/usr/bin/env ruby
+
+    require 'rubygems'
+    require 'aker'
+
+    Aker.configure {
+      authorities :ldap, :static
+      central "/etc/nubic/aker-staging.yml"
+    }
+
+    u = Aker.authority.valid_credentials?(:user, 'wakibbe', 'ekibder')
+        # => valid_credentials? returns a Aker::User on success
+
+    if !u
+      $stderr.puts "Bad credentials"
+      exit(1)
+    elsif u.permit?('Admin')
+      lookedup = Aker.authority.find_user(ARGV[0])
+      if lookedup
+        puts "#{ARGV[0]} is the username of #{lookedup.full_name}"
+      else
+        puts "#{ARGV[0]} isn't a valid username"
+      end
+    else
+      $stderr.puts "Unauthorized"
+      exit(2)
+    end
+
+See the rest of the API documentation for more information.
+
+Extending Aker
+--------------
+
+Aker was built for extensibility. Here are the highlights; see the
+relevant sections above for more.
+
+* {Aker::Authorities::Composite#valid_credentials? Authentication} and
+  {Aker::Authorities::Composite#amplify! authorization} can be
+  provided by implementing an {Aker::Authorities authority}. An
+  application can configure in multiple authorities and their results
+  will be intelligently combined. Authorities can also implement
+  {Aker::Authorities::Composite#on_authentication_success success} and
+  {Aker::Authorities::Composite#on_authentication_failure failure}
+  callbacks to provide for auditing or
+  {Aker::Authorities::Composite#veto? lockout} features.
+* An HTTP-based credential presentation mechanism can be implemented
+  as a {Aker::Modes mode}. E.g., you would write a mode to adapt to a
+  legacy single-sign-on system.
+* Authorities and modes can be customized through
+  {Aker::Configuration#parameters_for parameters} included in the
+  {Aker::Configuration configuration}.
+* Reusable extensions can be packaged as gems and registered alongside
+  Aker's built-in functionality. Extensions may use
+  {Aker::Configuration::Slice slices} to register themselves, set
+  defaults parameter values, and register middleware that will be
+  included relative to Aker's own middleware.
+
+Limitations
+-----------
+
+Aker's original iteration was a rails plugin built to assist the
+Northwestern University Biomedical Informatics Center in transitioning
+legacy systems to Ruby on Rails. Since then it's been used in dozens
+of applications, both ports of existing systems and ones newly
+built.
+
+While it can be adapted to many kinds of applications, it is probably
+not a good choice if you are not integrating with an existing
+authentication or authorization backend. It does not include any
+mechanism for provisioning users or letting users sign up for accounts
+on their own. Such things could be built for it, but if that's what
+you need then one of the other existing ruby security frameworks might
+get you up and running faster.

data/assets/aker/form/login.css

@@ -0,0 +1,73 @@
+html {
+  background-color: #393939;
+  font-size: 12px;
+  font-family: Helvetica, Arial, sans-serif;
+  margin: 0; padding: 0;
+}
+p.error {
+  text-align: center;
+  background-color: #c66;
+  color: #333;
+  margin: 1em 0;
+  padding: 1em;
+  font-size: 1.3em;
+}
+.access {
+  display: block;
+  margin: 2em 0;
+  border: solid #000;
+  border-width: 2px 0;
+  background-color: #999;
+  color: #fff;
+  width: 100%
+}
+.access .contents {
+  width: 24em;
+  margin: 0 auto;
+}
+.access h1 {
+  text-align: center;
+  font-size: 1.5em;
+  margin: 1em;
+  padding: 0;
+}
+.access a {
+  color: #fff;
+}
+.access a:visited {
+  color: #eed;
+}
+.access a:hover {
+  color: #fff;
+  background-color: #aa9;
+}
+.access .row {
+  margin: 0.5em;
+}
+.access .row:after {
+  display: block;
+  content: " ";
+  clear: both;
+  visibility: hidden;
+  height: 0;
+}
+.access .label {
+  text-align: right;
+  height: 2em;
+  font-weight: bold;
+  float: left;
+  width: 6em;
+  padding-top: 6px;
+}
+.access .value {
+  margin-left: 6.5em;
+}
+.access .text {
+  border: 1px solid #393939;
+  padding: 2px;
+}
+.access .button {
+  border: 1px outset #393939;
+  background-color: #393939;
+  color: #ddd;
+}

data/assets/aker/form/login.html.erb

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Please log in</title>
+    <link rel="stylesheet" type="text/css" href="<%= login_base %>/login.css" />
+  </head>
+  <body class="access">
+    <form method="POST" action="<%= login_base %>">
+      <input type="hidden" name="url" value="<%= options[:url] %>" />
+      <% if options[:logged_out] %>
+        <h1>Logged out</h1>
+      <% else %>
+        <h1>Please log in</h1>
+      <% end %>
+      <% if options[:login_failed] %>
+        <p class="error">Login failed</p>
+      <% elsif options[:session_expired] %>
+        <p class="error">Session expired</p>
+      <% end %>
+      <div class="contents">
+        <div class="row">
+          <div class="label">
+            <label for="username">Username</label>
+          </div>
+          <div class="value">
+            <input type="text" id="username" name="username" class="text" value="<%= escape_html(options[:username]) %>"/>
+          </div>
+        </div>
+        <div class="row">
+          <div class="label">
+            <label for="password">Password</label>
+          </div>
+          <div class="value">
+            <input type="password" id="password" name="password" class="text" />
+          </div>
+        </div>
+        <div class="row">
+          <div class="value">
+            <input type="submit" value="Log in" class="button" />
+          </div>
+        </div>
+      </div>
+  </body>
+</html>

data/lib/aker/authorities/automatic_access.rb

@@ -0,0 +1,36 @@
+require 'aker'
+
+module Aker::Authorities
+  ##
+  # An authority which grants all users access to the Aker
+  # environment's configured portal.  This allows you to mix
+  # authentication-only access control and group-authorization access
+  # control in the same application.
+  #
+  # This authority does not provide any credential validation, so it
+  # can't be used on its own.  Combine it with one of the
+  # {Aker::Authorities others}.
+  #
+  # If you only need authentication-only access control, it will be
+  # easier to just omit the {Aker::Configuration#portal portal} from
+  # your aker configuration.
+  class AutomaticAccess
+    def initialize(configuration)
+      unless configuration.portal?
+        raise "#{self.class.to_s.split('::').last} is unnecessary " <<
+          "if you don't have a portal configured."
+      end
+      @portal = configuration.portal
+    end
+
+    ##
+    # Adds the configured portal to the user if necessary.
+    #
+    # @return [Aker::User]
+    def amplify!(user)
+      user.portals << @portal unless user.portals.include?(@portal)
+      user.default_portal = @portal unless user.default_portal
+      user
+    end
+  end
+end