judy-activedirectory 1.1.0

data/lib/active_directory/rails/synchronizer.rb

@@ -0,0 +1,211 @@
+# 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,118 @@
+module ActiveDirectory
+			module Rails
+				module 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 # module User
+	end # module Rails
+end #module ActiveDirectory

data/lib/active_directory/timestamp.rb

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

data/lib/active_directory/user.rb

@@ -0,0 +1,142 @@
+module ActiveDirectory
+	class User < Base
+		include Member
+
+		UAC_ACCOUNT_DISABLED = 0x0002
+		UAC_NORMAL_ACCOUNT   = 0x0200 # 512
+
+		def self.filter # :nodoc:
+			Net::LDAP::Filter.eq(:objectClass,'user') & ~Net::LDAP::Filter.eq(:objectClass,'computer')
+		end
+
+		def self.required_attributes #:nodoc:
+			{ :objectClass => ['top', 'organizationalPerson', 'person', 'user'] }
+		end
+
+		#
+		# Try to authenticate the current User against Active Directory
+		# using the supplied password. Returns false upon failure.
+		#
+		# Authenticate can fail for a variety of reasons, primarily:
+		#
+		# * The password is wrong
+		# * The account is locked
+		# * The account is disabled
+		#
+		# User#locked? and User#disabled? can be used to identify the
+		# latter two cases, and if the account is enabled and unlocked,
+		# Athe password is probably invalid.
+		#
+		def authenticate(password)
+			return false if password.to_s.empty?
+
+			auth_ldap = @@ldap.dup.bind_as(
+				:filter => "(sAMAccountName=#{sAMAccountName})",
+				:password => password
+			)
+		end
+
+		#
+		# Return the User's manager (another User object), depending on
+		# what is stored in the manager attribute.
+		#
+		# Returns nil if the schema does not include the manager attribute
+		# or if no manager has been configured.
+		#
+		def manager
+			return nil if @entry.manager.nil?
+			User.find_by_distinguishedName(@entry.manager.to_s)
+		end
+
+		#
+		# Returns an array of Group objects that this User belongs to.
+		# Only the immediate parent groups are returned, so if the user
+		# Sally is in a group called Sales, and Sales is in a group
+		# called Marketting, this method would only return the Sales group.
+		#
+		def groups
+			@groups ||= memberOf.collect { |dn| Group.find_by_distinguishedName(dn) }
+		end
+
+		#
+		# Returns an array of User objects that have this
+		# User as their manager.
+		#
+		def direct_reports
+			return [] if @entry.directReports.nil?
+			@direct_reports ||= @entry.directReports.collect { |dn| User.find_by_distinguishedName(dn) }
+		end
+
+		#
+		# Returns true if this account has been locked out
+		# (usually because of too many invalid authentication attempts).
+		#
+		# Locked accounts can be unlocked with the User#unlock! method.
+		#
+		def locked?
+			!lockoutTime.nil? && lockoutTime.to_i != 0
+		end
+
+		#
+		# Returns true if this account has been disabled.
+		#
+		def disabled?
+			userAccountControl.to_i & UAC_ACCOUNT_DISABLED != 0
+		end
+
+		#
+		# Returns true if the user should be able to log in with a correct
+		# password (essentially, their account is not disabled or locked
+		# out).
+		#
+		def can_login?
+			!disabled? && !locked?
+		end
+
+    # Clear settings, make this account normal.
+    def enable!
+      if !disabled?
+        return false
+      end
+      uac = userAccountControl.to_i - UAC_ACCOUNT_DISABLED
+      self.userAccountControl = uac.to_s
+      self.save
+    end
+
+		#
+		# Change the password for this account.
+		#
+		# This operation requires that the bind user specified in
+		# Base.setup have heightened privileges. It also requires an
+		# SSL connection.
+		#
+		# If the force_change argument is passed as true, the password will
+		# be marked as 'expired', forcing the user to change it the next
+		# time they successfully log into the domain.
+		#
+		def change_password(new_password, force_change = false)
+			settings = @@settings.dup.merge({
+				:port => 636,
+				:encryption => { :method => :simple_tls }
+			})
+
+			ldap = Net::LDAP.new(settings)
+			ldap.modify(
+				:dn => distinguishedName,
+				:operations => [
+					[ :replace, :lockoutTime, [ '0' ] ],
+					[ :replace, :unicodePwd, [ Password.encode(new_password) ] ],
+					[ :replace, :userAccountControl, [ UAC_NORMAL_ACCOUNT.to_s ] ],
+					[ :replace, :pwdLastSet, [ (force_change ? '0' : '-1') ] ]
+				]
+			)
+		end
+
+		#
+		# Unlocks this account.
+		#
+		def unlock!
+			@@ldap.replace_attribute(distinguishedName, :lockoutTime, ['0'])
+		end
+	end
+end