adauth 1.0.0 → 1.0.1

data/.gitignore

@@ -3,3 +3,5 @@ pkg/*
 tmp/*
 *~
 spec/test_data.yml
+doc/*
+.yardoc/*

data/Gemfile.lock

@@ -1,13 +1,14 @@
 PATH
   remote: .
   specs:
-    adauth (0.0.1pre)
-      ruby-net-ldap
+    adauth (1.0.0)
+      net-ldap
 
 GEM
   remote: http://rubygems.org/
   specs:
     diff-lcs (1.1.2)
+    net-ldap (0.2.2)
     rspec (2.6.0)
       rspec-core (~> 2.6.0)
       rspec-expectations (~> 2.6.0)
@@ -16,7 +17,6 @@ GEM
     rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.6.0)
-    ruby-net-ldap (0.0.4)
 
 PLATFORMS
   ruby

data/Readme.rdoc

@@ -12,15 +12,11 @@ and run a bundle install
 
 == Usage
 
-Create an initializer in _config/initilaizers_ called adauth.rb and place this code in it:
+Adauth requires a config file which can be created by running the command
 
-    Adauth.configure do |c|
-        c.domain = "example.com" #The domain name used on your network e.g. example.com or example.local
-        c.server = "127.0.0.1" #The IP of any DC on your network
-        c.base = "dc=example, dc=com" #the base for your users.
-    end
+     rails g adauth:config
 
-c.port can also be used but defaults to 389 which is the default for AD/LDAP. For a full list of options see {Configuration}[...] on the wiki.
+This creates a config file for _example.com_ with all the values present along with helpful comments for getting Adauth up and running.
 
 Thats enough to very basically run Adauth, and if you prefer complete control over how your authentication is handled you can use this method:
 
@@ -28,7 +24,7 @@ Thats enough to very basically run Adauth, and if you prefer complete control ov
 
 Which has 2 possible return values nil if the users details are wrong or an instance of Adauth::User if the details are correct.
 
-Adauth provides generators and helper methods for getting your application up and running.
+Adauth provides a lot of additional functionality which can be used to get your authentication up and running quickly. See the {wiki}[https://github.com/Arcath/Adauth/wiki] for more information.
 
 == Developing
 

data/adauth.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
     s.summary = "Provides Active Directory authentication for Rails"
     
     s.add_development_dependency "rspec"
-    s.add_dependency "ruby-net-ldap"
+    s.add_dependency "net-ldap"
     
     s.files         = `git ls-files`.split("\n")
     s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")   

data/lib/adauth.rb

@@ -5,7 +5,17 @@ require 'adauth/config'
 require 'adauth/helpers'
 require 'adauth/user_model' if defined? ActiveRecord
 
+# The top level module
+#
+# For Adauths documentation please see the github wiki.
 module Adauth
+    
+    # Takes a username and password as an input and returns an instance of `Adauth::User`
+    #
+    # Called as
+    #    Adauth.authenticate("Username", "Password")
+    #
+    # Will return `nil` if the username/password combo is wrong, if the username/password combo is correct it will return an instance of `Adauth::User` which can be used to populate your database.
     def self.authenticate(login, pass)
         if @config.allowed_groups != []
             user = Adauth::User.authenticate(login, pass)
@@ -18,12 +28,27 @@ module Adauth
         end
     end
     
+    # Used to configure Adauth
+    #
+    # Called as
+    #    Adauth.configure do |c|
+    #        c.foo = "bar"
+    #    end
+    #
+    # Configures Adauth and is required for Adauth to work.
     def self.configure
        @config = Config.new
        yield(@config) 
     end
     
+    # Returns the config object
+    #
+    # Allows access to the adauth config object so you can call the config values in your application
     def self.config
         @config
     end
+    
+    # Rails generators
+    module Generators
+    end
 end

data/lib/adauth/config.rb

@@ -1,7 +1,12 @@
 module Adauth
+    
+    # Holds all of adauth config in attr_accessor values
     class Config
         attr_accessor :domain, :port, :base, :server, :allowed_groups, :denied_groups
         
+        # Creates a new instance of Adauth::Config
+        #
+        # Sets port, allowed_groups and denied_groups to default so they can be omitted from the config
         def initialize
            @port = 389
            @allowed_groups = []

data/lib/adauth/helpers.rb

@@ -1,11 +1,18 @@
 module Adauth
+    
+    # Helper methods for rails
     module Helpers
+        
+        # Creates a form_tag for the adauth form
+        #
+        # Sets the html id to "adauth_login" and the form destination to "/adauth"
         def adauth_form
         	form_tag '/adauth', :id => "adauth_login" do
         	    yield.html_safe
     	    end
         end
         
+        # Create the default form by calling `adauth_form` and passing a username and password input
         def default_adauth_form
             adauth_form do
                 "<p>#{label_tag :username}: 

data/lib/adauth/user.rb

@@ -1,5 +1,11 @@
 module Adauth
+    
+    # The class which links to Active Directory, based on http://metautonomo.us/2008/04/04/simplified-active-directory-authentication/
+    #
+    # Do no call Adauth::User.new, use Adauth::User.authenticate instead. For all of Adauth additional filtering use Adauth.authenticate.
     class User
+        
+        # Single vales where the method maps directly to one Active Directory attribute
         ATTR_SV = {
               :login => :samaccountname,
               :first_name => :givenname,
@@ -7,12 +13,19 @@ module Adauth
               :email => :mail,
               :name => :name
         }
-            
+        
+        # Multi values were the method needs to return an array for values.
         ATTR_MV = {
               :groups => [ :memberof,
                            Proc.new {|g| g.sub(/.*?CN=(.*?),.*/, '\1')} ]
         }
 
+        # Authenticates a user against Active Directory and returns an instance of self
+        #
+        # Called as:
+        #    Adauth::User.authenticate("username", "password")
+        #
+        # Usage would by-pass Adauths group filtering.
         def self.authenticate(login, pass)
             return nil if login.empty? or pass.empty?
             conn = Net::LDAP.new    :host => Adauth.config.server,
@@ -30,10 +43,14 @@ module Adauth
             return nil
         end
 
+        # Returns the full name of the user
+        #
+        # Combines the first_name and last_name attributes to create full_name
         def full_name
             self.first_name + ' ' + self.last_name
         end
 
+        # Returns true if the user is a member of the passed group.
         def member_of?(group)
             self.groups.include?(group)
         end

data/lib/adauth/user_model.rb

@@ -1,26 +1,58 @@
 module Adauth
+    
+    # Module desgined to be included in a ActiveRecord user model
     module UserModel
+        
+        # Adds class methods to the ActiveRecord model when included
         def self.included(base)
             base.extend ClassMethods
         end
         
+        # Returns an array of groups for the user
+        #
+        # Called as:
+        #    UserInstance.groups
+        #
+        # The array is generated from the group_strings attribute which is set by the adauth update and create methods. This array will match the windows security groups the user is a member of.
     	def groups
     	   group_strings.split(", ") 
 	    end
 	    
+	    # Update the user record using an instance of Adauth::User
+	    #
+	    # Called as:
+	    #    UserInstance.update_from_adauth(AdauthUserInstance)
+	    #
+	    # This method is called on login and shouldn't need to be called at any other time
 	    def update_from_adauth(adauth_user)
 	        self.group_strings = adauth_user.groups.join(", ")
 	        self.name = adauth_user.name
 	        self.save
         end
 	    
+	    # Class methods for the UserModel
 	    module ClassMethods
+	        
+	        # Used during the login process to return the users database record.
+	        #
+	        # Takes an instance of Adauth::User as an input
+	        #
+	        # Called as
+	        #     YourUserModel.return_and_create_with_adauth(AdauthUserInstance)
+	        #
+	        # If the user has no user record in the database one will be created. All the details on the record (new and old) will be updated to the lastest details from the AD server
 	        def return_and_create_with_adauth(adauth_user)
                 user = (find_by_login(adauth_user.login) || create_user_with_adauth(adauth_user))
                 user.update_from_adauth(adauth_user)
                 return user
             end
-
+            
+            # Creates a user record from an instance of Adauth::User
+            #
+            # Called as:
+            #    YourUserModel.create_user_with_adauth(AdauthUserInstance)
+            #
+            # Takes the Adauth::User input and creates a user record with matching details
             def create_user_with_adauth(adauth_user)
         		create! do |user|
         			user.login = adauth_user.login

data/lib/adauth/version.rb

@@ -1,3 +1,5 @@
 module Adauth
-    Version = "1.0.0"
+    
+    # The version of the gem
+    Version = "1.0.1"
 end

data/lib/generators/adauth/all/all_generator.rb

@@ -1,6 +1,13 @@
 module Adauth
     module Generators
+        
+        # Runs all of Adauths Generators
         class AllGenerator < Rails::Generators::Base
+            
+            # Calls all of Adauth Generators
+            #
+            # Called by running
+            #    rails g adauth:all
             def all_generators
                 generate "adauth:config"
                 generate "adauth:user_model"

data/lib/generators/adauth/config/config_generator.rb

@@ -1,8 +1,14 @@
 module Adauth
     module Generators
+        
+        # Generates a sample config file
         class ConfigGenerator < Rails::Generators::Base
             source_root File.expand_path('../templates', __FILE__)
             
+            # Generates a sample config file
+            #
+            # Called by running:
+            #    rails g adauth:config
             def generate_config
                 template "config.rb.erb", "config/initializers/adauth.rb"
             end

data/lib/generators/adauth/config/templates/config.rb.erb

@@ -32,4 +32,11 @@ Adauth.configure do |c|
 	# 
 	# Takes an array for group names
 	#c.allowed_groups = ["Group1", "Group2"]
+	
+	# Windows Security groups to deny
+	#
+	# Only allow users who aren't in these groups to login
+	#
+	# Takes an array for group names
+	#c.denied_groups = ["Group1", "Group2"]
 end

data/lib/generators/adauth/sessions/sessions_generator.rb

@@ -1,9 +1,17 @@
 module Adauth
     module Generators
+        
+        # Generates the sessions controller
         class SessionsGenerator < Rails::Generators::Base
             source_root File.expand_path('../templates', __FILE__)
             argument :model_name, :type => :string, :default => "user"
             
+            # Generates the sessions controller
+            #
+            # Called as:
+            #    rails g adauth:sessions
+            #
+            # Has 1 optional input of "model_name", which needs to be set the the model that include Adauth::UserModel
             def generate_sessions
                 template "sessions_controller.rb.erb", "app/controllers/sessions_controller.rb"
                 template "new.html.erb", "app/views/sessions/new.html.erb"

data/lib/generators/adauth/user_model/user_model_generator.rb

@@ -1,10 +1,18 @@
 module Adauth
     module Generators
+        
+        # Creates a user model with migration
         class UserModelGenerator < Rails::Generators::Base
             source_root File.expand_path('../templates', __FILE__)
             argument :model_name, :type => :string, :default => "user"
             argument :migration_name, :type => :string, :default => false
             
+            # Creates a user model with migration
+            #
+            # Called as:
+            #    rails g adauth:user_model
+            #
+            # Has 2 optional parameters, model_name which defaults to "user" and migration_name which defaults to "create_users"
             def generate_user_model
                 template "model.rb.erb", "app/models/#{file_name}.rb"
                 generate "migration", "#{migration_name_for_array}", "login:string", "group_strings:string", "name:string"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: adauth
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 1
   - 0
-  - 0
-  version: 1.0.0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors: 
 - Adam "Arcath" Laycock
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-22 00:00:00 +01:00
+date: 2011-08-01 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -33,7 +33,7 @@ dependencies:
   type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: ruby-net-ldap
+  name: net-ldap
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false