activedirectory 0.9.3 → 1.0.0

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

data/lib/active_directory/rails/user.rb

@@ -0,0 +1,137 @@
+#-- 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::Rails::User
+	def self.included(klass)
+		klass.extend(ClassMethods)
+		klass.send(:include, InstanceMethods)
+	end
+	
+	module InstanceMethods
+		# Is this Person active? Active people have valid
+		# usernames. Inactive people have empty usernames.
+		#
+		def active?
+			username != ""
+		end
+
+		# Whether or not this Person has a corresponding Active Directory
+		# account that we can synchronize with, through the PeopleSynchronizer.
+		#
+		def in_active_directory?
+			!guid.blank?
+		end
+
+		# Whether or not this Person can be authenticated with the
+		# given password, against Active Directory.
+		#
+		# For Active Directory authentication, we attempt to bind to the
+		# configured AD server as the user, and supply the password for
+		# authentication.
+		#
+		# There are two special cases for authentication, related to the
+		# environment the app is currently running in:
+		#
+		# *Development*
+		#
+		# In development, the blank password ('') will always cause this method
+		# to return true, thereby allowing developers to test functionality
+		# for a variety of roles.
+		#
+		# *Training*
+		#
+		# In training, a special training password ('trainme') will always
+		# cause this method to return true, thereby allowing trainers to
+		# use other people accounts to illustrate certain restricted processes.
+		#
+		def authenticates?(password)
+			# Never allow inactive users.
+			return false unless active?
+	
+			# Allow blank password for any account in development.
+			return true if password == "" and ENV['RAILS_ENV'] == 'development'
+			return true if password == "trainme" and ENV['RAILS_ENV'] == 'training'
+
+			# Don't go against AD unless we really mean it.
+			return false unless ENV['RAILS_ENV'] == 'production'
+
+			# If they are not in AD, fail.
+			return false unless in_active_directory?
+	
+			ad_user = ActiveDirectory::User.find_by_sAMAccountName(self.username)
+			ad_user and ad_user.authenticate(password)
+		end
+
+		def active_directory_equivalent=(ad_user)
+			return unless ad_user
+			update_attributes(
+				:first_name  => ad_user.givenName,
+				:middle_name => ad_user.initials,
+				:last_name   => ad_user.sn,
+				:username    => ad_user.sAMAccountName,
+				:email       => ad_user.mail,
+				:guid        => ad_user.objectGUID
+			)
+		end
+	end
+
+	module ClassMethods
+		# Attempt to authenticate someone with a username and password.
+		# This method properly handles both local store users and AD
+		# users.
+		#
+		# If the username is valid, and the password matches the username,
+		# the Person object corresponding to the username is return.
+		# 
+		# Otherwise, nil is returned, to indicate an authentication failure.
+		#
+		def authenticate(username, password)
+			person = find_by_username(username)
+			return person if (person and person.authenticates?(password))
+			nil
+		end
+
+		# Retrieves all of the Person objects that have corresponding
+		# Active Directory accounts. This method does not contact
+		# the AD servers to retrieve the AD objects -- that is left up
+		# to the caller.
+		#
+		def in_active_directory
+			find(:all, :conditions => 'guid IS NOT NULL AND guid != ""')
+		end
+
+		# Retrieves all Person objects that are currently active,
+		# meaning they have not been disabled by PeopleSynchronizer.
+		#
+		def active
+			find(:all, :conditions => 'username != ""')
+		end
+
+		# Retrieves all Person objects that are currently inactive,
+		# meaning they have been disabled by PeopleSynchronizer.
+		#
+		def inactive
+			find(:all, :conditions => 'username = ""')
+		end
+	end
+end 

data/lib/active_directory/timestamp.rb

@@ -0,0 +1,46 @@
+#-- 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 Timestamp
+		AD_DIVISOR = 10_000_000     #:nodoc:
+		AD_OFFSET  = 11_644_473_600 #:nodoc:
+
+		#
+		# Encodes a local Time object (or the number of seconds since January
+		# 1, 1970) into a timestamp that the Active Directory server can
+		# understand (number of 100 nanosecond time units since January 1, 1600)
+		# 
+		def self.encode(local_time)
+			(local_time.to_i + AD_OFFSET) * AD_DIVISOR
+		end
+
+		#
+		# Decodes an Active Directory timestamp (the number of 100 nanosecond time
+		# units since January 1, 1600) into a Ruby Time object.
+		#
+		def self.decode(remote_time)
+			Time.at( (remote_time.to_i / AD_DIVISOR) - AD_OFFSET )
+		end
+	end
+end