adauth 1.0.0 → 1.0.1

Sign up to get free protection for your applications and to get access to all the features.
data/.gitignore CHANGED
@@ -3,3 +3,5 @@ pkg/*
3
3
  tmp/*
4
4
  *~
5
5
  spec/test_data.yml
6
+ doc/*
7
+ .yardoc/*
@@ -1,13 +1,14 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- adauth (0.0.1pre)
5
- ruby-net-ldap
4
+ adauth (1.0.0)
5
+ net-ldap
6
6
 
7
7
  GEM
8
8
  remote: http://rubygems.org/
9
9
  specs:
10
10
  diff-lcs (1.1.2)
11
+ net-ldap (0.2.2)
11
12
  rspec (2.6.0)
12
13
  rspec-core (~> 2.6.0)
13
14
  rspec-expectations (~> 2.6.0)
@@ -16,7 +17,6 @@ GEM
16
17
  rspec-expectations (2.6.0)
17
18
  diff-lcs (~> 1.1.2)
18
19
  rspec-mocks (2.6.0)
19
- ruby-net-ldap (0.0.4)
20
20
 
21
21
  PLATFORMS
22
22
  ruby
@@ -12,15 +12,11 @@ and run a bundle install
12
12
 
13
13
  == Usage
14
14
 
15
- Create an initializer in _config/initilaizers_ called adauth.rb and place this code in it:
15
+ Adauth requires a config file which can be created by running the command
16
16
 
17
- Adauth.configure do |c|
18
- c.domain = "example.com" #The domain name used on your network e.g. example.com or example.local
19
- c.server = "127.0.0.1" #The IP of any DC on your network
20
- c.base = "dc=example, dc=com" #the base for your users.
21
- end
17
+ rails g adauth:config
22
18
 
23
- 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.
19
+ This creates a config file for _example.com_ with all the values present along with helpful comments for getting Adauth up and running.
24
20
 
25
21
  Thats enough to very basically run Adauth, and if you prefer complete control over how your authentication is handled you can use this method:
26
22
 
@@ -28,7 +24,7 @@ Thats enough to very basically run Adauth, and if you prefer complete control ov
28
24
 
29
25
  Which has 2 possible return values nil if the users details are wrong or an instance of Adauth::User if the details are correct.
30
26
 
31
- Adauth provides generators and helper methods for getting your application up and running.
27
+ 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.
32
28
 
33
29
  == Developing
34
30
 
@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
12
12
  s.summary = "Provides Active Directory authentication for Rails"
13
13
 
14
14
  s.add_development_dependency "rspec"
15
- s.add_dependency "ruby-net-ldap"
15
+ s.add_dependency "net-ldap"
16
16
 
17
17
  s.files = `git ls-files`.split("\n")
18
18
  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
@@ -5,7 +5,17 @@ require 'adauth/config'
5
5
  require 'adauth/helpers'
6
6
  require 'adauth/user_model' if defined? ActiveRecord
7
7
 
8
+ # The top level module
9
+ #
10
+ # For Adauths documentation please see the github wiki.
8
11
  module Adauth
12
+
13
+ # Takes a username and password as an input and returns an instance of `Adauth::User`
14
+ #
15
+ # Called as
16
+ # Adauth.authenticate("Username", "Password")
17
+ #
18
+ # 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.
9
19
  def self.authenticate(login, pass)
10
20
  if @config.allowed_groups != []
11
21
  user = Adauth::User.authenticate(login, pass)
@@ -18,12 +28,27 @@ module Adauth
18
28
  end
19
29
  end
20
30
 
31
+ # Used to configure Adauth
32
+ #
33
+ # Called as
34
+ # Adauth.configure do |c|
35
+ # c.foo = "bar"
36
+ # end
37
+ #
38
+ # Configures Adauth and is required for Adauth to work.
21
39
  def self.configure
22
40
  @config = Config.new
23
41
  yield(@config)
24
42
  end
25
43
 
44
+ # Returns the config object
45
+ #
46
+ # Allows access to the adauth config object so you can call the config values in your application
26
47
  def self.config
27
48
  @config
28
49
  end
50
+
51
+ # Rails generators
52
+ module Generators
53
+ end
29
54
  end
@@ -1,7 +1,12 @@
1
1
  module Adauth
2
+
3
+ # Holds all of adauth config in attr_accessor values
2
4
  class Config
3
5
  attr_accessor :domain, :port, :base, :server, :allowed_groups, :denied_groups
4
6
 
7
+ # Creates a new instance of Adauth::Config
8
+ #
9
+ # Sets port, allowed_groups and denied_groups to default so they can be omitted from the config
5
10
  def initialize
6
11
  @port = 389
7
12
  @allowed_groups = []
@@ -1,11 +1,18 @@
1
1
  module Adauth
2
+
3
+ # Helper methods for rails
2
4
  module Helpers
5
+
6
+ # Creates a form_tag for the adauth form
7
+ #
8
+ # Sets the html id to "adauth_login" and the form destination to "/adauth"
3
9
  def adauth_form
4
10
  form_tag '/adauth', :id => "adauth_login" do
5
11
  yield.html_safe
6
12
  end
7
13
  end
8
14
 
15
+ # Create the default form by calling `adauth_form` and passing a username and password input
9
16
  def default_adauth_form
10
17
  adauth_form do
11
18
  "<p>#{label_tag :username}:
@@ -1,5 +1,11 @@
1
1
  module Adauth
2
+
3
+ # The class which links to Active Directory, based on http://metautonomo.us/2008/04/04/simplified-active-directory-authentication/
4
+ #
5
+ # Do no call Adauth::User.new, use Adauth::User.authenticate instead. For all of Adauth additional filtering use Adauth.authenticate.
2
6
  class User
7
+
8
+ # Single vales where the method maps directly to one Active Directory attribute
3
9
  ATTR_SV = {
4
10
  :login => :samaccountname,
5
11
  :first_name => :givenname,
@@ -7,12 +13,19 @@ module Adauth
7
13
  :email => :mail,
8
14
  :name => :name
9
15
  }
10
-
16
+
17
+ # Multi values were the method needs to return an array for values.
11
18
  ATTR_MV = {
12
19
  :groups => [ :memberof,
13
20
  Proc.new {|g| g.sub(/.*?CN=(.*?),.*/, '\1')} ]
14
21
  }
15
22
 
23
+ # Authenticates a user against Active Directory and returns an instance of self
24
+ #
25
+ # Called as:
26
+ # Adauth::User.authenticate("username", "password")
27
+ #
28
+ # Usage would by-pass Adauths group filtering.
16
29
  def self.authenticate(login, pass)
17
30
  return nil if login.empty? or pass.empty?
18
31
  conn = Net::LDAP.new :host => Adauth.config.server,
@@ -30,10 +43,14 @@ module Adauth
30
43
  return nil
31
44
  end
32
45
 
46
+ # Returns the full name of the user
47
+ #
48
+ # Combines the first_name and last_name attributes to create full_name
33
49
  def full_name
34
50
  self.first_name + ' ' + self.last_name
35
51
  end
36
52
 
53
+ # Returns true if the user is a member of the passed group.
37
54
  def member_of?(group)
38
55
  self.groups.include?(group)
39
56
  end
@@ -1,26 +1,58 @@
1
1
  module Adauth
2
+
3
+ # Module desgined to be included in a ActiveRecord user model
2
4
  module UserModel
5
+
6
+ # Adds class methods to the ActiveRecord model when included
3
7
  def self.included(base)
4
8
  base.extend ClassMethods
5
9
  end
6
10
 
11
+ # Returns an array of groups for the user
12
+ #
13
+ # Called as:
14
+ # UserInstance.groups
15
+ #
16
+ # 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.
7
17
  def groups
8
18
  group_strings.split(", ")
9
19
  end
10
20
 
21
+ # Update the user record using an instance of Adauth::User
22
+ #
23
+ # Called as:
24
+ # UserInstance.update_from_adauth(AdauthUserInstance)
25
+ #
26
+ # This method is called on login and shouldn't need to be called at any other time
11
27
  def update_from_adauth(adauth_user)
12
28
  self.group_strings = adauth_user.groups.join(", ")
13
29
  self.name = adauth_user.name
14
30
  self.save
15
31
  end
16
32
 
33
+ # Class methods for the UserModel
17
34
  module ClassMethods
35
+
36
+ # Used during the login process to return the users database record.
37
+ #
38
+ # Takes an instance of Adauth::User as an input
39
+ #
40
+ # Called as
41
+ # YourUserModel.return_and_create_with_adauth(AdauthUserInstance)
42
+ #
43
+ # 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
18
44
  def return_and_create_with_adauth(adauth_user)
19
45
  user = (find_by_login(adauth_user.login) || create_user_with_adauth(adauth_user))
20
46
  user.update_from_adauth(adauth_user)
21
47
  return user
22
48
  end
23
-
49
+
50
+ # Creates a user record from an instance of Adauth::User
51
+ #
52
+ # Called as:
53
+ # YourUserModel.create_user_with_adauth(AdauthUserInstance)
54
+ #
55
+ # Takes the Adauth::User input and creates a user record with matching details
24
56
  def create_user_with_adauth(adauth_user)
25
57
  create! do |user|
26
58
  user.login = adauth_user.login
@@ -1,3 +1,5 @@
1
1
  module Adauth
2
- Version = "1.0.0"
2
+
3
+ # The version of the gem
4
+ Version = "1.0.1"
3
5
  end
@@ -1,6 +1,13 @@
1
1
  module Adauth
2
2
  module Generators
3
+
4
+ # Runs all of Adauths Generators
3
5
  class AllGenerator < Rails::Generators::Base
6
+
7
+ # Calls all of Adauth Generators
8
+ #
9
+ # Called by running
10
+ # rails g adauth:all
4
11
  def all_generators
5
12
  generate "adauth:config"
6
13
  generate "adauth:user_model"
@@ -1,8 +1,14 @@
1
1
  module Adauth
2
2
  module Generators
3
+
4
+ # Generates a sample config file
3
5
  class ConfigGenerator < Rails::Generators::Base
4
6
  source_root File.expand_path('../templates', __FILE__)
5
7
 
8
+ # Generates a sample config file
9
+ #
10
+ # Called by running:
11
+ # rails g adauth:config
6
12
  def generate_config
7
13
  template "config.rb.erb", "config/initializers/adauth.rb"
8
14
  end
@@ -32,4 +32,11 @@ Adauth.configure do |c|
32
32
  #
33
33
  # Takes an array for group names
34
34
  #c.allowed_groups = ["Group1", "Group2"]
35
+
36
+ # Windows Security groups to deny
37
+ #
38
+ # Only allow users who aren't in these groups to login
39
+ #
40
+ # Takes an array for group names
41
+ #c.denied_groups = ["Group1", "Group2"]
35
42
  end
@@ -1,9 +1,17 @@
1
1
  module Adauth
2
2
  module Generators
3
+
4
+ # Generates the sessions controller
3
5
  class SessionsGenerator < Rails::Generators::Base
4
6
  source_root File.expand_path('../templates', __FILE__)
5
7
  argument :model_name, :type => :string, :default => "user"
6
8
 
9
+ # Generates the sessions controller
10
+ #
11
+ # Called as:
12
+ # rails g adauth:sessions
13
+ #
14
+ # Has 1 optional input of "model_name", which needs to be set the the model that include Adauth::UserModel
7
15
  def generate_sessions
8
16
  template "sessions_controller.rb.erb", "app/controllers/sessions_controller.rb"
9
17
  template "new.html.erb", "app/views/sessions/new.html.erb"
@@ -1,10 +1,18 @@
1
1
  module Adauth
2
2
  module Generators
3
+
4
+ # Creates a user model with migration
3
5
  class UserModelGenerator < Rails::Generators::Base
4
6
  source_root File.expand_path('../templates', __FILE__)
5
7
  argument :model_name, :type => :string, :default => "user"
6
8
  argument :migration_name, :type => :string, :default => false
7
9
 
10
+ # Creates a user model with migration
11
+ #
12
+ # Called as:
13
+ # rails g adauth:user_model
14
+ #
15
+ # Has 2 optional parameters, model_name which defaults to "user" and migration_name which defaults to "create_users"
8
16
  def generate_user_model
9
17
  template "model.rb.erb", "app/models/#{file_name}.rb"
10
18
  generate "migration", "#{migration_name_for_array}", "login:string", "group_strings:string", "name:string"
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: adauth
3
3
  version: !ruby/object:Gem::Version
4
- hash: 23
4
+ hash: 21
5
5
  prerelease:
6
6
  segments:
7
7
  - 1
8
8
  - 0
9
- - 0
10
- version: 1.0.0
9
+ - 1
10
+ version: 1.0.1
11
11
  platform: ruby
12
12
  authors:
13
13
  - Adam "Arcath" Laycock
@@ -15,7 +15,7 @@ autorequire:
15
15
  bindir: bin
16
16
  cert_chain: []
17
17
 
18
- date: 2011-07-22 00:00:00 +01:00
18
+ date: 2011-08-01 00:00:00 +01:00
19
19
  default_executable:
20
20
  dependencies:
21
21
  - !ruby/object:Gem::Dependency
@@ -33,7 +33,7 @@ dependencies:
33
33
  type: :development
34
34
  version_requirements: *id001
35
35
  - !ruby/object:Gem::Dependency
36
- name: ruby-net-ldap
36
+ name: net-ldap
37
37
  prerelease: false
38
38
  requirement: &id002 !ruby/object:Gem::Requirement
39
39
  none: false