dm-ldap-adapter 0.4.3-java

data/History.txt

@@ -0,0 +1,75 @@
+version 0.4.3
+=============
+
+* test several environments: ruby-1.8.7/1.9.2, jruby-1.5.6/1.6.2 (1.8 and 1.9 where possible), DM-1.0.x/1.1.x, net-ldap and ruby-ldap gem as backend. run the specs against all possible combinations.
+
+* improvements with LdapArray properties
+
+version 0.4.2
+=============
+
+* Serial fieldnames are case insensitive now, i.e. allow capital as well 
+
+version 0.4.1
+=============
+
+* mutliline values inside Ldap::Array
+
+version 0.3.5
+=============
+
+* sorting can handle nil values now
+
+version 0.3.4
+=============
+
+* fixed bug with or condition
+
+* sort now case insensitive
+
+* added setup parameter to choose the facade the ldap adapter shall use
+
+version 0.3.3
+=============
+
+* fix bug with empty LdapArray for ruby-ldap-adapter
+
+* added order option to search with just using the first order attribute and ignoring the direction and other attributes
+
+version 0.3.2
+=============
+
+* lazy property are not loaded from ldap anymore
+
+* new facade which uses ruby-ldap, since it has better support for ldap protocol and is about 30% faster with search queries
+
+version 0.3.1
+=============
+
+* fixed LdapArray bug in collections
+
+* default of LdapArray is now a new object for each resource instance
+
+* allow Serial to be used in dn_prefix
+
+version 0.3.0
+=============
+
+* fixed bug where Serial and Integer,:serial=>true were handled differently. the Integer values are handle with all types which have an Integer as primitive
+
+* added dm-core gem dependency with version below 0.10.0
+
+* added LdapArray type for resources which allow the use of the multivalue ldap attriutes
+
+* allow conditions in queries, but only of the form "<property_name> <comparator> <value> [or <property_name> <comparator> <value>]*" where comparator is one of "=", "like"
+
+version 0.2.0
+=============
+
+* switched to Slf4r logger
+
+* the whole thing became a gem
+
+* cleaned up example
+
+* moved the SHA and SSHA calculation into its own helper class (incompatible change to older version)

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Kristian Meier
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,247 @@
+# dm-ldap-adapter
+
+*Homepage*: [http://github.com/mkristian/dm-ldap-adapter](http://github.com/mkristian/dm-ldap-adapter)
+
+*Git*: [git://github.com/mkristian/dm-ldap-adapter.git](git://github.com/mkristian/dm-ldap-adapter.git)
+
+*Author*:    Kristian Meier
+
+*Copyright*: 2008-2009
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+
+* Make your feature addition or bug fix.
+
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+
+* Send me a pull request.
+
+## DESCRIPTION:
+
+### usecase
+
+the usecase for that implementation was using an ldap server for user authentication and authorization. the ldap server is configured to have posixAccounts and posixGroups. on the datamapper side these accounts/groups are modeled with many-to-many relationship. further more the model classes should be in such a way that they can be used with another repository as well, i.e. they carry some ldap related configuration but this is only relevant for the ldap-adapter.
+
+### low level ldap library
+
+the ldap library which does the actual ldap protocol stuff is [http://rubyforge.org/projects/net-ldap] which is the default. the other ldap library is [http://rubyforge.org/projects/ruby-ldap]. just add a facade parameter when setting up DataMapper
+
+    DataMapper.setup(:ldap, {
+                   :adapter  => 'ldap',
+                   :facade => :ruby_ldap,
+     .... })
+
+or
+
+    DataMapper.setup(:ldap, {
+                   :adapter  => 'ldap',
+                   :facade => :net_ldap,
+     .... })
+
+### setup DataMapper
+
+    DataMapper.setup(:ldap, {
+                   :adapter  => 'ldap',
+                   :host => 'localhost',
+                   :port => '389',
+                   :base => "dc=example,dc=com",
+                   :facade => :ruby_ldap,
+                   :bind_name => "cn=admin,dc=example,dc=com",
+                   :password => "behappy"
+     })
+
+### examples
+
+see 'example/posix.rb' for user/group setup works with default installation of openldap on ubuntu (just change your password as needed in the code)
+
+## FEATURES/PROBLEMS:
+
+* the net-ldap has some issues with not closing the connections when an exception/error got raised, with limit the search result to 126 entries which gets fixed by making consecutives searches and collect the result.
+
+* error from the ldap server are only logged and do not raise any exceptions (to be changed in next release) with one exception: when creating a new ldap entry a duplicated entry will raise DataMapper::PersistenceError
+
+## SYNOPSIS:
+
+### distinguished name (DN) of a model
+
+there are three parts which makes the DN of a model, the base from the ldap conncetion, the `treebase` of the model and `dn_prefix` of an instance.
+
+    class User
+      include DataMapper::Resource
+      property :id, Serial, :field => "uidNumber"
+      dn_prefix { |user| "uid=#{user.login}"}
+      treebase "ou=people"
+    end
+
+with a base `dc=example,dc=com` we get a DN like the user 'admin'
+
+    uid=admin,ou=people,dc=example,dc=com
+
+### ldap entities are bigger than the model
+
+for example the ldap posixGroup has more attributes than the model class, it needs the `objectclass` attribute set to `posixGroup`.
+
+    class Group
+      include DataMapper::Resource
+      property :id, Serial, :field => "gidNumber"
+      property :name,     String, :field => "cn"
+      dn_prefix { |group| "cn=#{group.name}" }
+      treebase "ou=groups"
+      ldap_properties {{ :objectclass => "posixGroup"}}
+    end
+
+so with the help of the `ldap_properties` you can define a block which returns an hash with extra attributes. with such block you can make some calculations if needed, i.e. :homedirectory => "/home/#{login}" for the posixAccount.
+
+### authentication
+
+this uses the underlying bind of a ldap connection. so on any model where you have the `dn_prefix` and the `treebase` configured, you can call the method `authenticate(password)`. this will forward the request to the ldap server.
+
+### queries
+
+conditions in ldap depend on the attributes definition in the ldap schema. here is the list of what is working with that ldap adapter side and the usual AND between the conditions:
+
+* :eql
+* :not
+* :like
+* :in
+* Range
+
+not working are `:lt, :lte, :gt, :gte`
+
+*note*: sql handles `NULL` different from values, i.e.
+
+     select * from users where name = 'sd';
+
+and
+
+     select * from users where name != 'sd';
+
+gives the same result when *all* names are `NULL` !!!
+
+### OR conditions
+
+or-conditions can be done with :conditions option but only of the form "<property_name> <comparator> <value> [or <property_name> <comparator> <value>]*" where the comparator is one of "=", "like". it can be also combined with extra ANDs like this example
+
+    Contact.all(:name.like => "A%", :conditions => ["phone like '+49%' or mobile like '+49%'"])
+
+### multiple repositories
+
+most probably you have to work with ldap as one repository and a database as a second repository. for me it worked best to define the `default_repository` for each model in the model itself:
+
+    class User
+      . . .
+      def self.default_repository_name
+        :ldap
+      end
+    end
+
+    class Config
+      . . .
+      def self.default_repository_name
+        :db
+      end
+    end
+
+if you want to benefit from the advantages of the identidy maps you need to wrap your actions for *merb* see http://www.datamapper.org/doku.php?id=docs:identity_map or for *rails* put an `around_filter` inside application.rb
+
+     around_filter :repositories
+
+     def repositories
+       DataMapper.repository(:ldap) do
+         DataMapper.repository(:db) do
+           yield
+         end
+       end
+     end
+
+and to let the ldap resources use the ldap respository it is best to bind it to that repository like this
+
+  class User
+    . . .
+    def self.repository_name
+      :ldap
+    end
+  end
+
+### transactions
+
+the adapter offers a noop transaction, i.e. you can wrap everything into a transaction but the ldap part has no functionality.
+
+*note*: the ldap protocol does not know transactions
+
+### many-to-many associations
+
+staying with posix example there the groups has a memberuid attribute BUT unlike with relational databases it can have multiple values. to achieve a relationship with these values the underlying adapter needs to know that this specific attribute needs to be handled differently. for this `multivalue_field` comes into play. the ldap adapter clones the model and places the each memberuid in its own clone.
+
+    class GroupUser
+      include DataMapper::Resource
+      property :memberUid, String, :key => true
+      property :gidNumber, Integer, :key => true
+      dn_prefix { |group_user| "cn=#{group_user.group.name}" }
+      treebase "ou=groups"
+      ldap_properties do |group_user|
+        {:cn=>"#{group_user.group.name}",  :objectclass => "posixGroup"}
+      end
+
+      multivalue_field :memberuid
+
+    end
+
+### ldap attributes with many values
+
+let's say your LDAP has multiple email values for a users then you can define your resource class like that using the type *LdapArray* for such multivalue fields
+
+    class User
+      include DataMapper::Resource
+      property :id,        Serial, :field => "uidNumber"
+      property :login,     String, :field => "uid", :unique_index => true
+      property :mail,      LdapArray
+
+      dn_prefix { |user| "uid=#{user.login}"}
+      treebase "ou=people"
+      ldap_properties do |user|
+        properties = { :objectclass => ["inetOrgPerson", "posixAccount", "shadowAccount"], :loginshell => "/bin/bash", :gidNumber => "10000" }
+       properties
+      end
+    end
+
+## REQUIREMENTS:
+
+* slf4r the logging facade
+* net-ldap pure ruby ldap library
+* ruby-ldap (optional) ruby with native ldap code
+* logging (optional) if logging via logging is desired
+* log4r (optional) if logging via log4r is desired
+
+## INSTALL:
+
+* sudo gem install dm-ldap-adapter
+
+## LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Kristian Meier
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/ldap-commands.txt

@@ -0,0 +1,17 @@
+# populate ldap with basic data
+ldapadd -x -w behappy -c -D "cn=admin,dc=example,dc=com" < test.ldif
+
+# search the whole domain
+ldapsearch -x -w behappy -c -D "cn=admin,dc=example,dc=com" -b 'dc=example,dc=com'
+
+# search people
+ldapsearch -x -w behappy -c -D "cn=admin,dc=example,dc=com" -b 'ou=people,dc=example,dc=com'
+
+#search groups
+ldapsearch -x -w behappy -c -D "cn=admin,dc=example,dc=com" -b 'ou=groups,dc=example,dc=com'
+
+# printout delete commands for all people
+ldapsearch -x -w behappy -c -D "cn=admin,dc=example,dc=com" -b 'ou=people,dc=example,dc=com' "uid=*" | grep ^uid: | sed -e "s/^.....//" -e 's/$/,ou=people,dc=example,dc=com"/' -e 's/^/-x -w behappy -c -D "cn=admin,dc=example,dc=com" "uid=/' | xargs -L 1 echo ldapdelete
+
+# all groups
+ldapsearch -x -w behappy -c -D "cn=admin,dc=example,dc=com" -b 'ou=groups,dc=example,dc=com' "cn=*" | grep ^cn: | sed -e "s/^....//" -e 's/$/,ou=groups,dc=example,dc=com"/' -e 's/^/-x -w behappy -c -D "cn=admin,dc=example,dc=com" "cn=/' | xargs -L 1 echo ldapdelete

data/lib/adapters/ldap_adapter.rb

@@ -0,0 +1,370 @@
+require "dm-core"
+require 'slf4r/logger'
+# require 'adapters/noop_transaction'
+
+module Ldap
+
+  # the class provides two ways of getting a LdapFacade. either
+  # one which is put on the current Thread or a new one
+  class LdapConnection
+
+    include ::Slf4r::Logger
+
+    def initialize(options)
+      if options[:facade].nil?
+        require 'ldap/net_ldap_facade'
+        @facade = ::Ldap::NetLdapFacade
+      else
+        case options[:facade].to_sym
+        when :ruby_ldap
+          require 'ldap/ruby_ldap_facade'
+          @facade = ::Ldap::RubyLdapFacade
+        when :net_ldap
+          require 'ldap/net_ldap_facade'
+          @facade = ::Ldap::NetLdapFacade
+        else
+          "please add a :facade parameter to the adapter setup. possible values are :ruby_ldap or net_ldap"
+        end
+      end
+      logger.info("using #{@facade}")
+      @ldaps = { }
+      auth =  {
+        :method => :simple,
+        :username => options[:bind_name],
+        :password => options[:password]
+      }
+      @config = {
+        :host => options[:host],
+        :port => options[:port].to_i,
+        :auth => auth,
+        :base => options[:base]
+      }
+    end
+
+    # puts a LdapFacade into the current thread and executes the
+    # given block.
+    def open
+      begin
+        @facade.open(@config) do |ldap|
+          @ldaps[Thread.current] = @facade.new(ldap)
+          yield
+        end
+      ensure
+        @ldaps[Thread.current] = nil
+      end
+    end
+
+    # @return [Ldap::LdapFacade]
+    #  either the one from the current Thread or a new one
+    def current
+      ldap = @ldaps[Thread.current]
+      if ldap
+        ldap
+      else
+        @facade.new(@config)
+      end
+    end
+  end
+end
+
+require "dm-core"
+module DataMapper
+  class Query
+
+    class SortCaseInsensitive < Sort
+      def initialize(value, ascending = true)
+        if(value && value.is_a?(String))
+          super(value.upcase, ascending)
+        else
+          super
+        end
+      end
+    end
+
+    def sort_records_case_insensitive(records)
+      #Return unsorted records unless we have order defined
+      return records unless order
+      sort_order = order.map { |direction| [ direction.target, direction.operator == :asc ] }
+      
+      records.sort_by do |record|
+        sort_order.map do |(property, ascending)|
+          SortCaseInsensitive.new(record_value(record, property), ascending)
+        end
+      end
+    end
+  end
+  module Adapters
+    class LdapAdapter < AbstractAdapter
+
+      # @return [Ldap::LdapFacade]
+      #   ready to use LdapFacade
+      def ldap
+        @ldap_connection.current
+      end
+
+      def open_ldap_connection(&block)
+        @ldap_connection.open(&block)
+      end
+
+      def key_properties(resource)
+        resource.model.key.first
+      end
+
+      COMPARATORS = { "=" => :eql, ">=" => :gte, "<=" => :lte, "like" => :like }
+
+      # helper to remove datamapper specific classes from the conditions
+      # @param [Array] conditions
+      #   array of tuples: (action, property, new value)
+      # @return [Array]
+      #   tuples: (action, attribute name, new value)
+      def to_ldap_conditions(query)
+        conditions = query.conditions
+        ldap_conditions = []
+        conditions.operands.each do |c|
+          if c.is_a? Array
+            props = {}
+            query.fields.each{ |f| props[f.name] = f.field}
+            or_conditions = []
+            c[0].split('or').each do |e|
+              e.strip!
+              match = e.match("=|<=|>=|like")
+              or_conditions << [COMPARATORS[match.values_at(0)[0]],
+                                props[match.pre_match.strip.to_sym],
+                                match.post_match.strip.gsub(/'/, '')]
+            end
+            ldap_conditions << [:or_operator, or_conditions, nil]
+          else
+            comparator = c.slug
+            case comparator
+            when :raw
+            when :not
+                # TODO proper recursion !!!
+                ldap_conditions << [comparator, c.operands.first.subject.field, c.operands.first.send(:dumped_value)]
+            when :in
+              ldap_conditions << [:eql, c.subject.field, c.send(:dumped_value)]
+            else
+              if c.subject.is_a? Ldap::LdapArray
+                # assume a single value here !!!
+                val = c.send(:dumped_value)
+                ldap_conditions << [comparator, c.subject.field, val[1, val.size - 2]]
+              else
+                ldap_conditions << [comparator, c.subject.field, c.send(:dumped_value)]
+              end
+            end
+          end
+        end
+        ldap_conditions
+      end
+
+      include ::Slf4r::Logger
+
+      # @see AbstractAdapter
+#      def transaction_primitive
+ #       NoopTransaction.new
+  #    end
+
+      public
+
+      def initialize(name, options)
+        super(name, options)
+        @ldap_connection = ::Ldap::LdapConnection.new(@options)
+      end
+
+
+      def create(resources)
+        resources.select do |resource|
+          create_resource(resource)
+        end.size # just return the number of create resources
+      end
+
+      def update(attributes, collection)
+        collection.each do |resource|
+#puts "update"
+#p resource
+          update_resource(resource, attributes)
+
+        end.size
+      end
+      # @param [DataMapper::Resource] resource
+      #   to be created
+      # @see SimpleAdapter#create_resource
+      # @return [Fixnum]
+      #    value for the primary key or nil
+      def create_resource(resource)
+        logger.debug { resource.inspect }
+
+        props = resource.model.ldap_properties(resource)
+        key = nil
+        resource.send(:properties).each do |prop|
+          value = prop.get!(resource)
+          if prop.class == ::Ldap::LdapArray
+            props[prop.field.to_sym] = value unless value.nil? or value.size == 0
+          else
+            props[prop.field.to_sym] = value.to_s unless value.nil?
+          end
+          key = prop if prop.serial?
+        end
+        resource_dup = resource.dup
+        id = ldap.retrieve_next_id(resource.model.treebase,
+                                   key_properties(resource).field)
+        resource_dup.send("#{key_properties(resource).name}=".to_sym, id)
+        props[key_properties(resource).field.to_sym] = "#{id}"
+        key_value = begin
+                      ldap.create_object(resource.model.dn_prefix(resource_dup),
+                                         resource.model.treebase,
+                                         key_properties(resource).field,
+                                         props, resource.model.multivalue_field)
+                    rescue => e
+                      raise e unless resource.model.multivalue_field
+                      # TODO something with creating these multivalue objects
+                    end
+        logger.debug { "resource #{resource.inspect} key value: #{key_value.inspect}" + ", multivalue_field: " + resource.model.multivalue_field.to_s }
+        if key_value and !key.nil?
+          key.set!(resource, key_value.to_i)
+          resource
+        elsif resource.model.multivalue_field
+          multivalue_prop = resource.send(:properties).detect do |prop|
+            prop.field.to_sym == resource.model.multivalue_field
+          end
+          update_resource(resource,
+                          { multivalue_prop =>
+                            resource.send(multivalue_prop.name.to_sym)})
+        else
+          nil
+        end
+      end
+
+      # @param [DataMapper::Resource] resource
+      #   to be updated
+      # @param [Hash] attributes
+      #   new attributes for the resource
+      # @see SimpleAdapter#update_resource
+      def update_resource(resource, attributes)
+        actions = []
+        attributes.each do |property, value|
+          field = property.field.to_sym #TODO sym needed or string ???
+          if property.class == ::Ldap::LdapArray
+            value = property.load(value)
+            if resource.original_attributes[property].nil?
+              value.each do |v|
+                actions << [:add, field, v]
+              end
+            else
+              array_actions = []
+              resource.original_attributes[property].each do |ov|
+                unless value.member? ov
+                  actions << [:delete, field, ov.to_s]
+                end
+              end
+              value.each do |v|
+                unless resource.original_attributes[property].member? v
+                  actions << [:add, field, v.to_s]
+                end
+              end
+              array_actions
+            end
+          else
+            if resource.model.multivalue_field == property.field.to_sym
+              if value.nil?
+                actions << [:delete, field, resource.attribute_get(property.name).to_s]
+              else
+                actions << [:add, field, value.to_s]
+              end
+            elsif value.nil?
+              actions << [:delete, field, []]
+            elsif resource.original_attributes[property].nil?
+              actions << [:add, field, value.to_s]
+            else
+              actions << [:replace, field, value.to_s]
+            end
+          end
+        end
+#puts "actions"
+#p actions
+#puts
+        ldap.update_object(resource.model.dn_prefix(resource),
+                           resource.model.treebase,
+                           actions)
+      end
+
+      # @see AbstractAdapter#delete
+      def delete(collection)
+        collection.each do |resource|
+          if resource.model.multivalue_field
+            multivalue_prop = resource.send(:properties).detect do |prop|
+              prop.field.to_sym == resource.model.multivalue_field
+            end
+            update_resource(resource,
+                            { multivalue_prop => nil })
+          else
+            ldap.delete_object(resource.model.dn_prefix(resource),
+                               resource.model.treebase)
+          end
+        end
+      end
+
+      # @see AbstractAdapter#read
+      def read(query)
+        result = []
+        #get data values out of the query
+        resources = read_resources(query)
+        resources.each do |resource|
+          map = {}
+          query.fields.each_with_index do |property, idx|
+            map[property.field] = property.typecast(resource[idx])
+          end
+          result << map
+        end
+
+#puts "read_many"
+#p result
+        result = result.uniq if query.unique?
+        result = query.match_records(result) if query.model.multivalue_field
+        result = query.sort_records_case_insensitive(result)
+        result = query.limit_records(result)
+        result
+      end
+
+      def read_resources(query)
+        query_order = query.order.first.target.field if query.order
+        #Use empty string as default for order in query
+        order_by = query_order || ''
+
+        field_names = query.fields.collect {|f| f.field }
+        result = ldap.read_objects(query.model.treebase,
+                                   query.model.key.collect { |k| k.field },
+                                   to_ldap_conditions(query),
+                                   field_names, order_by)
+        if query.model.multivalue_field
+          props_result = []
+          result.each do |props|
+            # run over all values of the multivalue field
+            (props[query.model.multivalue_field] || []).each do |value|
+              values =  query.fields.collect do |f|
+                if query.model.multivalue_field == f.field.to_sym
+                  value
+                else
+                  prop = props[f.field.to_sym].first
+                  f.primitive == Integer ? prop.to_i : prop.join
+                end
+              end
+              props_result << values
+            end
+          end
+          props_result
+        else # no multivalue field
+          result.collect do |props|
+            query.fields.collect do |f|
+              prop = props[f.field.to_sym]
+              if f.class == Ldap::LdapArray
+                prop if prop
+              elsif prop
+                f.primitive == Integer ? prop.first.to_i : prop.join
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end