admapper 0.0.3

data/LICENSE

@@ -0,0 +1,23 @@
+LICENSE
+ 
+The MIT License
+ 
+Copyright (c) 2010 Brian P. Hogan
+ 
+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.rdoc

@@ -0,0 +1,183 @@
+==ADMapper
+Library to connect to ActiveDirectory and map your users to ActiveDirectory users.
+
+You supply your own classes and mix the User or Group module into your classes.
+
+== Why
+Because http://github.com/filefrog/activedirectory didn't work well for me and I wanted
+flexibility to use my own classes, whether those are in Sinatra or
+using full-blown ActiveRecord classes in a Rails app.
+
+== Installation
+
+It's a gem, so you can
+
+  gem install admapper
+
+Or you can clone the repo and build it yourself with
+
+  gem build admapper.gemspec
+
+== Usage
+Basic usage is simple. Include the gem
+
+  require 'rubygems'
+  require 'admapper'
+  
+Then add the mixin to your class of choice
+
+  class User
+    attr_accessor: username
+    include ADMapper::Resource
+  end
+  
+Finally, configure the connection:
+
+  ADMapper::Configuration.connection_info = {:username => "homer",
+                                             :password=>"foo",
+                                             :host => "your_ad_host",
+                                             :port=>"636",
+                                             :ssl => true,
+                                             :domain => "example.com"}
+                                             
+The connection_info method takes a hash, so you can use a YML file if you'd like:
+
+    CONFIG_OPTS = YAML::load(File.open(File.expand_path(File.dirname(__FILE__) + "/admapper.yml"))).symbolize_keys
+    ADMapper::Configuration.connection_info  
+                                                                         
+== Working with Users
+
+=== Finding someone by username
+
+  u = User.find_in_ad_by_username("homer")
+  
+This creates a new instance of your User class. If you're using ActiveRecord, you can save this.
+
+=== Mapping users
+
+We use the "username" column to find stuff in ActiveDirectory by default. But you may not have a username column - you might call it "login". You may also want to easily grab other info from ActiveDirectory and map it to your own objects. In your model, add this method:
+
+Simply map your model (keys of the hash) to ActiveDirectory (values of the hash)
+
+  def ad_map
+    {
+      :username => :samaccountname,
+      :full_name => :displayname
+    }
+  end
+
+When you call the find_in_ad_by_username method, this method gets called.
+You can also access the actual Net::LDAP::Entry object by calling 
+
+  user = User.find_in_ad_by_username("homer")
+  user.ad_user
+  user.ad_user.samaccountname
+  user.ad_user.givenname
+  
+=== Working with an existing user
+So maybe you have a user already.
+
+   u = User.find(1)
+
+And you want his AD information? Fetch it. It'll default to looking up the user in ActiveDirectory by the <tt>username</tt> attribute.
+
+   u.find_in_ad
+  
+This will fill in the attributes you specified in your ad_map method.
+
+You can use a different field. If you store the username as "login", do this:
+
+   u.find_in_ad(:key => "login")
+   
+  
+=== Authenticating a user
+
+Don't do this. Taking someone's password and passing it on to Active Directory is just stupid. Use CAS, Shibboleth, or something else that prevents your app from ever seeing a user's password. If you insist on doing this, use SSL, filter the password out of your logs, and pray. This will let you do what you want
+
+   User.authenticate_with_active_directory("homer", "1234") 
+   
+It'll return true or false. It won't return a user. I assume you'll be wrapping this call in something else that will fetch the user object from your local DB. 
+
+== Groups
+
+Working on group support. Got a few things working:
+
+=== Getting groups
+
+Create your own class
+
+    class Group
+      attr_accessor :name
+      include ADMapper::Group
+    end
+
+Then look for a group
+
+   g = Group.find_in_ad_by_name("Marketing")
+   
+You can also look for groups
+
+   groups = Group.find_all_in_ad_by_name("HR.*")
+   
+=== Users and their groups
+
+Need to find all groups for a user?
+
+    class Group
+      attr_accessor :name
+      include ADMapper::Group
+    end
+
+    class User
+      attr_accessor :name, :username
+  
+      include ADMapper::User
+      set_group_class Group
+    end
+    
+Then get a user
+
+   u = User.find(1)
+   u.find_in_ad
+   groups = u.groups
+
+== Testing
+
+I'm not giving you my credentials, so you'll need to supply your own. Create the file 
+
+   test/admapper.yml
+   
+and put this inside:
+
+  username: "username"
+  password: "password"
+  domain: "example.com"
+  host: "domain.controller.example.com"
+  ssl: true
+  port: 636
+
+Then open test_helper and change the GROUP constant to a group that your username is a member of.
+
+Given good credentials, the tests should pass. 
+
+== Patches
+  * Fork it
+  * Write a test
+  * Make a fix
+  * send a patch or a pull request.
+  * Don't touch the changelog. 
+  * If it doesn't have a test, I'm not looking at it.
+  
+If this doesn't do what you want it to do, fork this and write your own library. I'm sharing this as a starting point and this is the bare minimum I need to get my AD tasks accomplished.
+
+== Changelog
+0.0.3 (2010-11-08)
+ * Added group lookup by name
+ * Added ability to get groups for a user
+0.0.2 (2010-03-31)
+ * refactoring to a central configuration option
+ * removed ad_connect! class method from resource module. Use a single global connection
+0.0.1 (2010-03-30)
+ * Initial mixin and basic support for finding stuff via AD
+ * Mapping objects
+ * Tests

data/Rakefile

@@ -0,0 +1,34 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+ 
+$LOAD_PATH << File.join(File.dirname(__FILE__), 'lib')
+require 'ADMapper'
+
+desc "Run the tests"
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+Rake::TestTask.new(:t) do |t|
+  t.libs << 'test'
+  t.pattern = ENV["TEST"]
+  t.verbose = true
+end
+
+desc 'Start an IRB session with all necessary files required.'
+task :shell do |t|
+  chdir File.dirname(__FILE__)
+  exec 'irb -I lib/ -I lib/ADMapper -r rubygems -r net-ldap -r tempfile -r init'
+end
+
+desc 'Generate documentation for ADMapper'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = 'ADMapper'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), "lib", "admapper")

data/lib/admapper.rb

@@ -0,0 +1,8 @@
+# ADMapper is a simple wrapper for ActiveRecord user lookup and authentication.
+require 'yaml'
+require 'net/ldap'
+require 'admapper/extensions'
+require 'admapper/configuration'
+require 'admapper/connection'
+require 'admapper/user'
+require 'admapper/group'

data/lib/admapper/configuration.rb

@@ -0,0 +1,13 @@
+module ADMapper
+  # Holds configuration options.
+  class Configuration
+
+    @connection_info = nil
+    class << self; attr_accessor :connection_info; end
+
+  end
+  
+  # Configuration exception
+  class ConfigurationMissingError < StandardError
+  end
+end

data/lib/admapper/connection.rb

@@ -0,0 +1,69 @@
+module ADMapper
+  class Connection
+      @@ad_connection = nil
+      @@ad_treebase = nil
+      @@ad_user_filter = nil
+      
+      def self.treebase
+        @@ad_treebase
+      end
+      
+      # class method to return the current connection
+      def self.current_connection
+        self.ad_connect_if_not_connected
+        @@ad_connection
+      end
+      
+      def self.current_connection=(conn)
+        @@ad_connection = conn
+      end
+      
+     # config_options = {:username => "homer",
+      #                   :password => "1234",
+      #                   :domain => "springfieldnuclear.com",
+      #                   :host => "ad.springfieldnuclear.com",
+      #                   :ssl => true,
+      #                   :port => 636}
+      #
+      # if ad_connect!(config_options)
+      #    ....
+      # else
+      #   ...
+      # end
+      def self.ad_connect!(config = nil)
+       config ||= ADMapper::Configuration.connection_info
+
+       raise ADMapper::ConfigurationMissingError if config.nil?
+       username = config[:username]
+       password = config[:password]
+       domain = config[:domain]
+       host = config[:host]
+       port = config[:port]
+       dc1 = domain.split(".").first
+       dc2 = domain.split(".").last
+       ssl = config[:ssl] ? true : false
+       self.current_connection = initialize_ldap_con(username + "@#{domain}", password, host, port, ssl) 
+       @@ad_treebase = "DC=#{dc1},DC=#{dc2}" 
+       @@ad_user_filter = Net::LDAP::Filter.eq( "sAMAccountName", username ) 
+       self.current_connection.bind
+      end
+       
+      # initializes the connection to the ldap server. Does not bind.
+      def self.initialize_ldap_con(user_name, password, host, port, ssl)
+         ldap = Net::LDAP.new
+         ldap.host = host
+         ldap.port = port #required for SSL connections, 389 is the default plain text port
+         if ssl 
+           ldap.encryption :simple_tls #also required to tell Net:LDAP that we want SSL
+         end
+         ldap.auth "#{user_name}","#{password}"
+         ldap #explicitly return the ldap connection object
+      end
+     
+       # connects if not connected already
+       def self.ad_connect_if_not_connected
+         self.ad_connect! if @@ad_connection.nil?
+       end
+    
+  end
+end

data/lib/admapper/extensions.rb

@@ -0,0 +1,8 @@
+class Hash
+  def symbolize_keys
+    inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
+    end
+  end                                                  
+end

data/lib/admapper/group.rb

@@ -0,0 +1,90 @@
+module ADMapper
+  
+  module Group
+    
+    def self.included(model)
+      model.class_eval do
+        extend  ADMapper::Group::ClassMethods
+        include ADMapper::Group::InstanceMethods
+        attr_accessor :ad_group
+      end
+    
+    end
+    
+    module InstanceMethods
+            
+      # maps the ad_user's attributes to your class' attributes
+      #. Implement the ad_map method in your own class to control how fields map.
+      def map_group_from_ad(ad_group)
+         self.ad_map.each do |group_object_field, ad_object_field|           
+           self.send("#{group_object_field}=", ad_group.send(ad_object_field).to_s)
+        end
+        self.ad_group = ad_group
+      end     
+    
+      # Default mapping of user object to active directory.
+      # You will most likely want to implement this in your own class
+      # instead of using this very basic default.
+      # Simply map your model (keys of the hash) to ActiveDirectory (values of the hash)
+      #
+      #   def ad_map
+      #     {
+      #       :username => :samaccountname,
+      #       :full_name => :displayname
+      #     }
+      #   end
+      def ad_map
+        {:name => :cn}
+      end
+    end
+    
+    module ClassMethods
+      
+      def find_in_ad_by_name(groupname)
+        attrs = [ "cn", "ou" , "objectClass"]
+        filter = Net::LDAP::Filter.eq( "objectClass", "group" )
+        name_filter = Net::LDAP::Filter.eq( "cn", groupname )
+        ad_connection = ADMapper::Connection.current_connection
+        ad_group = nil
+        ad_connection.search( :base => ADMapper::Connection.treebase,
+                             :attributes => attrs, 
+                             :filter => filter & name_filter ) do |entry|
+                             if entry
+                                ad_group = self.new
+                                ad_group.map_group_from_ad(entry)
+                                break
+                             end                
+        end
+        ad_group
+        
+      end
+      def find_all_in_ad_by_name(groupname)
+      
+        attrs = [ "cn", "ou" , "objectClass"]
+        filter = Net::LDAP::Filter.eq( "objectClass", "group" )
+        name_filter = Net::LDAP::Filter.eq( "cn", groupname )
+        ad_connection = ADMapper::Connection.current_connection
+        ad_groups = []
+        
+        ad_connection.search( :base => ADMapper::Connection.treebase,
+                             :attributes => attrs, 
+                             :filter => filter & name_filter ) do |entry|
+                             ad_group = entry
+                             if ad_group
+                                group = self.new
+                                group.map_group_from_ad(ad_group)
+                                ad_groups << group
+                             end
+                             
+                               
+        end
+         
+        ad_groups
+        
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/admapper/user.rb

@@ -0,0 +1,165 @@
+module ADMapper
+  
+  module User
+    
+    def self.included(model)
+      model.class_eval do
+        extend  ADMapper::User::ClassMethods
+        include ADMapper::User::InstanceMethods
+        attr_accessor :ad_user
+      end
+    
+    end
+    
+    module InstanceMethods
+      
+      # Returns the groups for a user.
+      def groups
+        groups = []
+        
+         search_filter = Net::LDAP::Filter.eq("sAMAccountName", self.ad_user.samaccountname.first)
+            ad_connection = ADMapper::Connection.current_connection
+            ad_connection.search(:base => ADMapper::Connection.treebase,
+                                   :filter => search_filter) do |entry|
+
+                                     entry.each do |attribute, values|      
+                                     if attribute.to_s.match(/memberof/)
+                                          values.each do |value|
+                                            a = value.split(',')
+                                            md = a[0].match(/CN=(.+)/)
+
+                                            groups << md[1]
+                                          end
+                                        end
+                                     end
+         end
+         
+         groups.collect do |g|
+           self.class.group_class.find_in_ad_by_name(g)
+         end.compact
+         
+         
+      end
+      
+  
+      
+      def member_of?(group)
+        group_member = false
+        
+        search_filter = Net::LDAP::Filter.eq("sAMAccountName", self.ad_user.samaccountname.first)
+           ad_connection = ADMapper::Connection.current_connection
+           ad_connection.search(:base => ADMapper::Connection.treebase,
+                                  :filter => search_filter) do |entry|
+                                    
+                                    entry.each do |attribute, values|      
+                                    if attribute.to_s.match(/memberof/)
+                                         values.each do |value|
+                                           a = value.split(',')
+                                           md = a[0].match(/CN=(.+)/)
+
+                                           # user is a member of the right group
+                                           if md[1] == group
+                                             group_member = true
+                                           end
+                                         end
+                                       end
+                                    end
+        end
+        group_member
+        
+      end
+      
+      
+      # finds a user in active directory using the internal key.
+      # Defaults to username
+      def find_in_ad(options = {:key => :username})
+        username = send(options[:key])
+        ad_user = self.class.ad_query_by_username(username)
+        return nil if ad_user.nil?
+        self.map_user_from_ad(ad_user)
+        true
+      end
+      
+      # maps the ad_user's attributes to your class' attributes
+      #. Implement the ad_map method in your own class to control how fields map.
+      def map_user_from_ad(ad_user)
+         self.ad_map.each do |user_object_field, ad_object_field|           
+           self.send("#{user_object_field}=", ad_user.send(ad_object_field).to_s)
+        end
+        self.ad_user = ad_user
+      end     
+    
+      # Default mapping of user object to active directory.
+      # You will most likely want to implement this in your own class
+      # instead of using this very basic default.
+      # Simply map your model (keys of the hash) to ActiveDirectory (values of the hash)
+      #
+      #   def ad_map
+      #     {
+      #       :username => :samaccountname,
+      #       :full_name => :displayname
+      #     }
+      #   end
+      def ad_map
+        {:username => :samaccountname}
+      end
+
+    end
+    
+    module ClassMethods
+       attr_accessor :group_class
+       
+       def set_group_class(group_class)
+         self.group_class = group_class
+       end
+       
+       # Authenticating users:
+       # Don't do this. Taking someone's password and passing it 
+       # on to Active Directory is just stupid. Use CAS, Shibboleth, or 
+       # something else that prevents your app from ever seeing a user's password. 
+       # If you insist on doing this, use SSL, filter the password out of your logs,
+       # and pray. This will let you do what you want
+       # 
+       #    User.authenticate_with_active_directory("homer", "1234") 
+       # 
+       # It'll return true or false. It won't return a user. I assume you'll be wrapping this call in something else that will fetch the user object from your local DB.
+       def authenticate_with_active_directory(username, password)
+         auth_ldap = ADMapper::Connection.current_connection.dup.bind_as(
+          :filter => Net::LDAP::Filter.eq( "sAMAccountName", username ),
+          :base => ADMapper::Connection.treebase,
+          :password => password
+         )
+       
+       end
+       
+       # Find a user in AD by the given username
+       # Calls #map_user_from_ad on the returned results
+       # so you can manage it yourself.
+       def find_in_ad_by_username(username)
+         ad_user = ad_query_by_username(username)
+         return nil if ad_user.nil?
+         
+         user = self.new
+         user.map_user_from_ad(ad_user)
+         user
+       end
+  
+       # find a user in AD by the given userame.
+       # Connects if not connected
+       # Returns an AD object
+       def ad_query_by_username(username)
+       
+         user = nil
+         search_filter = Net::LDAP::Filter.eq( "sAMAccountName", username ) 
+            ad_connection = ADMapper::Connection.current_connection
+            ad_connection.search(:base => ADMapper::Connection.treebase,
+                                   :filter => search_filter, 
+                                   :attributes => ['dn','sAMAccountName','displayname','SN','givenName']) do |ad_user|      
+             user = ad_user
+         end
+         user
+       end
+     
+    end
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification 
+name: admapper
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 3
+  version: 0.0.3
+platform: ruby
+authors: 
+- Brian Hogan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-08 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: net-ldap
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 0
+        - 1
+        - 1
+        version: 0.1.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 43
+        segments: 
+        - 0
+        - 9
+        - 8
+        version: 0.9.8
+  type: :development
+  version_requirements: *id002
+description: 
+email: brianhogan@napcs.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- LICENSE
+- Rakefile
+- init.rb
+- lib/admapper.rb
+- lib/admapper/extensions.rb
+- lib/admapper/connection.rb
+- lib/admapper/group.rb
+- lib/admapper/configuration.rb
+- lib/admapper/user.rb
+has_rdoc: true
+homepage: http://www.napcs.com/projects/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: 
+- net-ldap
+rubyforge_project: admapper
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Friendly mixin for working with Microsoft's ActiveDirectory
+test_files: []
+