ldap_fluff

= LDAP Fluff

Provides multiple implementations of LDAP queries for various backends

Supports Active Directory, FreeIPA and posix-style LDAP

== Installation

Now available in the rubygems.org repo, https://rubygems.org/gems/ldap_fluff

$ gem install ldap_fluff

== Rails Application Configuration

You'll have to configure the gem a little bit to get it hooked into your LDAP server.

It exposes these methods: authenticate?(username, password) returns true if the username & password combo bind correctly

group_list(uid) returns the set of LDAP groups a user belongs to in a string list

user_list(gid) returns the set of users that belong to an LDAP group

is_in_groups?(uid, grouplist) returns true if the user provided is in all of the groups listed in grouplist

valid_user?(uid) returns true if the user provided exists

valid_group?(uid) returns true if the group provided exists

find_user(uid) returns the LDAP entry of the user if found, nil if not found

find_group(gid) returns the LDAP entry of the group if found, nil if not found

These methods are handy for using LDAP for both authentication and authorization.

This gem integrates with warden/devise quite nicely.

Your global configuration must provide information about your LDAP host to function properly.

host: # ip address or hostname port: # port encryption: # blank, :simple_tls, or :start_tls base_dn: # base DN for LDAP auth, eg dc=redhat,dc=com group_base: # base DN for your LDAP groups, eg ou=Groups,dc=redhat,dc=com use_netgroups: # false by default, use true if you want to use netgroup triples, # supported only for server type :free_ipa and :posix server_type: # type of server. default == :posix. :active_directory, :posix, :free_ipa ad_domain: # domain for your users if using active directory, eg redhat.com service_user: # service account for authenticating LDAP calls. required unless you enable anon service_pass: # service password for authenticating LDAP calls. required unless you enable anon anon_queries: # false by default, true if you don't want to use the service user instrumentation_service: # nil by default, an object that supports the ActiveSupport::Notifications API

You can pass these arguments as a hash to LdapFluff to get a valid LdapFluff object.

ldap_config = { :host => "freeipa.localdomain", :port => 389, :encryption => nil, :base_dn => "DC=mydomain,DC=com", :group_base => "DC=groups,DC=mydomain,DC=com", :attr_login => "uid", :server_type => :free_ipa, :service_user => "admin", :search_filter => "(objectClass=*)", :service_pass => "mypass", :anon_queries => false }

fluff = LdapFluff.new(ldap_config) fluff.valid_user?("admin") # returns true

=== TLS support

ldap_fluff fully supports simple_tls and start_tls encryption, but most likely you'll need to add your server's CAs to the local bundle. on a Red Hat style system, it's probably something like this:

$ cat ldap_server_ca.crt >> /etc/pki/tls/certs/ca-bundle.crt

=== A note on ActiveDirectory

ldap_fluff does not support searching/binding global catalogs

service_user (formatted as "ad_domain/username") and service_pass OR anon_queries are required for AD support

Group membership searches will use "msds-memberOfTransitive" where possible, and will fall back to a recursive lookup

=== A note on FreeIPA

ldap_fluff appends cn=groups,cn=accounts to the beginning of all BIND calls. You do not need to include this in your base_dn string

=== Instrumentation

Both net-ldap and ldap_fluff support instrumentation of API calls, which can help debug performance issues or to find what LDAP queries are being made.

The :instrumentation_service item in the configuration should support an equivalent API to ActiveSupport::Notifications. ldap_fluff will use this and also pass it to net-ldap.

When using Rails, pass :instrumentation_service => ActiveSupport::Notifications and then subscribe to, and optionally log events (e.g. https://gist.github.com/mnutt/566725).

== Contributing

Feel free to file PR against our github repository.

== License

ldap_fluff is licensed under the GPLv2. Please read LICENSE for more information.