README.md in devise_ldap_authenticatable-0.1.6 vs README.md in devise_ldap_authenticatable-0.3.3

- old
+ new

@@ -1,144 +1,96 @@ -Devise LDAP Authenticatable - Based on Devise-Imapable -================= +Devise LDAP Authenticatable +=========================== Devise LDAP Authenticatable is a LDAP based authentication strategy for the [Devise](http://github.com/plataformatec/devise) authentication framework. If you are building applications for use within your organization which require authentication and you want to use LDAP, this plugin is for you. +For a screencast with an example application, please visit: [http://random-rails.blogspot.com/2010/07/ldap-authentication-with-devise.html](http://random-rails.blogspot.com/2010/07/ldap-authentication-with-devise.html) + Requirements ------------ -- Rails 2.3.5 -- Devise 1.0.6 -- Net-LDAP 0.1.1 +- An LDAP server (tested on OpenLDAP) +- Rails 3.0.0.beta4 +- Devise 1.1.rc2 +- ruby-net-ldap 0.0.4 -**_Please Note_** - -You must use the net-ldap gem and _NOT_ the ruby-net-ldap gem. - Installation ------------ - gem install devise_ldap_authenticatable +**_Please Note_** -and - - config.gem 'devise_ldap_authenticatable' +This will versions 0.3.0 and above will only work for Rails 3 applications. Please use version 0.2.x for Rails 2 apps. +In the Gemfile for your application: + + gem "devise", "1.1.rc2" + gem "devise_ldap_authenticatable" + Setup ----- -Once devise\_ldap\_authenticatable is installed, all you need to do is setup the user model which includes a small addition to the model itself and to the schema. +Run the rails generator -First the schema : + rails generate devise_ldap_authenticatable:install - create_table :users do |t| - t.ldap_authenticatable, :null => false - end +This will install the sample.yml, update the devise.rb initializer, and update your user model. There are some options you can pass to it: -and indexes (optional) : + [--user-model=USER_MODEL] # Model to update + # Default: user + [--update-model] # Update model to change from database_authenticatable to ldap_authenticatable + # Default: true - add_index :login, :unique => true -and don’t forget to migrate : - - rake db:migrate. - -then the model : - - class User < ActiveRecord::Base - devise :ldap_authenticatable, :rememberable, :trackable, :timeoutable - - # Setup accessible (or protected) attributes for your model - attr_accessible :login, :ldap_attributes, :password, :remember_me - ... - end - -and finally change the authentication key in the devise initializer : - - Devise.setup do |config| - ... - config.authentication_keys = [ :login ] - ... - end - -The string stored in ldap_attributes will be inserted between the login and base to provide the full dn used to bind. -I recommend using :rememberable, :trackable, :timeoutable as it gives a full feature set for logins. - Usage ----- -Devise LDAP Authenticatable works in replacement of Authenticatable, -but because we have to change the authentication\_keys, you'll need to run: +Devise LDAP Authenticatable works in replacement of Database Authenticatable - script/generate devise_views - -and customize your login pages to use :login, instead of :email. - ------------------------------------------------------------- - **_Please Note_** -This devise plugin has not been tested with Authenticatable enabled at the same time. This is meant as a drop in replacement for Authenticatable allowing for a semi single sign on approach. +This devise plugin has not been tested with DatabaseAuthenticatable enabled at the same time. This is meant as a drop in replacement for DatabaseAuthenticatable allowing for a semi single sign on approach. Configuration ----------------------- +------------- In initializer `config/initializers/devise.rb` : - Devise.setup do |config| - # Required - config.ldap_host = 'ldap.mydomain.com' - config.ldap_port = 389 - config.ldap_base_dn = 'ou=People,dc=local' - config.ldap_login_attribute = 'uid' - - # Optional, these will default to false or nil if not set - config.ldap_ssl = true - config.ldap_create_user = true - end - -* ldap\_host - * The host of your LDAP server - -* ldap\_port - * The port your LDAP service is listening on. - -* ldap\_base_dn - * The DN that is appended to the login before the LDAP bind is performed. - -* ldap\_login_attribute - * The attribute that is prepended to the login and the base dn to form the - full DN that is used for the bind. - * Example: - * config.ldap\_base_dn = 'ou=People,dc=local' - * config.ldap\_login_attribute = 'uid' - * So when trying to login with 'admin' for example, 'admin' would be - the value stored in login field, but the actual DN used for the bind - would be 'uid=admin,ou=People,dc=local' - -* ldap\_ssl - * Enables SSL (ldaps) encryption. START_TLS encryption will be added when the net-ldap gem adds support for it. - * ldap\_create\_user * If set to true, all valid LDAP users will be allowed to login and an appropriate user record will be created. If set to false, you will have to create the user record before they will be allowed to login. +* ldap\_config + * Where to find the LDAP config file. Commented out to use the default, change if needed. +* ldap\_update\_password + * When doing password resets, if true will update the LDAP server. Requires admin password in the ldap.yml + +Testing +------- + +This has been tested using the following setup: + +* Mac OSX 10.6 +* OpenLDAP 2.4.11 +* REE 1.8.7 (2010.02) + +All unit and functional tests are part of a sample rails application under test/rails_app and requires a working LDAP sever. There are config files and setup instructions under test/ldap + References ---------- +* [Original Plugin](http://github.com/cschiewek/devise_ldap_authenticatable) * [Devise](http://github.com/plataformatec/devise) * [Warden](http://github.com/hassox/warden) TODO ---- -- Add support for defining DN format to make logins cleaner -- Tests +View on [Pivotal Tracker](http://www.pivotaltracker.com/projects/97318). Released under the MIT license -Copyright (c) 2010 Curtis Schiewek +Copyright (c) 2010 Curtis Schiewek, Daniel McNevin