aker 3.0.0.pre

data/lib/aker/ldap/authority.rb

@@ -0,0 +1,392 @@
+require 'net/ldap'
+require 'aker/ldap'
+
+module Aker::Ldap
+  ##
+  # A generic authority for performing authentication and user lookup
+  # via an LDAP server.  It authenticates username/password
+  # combinations and fills in demographic information from the LDAP
+  # record.  It also implements {#find_users find_users} to provide
+  # searches separately from authentication.
+  #
+  # This authority supports multiple instances if you need to combine
+  # the results from multiple LDAP servers in a single Aker
+  # configuration. Setting up multiple instances either requires
+  # directly constructing the instances (i.e., not using the `:ldap`
+  # alias and having Aker construct them for you) or writing
+  # separately constructable subclasses. The former makes sense for
+  # one-off configurations while the latter is better for reuse. See
+  # also {Configuration::Slice} for setting default parameters in
+  # extensions and {Configuration#alias_authority} for giving pithy
+  # names to authority subclasses.
+  #
+  # @example Configuring a single LDAP authority
+  #    Aker.configure {
+  #      ldap_parameters :server => "ldap.example.org"
+  #      authority :ldap
+  #    }
+  #
+  # @example Configuring multiple LDAP authorities via manual construction
+  #    Aker.configure {
+  #      hr_parameters :server => "hr.example.com", :port => 5003
+  #      dept_parameters :server => "ldap.mydept.example.com"
+  #
+  #      hr_ldap = Aker::Ldap::Authority.new(this, :hr)
+  #      dept_ldap = Aker::Ldap::Authority.new(this, :dept)
+  #
+  #      authorities hr_ldap, dept_ldap
+  #    }
+  #
+  # @example Defining multiple LDAP authorities via subclassing
+  #    # Not pictured: using a default slice and aliasing to make
+  #    # these authorities look like built-in authorities.
+  #
+  #    class HrLdap < Aker::Ldap::Authority
+  #      def initialize(config); super config, :hr; end
+  #    end
+  #    class DeptLdap < Aker::Ldap::Authority
+  #      def initialize(config); super config, :dept; end
+  #    end
+  #
+  #    Aker.configure {
+  #      hr_parameters :server => "hr.example.com", :port => 5003
+  #      dept_parameters :server => "ldap.mydept.example.com"
+  #      authorities HrLdap, DeptLdap
+  #    }
+  #
+  # @since 2.2.0
+  # @author Rhett Sutphin
+  class Authority
+    ##
+    # @see #attribute_map
+    DEFAULT_ATTRIBUTE_MAP = {
+      :uid => :username,
+      :sn => :last_name,
+      :givenname => :first_name,
+      :title => :title,
+      :mail => :email,
+      :telephonenumber => :business_phone,
+      :facsimiletelephonenumber => :fax,
+    }.freeze
+
+    ##
+    # Create a new instance.
+    #
+    # @param [Configuration, Hash] config the configuration for
+    #   this instance.  If a hash, the parameters are extracted
+    #   directly.  If a {Configuration}, the parameters are
+    #   extracted using {Configuration#parameters_for
+    #   parameters_for(name)} (where `name` is the name parameter to
+    #   this constructor; default is `:ldap`).
+    #
+    # @option config [String] :server The hostname for the LDAP server
+    #   (required)
+    #
+    # @option config [Integer] :port (636) The port to use to connect to the
+    #  LDAP server
+    #
+    # @option config [Boolean] :use_tls (true) Whether the LDAP server
+    #   uses TLS. Note that if you set this to false, you'll probably
+    #   need to change the port as well.
+    #
+    # @option config [String] :user A username to use to bind to
+    #   the server before searching or authenticating (optional)
+    #
+    # @option config [String] :password The password that goes with
+    #   *:user* (optional; required if *:user* is specified)
+    #
+    # @option config [Hash<Symbol, Symbol>] :attribute_map Extensions
+    #   and overrides for the LDAP-to-Aker user attribute
+    #   mapping. See {#attribute_map} for details.
+    #
+    # @option config [Hash<Symbol, #call>] :attribute_processors See
+    #   {#attribute_processors} for details.
+    #
+    # @option config [Hash<Symbol, Symbol>] :criteria_map See
+    #   {#criteria_map} for details.
+    #
+    # @param [Symbol] name the name for this authority. If you need to
+    #   have multiple LDAP authorities in the same configuration,
+    #   distinguish them by name.
+    def initialize(config, name=:ldap)
+      @config =
+        case config
+        when Aker::Configuration
+          config.parameters_for(name)
+        else
+          config
+        end
+      validate_config!
+    end
+
+    def config
+      @config
+    end
+    protected :config
+
+    ##
+    # The configured server's hostname or other address.
+    # @return [String]
+    def server
+      @config[:server]
+    end
+
+    ##
+    # The port to use when connecting to the server.
+    # Defaults to 636.
+    # @return [Integer]
+    def port
+      @config[:port] || 636
+    end
+
+    ##
+    # The user to bind as before searching or authenticating.
+    # @return [String,nil]
+    def user
+      @config[:user]
+    end
+
+    ##
+    # The password to use with {#user}.
+    # @return [String,nil]
+    def password
+      @config[:password]
+    end
+
+    ##
+    # Whether to use TLS when communicating with the server.  TLS is enabled by
+    # default.
+    # @return [Boolean]
+    def use_tls
+      @config[:use_tls].nil? ? true : @config[:use_tls]
+    end
+
+    ##
+    # The mapping between attributes from the LDAP server and
+    # {Aker::User} attributes. This mapping is used in two ways:
+    #
+    # * When returning users from the LDAP server, the first value for any
+    #   mapped attribute is used as the value for that attribute in the
+    #   user object.
+    # * Aker user attributes in this map will be translated into LDAP
+    #   attributes when doing a criteria query with {#find_users}.
+    #
+    # There is a default mapping which will be reasonable for many
+    # cases. To extend it, provide the `:attribute_map` parameter when
+    # constructing this authority.
+    #
+    # If this mapping is not reversible (i.e., each value is unique),
+    # then the behavior of this authority is not defined. Each value
+    # in this map must be a writable attribute on Aker::User.
+    #
+    # @example
+    #   ldap.attribute_map # => { :givenname => :first_name }
+    #   ldap.find_user('jmt123')
+    #     # => The givenName attribute in the LDAP record will be
+    #     #    mapped to Aker::User#first_name in the returned user
+    #   ldap.find_users(:first_name => 'Jo')
+    #     # => The LDAP server will be queried using givenName=Jo.
+    #
+    # @return [Hash<Symbol, Symbol>] the mapping from LDAP attribute
+    #   to Aker user attribute.
+    def attribute_map
+      @attribute_map ||= DEFAULT_ATTRIBUTE_MAP.merge(@config[:attribute_map] || {})
+    end
+
+    ##
+    # @return [Hash<Symbol, Symbol>] The reverse of {#attribute_map}.
+    def reverse_attribute_map
+      @reverse_attribute_map ||= attribute_map.inject({}) { |h, (k, v)| h[v] = k; h }
+    end
+    protected :reverse_attribute_map
+
+    ##
+    # A set of named procs which will be applied while creating a
+    # {Aker::User} from an LDAP entry. The values in the map should
+    # be procs. Each proc should accept three arguments:
+    #
+    # * The user being created from the LDAP entry.
+    # * The full ldap entry. This is a hash-like object that allows
+    #   you to retrieve LDAP attributes using their names in lower
+    #   case. Values in the entry may be arrays or scalars. They may
+    #   not be serializable, so before copying a value out you should
+    #   be sure to dup it.
+    # * A proc that allows you to safely extract a single value from
+    #   the entry. The values returned from this proc are safe to set
+    #   directly in the user.
+    #
+    # If there is an entry in this mapping whose key is the same as a
+    # key in {#attribute_map}, the processor will be used instead of
+    # the simple mapping implied by `attribute_map`.
+    #
+    # @example An example processor
+    #   lambda { |user, entry, s|
+    #     user.identifiers[:ssn] = s[:ssn]
+    #   }
+    #
+    # @return [Hash<Symbol, #call>]
+    def attribute_processors
+      @attribute_processors ||= attribute_map_processors.merge(@config[:attribute_processors] || {})
+    end
+
+    def attribute_map_processors
+      Hash[attribute_map.collect { |ldap, aker|
+        [ldap, lambda { |user, entry, s| user.send("#{aker}=", s[ldap]) }]
+      }]
+    end
+    private :attribute_map_processors
+
+    ##
+    # A mapping between attributes from the LDAP server and criteria
+    # keys used in {#find_users}. This mapping will be used when
+    # translating criteria hashes into LDAP queries. It is similar to
+    # {#attribute_map} in that way, but there are two differences:
+    #
+    # * The mapping is [criteria key] => [LDAP attribute]. This is the
+    #   reverse of `attribute_map`.
+    # * The "criteria" in `attribute_map` have to be {Aker::User}
+    #   attribute names. This map does not have that restriction.
+    #
+    # If a criterion appears both in this map and `attribute_map`, the
+    # mapping in this map is used.
+    #
+    # @return [Hash<Symbol,Symbol>]
+    def criteria_map
+      @config[:criteria_map] || {}
+    end
+
+    ##
+    # @private (only exposed for testing)
+    # @return [Hash]
+    def ldap_parameters
+      {
+        :host => server, :port => port,
+        :auth => if user
+                   { :method => :simple, :username => user, :password => password }
+                 else
+                   { :method => :anonymous }
+                 end,
+        :encryption => (:simple_tls if use_tls)
+      }
+    end
+
+    ##
+    # Verifies a username and password using the configured NU LDAP
+    # server.  Only supports the `:user` credential kind.  There must
+    # be exactly two credentials.
+    #
+    # @return [User, nil, :unsupported] a complete user record
+    #   if the credentials are valid, `nil` if they aren't valid, and
+    #   `:unsupported` if the first parameter is anything other than
+    #   `:user`
+    def valid_credentials?(kind, *credentials)
+      return :unsupported unless kind == :user
+
+      username, password = credentials
+      return nil unless password && !password.strip.empty?
+
+      with_ldap do |ldap|
+        result = find_by_criteria(ldap, :username => username)
+        if result.size == 1
+          return ldap.authentic?(one_value(result[0], :dn), password) ? create_user(result[0]) : nil
+        else
+          return nil
+        end
+      end
+    end
+
+    ##
+    # Searches for and returns users matching the given criteria.  If
+    # the criteria is a `String`, it is treated as a username.  If it
+    # is a `Hash`, the keys are interpreted as {Aker::User} attribute
+    # names. Those attributes which are directly mappable to LDAP
+    # attributes will be used to build a filtered LDAP query.  If the
+    # `Hash` contains no keys which are mappable to LDAP attribute
+    # names, no query will be performed and an empty array will be
+    # returned.
+    #
+    # @see Composite#find_users
+    # @return [Array<User>]
+    def find_users(*criteria)
+      with_ldap do |ldap|
+        result = find_by_criteria(ldap, *criteria)
+        return result.collect { |r| create_user(r) }
+      end
+    end
+    include ::Aker::Authorities::Support::FindSoleUser
+
+    protected
+
+    def create_user(ldap_entry)
+      Aker::User.new(one_value(ldap_entry, :uid)).tap do |u|
+        s = lambda { |k| one_value(ldap_entry, k) }
+        attribute_processors.reject { |k, v| k == :username }.each do |k, processor|
+          processor.call(u, ldap_entry, s)
+        end
+
+        u.extend UserExt
+        u.ldap_attributes = ldap_entry
+      end
+    end
+
+    def create_criteria_filter(criterion)
+      case criterion
+      when Hash
+        criterion.collect { |aker_attribute, value|
+          create_single_filter(aker_attribute.to_sym, value)
+        }.compact.inject { |all, filter|
+          all & filter
+        }
+      else
+        create_criteria_filter(:username => criterion.to_s)
+      end
+    end
+
+    def with_ldap
+      # Net::LDAP.open leaks connections in 0.0.4, so do this instead
+      ldap = Net::LDAP.new(ldap_parameters)
+      yield ldap
+    end
+
+    def find_by_criteria(ldap, *criteria)
+      filter = criteria.collect { |c| create_criteria_filter(c) }.inject { |a, f| a | f }
+      return [] unless filter
+      base = "dc=northwestern,dc=edu"
+      ldap.search(:filter => filter, :base => base)
+    end
+
+    def one_value(ldap_entry, key)
+      item = [*ldap_entry[key]].first
+      item.nil? ? nil : item.dup
+    end
+
+    def validate_config!
+      self.server or raise "The server parameter is required for ldap."
+      if self.user.nil? ^ self.password.nil?
+        raise "For ldap, both user and password are required if one is set."
+      end
+    end
+
+    def create_single_filter(aker_attribute, value)
+      ldap_attribute = criteria_map[aker_attribute] || reverse_attribute_map[aker_attribute]
+      if !value.nil? && ldap_attribute
+        Net::LDAP::Filter.eq(ldap_attribute.to_s, value)
+      end
+    end
+  end
+end
+
+##
+# Aker-specific extensions to net/ldap.
+class Net::LDAP
+  ##
+  # Sugar for using LDAP bind to verify a password.
+  #
+  # @param dn [String] a full distinguished name
+  # @param password [String] a password to check
+  # @return [Boolean]
+  def authentic?(dn, password)
+    self.authenticate(dn, password)
+    self.bind
+  end
+end

data/lib/aker/ldap/user_ext.rb

@@ -0,0 +1,19 @@
+require 'aker/ldap'
+
+module Aker::Ldap
+  ##
+  # Extensions to {Aker::User} for users that were found in
+  # an LDAP server.
+  #
+  # @see Aker::Ldap::Authority
+  module UserExt
+    ##
+    # A hash of all the attributes in the user's ldap
+    # record. The keys are downcased versions of the
+    # (case-insensitive) LDAP keys.  Values are arrays of strings
+    # (since LDAP allows multiple instances of the same key).
+    #
+    # @return [Hash<Symbol, Array<String>>]
+    attr_accessor :ldap_attributes
+  end
+end

data/lib/aker/ldap.rb

@@ -0,0 +1,22 @@
+require 'aker'
+
+module Aker
+  ##
+  # Namespace for LDAP-related functionality in Aker.
+  module Ldap
+    autoload :Authority, 'aker/ldap/authority'
+    autoload :UserExt,   'aker/ldap/user_ext'
+
+    ##
+    # @private
+    class Slice < Aker::Configuration::Slice
+      def initialize
+        super do
+          alias_authority :ldap, Authority
+        end
+      end
+    end
+  end
+end
+
+Aker::Configuration.add_default_slice(Aker::Ldap::Slice.new)

data/lib/aker/modes/base.rb

@@ -0,0 +1,85 @@
+require 'aker'
+require 'warden'
+
+module Aker
+  module Modes
+    ##
+    # Base class for all authentication modes.
+    #
+    # An _authentication mode_ is an an object that implements an
+    # authentication protocol. Modes may be _interactive_, meaning that they
+    # require input from a human, and/or _non-interactive_, meaning that they
+    # can be used without user intervention.
+    #
+    # For mode implementors: While it is not strictly necessary to implement
+    # aker modes as subclasses of `Aker::Modes::Base`, it is recommended that
+    # you do so.
+    #
+    # @author David Yip
+    class Base < Warden::Strategies::Base
+      include Aker::Rack::EnvironmentHelper
+
+      ##
+      # Exposes the configuration this mode should use.
+      #
+      # @return [Aker::Configuration]
+      def configuration
+        super(env)
+      end
+
+      ##
+      # Exposes the authority this mode will use to validate
+      # credentials.  Internally it is extracted from the
+      # `aker.authority` Rack environment variable.
+      #
+      # @return [Object]
+      def authority
+        super(env)
+      end
+
+      ##
+      # Whether or not the current request is interactive.
+      #
+      # @return [Boolean]
+      def interactive?
+        super(env)
+      end
+
+      ##
+      # Used by Warden to determine whether or not it should store user
+      # information in the session.  In Aker, this is computed as the result
+      # of {#interactive?}.
+      #
+      # N.B. The `!!` is present because Warden requires that this method return
+      # `false` (not `false` or `nil`) for session serialization to be disabled.
+      #
+      # @see
+      #   http://rubydoc.info/gems/warden/1.0.3/Warden/Strategies/Base#store%3F-instance_method
+      #   Warden::Strategies::Base#store documentation
+      # @see
+      #   https://github.com/hassox/warden/blob/v1.0.3/lib/warden/proxy.rb#L158
+      #   Warden's expectations for this method
+      #
+      # @return [Boolean]
+      def store?
+        !!interactive?
+      end
+
+      ##
+      # Authenticates a user.
+      #
+      # {#authenticate!} expects `kind` and `credentials` to be
+      # defined.  See subclasses for examples.
+      #
+      # If authentication is successful, then success! (from
+      # `Warden::Strategies::Base`) is called with a {User} object.
+      # If authentication fails, then nothing is done.
+      #
+      # @return [void]
+      def authenticate!
+        user = authority.valid_credentials?(kind, *credentials)
+        success!(user) if user
+      end
+    end
+  end
+end

data/lib/aker/modes/http_basic.rb

@@ -0,0 +1,100 @@
+require 'aker'
+require 'base64'
+
+module Aker
+  module Modes
+    ##
+    # A non-interactive and interactive mode that provides HTTP Basic
+    # authentication.
+    #
+    # This mode operates non-interactively when an Authorization header with a
+    # Basic challenge is present.  It operates interactively when it is
+    # configured as an interactive authentication mode.
+    #
+    # @see http://www.ietf.org/rfc/rfc2617.txt
+    #      RFC 2617
+    # @author David Yip
+    class HttpBasic < Aker::Modes::Base
+      include Support::Rfc2617
+
+      ##
+      # Recognizes valid Basic challenges.
+      #
+      # An HTTP Basic challenge is the word "Basic", followed by one space,
+      # followed by a Base64-encoded string.
+      #
+      # @see http://www.ietf.org/rfc/rfc2045.txt
+      #      RFC 2045, section 6.8
+      BasicPattern = %r{^Basic ((?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?)$}
+
+      ##
+      # A key that refers to this mode; used for configuration convenience.
+      #
+      # @return [Symbol]
+      def self.key
+        :http_basic
+      end
+
+      ##
+      # The type of credentials supplied by this mode.
+      #
+      # @return [Symbol]
+      def kind
+        :user
+      end
+
+      # Decodes and extracts a (username, password) pair from an Authorization
+      # header.
+      #
+      # This method checks if the format of the Authorization header is a valid
+      # response to a Basic challenge.  If it is, then a username (and possibly
+      # a password) are returned.  If it is not, then an empty array is
+      # returned.
+      #
+      # @return [Array<String>] username and password, username, or an empty
+      #                         array
+      #
+      # @see BasicPattern
+      # @see http://www.ietf.org/rfc/rfc2617.txt
+      #      RFC 2617, section 2
+      def credentials
+        key = 'HTTP_AUTHORIZATION'
+        matches = env[key].match(BasicPattern) if env.has_key?(key)
+
+        if matches && matches[1]
+          Base64.decode64(matches[1]).split(':', 2)
+        else
+          []
+        end
+      end
+
+      ##
+      # Returns true if a valid Basic challenge is present, false otherwise.
+      def valid?
+        credentials.length == 2
+      end
+
+      ##
+      # Builds a Rack response with status 401 that indicates a need for
+      # authentication.
+      #
+      # With Web browsers, this will cause a username/password dialog to
+      # appear.
+      #
+      # @return [Rack::Response]
+      def on_ui_failure
+        ::Rack::Response.new([], 401, {'WWW-Authenticate' => challenge})
+      end
+
+      ##
+      # Used to build a WWW-Authenticate header that will be returned to a
+      # client when authentication is required.
+      #
+      # @see HttpMode#challenge
+      # @return [String]
+      def scheme
+        "Basic"
+      end
+    end
+  end
+end

data/lib/aker/modes/support/attempted_path.rb

@@ -0,0 +1,22 @@
+require 'aker/modes/support'
+
+module Aker::Modes::Support
+  ##
+  # If a user fails authentication, the URL that user was trying to access is
+  # stored in the `:attempted_path` key in the `warden.options` environment
+  # variable.
+  #
+  # AttemptedPath provides code to extract the attempted path that can be
+  # shared amongst objects that need this information.
+  module AttemptedPath
+    ##
+    # Returns the path that a user was trying to access.
+    #
+    # @return [String, nil] a String if a path exists, nil otherwise
+    def attempted_path
+      if env['warden.options']
+        env['warden.options'][:attempted_path]
+      end
+    end
+  end
+end

data/lib/aker/modes/support/rfc_2617.rb

@@ -0,0 +1,32 @@
+require 'aker/modes/support'
+
+module Aker
+  module Modes
+    module Support
+      ##
+      # A mixin providing common methods for modes which implement
+      # authentication according to RFC 2616 and RFC 2617.
+      module Rfc2617
+        ##
+        # Builds the content of the WWW-Authenticate challenge header for
+        # a particular mode.  Requires that the target mode implement
+        # `#scheme`.
+        #
+        # @return [String] the challenge
+        def challenge
+          "#{scheme} realm=\"#{realm}\""
+        end
+
+        ##
+        # Determines the value to use for the required "realm" challenge
+        # parameter.  If set, the {Aker::Configuration#portal portal} is
+        # used.  Otherwise "Aker" is used.
+        #
+        # @return [String]
+        def realm
+          (configuration.portal? ? configuration.portal : 'Aker').to_s
+        end
+      end
+    end
+  end
+end

data/lib/aker/modes/support.rb

@@ -0,0 +1,12 @@
+require 'aker/modes'
+
+module Aker
+  module Modes
+    ##
+    # Library code shared by modes and their middleware lives here.
+    module Support
+      autoload :AttemptedPath,          'aker/modes/support/attempted_path'
+      autoload :Rfc2617,                'aker/modes/support/rfc_2617'
+    end
+  end
+end