chuckdbacon-activedirectory 1.0.4

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

@@ -0,0 +1,162 @@
+#-- 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 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

data/lib/active_directory/password.rb

@@ -0,0 +1,42 @@
+#-- 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 Password
+		#
+		# Encodes an unencrypted password into an encrypted password
+		# that the Active Directory server will understand.
+		#
+		def self.encode(password)
+			("\"#{password}\"".split(//).collect { |c| "#{c}\000" }).join
+		end
+
+		#
+		# Always returns nil, since you can't decrypt the User's encrypted
+		# password.
+		#
+		def self.decode(hashed)
+			nil
+		end
+	end
+end

data/lib/active_directory/rails/synchronizer.rb

@@ -0,0 +1,234 @@
+#-- 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
+
+# UserSynchronizer is a utility class that encapsulates dealings
+# with the Active Directory backend. It is primarily responsible for
+# updating Active Directory people in the local database from the
+# Active Directory store. In this fashion, name changes, email address
+# changes and such are all handled invisibly.
+#
+# UserSynchronizer is also responsible for disabling people who are no
+# longer in the Sales Tracker group, and creating people who are in the group,
+# but not in the local database. This gives us another administrative
+# convenience, since new hires will be added to the system with some
+# regularity, and terminations are eventually cleaned out.
+#
+# UserSynchronizer.sync_users_in_group will return a hash with the following keys:
+#   * :added - An array of ActiveDirectory::User objects that were added.
+#   * :disabled - An array of ActiveDirectory::User objects that were disabled.
+#   * :updated - An array of ActiveDirectory::User objects that were updated.
+#
+# The following method illustrates how this would be used to notify a site
+# administrator to changes brought about by synchronization:
+#
+#   def report(results)
+#     puts "#####################################################"
+#     puts "#  Active Directory People Synchronization Summary  #"
+#     puts "#####################################################"
+#     puts
+#
+#     puts "New People Added (#{results[:added].size})"
+#     puts "-----------------------------------------------------"
+#     results[:added].sort_by(&:name).each { |p| out.puts " + #{p.name}" }
+#     puts
+#
+#     puts "People Disabled (#{results[:disabled].size})"
+#     puts "-----------------------------------------------------"
+#     results[:disabled].sort_by(&:name).each { |p| out.puts " - #{p.name}" }
+#     puts
+#
+#     puts "Existing People Updated (#{results[:updated].size})"
+#     puts "-----------------------------------------------------"
+#     results[:updated].sort_by(&:name).each { |p| out.puts " u #{p.name}" }
+#     puts
+#   end
+#
+class ActiveDirectory::Rails::UserSynchronizer
+	@@default_group = nil
+	cattr_accessor :default_group
+
+	@@run_handler = nil
+	cattr_accessor :run_handler
+
+	@@attribute_map = {
+		:first_name => :givenName,
+		:last_name  => :sn,
+		:username   => :sAMAccountName,
+		:email      => :mail,
+	}
+	cattr_accessor :attribute_map
+
+	@@person_class = Person
+	cattr_accessor :person_class
+
+	class << self
+		# The primary interface to synchronization, run processes
+		# all of the Active Directory changes, additions and removals
+		# through sync_users_in_group, and then notifies administrators
+		# if it finds anyone new.
+		#
+		# This is the preferred way to run the UserSynchronizer.
+		#
+		def run
+			results = sync_users_in_group
+			@@run_handler.nil? results : @@run_handler.call(results)
+		end
+
+		# Compares the membership of the Active Directory group named
+		# `group_name' and AD-enabled accounts in the local database.
+		#
+		# This method is the workhorse of UserSynchronizer, handling
+		# the addition, removal and updates of AD people.
+		#
+		# It will return either false, or a hash with three keys, :added, :updated
+		# and :disabled, each of which contains an array of the Person
+		# objects that were (respectively) added, updated and disabled.
+		#
+		# If the given group_name does not resolve to a valid
+		# ActiveDirectory::Group object, sync_users_in_group will return
+		# false.
+		#
+		# The return value (for example) can be used by a notification process
+		# to construct a message detailing who was added, removed, etc.
+		#
+		def sync_users_in_group(group_name = nil)
+			group_name ||= @@default_group
+			return false unless group_name
+
+			ad_group = ActiveDirectory::Group.find_by_sAMAccountName(group_name)
+			return false unless ad_group
+
+			@people = person_class.in_active_directory.index_by(&:guid)
+
+			summary = {
+				:added    => [],
+				:disabled => [],
+				:updated  => []
+			}
+
+			# Find all member users (recursively looking at member groups)
+			# and synchronize! them with their Person counterparts.
+			#
+			ad_group.member_users(true).each do |ad_user|
+				person = @people[ad_user.objectGUID]
+				if person
+					synchronize!(person, ad_user)
+					@people.delete(ad_user.objectGUID)
+					summary[:updated] << person
+				else
+					person = create_from(ad_user)
+					summary[:added] << person
+				end
+			end
+
+			# Disable AD users we didn't find in AD.
+			# Because we are not clearing the GUID in the disable! call,
+			# we may process someone more than once.
+			#
+			@people.each do |guid, person|
+				disable!(person)
+				summary[:disabled] << person
+			end
+
+			summary
+		end
+
+		# Synchronize a peron with AD store by looking up their username.
+		#
+		# This is used for the initial bootstrap, because we don't know
+		# a person's objectGUID offhand. It will probably never be seen
+		# in any production code.
+		#
+		def update_using_username(person)
+			ad_user = ActiveDirectory::User.find_by_sAMAccountName(person.username)
+			synchronize!(person, ad_user)
+		end
+
+		# Sync a person with AD store by looking up their GUID
+		# (This is the most reliable option, as a username can change,
+		# but the GUID will stay the same).
+		#
+		# This method is not used in production, but can be useful in
+		# a console'd environment to selectively update just a few people.
+		#
+		def update_using_guid(person)
+			ad_user = ActiveDirectory::User.find_by_objectGUID(person.guid)
+			synchronize!(person, ad_user)
+		end
+
+		# Synchronize the attributes of the given Person with those
+		# found in the (hopefully associated) Active Directory user
+		#
+		# Because we are managing a mixed database of both AD and non-AD
+		# people, we have to be careful. We cannot assume that a nil
+		# ad_user argument means the person should be disabled.
+		#
+		def synchronize!(person, ad_user)
+			person.update_attributes(attributes_from(ad_user)) if ad_user
+		end
+
+		# Disable a person, and clear out their authentication information.
+		# This is primarily used when we find terminated employees who are
+		# still in the local database as AD users, but no longer have an
+		# AD account.
+		#
+		# There is a special case for people who have not logged sales.
+		# They are removed outright, to keep terminated trainees from
+		# cluttering up the Person table.
+		#
+		# Note that we do not clear their GUID. Active Directory is not
+		# supposed to re-use its GUIDs, so we should be safe there.
+		#
+		def disable!(person)
+			if person.respond_to? :removable? and !person.removable?
+				person.update_attribute(:username, '')
+				person.update_attribute(:email,    '')
+			else
+				person.destroy
+			end
+		end
+
+		# Creates a new Person object based on the attributes of
+		# an Active Directory user. sync_users_in_group uses this when
+		# it finds new people.
+		#
+		# All Person objects will be created as generic Persons,
+		# not CSRs or TeamLeaders. Administrators are responsible
+		# for promoting and associating new people in the backend.
+		#
+		def create_from(ad_user)
+			person = person_class.create(attributes_from(ad_user))
+		end
+
+		# Translates the attributes of ad_user into a hash that can
+		# be used to create or update a Person object.
+		#
+		def attributes_from(ad_user)
+			h = {}
+			@@attribute_map.each { |local, remote| h[local] = ad_user.send(remote) }
+			h[:guid] = ad_user.objectGUID
+			h[:password => '']
+			h
+		end
+	end
+end