github-ldap 1.3.3 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f417737b5a49cba30ca466e8ef2a361894d4069a
-  data.tar.gz: fad20f08e322deb3b0a3303f4a5b9b2c0fce1469
+  metadata.gz: 053a59e45e7ee63a06ee943da318bf9362455306
+  data.tar.gz: d2b435150ad904b336490fa9e5bc863b6ab6d38d
 SHA512:
-  metadata.gz: 7fed87fe08383e0a6a264e99396aa8a7e9ed22d85dd5bdba0f100f9b558c5ac548718d1e7825cc01022329a877f0471138bab7eca2679d5f6c602ba9fb7bba1b
-  data.tar.gz: ee4bf4726436769b4109d052b2d5071e1f1ef26029ee3ab5b29ee020d60dcfdfff867ef11a8b4f624ec271ac60f46f153007f6dbe8220825e1aff8f380327a42
+  metadata.gz: 195ae9040327fb236460618d6efeaf5588f07d33edc06220d312790643d81b6892ec063045dac7e4de5dd73444e8cead35baf1555ed57659855d519d0e297a15
+  data.tar.gz: a5a047f799e6653cfbfc83749ed452ea2e3b0af1452930cdae78b51bf94461ce0bbb23ebe5a2b1672f348a1826a21633552680ae16cff56ddfffcc0a249e1b07

data/.travis.yml

@@ -1,7 +1,20 @@
 language: ruby
 rvm:
-    - 1.9.3
-    - 2.1.0
+  - 1.9.3
+  - 2.1.0
 
+env:
+  - TESTENV=openldap
+  - TESTENV=apacheds
+
+install:
+  - if [ "$TESTENV" = "openldap" ]; then ./script/install-openldap; fi
+  - bundle install
+
+script:
+  - ./script/cibuild-$TESTENV
+
+matrix:
+  fast_finish: true
 notifications:
   email: false

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# CHANGELOG
+
+## v1.4.0
+
+* Document constructor options [#57](https://github.com/github/github-ldap/pull/57)
+* [CI] Add Vagrant box for running tests against OpenLDAP locally [#55](https://github.com/github/github-ldap/pull/55)
+* Run all tests, including those in subdirectories [#54](https://github.com/github/github-ldap/pull/54)
+* Add ActiveDirectory membership validator [#52](https://github.com/github/github-ldap/pull/52)
+* Merge dev-v2 branch into master [#50](https://github.com/github/github-ldap/pull/50)
+* Pass through search options for GitHub::Ldap::Domain#user? [#51](https://github.com/github/github-ldap/pull/51)
+* Fix membership validation tests [#49](https://github.com/github/github-ldap/pull/49)
+* Add CI build for OpenLDAP integration [#48](https://github.com/github/github-ldap/pull/48)
+* Membership Validators [#45](https://github.com/github/github-ldap/pull/45)

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in github-ldap.gemspec
 gemspec
+
+group :test, :development do
+  gem "byebug", :platforms => [:mri_20, :mri_21]
+end

data/README.md

@@ -1,4 +1,4 @@
-<a href="https://travis-ci.org/github/github-ldap">![Build Status](https://travis-ci.org/github/github-ldap.png)</a>
+<a href="https://travis-ci.org/github/github-ldap">![Build Status](https://travis-ci.org/github/github-ldap.png?branch=master)</a>
 
 # Github::Ldap
 
@@ -42,6 +42,8 @@ Initialize a new adapter using those required options:
   ldap = GitHub::Ldap.new options
 ```
 
+See GitHub::Ldap#initialize for additional options.
+
 ### Querying
 
 Searches are performed against an individual domain base, so the first step is to get a new `GitHub::Ldap::Domain` object for the connection:
@@ -128,3 +130,15 @@ end
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## Releasing
+
+This section is for gem maintainers to cut a new version of the gem. See
+[jch/release-scripts](https://github.com/jch/release-scripts) for original
+source of release scripts.
+
+* Create a new branch from `master` named `release-x.y.z`, where `x.y.z` is the version to be released
+* Update `github-ldap.gemspec` to x.y.z following [semver](http://semver.org)
+* Run `script/changelog` and paste the draft into `CHANGELOG.md`. Edit as needed
+* Create pull request to solict feedback
+* After merging the pull request, on the master branch, run `script/release`

data/Rakefile

@@ -3,7 +3,7 @@ require 'rake/testtask'
 
 Rake::TestTask.new do |t|
   t.libs << "test"
-  t.pattern = "test/*_test.rb"
+  t.pattern = "test/**/*_test.rb"
 end
 
 task :default => :test

data/github-ldap.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "github-ldap"
-  spec.version       = "1.3.3"
+  spec.version       = "1.4.0"
   spec.authors       = ["David Calavera"]
   spec.email         = ["david.calavera@gmail.com"]
   spec.description   = %q{Ldap authentication for humans}
@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'net-ldap', '~> 0.7.0'
+  spec.add_dependency 'net-ldap', '~> 0.9.0'
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency 'ladle'

data/lib/github/ldap.rb

@@ -8,6 +8,10 @@ module GitHub
     require 'github/ldap/posix_group'
     require 'github/ldap/virtual_group'
     require 'github/ldap/virtual_attributes'
+    require 'github/ldap/instrumentation'
+    require 'github/ldap/membership_validators'
+
+    include Instrumentation
 
     extend Forwardable
 
@@ -23,12 +27,45 @@ module GitHub
     # Returns a Net::LDAP::Entry if the operation succeeded.
     def_delegator :@connection, :bind
 
-    attr_reader :uid, :search_domains, :virtual_attributes
+    # Public - Opens a connection to the server and keeps it open for the
+    # duration of the block.
+    #
+    # Returns the return value of the block.
+    def_delegator :@connection, :open
+
+    attr_reader :uid, :search_domains, :virtual_attributes,
+                :instrumentation_service
 
+    # Build a new GitHub::Ldap instance
+    #
+    # ## Connection
+    #
+    # host: required string ldap server host address
+    # port: required string or number ldap server port
+    # encryption: optional string. `ssl` or `tls`. nil by default
+    # admin_user: optional string ldap administrator user dn for authentication
+    # admin_password: optional string ldap administrator user password
+    #
+    # ## Behavior
+    #
+    # uid: optional field name used to authenticate users. Defaults to `sAMAccountName` (what ActiveDirectory uses)
+    # virtual_attributes: optional. boolean true to use server's virtual attributes. Hash to specify custom mapping. Default false.
+    # recursive_group_search_fallback: optional boolean whether membership checks should recurse into nested groups when virtual attributes aren't enabled. Default false.
+    # posix_support: optional boolean `posixGroup` support. Default true.
+    # search_domains: optional array of string bases to search through
+    #
+    # ## Diagnostics
+    #
+    # instrumentation_service: optional ActiveSupport::Notifications compatible object
+    #
     def initialize(options = {})
       @uid = options[:uid] || "sAMAccountName"
 
-      @connection = Net::LDAP.new({host: options[:host], port: options[:port]})
+      @connection = Net::LDAP.new({
+        host: options[:host],
+        port: options[:port],
+        instrumentation_service: options[:instrumentation_service]
+      })
 
       if options[:admin_user] && options[:admin_password]
         @connection.authenticate(options[:admin_user], options[:admin_password])
@@ -49,6 +86,9 @@ module GitHub
       # search_domains is a connection of bases to perform searches
       # when a base is not explicitly provided.
       @search_domains = Array(options[:search_domains])
+
+      # enables instrumenting queries
+      @instrumentation_service = options[:instrumentation_service]
     end
 
     # Public - Whether membership checks should recurse into nested groups when
@@ -126,17 +166,20 @@ module GitHub
     #
     # Returns an Array of Net::LDAP::Entry.
     def search(options, &block)
-      result = if options[:base]
-        @connection.search(options, &block)
-      else
-        search_domains.each_with_object([]) do |base, result|
-          rs = @connection.search(options.merge(:base => base), &block)
-          result.concat Array(rs) unless rs == false
-        end
+      instrument "search.github_ldap", options.dup do |payload|
+        result =
+          if options[:base]
+            @connection.search(options, &block)
+          else
+            search_domains.each_with_object([]) do |base, result|
+              rs = @connection.search(options.merge(:base => base), &block)
+              result.concat Array(rs) unless rs == false
+            end
+          end
+
+        return [] if result == false
+        Array(result)
       end
-
-      return [] if result == false
-      Array(result)
     end
 
     # Internal - Determine whether to use encryption or not.

data/lib/github/ldap/domain.rb

@@ -110,11 +110,15 @@ module GitHub
       # Check if a user exists based in the `uid`.
       #
       # login: is the user's login
+      # search_options: Net::LDAP#search compatible options to pass through
       #
       # Returns the user if the login matches any `uid`.
       # Returns nil if there are no matches.
-      def user?(login)
-        search(filter: login_filter(@uid, login), size: 1).first
+      def user?(login, search_options = {})
+        options = search_options.merge \
+          filter: login_filter(@uid, login),
+          size: 1
+        search(options).first
       end
 
       # Check if a user can be bound with a password.

data/lib/github/ldap/filter.rb

@@ -20,16 +20,18 @@ module GitHub
 
       # Filter to check group membership.
       #
-      # entry: finds groups this Net::LDAP::Entry is a member of (optional)
+      # entry: finds groups this entry is a member of (optional)
+      #        Expects a Net::LDAP::Entry or String DN.
       #
       # Returns a Net::LDAP::Filter.
       def member_filter(entry = nil)
         if entry
+          entry = entry.dn if entry.respond_to?(:dn)
           MEMBERSHIP_NAMES.
-            map {|n| Net::LDAP::Filter.eq(n, entry.dn) }.reduce(:|)
+            map {|n| Net::LDAP::Filter.eq(n, entry) }.reduce(:|)
         else
           MEMBERSHIP_NAMES.
-            map {|n| Net::LDAP::Filter.pres(n) }.        reduce(:|)
+            map {|n| Net::LDAP::Filter.pres(n) }.     reduce(:|)
         end
       end
 
@@ -41,10 +43,16 @@ module GitHub
       # uid_attr: specifies the memberUid attribute to match with
       #
       # Returns a Net::LDAP::Filter or nil if no entry has no UID set.
-      def posix_member_filter(entry, uid_attr)
-        if !entry[uid_attr].empty?
-          entry[uid_attr].map { |uid| Net::LDAP::Filter.eq("memberUid", uid) }.
-                          reduce(:|)
+      def posix_member_filter(entry_or_uid, uid_attr = nil)
+        case entry_or_uid
+        when Net::LDAP::Entry
+          entry = entry_or_uid
+          if !entry[uid_attr].empty?
+            entry[uid_attr].map { |uid| Net::LDAP::Filter.eq("memberUid", uid) }.
+                            reduce(:|)
+          end
+        when String
+          Net::LDAP::Filter.eq("memberUid", entry_or_uid)
         end
       end
 

data/lib/github/ldap/group.rb

@@ -12,7 +12,7 @@ module GitHub
     class Group
       include Filter
 
-      GROUP_CLASS_NAMES = %w(groupOfNames groupOfUniqueNames posixGroup)
+      GROUP_CLASS_NAMES = %w(groupOfNames groupOfUniqueNames posixGroup group)
 
       attr_reader :ldap, :entry
 

data/lib/github/ldap/instrumentation.rb

@@ -0,0 +1,28 @@
+module GitHub
+  class Ldap
+    # Encapsulates common instrumentation behavior.
+    module Instrumentation
+      attr_reader :instrumentation_service
+      private     :instrumentation_service
+
+      # Internal: Instrument a block with the defined instrumentation service.
+      #
+      # Yields the event payload if a block is given.
+      #
+      # Skips instrumentation if no service is set.
+      #
+      # Returns the return value of the block.
+      def instrument(event, payload = {})
+        payload = (payload || {}).dup
+        if instrumentation_service
+          instrumentation_service.instrument(event, payload) do |payload|
+            payload[:result] = yield(payload) if block_given?
+          end
+        else
+          yield(payload) if block_given?
+        end
+      end
+      private :instrument
+    end
+  end
+end

data/lib/github/ldap/membership_validators.rb

@@ -0,0 +1,18 @@
+require 'github/ldap/membership_validators/base'
+require 'github/ldap/membership_validators/classic'
+require 'github/ldap/membership_validators/recursive'
+require 'github/ldap/membership_validators/active_directory'
+
+module GitHub
+  class Ldap
+    # Provides various strategies for validating membership.
+    #
+    # For example:
+    #
+    #   groups = domain.groups(%w(Engineering))
+    #   validator = GitHub::Ldap::MembershipValidators::Classic.new(ldap, groups)
+    #   validator.perform(entry) #=> true
+    #
+    module MembershipValidators; end
+  end
+end

data/lib/github/ldap/membership_validators/active_directory.rb

@@ -0,0 +1,56 @@
+module GitHub
+  class Ldap
+    module MembershipValidators
+      ATTRS = %w(dn)
+      OID   = "1.2.840.113556.1.4.1941"
+
+      # Validates membership using the ActiveDirectory "in chain" matching rule.
+      #
+      # The 1.2.840.113556.1.4.1941 matching rule (LDAP_MATCHING_RULE_IN_CHAIN)
+      # "walks the chain of ancestry in objects all the way to the root until
+      # it finds a match".
+      # Source: http://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx
+      #
+      # This means we have an efficient method of searching membership even in
+      # nested groups, performed on the server side.
+      class ActiveDirectory < Base
+        def perform(entry)
+          # short circuit validation if there are no groups to check against
+          return true if groups.empty?
+
+          # search for the entry on the condition that the entry is a member
+          # of one of the groups or their subgroups.
+          #
+          # Sets the entry to the base and scopes the search to the base,
+          # according to the source documentation, found here:
+          # http://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx
+          matched = ldap.search \
+            filter: membership_in_chain_filter(entry),
+            base:   entry.dn,
+            scope:  Net::LDAP::SearchScope_BaseObject,
+            attributes: ATTRS
+
+          # membership validated if entry was matched and returned as a result
+          matched.map(&:dn).include?(entry.dn)
+        end
+
+        # Internal: Constructs a membership filter using the "in chain"
+        # extended matching rule afforded by ActiveDirectory.
+        #
+        # Returns a Net::LDAP::Filter object.
+        def membership_in_chain_filter(entry)
+          group_dns.map do |dn|
+            Net::LDAP::Filter.ex("memberOf:#{OID}", dn)
+          end.reduce(:|)
+        end
+
+        # Internal: the group DNs to check against.
+        #
+        # Returns an Array of String DNs.
+        def group_dns
+          @group_dns ||= groups.map(&:dn)
+        end
+      end
+    end
+  end
+end

data/lib/github/ldap/membership_validators/base.rb

@@ -0,0 +1,37 @@
+module GitHub
+  class Ldap
+    module MembershipValidators
+      class Base
+
+        # Internal: The GitHub::Ldap object to search domains with.
+        attr_reader :ldap
+
+        # Internal: an Array of Net::LDAP::Entry group objects to validate with.
+        attr_reader :groups
+
+        # Public: Instantiate new validator.
+        #
+        # - ldap:   GitHub::Ldap object
+        # - groups: Array of Net::LDAP::Entry group objects
+        def initialize(ldap, groups)
+          @ldap   = ldap
+          @groups = groups
+        end
+
+        # Abstract: Performs the membership validation check.
+        #
+        # Returns Boolean whether the entry's membership is validated or not.
+        # def perform(entry)
+        # end
+
+        # Internal: Domains to search through.
+        #
+        # Returns an Array of GitHub::Ldap::Domain objects.
+        def domains
+          @domains ||= ldap.search_domains.map { |base| ldap.domain(base) }
+        end
+        private :domains
+      end
+    end
+  end
+end

data/lib/github/ldap/membership_validators/classic.rb

@@ -0,0 +1,34 @@
+module GitHub
+  class Ldap
+    module MembershipValidators
+      # Validates membership using `GitHub::Ldap::Domain#membership`.
+      #
+      # This is a simple wrapper for existing functionality in order to expose
+      # it consistently with the new approach.
+      class Classic < Base
+        def perform(entry)
+          # short circuit validation if there are no groups to check against
+          return true if groups.empty?
+
+          domains.each do |domain|
+            membership = domain.membership(entry, group_names)
+
+            if !membership.empty?
+              entry[:groups] = membership
+              return true
+            end
+          end
+
+          false
+        end
+
+        # Internal: the group names to look up membership for.
+        #
+        # Returns an Array of String group names (CNs).
+        def group_names
+          @group_names ||= groups.map { |g| g[:cn].first }
+        end
+      end
+    end
+  end
+end