activedirectory 0.9.3 → 1.0.0

data/lib/active_directory/computer.rb

@@ -0,0 +1,38 @@
+#-- license
+#
+# This file is part of the Ruby Active Directory Project
+# on the web at http://rubyforge.org/projects/activedirectory
+#
+#  Copyright (c) 2008, James Hunt <filefrog@gmail.com>
+#    based on original code by Justin Mecham
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#++ license
+
+module ActiveDirectory
+	class Computer < Base
+		def self.filter # :nodoc:
+			Net::LDAP::Filter.eq(:objectClass,'computer')
+		end
+
+		def self.required_attributes # :nodoc:
+			{ :objectClass => [ 'top', 'person', 'organizationalPerson', 'user', 'computer' ] }
+		end
+
+		def hostname
+			dNSHostName || name
+		end
+	end
+end

data/lib/active_directory/container.rb

@@ -0,0 +1,117 @@
+#-- license
+#
+# This file is part of the Ruby Active Directory Project
+# on the web at http://rubyforge.org/projects/activedirectory
+#
+#  Copyright (c) 2008, James Hunt <filefrog@gmail.com>
+#    based on original code by Justin Mecham
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#++ license
+
+module ActiveDirectory
+	#
+	# The ActiveDirectory::Container class represents a more malleable way
+	# of dealing with LDAP Distinguished Names (dn), like
+	# "cn=UserName,ou=Users,dc=example,dc=org".
+	#
+	# The following two representations of the above dn are identical:
+	#
+	#   dn = "cn=UserName,ou=Users,dc=example,dc=org"
+	#   dn = ActiveDirectory::Container.dc('org').dc('example').ou('Users').cn('UserName').to_s
+	#
+	class Container
+		attr_reader :type
+		attr_reader :name
+		attr_reader :parent
+
+		def initialize(type, name, node = nil) #:nodoc:
+			@type = type
+			@name = name
+			@node = node
+		end
+
+		#
+		# Creates a starting OU (Organizational Unit) dn part.
+		#
+		#   # ou_part = "ou=OrganizationalUnit"
+		#   ou_part = ActiveDirectory::Container.ou('OrganizationalUnit').to_s
+		#
+		def self.ou(name)
+			new(:ou, name, nil)
+		end
+
+		#
+		# Creates a starting DC (Domain Component) dn part.
+		#
+		#   # dc_part = "dc=net"
+		#   dc_part = ActiveDirectory::Container.dc('net').to_s
+		#
+		def self.dc(name)
+			new(:dc, name, nil)
+		end
+
+		#
+		# Creates a starting CN (Canonical Name) dn part.
+		#
+		#   # cn_part = "cn=CanonicalName"
+		#   cn_part = ActiveDirectory::Container.cn('CanonicalName').to_s
+		#
+		def self.cn(name)
+			new(:cn, name, nil)
+		end
+
+		#
+		# Appends an OU (Organizational Unit) dn part to another Container.
+		#
+		#   # ou = "ou=InfoTech,dc=net"
+		#   ou = ActiveDirectory::Container.dc("net").ou("InfoTech").to_s
+		#
+		def ou(name)
+			self.class.new(:ou, name, self)
+		end
+
+		#
+		# Appends a DC (Domain Component) dn part to another Container.
+		#
+		#   # base = "dc=example,dc=net"
+		#   base = ActiveDirectory::Container.dc("net").dc("example").to_s
+		#
+		def dc(name)
+			self.class.new(:dc, name, self)
+		end
+
+		#
+		# Appends a CN (Canonical Name) dn part to another Container.
+		#
+		#    # user = "cn=UID,ou=Users"
+		#    user = ActiveDirectory::Container.ou("Users").cn("UID")
+		#
+		def cn(name)
+			self.class.new(:cn, name, self)
+		end
+
+		#
+		# Converts the Container object to its String representation.
+		#
+		def to_s
+			@node ? "#{@type}=#{name},#{@node.to_s}" : "#{@type}=#{name}"
+		end
+
+		def ==(other) #:nodoc:
+			to_s.downcase == other.to_s.downcase
+		end
+	end
+end

data/lib/active_directory/group.rb

@@ -1,109 +1,162 @@
-#--
-# Active Directory Module for Ruby
+#-- license
 #
-# Copyright (c) 2005-2006 Justin Mecham
+# This file is part of the Ruby Active Directory Project
+# on the web at http://rubyforge.org/projects/activedirectory
 #
-# 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:
+#  Copyright (c) 2008, James Hunt <filefrog@gmail.com>
+#    based on original code by Justin Mecham
 #
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
 #
-# 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.
-#++
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#++ license
 
 module ActiveDirectory
-
-  #
-  # Represents a Group object within an Active Directory instance.
-  #
-  class Group < Base
-
-    # Distinguished Name (DN)
-    attr_accessor :dn
-
-    # Description
-    attr_accessor :description
-
-    # Common Name (CN)
-    attr_accessor :name
-
-    # Users who are members of this Group
-    attr          :members
-
-    #
-    # Attributes that we wish to pull from Active Directory for any Group that
-    # can be located within the directory.
-    #
-    ATTRIBUTES = ["distinguishedName",    # DN of Group
-                  "name",                 # Group Name
-                  "member",               # DN References to Members
-                  "description"] #:nodoc: # Description
-
-    #
-    # Attempts to load a Group by a Distinguished Name (DN).
-    #
-    def initialize(identifier)
-
-      identifier = identifier.delete("\\")
-
-      load_by_dn(identifier)
-
-    end
-
-    #
-    # Proxy for loading and returning the members of this group.
-    #
-    def members #:nodoc:
-      members = Array.new
-      unless @members.nil?
-        for user_dn in @members
-          members << User.new(user_dn)
-        end
-      end
-      members
-    end
-
-    private
-
-    #
-    # Attempt to load a Group by its Distinguished Name (DN).
-    #
-    def load_by_dn(dn)
-
-      if dn.nil? or dn.length == 0
-        raise ArgumentError, "No distinguished name provided."
-      end
-
-      # De-escape the DN
-      dn = dn.gsub(/"/, "\\\"")
-
-      entries = Base.search(dn, LDAP::LDAP_SCOPE_BASE,
-                  "(&(objectClass=group))", ATTRIBUTES)
-
-      raise UnknownGroupError if (entries.nil? or entries.length != 1)
-
-      parse_ldap_entry(entries[0])
-
-    end
-
-    def parse_ldap_entry(entry)
-      @dn          = entry['distinguishedName'][0].delete("\\")
-      @name        = entry['name'][0].delete("\\")
-      @description = entry['description'][0] unless entry['description'].nil?
-      @members     = entry['member']
-    end
-    
-  end
-
-end
+	class Group < Base
+		include Member
+
+		def self.filter # :nodoc:
+			Net::LDAP::Filter.eq(:objectClass,'group')
+		end
+
+		def self.required_attributes # :nodoc:
+			{ :objectClass => [ 'top', 'group' ] }
+		end
+
+		def reload # :nodoc:
+			@member_users_non_r  = nil
+			@member_users_r      = nil
+			@member_groups_non_r = nil
+			@member_groups_r     = nil
+			@groups              = nil
+			super
+		end
+
+		#
+		# Returns true if the passed User or Group object belongs to
+		# this group. For performance reasons, the check is handled
+		# by the User or Group object passed.
+		#
+		def has_member?(user)
+			user.member_of?(self)
+		end
+
+		#
+		# Add the passed User or Group object to this Group. Returns true if
+		# the User or Group is already a member of the group, or if the operation
+		# to add them succeeds.
+		#
+		def add(new_member)
+			return false unless new_member.is_a?(User) || new_member.is_a?(Group)
+			if @@ldap.modify(:dn => distinguishedName, :operations => [
+				[ :add, :member, new_member.distinguishedName ]
+			])
+				return true
+			else
+				return has_member?(new_member)
+			end
+		end
+
+		#
+		# Remove a User or Group from this Group. Returns true if the User or
+		# Group does not belong to this Group, or if the oepration to remove them
+		# succeeds.
+		#
+		def remove(member)
+			return false unless member.is_a?(User) || member.is_a?(Group)
+			if @@ldap.modify(:dn => distinguishedName, :operations => [
+				[ :delete, :member, member.distinguishedName ]
+			])
+				return true
+			else
+				return !has_member?(member)
+			end
+		end
+
+		def has_members?
+			begin
+				return (@entry.member.nil? || @entry.member.empty?) ? false : true
+			rescue NoMethodError
+				return false
+			end
+		end
+
+		#
+		# Returns an array of all User objects that belong to this group.
+		#
+		# If the recursive argument is passed as false, then only Users who
+		# belong explicitly to this Group are returned.
+		#
+		# If the recursive argument is passed as true, then all Users who
+		# belong to this Group, or any of its subgroups, are returned.
+		# 
+		def member_users(recursive = false)
+			return [] unless has_members?
+			if recursive
+				if @member_users_r.nil?
+					@member_users_r = []
+					@entry.member.each do |member_dn|
+						subuser = User.find_by_distinguishedName(member_dn)
+						if subuser
+							@member_users_r << subuser
+						else
+							subgroup = Group.find_by_distinguishedName(member_dn)
+							if subgroup
+								@member_users_r = @member_users_r.concat(subgroup.member_users(true))
+							end
+						end
+					end
+				end
+				return @member_users_r
+			else
+				@member_users_non_r ||= @entry.member.collect { |dn| User.find_by_distinguishedName(dn) }.delete_if { |u| u.nil? }
+			end
+		end
+
+		#
+		# Returns an array of all Group objects that belong to this group.
+		#
+		# If the recursive argument is passed as false, then only Groups that
+		# belong explicitly to this Group are returned.
+		#
+		# If the recursive argument is passed as true, then all Groups that
+		# belong to this Group, or any of its subgroups, are returned.
+		# 
+		def member_groups(recursive = false)
+			return [] unless has_members?
+			if recursive
+				if @member_groups_r.nil?
+					@member_groups_r = []
+					@entry.member.each do |member_dn|
+						subgroup = Group.find_by_distinguishedName(member_dn)
+						if subgroup
+							@member_groups_r << subgroup
+							@member_groups_r = @member_groups_r.concat(subgroup.member_groups(true))
+						end
+					end
+				end
+				return @member_groups_r
+			else
+				@member_groups_non_r ||= @entry.member.collect { |dn| Group.find_by_distinguishedName(dn) }.delete_if { |g| g.nil? }
+			end
+		end
+
+		#
+		# Returns an array of Group objects that this Group belongs to.
+		#
+		def groups
+			return [] if memberOf.nil?
+			@groups ||= memberOf.collect { |group_dn| Group.find_by_distinguishedName(group_dn) }
+		end
+	end
+end

data/lib/active_directory/member.rb

@@ -0,0 +1,56 @@
+#-- license
+#
+# This file is part of the Ruby Active Directory Project
+# on the web at http://rubyforge.org/projects/activedirectory
+#
+#  Copyright (c) 2008, James Hunt <filefrog@gmail.com>
+#    based on original code by Justin Mecham
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#++ license
+
+module ActiveDirectory
+	module Member
+		#
+		# Returns true if this member (User or Group) is a member of
+		# the passed Group object.
+		#
+		def member_of?(usergroup)
+			group_dns = memberOf
+			return false if group_dns.nil? || group_dns.empty?
+			#group_dns = [group_dns] unless group_dns.is_a?(Array)
+			group_dns.include?(usergroup.dn)
+		end
+
+		#
+		# Add the member to the passed Group object. Returns true if this object
+		# is already a member of the Group, or if the operation to add it succeeded.
+		#
+		def join(group)
+			return false unless group.is_a?(Group)
+			group.add(self)
+		end
+
+		#
+		# Remove the member from the passed Group object. Returns true if this
+		# object is not a member of the Group, or if the operation to remove it
+		# succeeded.
+		#
+		def unjoin(group)
+			return false unless group.is_a?(Group)
+			group.remove(self)
+		end
+	end
+end