Class: Jamf::LdapServer

Inherits:
APIObject show all
Defined in:
lib/jamf/api/classic/api_objects/ldap_server.rb

Overview

An LDAP server in the JSS.

This class doesn’t curretly provide creation or updaing of LDAP server definitions in the JSS. Please use the JSS web UI.

However, it does provide methods for querying users and usergroups from LDAP servers, and checking group membership.

The class methods LdapServer.user_in_ldap? and LdapServer.group_in_ldap? can be used to check all defined LDAP servers for a user or group. They are used by Scopable::Scope when adding user and groups to scope limitations and exceptions.

Within an LdapServer instance, the methods #find_user and #find_group will return all matches in the server for a given search term.

See Also:

Constant Summary collapse

RSRC_BASE =

The base for REST resources of this class

'ldapservers'.freeze
RSRC_LIST_KEY =

the hash key used for the JSON list output of all objects in the JSS

:ldap_servers
RSRC_OBJECT_KEY =

The hash key used for the JSON object output. It’s also used in various error messages

:ldap_server
DEFAULT_PORT =

the default LDAP port

389
SEARCH_SCOPES =

possible values for search scope

['All Subtrees', 'First Level Only'].freeze
AUTH_TYPES =

possible authentication types

{ 'none' => :anonymous, 'simple' => :simple, 'CRAM-MD5' => :cram_md5, 'DIGEST-MD5' => :digest_md5 }.freeze
REFERRAL_RESPONSES =

possible referral responses

['', nil, 'follow', 'ignore'].freeze
OBJECT_CLASS_MAPPING_OPTIONS =

possible objectclass mapping options

%w[any all].freeze
OBJECT_HISTORY_OBJECT_TYPE =

the object type for this object in the object history table. See APIObject#add_object_history_entry

80

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**args) ⇒ LdapServer

See Jamf::APIObject#initialize



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 264

def initialize(**args)
  super

  @hostname = @init_data[:connection][:hostname]
  @port = @init_data[:connection][:port]
  @use_ssl = @init_data[:connection][:use_ssl]
  @authentication_type = AUTH_TYPES[@init_data[:connection][:authentication_type]]
  @open_close_timeout = @init_data[:connection][:open_close_timeout]
  @search_timeout = @init_data[:connection][:search_timeout]
  @referral_response = @init_data[:connection][:referral_response]
  @use_wildcards = @init_data[:connection][:use_wildcards]

  @lookup_dn = @init_data[:connection][:account][:distinguished_username]
  @lookup_pw_sha256 = @init_data[:connection][:account][:password_sha256]

  @user_mappings = @init_data[:mappings_for_users][:user_mappings]
  @user_group_mappings = @init_data[:mappings_for_users][:user_group_mappings]
  @user_group_membership_mappings = @init_data[:mappings_for_users][:user_group_membership_mappings]

  @connection = nil
  @connected = false
end

Instance Attribute Details

#authentication_type ⇒ String (readonly)

Returns what authentication method should be used?.

Returns:

  • (String) —

    what authentication method should be used?



179
180
181
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 179

def authentication_type
  @authentication_type
end

#hostanme ⇒ String (readonly)

Returns the hostname of the server.

Returns:

  • (String) —

    the hostname of the server



170
171
172
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 170

def hostanme
  @hostanme
end

#lookup_dn ⇒ String (readonly)

Returns the Distinguished Name of the account used for connections/lookups?.

Returns:

  • (String) —

    the Distinguished Name of the account used for connections/lookups?



182
183
184
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 182

def lookup_dn
  @lookup_dn
end

#lookup_pw_sha256 ⇒ String (readonly)

Returns the password for the connection/lookup account, as a SHA256 digest.

Returns:

  • (String) —

    the password for the connection/lookup account, as a SHA256 digest.



185
186
187
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 185

def lookup_pw_sha256
  @lookup_pw_sha256
end

#open_close_timeout ⇒ Integer (readonly)

Returns timeout, in seconds, for opening LDAP connections.

Returns:

  • (Integer) —

    timeout, in seconds, for opening LDAP connections



188
189
190
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 188

def open_close_timeout
  @open_close_timeout
end

#port ⇒ Integer (readonly)

Returns the port for ldap.

Returns:

  • (Integer) —

    the port for ldap



173
174
175
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 173

def port
  @port
end

#referral_response ⇒ String (readonly)

Returns the referral response from the server.

Returns:

  • (String) —

    the referral response from the server



194
195
196
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 194

def referral_response
  @referral_response
end

#search_timeout ⇒ Integer (readonly)

Returns timeout, in seconds, for search queries.

Returns:

  • (Integer) —

    timeout, in seconds, for search queries



191
192
193
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 191

def search_timeout
  @search_timeout
end

#use_ssl ⇒ Boolean (readonly)

Returns should the connection use ssl?.

Returns:

  • (Boolean) —

    should the connection use ssl?



176
177
178
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 176

def use_ssl
  @use_ssl
end

#use_wildcards ⇒ Boolean (readonly)

Returns should searches use wildcards?.

Returns:

  • (Boolean) —

    should searches use wildcards?



197
198
199
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 197

def use_wildcards
  @use_wildcards
end

#user_group_mappings ⇒ Hash<Symbol=>String> (readonly)

The LDAP attributes mapped to various user group data

The hash keys are:

  • :search_base =>

  • :search_scope =>

  • :object_classes =>

  • :map_object_class_to_any_or_all =>

  • :map_group_id =>

  • :map_group_name =>

  • :map_group_uuid =>

Returns:



235
236
237
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 235

def user_group_mappings
  @user_group_mappings
end

#user_group_membership_mappings ⇒ Hash<Symbol=>String> (readonly)

The LDAP attributes used to identify a user as a member of a group

The hash keys are:

  • :user_group_membership_stored_in =>

  • :map_user_membership_use_dn =>

  • :map_group_membership_to_user_field =>

  • :group_id =>

  • :map_object_class_to_any_or_all =>

  • :append_to_username =>

  • :username =>

  • :object_classes =>

  • :use_dn =>

  • :search_base =>

  • :recursive_lookups =>

  • :search_scope =>

  • :map_user_membership_to_group_field =>

Returns:



256
257
258
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 256

def user_group_membership_mappings
  @user_group_membership_mappings
end

#user_mappings ⇒ Hash<Symbol=>String> (readonly)

The LDAP attributes mapped to various user data

The hash keys are:

  • :search_base =>

  • :search_scope =>

  • :object_classes =>

  • :map_object_class_to_any_or_all =>

  • :map_username =>

  • :map_user_id =>

  • :map_department =>

  • :map_building =>

  • :map_room =>

  • :map_realname =>

  • :map_phone =>

  • :map_email_address =>

  • :map_position =>

  • :map_user_uuid =>

  • :append_to_email_results =>

Returns:



220
221
222
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 220

def user_mappings
  @user_mappings
end

Class Method Details

.check_membership(ldap_server, user, group, api: nil, cnx: Jamf.cnx) ⇒ Boolean

On a given server, does a given group contain a given user?

This class method allows the check to happen without instanting the LdapServer.

Parameters:

  • server (String, Integer) —

    The name or id of the LDAP server to use

  • user (String) —

    the username to check for memebership in the group

  • group (String) —

    the group name to see if the user is a member

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the API connection to use for the search

Returns:

  • (Boolean) —

    is the user a member of the group?

Raises:



151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 151

def self.check_membership(ldap_server, user, group, api: nil, cnx: Jamf.cnx)
  cnx = api if api

  ldap_server_id = valid_id ldap_server, cnx: cnx
  raise Jamf::NoSuchItemError, "No LdapServer matching #{ldap_server}" unless ldap_server_id

  rsrc = "#{RSRC_BASE}/id/#{ldap_server_id}/group/#{CGI.escape group.to_s}/user/#{CGI.escape user.to_s}"
  member_check = cnx.c_get rsrc

  !member_check[:ldap_users].empty?
end

.group_in_ldap?(group, api: nil, cnx: Jamf.cnx) ⇒ Boolean

For Backward Compatibility,

Parameters:

  • user (String) —

    a group name to search for in all LDAP servers

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the API connection to use for the search

Returns:

  • (Boolean) —

    Does the group exist in any LDAP server?



130
131
132
133
134
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 130

def self.group_in_ldap?(group, api: nil, cnx: Jamf.cnx)
  cnx = api if api

  server_for_group(group, cnx: cnx) ? true : false
end

.server_for_group(group, api: nil, cnx: Jamf.cnx) ⇒ Integer?

Does a group exist in any ldap server?

Parameters:

  • group (String) —

    a group to search for in all LDAP servers

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the API connection to use for the search

Returns:

  • (Integer, nil) —

    the id of the first LDAP server with the group, nil if not found



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 111

def self.server_for_group(group, api: nil, cnx: Jamf.cnx)
  cnx = api if api

  all_objects(:refresh, cnx: cnx).each do |ldap|
    next if ldap.find_group(group, :exact).empty?

    return ldap.id
  end
  nil
end

.server_for_user(user, api: nil, cnx: Jamf.cnx) ⇒ Integer?

Returns the id of the first LDAP server with the user, nil if not found.

Returns:

  • (Integer, nil) —

    the id of the first LDAP server with the user, nil if not found



77
78
79
80
81
82
83
84
85
86
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 77

def self.server_for_user(user, api: nil, cnx: Jamf.cnx)
  cnx = api if api

  all_objects(:refresh, cnx: cnx).each do |ldap|
    next if ldap.find_user(user, :exact).empty?

    return ldap.id
  end
  nil
end

.user_in_ldap?(user, api: nil, cnx: Jamf.cnx) ⇒ Boolean

For Backward Compatibility,

Parameters:

  • user (String) —

    a username to search for in all LDAP servers

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the API connection to use for the search

Returns:

  • (Boolean) —

    Does the user exist in any LDAP server?



96
97
98
99
100
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 96

def self.user_in_ldap?(user, api: nil, cnx: Jamf.cnx)
  cnx = api if api

  server_for_user(user, cnx: cnx) ? true : false
end

Instance Method Details

#check_membership(user, group) ⇒ Boolean?

Returns is the user a member? Nil if unable to check.

Parameters:

  • user (String) —

    the username to check for memebership in the group

  • group (String) —

    the group name to see if the user is a member

Returns:

  • (Boolean, nil) —

    is the user a member? Nil if unable to check

Raises:



324
325
326
327
328
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 324

def check_membership(user, group)
  raise Jamf::NoSuchItemError, 'LdapServer not yet saved in the JSS' unless @in_jss

  self.class.check_membership @id, user, group, cnx: @cnx
end

#find_group(group, exact = false) ⇒ Array<Hash>

Returns The groupname and uid for all groups matching the query.

Parameters:

  • group (String) —

    the group name to search for

  • exact (Boolean) (defaults to: false) —

    if true, force an exact match, otherwuse use wildcards

Returns:

  • (Array<Hash>) —

    The groupname and uid for all groups matching the query

Raises:



311
312
313
314
315
316
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 311

def find_group(group, exact = false)
  raise Jamf::NoSuchItemError, 'LdapServer not yet saved in the JSS' unless @in_jss

  raw = cnx.c_get("#{RSRC_BASE}/id/#{@id}/group/#{CGI.escape group.to_s}")[:ldap_groups]
  exact ? raw.select { |u| u[:groupname] == group } : raw
end

#find_user(user, exact = false) ⇒ Array<Hash>

Search for a user in this ldap server

Parameters:

  • user (String) —

    the username to search for

  • exact (Boolean) (defaults to: false) —

    if true, force an exact match, otherwise use wildcards

Returns:

  • (Array<Hash>) —

    The mapped LDAP data for all usernames matching the query

Raises:



298
299
300
301
302
303
 
# File 'lib/jamf/api/classic/api_objects/ldap_server.rb', line 298

def find_user(user, exact = false)
  raise Jamf::NoSuchItemError, 'LdapServer not yet saved in the JSS' unless @in_jss

  raw = cnx.c_get("#{RSRC_BASE}/id/#{@id}/user/#{CGI.escape user.to_s}")[:ldap_users]
  exact ? raw.select { |u| u[:username] == user } : raw
end