Devise LDAP Authenticatable

Devise LDAP Authenticatable is a LDAP based authentication strategy for the 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

Please Note

If you are using rails 2.x then use 0.1.x series of gem, and see the rails2 branch README for instructions.

Requirements

These gems are dependencies of the gem:

Installation

Please Note

This will only work for Rails 3 applications.

In the Gemfile for your application:

gem "devise", "1.1.2"
gem "devise_ldap_authenticatable"

To get the latest version, pull directly from github instead of the gem:

gem "devise_ldap_authenticatable", :git => "git://github.com/cschiewek/devise_ldap_authenticatable.git"

Setup

Run the rails generators for devise (please check the devise documents for further instructions)

rails generate devise:install
rails generate devise MODEL_NAME

Run the rails generator for devise_ldap_authenticatable

rails generate devise_ldap_authenticatable:install [options]

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:

Options:

[--user-model=USER_MODEL]  # Model to update
                           # Default: user
[--update-model]           # Update model to change from database_authenticatable to ldap_authenticatable
                           # Default: true
[--add-rescue]             # Update Application Controller with resuce_from for DeviseLdapAuthenticatable::LdapException
                           # Default: true
[--advanced]               # Add advanced config options to the devise initializer

Usage

Devise LDAP Authenticatable works in replacement of Database Authenticatable

Please Note

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.

The field that is used for logins is the first key that's configured in the config/devise.rb file under config.authentication_keys, which by default is email. For help changing this, please see the Railscast that goes through how to customize Devise.

Configuration

In initializer config/initializers/devise.rb :

Advanced Configuration

These parameters will be added to config/initializers/devise.rb when you pass the --advanced switch to the generator:

Testing

This has been tested using the following setup:

All unit and functional tests are part of a sample rails application under test/rails_app and requires a working LDAP sever.

Build / Start Instructions for Test LDAP Server

Make sure that directories test/ldap/openldap-data and test/ldap/openldap-data/run exist.

  1. To start the server, run ./run_server.sh
  2. Add the basic structure: ldapadd -x -h localhost -p 3389 -x -D "cn=admin,dc=test,dc=com" -w secret -f base.ldif
    • this creates the users / passwords:
  3. You should now be able to run the tests in test/rails_app by running: rake

For a LDAP server running SSL

  1. To start the server, run: ./run_server.sh --ssl
  2. Add the basic structure: ldapadd -x -H ldaps://localhost:3389 -x -D "cn=admin,dc=test,dc=com" -w secret -f base.ldif
    • this creates the users / passwords:
  3. You should now be able to run the tests in test/rails_app by running: LDAP_SSL=true rake

Please Note

In your system LDAP config file (on OSX it's /etc/openldap/ldap.conf) make sure you have the following setting:

TLS_REQCERT never

This will allow requests to go to the test LDAP server without being signed by a trusted root (it uses a self-signed cert)

References

TODO

View on Pivotal Tracker.

Released under the MIT license

Copyright (c) 2010 Curtis Schiewek, Daniel McNevin