aker 3.0.0.pre

data/lib/aker/authorities/composite.rb

@@ -0,0 +1,301 @@
+require 'aker'
+
+module Aker::Authorities
+  ##
+  # This authority provides a uniform entry point for multiple
+  # authorities.
+  #
+  # The documentation on each method describes how the implementation
+  # for a specific authority should work in addition to the way this
+  # authority aggregates results.  For any particular authority, all
+  # methods are optional (of course, it would be pointless to
+  # configure in an authority which doesn't implement any of them).
+  class Composite
+    ##
+    # The ordered series of authorities whose results this authority
+    # aggregates.  The members of this array should implement one or
+    # more of the methods in the authority informal interface (i.e.,
+    # the other methods in this class).
+    #
+    # @return [Array]
+    attr_accessor :authorities
+
+    ##
+    # Creates a new instance.
+    #
+    # @param [Aker::Configuration] config the configuration to use
+    #   for this authority.  The {#authorities} attribute for this
+    #   instance will default to {Aker::Configuration#authorities
+    #   config.authorities}.  Its {Aker::Configuration#portal portal}
+    #   (if any) will be used as the {Aker::User#default_portal
+    #   default portal} for any authenticated users which don't have
+    #   one.
+    def initialize(config)
+      @config = config
+    end
+
+    def authorities
+      @authorities || @config.authorities
+    end
+
+    ##
+    # The main authentication and authorization entry point for an
+    # authority.  A concrete authority can return one of four things
+    # from its implementation of this method:
+    #
+    # * A {Aker::User} instance if the credentials are valid.  The
+    #   instance represents the user that corresponds to these
+    #   credentials, with all the attributes and authorization
+    #   information that the verifying authority knows about.
+    # * `nil` if the credentials aren't valid according to the
+    #   authority.
+    # * `false` if the authority wants to prevent the presenter of
+    #   these credentials from authenticating, even if another
+    #   authority says they are valid.
+    # * `:unsupported` if the authority can never authenticate
+    #   credentials of the provided kind.  Semantically this is the
+    #   same as `nil`, but it allows `Composite` to provide a useful
+    #   debugging message if none of the authorities are capable of
+    #   validating a submitted kind.
+    #
+    # The composite implementation provided by this class does the
+    # following:
+    #
+    # * Executes `valid_credentials?` on all the configured authorities
+    #   that implement it.
+    # * Returns `false` if any of the authorities return `false`.
+    # * Returns `nil` if none of the authorities returned a user.
+    # * Selects the first user returned by any of the authorities.
+    # * Returns `false` if any of the authorities {#veto? veto} the
+    #   user.
+    # * Otherwise returns the user, {#amplify! amplified}.
+    #
+    # On failure, the {#on_authentication_failure} callback is called
+    # on any authority which provides it.  Similarly on success, the
+    # {#on_authentication_success} callback is called on all the
+    # authorities which support it.
+    #
+    # @param [Symbol] kind a symbol describing the semantics of the
+    #   supplied credentials.  Different authorities may support
+    #   different kinds (or multiple authorities may support the same
+    #   kind).
+    # @param [Array] *credentials the actual credentials.  The form of
+    #   these is dependent on the kind.
+    #
+    # @return [Aker::User,false,nil] the aggregated result of calling
+    #   `valid_credentials?` on all the configured {#authorities}.
+    #   If the credentials are valid, the returned user will already
+    #   be {#amplify! amplified}.
+    def valid_credentials?(kind, *credentials)
+      results = poll(:valid_credentials?, kind, *credentials)
+      if results.empty?
+        raise "No authentication-providing authority is configured.  " <<
+          "At least one authority must implement #valid_credentials?."
+      end
+      user, authenticating_authority = results.detect { |r, authority| r && r != :unsupported }
+
+      unless user
+        msg =
+          if results.collect { |r, auth| r }.uniq == [:unsupported]
+            "no configured authorities support #{kind.inspect} credentials"
+          else
+            "invalid credentials"
+          end
+        on_authentication_failure(nil, kind, credentials, msg)
+        return nil
+      end
+
+      vc_vetoers = results.select { |r, authority| r == false }.collect { |r, authority| authority }
+      unless vc_vetoers.empty?
+        msg = "credentials vetoed by #{vc_vetoers.collect(&:to_s).join(', ')}"
+        on_authentication_failure(user, kind, credentials, msg)
+        return false
+      end
+
+      veto_vetoers = poll(:veto?, user).
+        select { |result, authority| result }.collect { |result, authority| authority }
+      unless veto_vetoers.empty?
+        msg = "user vetoed by #{veto_vetoers.collect(&:to_s).join(', ')}"
+        on_authentication_failure(user, kind, credentials, msg)
+        return false
+      end
+
+      amplify!(user)
+      on_authentication_success(user, kind, credentials, authenticating_authority)
+      user
+    end
+
+    ##
+    # Allows an authority to unconditionally block access for a user.
+    #
+    # If an authority sometimes wishes to prevent authentication for a
+    # user, even if some authority has indicated that he or she has
+    # {#valid_credentials? valid credentials}, it can implement this
+    # method and return true when appropriate.
+    #
+    # The composite behavior aggregates the responses for all
+    # implementing authorities, returning true if any of them return
+    # true.
+    #
+    # @param [Aker::User] user the user who will be declared
+    #   authentic unless this method returns true.
+    #
+    # @return [Boolean] true to block access, false otherwise
+    def veto?(user)
+      poll(:veto?, user).detect { |result, authority| result }
+    end
+
+    ##
+    # A callback which is invoked when {#valid_credentials?}
+    # is about to return a new user.  It has no control over whether
+    # authentication will proceed &mdash; it's just a notification.
+    #
+    # The composite behavior is to invoke the callback on all the
+    # authorities which implement it.
+    #
+    # @param [Aker::User] user the user which has been authenticated.
+    # @param [Symbol] kind the kind of credentials (the same value
+    #   originally passed to {#valid_credentials?}).
+    # @param [Array] credentials the actual credentials which were
+    #   determined to be valid (the same value originally passed to
+    #   {#valid_credentials?}).
+    # @param [Object] authenticating_authority the (first) authority
+    #   which determined that the credentials were valid.
+    #
+    # @return [void]
+    def on_authentication_success(user, kind, credentials, authenticating_authority)
+      @config.logger.info("User \"#{user.username}\" was successfully authenticated " <<
+                          "by #{authenticating_authority.class}.")
+      poll(:on_authentication_success, user, kind, credentials, authenticating_authority)
+    end
+
+    ##
+    # A callback which is invoked when {#valid_credentials?}  is going
+    # to return `false` or `nil`.  It has no control over whether
+    # authentication will proceed &mdash; it's just a notification.
+    #
+    # The composite behavior is to invoke the callback on all the
+    # authorities which implement it.
+    #
+    # @param [Aker::User,nil] user the user whose access is being
+    #   denied.  This may be nil if the authentication failure happens
+    #   before the credentials are mapped to a user.
+    # @param [Symbol] kind the kind of credentials (the same value
+    #   originally passed to {#valid_credentials?}).
+    # @param [Array] credentials the actual credentials which were
+    #   determined to be valid (the same value originally passed to
+    #   {#valid_credentials?}).
+    # @param [String] reason the reason why authentication failed,
+    #   broadly speaking; e.g., `"invalid credentials"` or `"user vetoed
+    #   by MyLockoutAuthority"`.
+    #
+    # @return [void]
+    def on_authentication_failure(user, kind, credentials, reason)
+      @config.logger.info("Authentication attempt#{" by \"#{user.username}\"" if user} " <<
+                          "failed: #{reason}.")
+      poll(:on_authentication_failure, user, kind, credentials, reason)
+    end
+
+    ##
+    # Fills in any information about the user which the authority
+    # knows but which is not already present in the given object.
+    # In addition to the simple attributes on {Aker::User}, this
+    # method should fill in all available authorization information.
+    #
+    # The composite behavior is to invoke `amplify!` on each of the
+    # configured {#authorities} in series, passing the given user to
+    # each.
+    #
+    # @param [Aker::User] user the user to modify in-place.
+    #
+    # @return [Aker::User] the passed-in user
+    #
+    # @see Aker::User#merge!
+    def amplify!(user)
+      user.default_portal = @config.portal if @config.portal? && !user.default_portal
+      poll(:amplify!, user)
+      user
+    end
+
+    ##
+    # Finds users matching the given criteria.  Criteria may either be
+    # `String`s or `Hash`es.  If it's a single `String`, it is
+    # interpreted as a username and this method will return an array
+    # containing either a single user with that username or an empty
+    # array.  If the criteria is a `Hash`, the behavior will be
+    # authority-dependent.  However, all the attributes of
+    # {Aker::User} are reserved parameter names &mdash; if an
+    # authority interprets the value associated with a {Aker::User}
+    # attribute name, it must be interpreted as an exact-match
+    # criteria for that authority's understanding of that attribute
+    # (whatever it is).
+    #
+    # If more than one criterion is provided, each value is treated
+    # separately according to the description given above for a single
+    # value.  The resulting array will contain each matching user
+    # exactly once.  It will not be possible to determine from the
+    # results alone which returned user matched which criterion.
+    #
+    # Examples:
+    #
+    #     authority.find_users("wakibbe") # => that single user, if
+    #                                     #    the username is known
+    #     authority.find_users(:first_name => 'Warren')
+    #                                     # => all the users named
+    #                                     #    Warren
+    #     authority.find_users(
+    #       :first_name => 'Warren', :last_name => 'Kibbe')
+    #                                     # => all the users named
+    #                                     #    Warren Kibbe
+    #     authority.find_users(
+    #       { :first_name => 'Warren' }, { :last_name => 'Kibbe' })
+    #                                     # => all the users with
+    #                                     #    first name Warren or
+    #                                     #    last name Kibbe
+    #
+    # The composite behavior is to invoke `find_users` on all the
+    # authorities which support it and merge the resulting lists.  Any
+    # users with the same username are merged using
+    # {Aker::User#merge!}.  Finally, all the users are {#amplify!
+    # amplified}.
+    #
+    # This method will always return an array.
+    #
+    # @param [Array<Hash,#to_s>] criteria (see above)
+    #
+    # @return [Array<Aker::User>] the matching users
+    def find_users(*criteria)
+      poll(:find_users, *criteria).
+        collect { |result, authority| result }.
+        compact.
+        inject([]) { |aggregate, users| merge_user_lists!(aggregate, users.compact) }.
+        each { |user| amplify!(user) }
+    end
+    include Support::FindSoleUser
+
+    protected
+
+    def merge_user_lists!(target, new_users)
+      new_users.each do |u|
+        existing = target.find { |t| t.username == u.username }
+        if existing
+          existing.merge!(u)
+        else
+          target << u
+        end
+      end
+      target
+    end
+
+    ##
+    # Invokes the specified method with the specified arguments on all
+    # the authorities which will respond to it.
+    def poll(method, *args)
+      authorities.select { |a|
+        a.respond_to?(method)
+      }.collect { |a|
+        [a.send(method, *args), a]
+      }
+    end
+  end
+end

data/lib/aker/authorities/static.rb

@@ -0,0 +1,283 @@
+require 'aker'
+require 'yaml'
+
+module Aker::Authorities
+  ##
+  # An authority which is configured entirely in memory.  It's not
+  # intended for production, but rather for testing (particularly
+  # integrated testing) and bootstrapping (e.g., for rapidly testing
+  # out aker in an application before setting up the infrastructure
+  # needed for {Ldap} or a custom authority).
+  class Static
+    ##
+    # Creates a new instance.  Does not use any configuration properties.
+    def initialize(ignored=nil)
+      self.clear
+    end
+
+    ##
+    # Creates a new instance from a file.  You can use the result of
+    # this method directly in a Aker configuration block.  E.g.:
+    #
+    #     Aker.configure {
+    #       authority Aker::Authorities::Static.from_file(File.expand_path("../static-auth.yml", __FILE__))
+    #     }
+    #
+    # @param [String] filename the name of a YAML file containing the
+    #   format outlined for {#load!}
+    #
+    # @return [Static] a new instance
+    #
+    # @see #load! the file format
+    def self.from_file(filename)
+      File.open(filename) { |f| self.new.load!(f) }
+    end
+
+    ###### AUTHORITY API IMPLEMENTATION
+
+    ##
+    # Verifies the credentials against the set provided by calls to
+    # {#valid_credentials!} and {#load!}.  Supports all kinds.
+    #
+    # @return [Aker::User, nil]
+    def valid_credentials?(kind, *credentials)
+      found_username =
+        (all_credentials(kind).detect { |c| c[:credentials] == credentials } || {})[:username]
+      @users[found_username]
+    end
+
+    ##
+    # Merges in the authorization information in this authority for the
+    # given user.
+    #
+    # @param [Aker::User] user the target user
+    #
+    # @return [Aker::User] the input user, modified
+    def amplify!(user)
+      base = @users[user.username]
+      return user unless base
+
+      user.merge!(base)
+    end
+
+    ##
+    # Returns the any users which match the given criteria from the
+    # set that have been loaded with {#load!}, {#valid_credentials!},
+    # and {#user}.
+    #
+    # @param [Array<Hash,#to_s>] criteria as described in
+    #   {Composite#find_users}.
+    # @return [Array<Aker::User>]
+    def find_users(*criteria)
+      criteria.collect do |criteria_group|
+        unless Hash === criteria_group
+          criteria_group = { :username => criteria_group.to_s }
+        end
+        props = criteria_group.keys.select { |k|
+          Aker::User.instance_methods.include?(k.to_s) || # for 1.8.7
+          Aker::User.instance_methods.include?(k.to_sym)  # for 1.9.1
+        }
+        if props.empty?
+          []
+        else
+          @users.values.select do |user|
+            props.inject(true) { |result, prop| result && user.send(prop) == criteria_group[prop] }
+          end
+        end
+      end.flatten.uniq
+    end
+
+    ###### SETUP METHODS
+
+    ##
+    # Creates or updates one of the user records in this authority.  If
+    # provided a block, the user will be yielded to it.  This the
+    # mechanism to use to set attributes, portals, and group
+    # memberships on the users returned by {#valid_credentials?}.
+    # Example:
+    #
+    #     auth.user("wakibbe") do |u|
+    #       u.first_name = "Warren"
+    #       u.portals << :ENU
+    #     end
+    #
+    #     auth.user("wakibbe").first_name # => "Warren"
+    #
+    # @param [String] username the username for the user to create,
+    #   update, or just read
+    #
+    # @return [Aker::User] the single user for `username` (possibly
+    #   newly created; never nil)
+    #
+    # @see #load!
+    def user(username, &block)
+      u = (@users[username] ||= Aker::User.new(username))
+      u.tap(&block) if block
+      u
+    end
+
+    ##
+    # Associate the given set of credentials of a particular kind with
+    # the specified user.  Note that all kinds require a username
+    # (unlike with {#valid_credentials?}).  Examples:
+    #
+    #     auth.valid_credentials!(:user, "wakibbe", "ekibder")
+    #     auth.valid_credentials!(:api_key, "notis-app", "12345-67890")
+    #
+    # @param [Symbol] kind the kind of credentials these are.
+    #   Anything is allowed.
+    # @param [String] username the username for the user which is
+    #   authenticated by these credentials.
+    # @param [Array<String>,nil] *credentials the credentials
+    #   themselves.  (Note that you need not repeat the username for
+    #   the :user kind.)
+    #
+    # @return [void]
+    def valid_credentials!(kind, username, *credentials)
+      if kind == :user
+        credentials = [username, *credentials]
+      end
+      all_credentials(kind) << { :username => username, :credentials =>  credentials }
+      @users[username] ||= Aker::User.new(username)
+    end
+
+    ##
+    # Loads a YAML doc and uses its contents to initialize the
+    # authority's authentication and authorization data.
+    #
+    # Sample doc:
+    #
+    #     users:
+    #       wakibbe:               # username
+    #         password: ekibder    # password for :user auth (optional)
+    #         first_name: Warren   # any attributes from Aker::User may
+    #         last_name: Kibbe     #   be set here
+    #         identifiers:         # identifiers will be loaded with
+    #           employee_id: 4     # symbolized keys
+    #         portals:             # portal & group auth info (optional)
+    #           - SQLSubmit        # A groupless portal
+    #           - ENU:             # A portal with simple groups
+    #             - User
+    #           - NOTIS:           # A portal with affiliated groups
+    #             - Manager: [23]
+    #             - User           # you can mix affiliated and simple
+    #
+    #     groups:                  # groups for hierarchical portals
+    #       NOTIS:                 # (these aren't real NOTIS groups)
+    #         - Admin:
+    #           - Manager:
+    #             - User
+    #           - Auditor
+    #
+    # @param [#read] io a readable handle (something that can be passed to
+    #   `YAML.load`)
+    #
+    # @return [Static] self
+    def load!(io)
+      doc = YAML.load(io)
+      return self unless doc
+      (doc["groups"] || {}).each do |portal, top_level_groups|
+        @groups[portal.to_sym] = top_level_groups.collect { |group_data| build_group(group_data) }
+      end
+      (doc["users"] || {}).each do |username, config|
+        valid_credentials!(:user, username, config["password"]) if config["password"]
+        user(username) do |u|
+          attr_keys = config.keys
+          (attr_keys - ["password", "portals", "identifiers"]).each do |k|
+            setter = "#{k}="
+            if u.respond_to?(setter)
+              u.send(setter, config[k])
+            end
+          end
+
+          (config["portals"] || []).each do |portal_data|
+            portal, group_data =
+              if String === portal_data
+                portal_data
+              else
+                portal_data.to_a.first
+              end
+
+            u.default_portal = portal unless u.default_portal
+
+            u.portals << portal.to_sym
+            if group_data
+              u.group_memberships(portal).concat(load_group_memberships(portal.to_sym, group_data))
+            end
+          end
+
+          (config["identifiers"] || {}).each do |ident, value|
+            u.identifiers[ident.to_sym] = value
+          end
+        end
+      end
+
+      self
+    end
+
+    ##
+    # Resets the user and authorization data to the same state it was
+    # in at initialization.
+    #
+    # @return [Static] self
+    def clear
+      @groups = {}
+      @users = {}
+      @credentials = {}
+      self
+    end
+
+    private
+
+    def all_credentials(kind)
+      @credentials[kind] ||= []
+    end
+
+    def build_group(group_data)
+      group_name, children =
+        if String === group_data
+          [group_data, []]
+        else
+          group_data.to_a.first
+        end
+
+      group = Aker::Group.new(group_name)
+      children.each do |ch_group_data|
+        group << build_group(ch_group_data)
+      end
+      group
+    end
+
+    ##
+    # Transform the group membership info from the static yaml format
+    # into {Aker::GroupMembership} instances.
+    #
+    # @param [Array<String,Hash<String,Array<Fixnum>>>] group_data
+    def load_group_memberships(portal, group_data)
+      group_data.collect do |entry|
+        group, affiliates =
+          if String === entry
+            entry
+          else
+            entry.to_a.first
+          end
+
+        gm = Aker::GroupMembership.new(find_or_create_group(portal, group))
+        if affiliates
+          gm.affiliate_ids = affiliates
+        end
+        gm
+      end
+    end
+
+    # @return [Aker::Group]
+    def find_or_create_group(portal, group_name)
+      existing = (@groups[portal] ||= []).collect { |top|
+        top.find { |g| g.name == group_name }
+      }.compact.first
+      return existing if existing
+      @groups[portal] << Aker::Group.new(group_name)
+      @groups[portal].last
+    end
+  end
+end

data/lib/aker/authorities/support/find_sole_user.rb

@@ -0,0 +1,24 @@
+require 'aker/authorities/support'
+
+module Aker::Authorities::Support
+  ##
+  # Provides a singular version of the `find_users` authority method.
+  # Authorities which implement that method can mix this in to get
+  # `find_user` for free.
+  module FindSoleUser
+    ##
+    # Finds the sole user which meets the given criteria.  If more
+    # than one user meets the criteria, no users are returned.
+    #
+    # @see Aker::Authorities::Composite#find_users
+    # @return [Aker::User,nil] the sole matching user or `nil`
+    def find_user(criteria)
+      result = find_users(criteria)
+      if result.size == 1
+        result.first
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/aker/authorities/support.rb

@@ -0,0 +1,9 @@
+require 'aker/authorities'
+
+module Aker::Authorities
+  ##
+  # Library code shared by authorities lives here.
+  module Support
+    autoload :FindSoleUser, 'aker/authorities/support/find_sole_user'
+  end
+end

data/lib/aker/authorities.rb

@@ -0,0 +1,46 @@
+require 'aker'
+
+module Aker
+  ##
+  # The namespace for authorities in Aker.  The duck-typed definition
+  # of an authority is is outlined in the documentation for
+  # {Aker::Authorities::Composite Composite}.
+  #
+  # Aker ships with four authorities:
+  #
+  # - {Aker::Cas::Authority :cas} provides CAS ticket verification
+  #   using a CAS 2 server.
+  # - {Aker::Ldap::Authority :ldap} verifies usernames and
+  #   passwords using an LDAP server.
+  # - {Aker::Authorities::Static :static} provides credential
+  #   verification and user authorization based on an in-memory set of
+  #   users. It can be configured in code or by loading a YAML file.
+  #   It is intended for integrated tests and application
+  #   bootstrapping.
+  # - {Aker::Authorities::AutomaticAccess :automatic_access} allows
+  #   any authenticated user to access your application, even when you
+  #   have a portal configured.
+  #
+  # @see Aker::Configuration#authorities=
+  module Authorities
+    autoload :AutomaticAccess, 'aker/authorities/automatic_access'
+    autoload :Composite,       'aker/authorities/composite'
+    autoload :Static,          'aker/authorities/static'
+
+    autoload :Support,         'aker/authorities/support'
+
+    ##
+    # The slice that aliases the default authorities.
+    # @private
+    class Slice < Aker::Configuration::Slice
+      def initialize
+        super do
+          alias_authority :automatic_access, Aker::Authorities::AutomaticAccess
+          alias_authority :static, Aker::Authorities::Static
+        end
+      end
+    end
+  end
+end
+
+Aker::Configuration.add_default_slice(Aker::Authorities::Slice.new)