Skip to content

An LDAP gem for querying LDAP in various styles: Active Directory, FreeIPA & POSIX

License

Notifications You must be signed in to change notification settings

theforeman/ldap_fluff

Repository files navigation

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, 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. 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.

About

An LDAP gem for querying LDAP in various styles: Active Directory, FreeIPA & POSIX

Topics

Resources

License

Stars

Watchers

Forks

Languages