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_exceptions.rb,
lib/ucb_ldap_affiliation.rb,
lib/ucb_ldap_student_term.rb,
lib/person/generic_attributes.rb,
lib/ucb_ldap_schema_attribute.rb,
lib/person/affiliation_methods.rb,
lib/ucb_ldap_person_job_appointment.rb

Overview

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, GenericAttributes, Schema Classes: Address, Affiliation, BadAttributeNameException, BindFailedException, ConnectionFailedException, DirectoryNotUpdatedException, Entry, JobAppointment, Namespace, Org, Person, Service, StudentTerm

Constant Summary collapse

HOST_PRODUCTION = 
'ldap.berkeley.edu'
HOST_TEST = 
'ldap-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.



48
49
50
51
 
# File 'lib/ucb_ldap.rb', line 48

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().



140
141
142
143
144
 
# File 'lib/ucb_ldap.rb', line 140

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

.bind(bind_file, environment) ⇒ Object 



120
121
122
123
124
125
 
# File 'lib/ucb_ldap.rb', line 120

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.



116
117
118
 
# File 'lib/ucb_ldap.rb', line 116

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



54
55
56
 
# File 'lib/ucb_ldap.rb', line 54

def clear_authentication
  authenticate(nil, nil)
end

.clear_instance_variables ⇒ Object

Used for testing



196
197
198
199
200
201
 
# File 'lib/ucb_ldap.rb', line 196

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

.connection_open? ⇒ Boolean

Returns true if we have a Net::LDAP instance with an open connection.

Returns:

  • (Boolean) 


148
149
150
151
152
 
# File 'lib/ucb_ldap.rb', line 148

def connection_open?
  @net_ldap.nil? ? false : ldap_ping
rescue
  false
end

.host ⇒ Object

Returns LDAP host used for lookups. Default is HOST_PRODUCTION.



59
60
61
 
# File 'lib/ucb_ldap.rb', line 59

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.



70
71
72
73
74
75
 
# File 'lib/ucb_ldap.rb', line 70

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

.ldap_ping ⇒ Object

Returns true if connection simple search works.



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/ucb_ldap.rb', line 155

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.



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

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.



133
134
135
 
# File 'lib/ucb_ldap.rb', line 133

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



85
86
87
 
# File 'lib/ucb_ldap.rb', line 85

def net_ldap
  connection_open? ? @net_ldap : new_net_ldap
end

.new_net_ldap ⇒ Object

Returns new Net::LDAP instance. Also reaches into the Net::LDAP to set the @open_connection instance variable.

Warning: this seems to be contrary to the Net::LDAP author’s intent and may break with future versions of Net::LDAP.



172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/ucb_ldap.rb', line 172

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

.new_net_ldap_connection ⇒ Object

Return a new Net::LDAP::Connection



185
186
187
188
189
190
191
192
193
 
# File 'lib/ucb_ldap.rb', line 185

def new_net_ldap_connection
  Net::LDAP::Connection.new(
    :host => host,
    :port => 636,
    :encryption => {:method => :simple_tls}
  )
rescue Net::LDAP::LdapError
  raise UCB::LDAP::ConnectionFailedException
end

.password ⇒ Object

:nodoc:



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

def password #:nodoc:
  @password
end

.username ⇒ Object

:nodoc:



93
94
95
 
# File 'lib/ucb_ldap.rb', line 93

def username #:nodoc:
  @username
end