Module: UCB::LDAP

Defined in:
lib/ucb_ldap.rb,
lib/ucb_ldap/org.rb,
lib/ucb_ldap/entry.rb,
lib/ucb_ldap/person.rb,
lib/ucb_ldap/schema.rb,
lib/ucb_ldap/address.rb,
lib/ucb_ldap/service.rb,
lib/ucb_ldap/namespace.rb,
lib/ucb_ldap/affiliation.rb,
lib/ucb_ldap/student_term.rb,
lib/ucb_ldap/expired_person.rb,
lib/ucb_ldap/job_appointment.rb,
lib/ucb_ldap/schema_attribute.rb,
lib/ucb_ldap/person/common_attributes.rb,
lib/ucb_ldap/person/affiliation_methods.rb

Overview

:nodoc:

UCB::LDAP

If you are doing searches that don’t require a privileged bind and are accessing the default (production) server you probably don’t need to call any of the methods in this module.

Methods in this module are about making connections to the LDAP directory.

Interaction with the directory (searches and updates) is usually through the search() and other methods of UCB::LDAP::Entry and its sub-classes.

Defined Under Namespace

Modules: AffiliationMethods, CommonAttributes, Schema Classes: Address, Affiliation, BindFailedException, ConnectionFailedException, DirectoryNotUpdatedException, Entry, ExpiredPerson, JobAppointment, Namespace, Org, Person, Service, StudentTerm

Constant Summary collapse

BadAttributeNameException =

:nodoc:

Class.new(Exception)
HOST_PRODUCTION = 
'nds.berkeley.edu'
HOST_TEST = 
'nds-test.berkeley.edu'

Class Method Summary collapse

Class Method Details

.authenticate(username, password) ⇒ Object

Give (new) bind credentials to LDAP. An attempt will be made to bind and will raise BindFailedException if bind fails.

Call clear_authentication() to remove privileged bind.



82
83
84
85
 
# File 'lib/ucb_ldap.rb', line 82

def authenticate(username, password)
  @username, @password = username, password
  new_net_ldap() # to force bind()
end

.authentication_information ⇒ Object

The value of the :auth parameter for Net::LDAP.new.



191
192
193
194
195
 
# File 'lib/ucb_ldap.rb', line 191

def authentication_information
  password.nil? ?
      { :method => :anonymous } :
      { :method => :simple, :username => username, :password => password }
end

.bind(bind_file, environment) ⇒ Object 



164
165
166
167
168
169
 
# File 'lib/ucb_ldap.rb', line 164

def bind(bind_file, environment)
  raise "Can't find bind file: #{bind_file}" unless FileTest.exists?(bind_file)
  binds = YAML.load(IO.read(bind_file))
  bind = binds[environment] || raise("Can't find environment=#{environment} in bind file")
  authenticate(bind['username'], bind['password'])
end

.bind_for_rails(bind_file = "#{::Rails.root}/config/ldap.yml", environment = ::Rails.env) ⇒ Object

If you are using UCB::LDAP in a Rails application you can specify binds on a per-environment basis, just as you can with database credentials.

# in ../config/ldap.yml

development:
  username: user_dev
  password: pass_dev

# etc.

# in ../config/environment.rb

require 'ucb_ldap'
UCB::LDAP.bind_for_rails()

Runtime error will be raised if bind_file not found or if environment key not found in bind_file.



160
161
162
 
# File 'lib/ucb_ldap.rb', line 160

def bind_for_rails(bind_file = "#{::Rails.root}/config/ldap.yml", environment = ::Rails.env)
  bind(bind_file, environment)
end

.clear_authentication ⇒ Object

Removes current bind (username, password).



90
91
92
 
# File 'lib/ucb_ldap.rb', line 90

def clear_authentication
  authenticate(nil, nil)
end

.clear_instance_variables ⇒ Object

Used for testing



231
232
233
234
235
236
 
# File 'lib/ucb_ldap.rb', line 231

def clear_instance_variables
  @host = nil
  @net_ldap = nil
  @username = nil
  @password = nil
end

.host ⇒ Object

Returns LDAP host used for lookups. Default is HOST_PRODUCTION.



97
98
99
 
# File 'lib/ucb_ldap.rb', line 97

def host
  @host || HOST_PRODUCTION
end

.host=(host) ⇒ Object

Setter for #host.

Note: validation of host is deferred until a search is performed or #authenticate() is called at which time a bad host will raise ConnectionFailedException.

Don’t want to reconnect unless host really changed.



110
111
112
113
114
115
 
# File 'lib/ucb_ldap.rb', line 110

def host=(host)
  if host != @host
    @host = host
    @net_ldap = nil
  end
end

.ldap_ping ⇒ Object

Returns true if connection simple search works.



200
201
202
203
204
205
206
207
208
209
 
# File 'lib/ucb_ldap.rb', line 200

def ldap_ping
  search_attrs = {
      :base => "",
      :scope => Net::LDAP::SearchScope_BaseObject,
      :attributes => [1.1]
  }
  result = false
  @net_ldap.search(search_attrs) { result = true }
  result
end

.local_date_parse(arg) ⇒ Object

Returns arg as a Ruby Date in local time zone. Returns nil if arg is nil.



174
175
176
 
# File 'lib/ucb_ldap.rb', line 174

def local_date_parse(arg)
  arg.nil? ? nil : Date.parse(Time.parse(arg.to_s).localtime.to_s)
end

.local_datetime_parse(arg) ⇒ Object

Returns arg as a Ruby DateTime in local time zone. Returns nil if arg is nil.



181
182
183
 
# File 'lib/ucb_ldap.rb', line 181

def local_datetime_parse(arg)
  arg.nil? ? nil : DateTime.parse(Time.parse(arg.to_s).localtime.to_s)
end

.net_ldap ⇒ Object

Returns Net::LDAP instance that is used by UCB::LDAP::Entry and subclasses for directory searches.

You might need this to perform searches not supported by sub-classes of Entry.

Note: callers should not cache the results of this call unless they are prepared to handle timed-out connections (which this method does).



127
128
129
 
# File 'lib/ucb_ldap.rb', line 127

def net_ldap
  @net_ldap ||= new_net_ldap
end

.new_net_ldap ⇒ Object

Returns new Net::LDAP instance.



214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/ucb_ldap.rb', line 214

def new_net_ldap
  params = {
      :host => host,
      :auth => authentication_information,
      :port => 636,
      :encryption => { :method => :simple_tls }
  }
  @net_ldap = Net::LDAP.new(params)
  @net_ldap.bind || raise(BindFailedException)
  @net_ldap
rescue Net::LDAP::LdapError => e
  raise(BindFailedException)
end

.password ⇒ Object

:nodoc:



131
132
133
 
# File 'lib/ucb_ldap.rb', line 131

def password #:nodoc:
  @password
end

.username ⇒ Object

:nodoc:



135
136
137
 
# File 'lib/ucb_ldap.rb', line 135

def username #:nodoc:
  @username
end

.with_credentials(username_to_use, password_to_use) ⇒ Object

Execute UCB::LDAP commands with a different username and password. Original credentials are restored.



65
66
67
68
69
70
71
72
73
74
 
# File 'lib/ucb_ldap.rb', line 65

def with_credentials(username_to_use, password_to_use)
  original_username = username
  original_password = password

  UCB::LDAP.authenticate(username_to_use, password_to_use)

  yield
ensure
  UCB::LDAP.authenticate(original_username, original_password)
end