Puppet-LDAPquery

A Puppet function to query LDAP.

Dependencies

The Ruby net-ldap gem is required to communicate with LDAP. To install this use the following command: puppetserver gem install net-ldap. Version 0.11.0 or newer of net-ldap is required.

In some environments, when ldapquery::search() is used on Puppet Server, an error like the following may appear.

Error while evaluating a Function Call

Please make sure you have jruby-openssl at least 0.10.1 with puppetserver gem install jruby-openssl -v 0.10.1.

REFERENCE

For detailed information on this module's functions, see the REFERENCE.md

Usage

This module provides two function variants. ldapquery::query is the legacy implementation where LDAP connection options are sourced from puppet.conf on your Puppetserver.

ldapquery::search is the replacement implementation. It provides more flexibility than ldapquery::query and doesn't reuse ldap related settings from puppet.conf. All connection options can be specified in the function call and can be different each time you call the function. For convenience, it is also possible to specify defaults to be used in all functions calls in /etc/puppetlabs/puppet/ldapquery.yaml. This can also be useful if you want to manage the credentials used to contact your ldap server separately from the code that calls the function.

Simple example

ldapquery::search(
  'dc=acme,dc=example,dc=com', # Search base
  '(objectClass=dnsDomain)',   # filter
  ['dc'],                      # attributes
  {                            # connection arguments
    host => 'ldap.example.com',
    auth => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

A full set of examples can be found in the REFERENCE.md file.

LDAP connection arguments

LDAP server connection options either have to be specified when calling the function, (in the 4th argument), or configured as defaults on the puppetserver in /etc/puppetlabs/puppet/ldapquery.yaml

Everything that the net-ldap library supports should work with this function, (eg. connecting to multiple LDAP servers, using TLS etc.) The REFERENCE.MD file has many examples. The examples that follow have omitted this option for simplicity. It can be assumed they have been configured on the puppetserver.

Filters and attributes

Simply passing the search base and an rfc4515 search filter string to ldapquery::search() will return the results of the query in list form. Optionally, a list of attributes of which to return the values may also be passed.

Consider the following manifest. (For simplicity, the declaration of $ldap_args has been left off of the following examples).

$base = 'dc=acme,dc=example,dc=com'

$filter = '(uid=zach)'

$attributes = [
  'loginshell',
  'uidnumber',
  'uid',
  'homedirectory',
]

$zach = ldapquery::search($base, $filter, $attributes)

Assuming there is only one LDAP object with the uid=zach, then the variable $zach now holds the following data structure:

[
  {
    'uid'           => ['zach'],
    'loginshell'    => ['/bin/zsh'],
    'uidnumber'     => ['123'],
    'homedirectory' => ['/var/users/zach'],
  }
]

Note that the key values are an array. This should make implementation code simpler, if a bit more verbose, and avoid having to check if the value is an array or a string, because it always is.

Here is a slightly more complicated example that will generate virtual ssh_authorized_key resources for every 'posixAccount' that has a non-empty 'sshPublicKey' attribute.

$base = 'dc=acme,dc=example,dc=com'

$attributes = [
  'uid',
  'sshPublicKey'
]

$key_query = '(&(objectClass=ldapPublicKey)(sshPublicKey=*)(objectClass=posixAccount))'

$key_results = ldapquery::search($base, $key_query, $attributes)
$key_results.each |$u| {
  any2array($u['sshpublickey']).each |$k| {
    $keyparts = split($k, ' ')

    # Retrieve the comment portion
    if $keyparts =~ Array[String, 3] {
      $comment  = $keyparts[2]
    } else {
      $comment  = ''
    }

    $uid = $u['uid'][0]

    @ssh_authorized_key { "${uid}_${comment}":
      user => $uid,
      type => $keyparts[0],
      key  => $keyparts[1],
      tag  => 'ldap',
    }
  }
}

The legacy function ldapquery::query

This implementation has been replaced by the more advanced version ldapquery::search documented above. It should be considered DEPRECATED and may be removed in a future release. For completeness, documentation specific to this function is retained in this release and follows.

On the Puppetserver

You must set the necessary variables in puppet.conf so the puppetserver can connect to your LDAP server. You also have to place the CA certificate (and possible intermediate certificates) of the tls certificate of your ldap server in pem format in a file called ldap_ca.pem in your puppetconf folder.

You can simply add the static values like so:

[master]
ldaptls = true
ldapport = 636
ldapserver = ldap.example.com
ldapbase = dc=example,dc=com
ldapuser = cn=puppet,ou=people,dc=example,dc=com
ldappassword = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Or, use Puppet to manage the values in puppet.conf by adding something like the following to the manifest that manages your master's puppet.conf.

$ldap_base   = hiera('ldap_base') # dc=example,dc=com
$ldap_user   = hiera('ldap_user') # cn=ldapuser,dc=puppetlabs,dc=com
$ldap_pass   = hiera('ldap_pass') # ultrasecure

package { 'net-ldap':
  ensure   => present,
  provider => 'gem'
}

file { '/etc/puppetlabs/puppet/ldap_ca.pem':
  owner  => 'root',
  group  => '0',
  mode   => '0644',
  source => /path/to/my/ldap/ca.pem,
}

Ini_setting {
  ensure  => present,
  section => 'master',
  path    => '/etc/puppetlabs/puppet/puppet.conf',
}

ini_setting { 'ldapserver':
  setting => 'ldapserver',
  value   => 'ldap.example.com',
}

ini_setting { 'ldapport':
  setting => 'ldapport',
  value   => '636',
}

ini_setting { 'ldapbase':
  setting => 'ldapbase',
  value   => $ldap_base,
}

ini_setting { 'ldapuser':
  setting => 'ldapuser',
  value   => $ldap_user,
}

ini_setting { 'ldappassword':
  setting => 'ldappassword',
  value   => $ldap_pass,
}

ini_setting { 'ldaptls':
  setting => 'ldaptls',
  value   => true,
}

Reference

Table of Contents

Functions

• ldapquery: DEPRECATED. Use the namespaced function ldapquery::query instead or migrate to the replacement ldapquery::search function instead.
• ldapquery::query: Provides a legacy query interface to an LDAP server
• ldapquery::search: Provides a search query interface to LDAP server(s). This function is a replacement for ldapquery::query.

Functions

ldapquery

Type: Ruby 4.x API

DEPRECATED. Use the namespaced function ldapquery::query instead or migrate to the replacement ldapquery::search function instead.

ldapquery(Any *$args)

The ldapquery function.

Returns: Any

*args

Data type: Any

ldapquery::query

Type: Ruby 4.x API

This function uses LDAP connection options sourced from puppet.conf and is DEPRECATED. Consider migrating to ldapquery::search instead.

Examples

Simple query

ldapquery::query("(objectClass=dnsDomain)", ['dc'])

More complex query for ssh public keys

ldapquery::query('(&(objectClass=ldapPublicKey)(sshPublicKey=*)(objectClass=posixAccount))', ['uid', 'sshPublicKey'])

ldapquery::query(String[1] $filter, Optional[Array[String[1]]] $attributes, Optional[Options] $options)

This function uses LDAP connection options sourced from puppet.conf and is DEPRECATED. Consider migrating to ldapquery::search instead.

Returns: Any

Examples

Simple query

ldapquery::query("(objectClass=dnsDomain)", ['dc'])

More complex query for ssh public keys

ldapquery::query('(&(objectClass=ldapPublicKey)(sshPublicKey=*)(objectClass=posixAccount))', ['uid', 'sshPublicKey'])

filter

Data type: String[1]

The filter you want to query the LDAP server with

attributes

Data type: Optional[Array[String[1]]]

Which attributes you want to query

options

Data type: Optional[Options]

Function options where you can specify base, scope, and server.

ldapquery::search

Type: Ruby 4.x API

Provides a search query interface to LDAP server(s). This function is a replacement for ldapquery::query.

Examples

Querying an LDAP server on the default port with a username and password

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host => 'ldap.example.com',
    auth => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Trying to connect to multiple LDAP servers to perform the search

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    hosts => [
      [ldap1.example.com, 389],
      [ldap2.example.com, 389],
    ],
    auth => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Not specifying ldap_args as all options needed exist in ldapquery.yaml.

# /etc/puppetlabs/puppet/ldapquery.yaml
# ---
# base: dc=acme,dc=example,dc=com
# host: ldap.example.com
# auth:
#   method: simple
#   username: ldapuser
#   password: ldappassword

ldapquery::search(
  undef, # `base` can also be set in `ldapquery.yaml`
  '(objectClass=dnsDomain)',
  ['dc'],
)

Querying an LDAP server using TLS and the system cert store

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host       => 'ldap.example.com',
    port       => 636,
    encryption => {
      method => simple_tls,
    },
    auth       => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Querying an LDAP server using TLS with a custom CA certificate

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host       => 'ldap.example.com',
    port       => 636,
    encryption => {
      method      => simple_tls,
      tls_options => { ca_file => '/path/to/custom-ca.crt' },
    },
    auth       => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Querying an LDAP server on the standard port but then encrypting all traffic using STARTTLS

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host       => 'ldap.example.com',
    port       => 389, # Default included for clarity
    encryption => {
      method => start_tls,
    },
    auth       => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Specifying a 1 minute search_timeout, (and connect_timeout via ldapquery.yaml)

# /etc/puppetlabs/puppet/ldapquery.yaml
# ---
# base: dc=acme,dc=example,dc=com
# host: ldap.example.com
# auth:
#   method: simple
#   username: ldapuser
#   password: ldappassword
# connect_timeout: 30

ldapquery::search(
  undef, # Use `base` from `ldapquery.yaml`
  '(objectClass=dnsDomain)',
  ['dc'],
  {}, # Use `ldapquery.yaml`
  'sub',
  60,
)

ldapquery::search(Optional[String[1]] $base, Optional[String[1]] $filter, Optional[Array[String[1],1]] $attributes, Optional[Optional[LDAPArgs]] $ldap_args, Optional[Optional[Enum["sub","base","single"]]] $scope, Optional[Optional[Integer[1]]] $search_timeout, Optional[Optional[Boolean]] $soft_fail)

The ldapquery::search function.

Returns: Optional[Array] The returned query results.

Examples

Querying an LDAP server on the default port with a username and password

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host => 'ldap.example.com',
    auth => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Trying to connect to multiple LDAP servers to perform the search

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    hosts => [
      [ldap1.example.com, 389],
      [ldap2.example.com, 389],
    ],
    auth => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Not specifying ldap_args as all options needed exist in ldapquery.yaml.

# /etc/puppetlabs/puppet/ldapquery.yaml
# ---
# base: dc=acme,dc=example,dc=com
# host: ldap.example.com
# auth:
#   method: simple
#   username: ldapuser
#   password: ldappassword

ldapquery::search(
  undef, # `base` can also be set in `ldapquery.yaml`
  '(objectClass=dnsDomain)',
  ['dc'],
)

Querying an LDAP server using TLS and the system cert store

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host       => 'ldap.example.com',
    port       => 636,
    encryption => {
      method => simple_tls,
    },
    auth       => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Querying an LDAP server using TLS with a custom CA certificate

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host       => 'ldap.example.com',
    port       => 636,
    encryption => {
      method      => simple_tls,
      tls_options => { ca_file => '/path/to/custom-ca.crt' },
    },
    auth       => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Querying an LDAP server on the standard port but then encrypting all traffic using STARTTLS

ldapquery::search(
  'dc=acme,dc=example,dc=com',
  '(objectClass=dnsDomain)',
  ['dc'],
  {
    host       => 'ldap.example.com',
    port       => 389, # Default included for clarity
    encryption => {
      method => start_tls,
    },
    auth       => {
      method   => simple,
      username => 'ldapuser',
      password => 'ldappassword',
    },
  },
)

Specifying a 1 minute search_timeout, (and connect_timeout via ldapquery.yaml)

# /etc/puppetlabs/puppet/ldapquery.yaml
# ---
# base: dc=acme,dc=example,dc=com
# host: ldap.example.com
# auth:
#   method: simple
#   username: ldapuser
#   password: ldappassword
# connect_timeout: 30

ldapquery::search(
  undef, # Use `base` from `ldapquery.yaml`
  '(objectClass=dnsDomain)',
  ['dc'],
  {}, # Use `ldapquery.yaml`
  'sub',
  60,
)

base

Data type: Optional[String[1]]

The search base to use for this query. If set to undef, the base must be set as a default in ldapquery.yaml instead.

filter

Data type: Optional[String[1]]

The LDAP search filter to use during the query. If set to undef, the default objectclass=* will be used.

attributes

Data type: Optional[Array[String[1],1]]

The LDAP attributes to return from the server.

ldap_args

Data type: Optional[Optional[LDAPArgs]]

A Hash containing the options used when connecting to the LDAP server(s). See the net-ldap documentation for all the options you can use. This configuration is merged with, (and overrides), any options loaded from /etc/puppetlabs/puppet/ldapquery.yaml. If omitted, ldapquery.yaml must contain all the options you need.

scope

Data type: Optional[Optional[Enum["sub","base","single"]]]

The LDAP search scope, (indicates the set of entries at or below the search base DN that may be considered potential matches for a search operation).

search_timeout

Data type: Optional[Optional[Integer[1]]]

The maximum time in seconds allowed for a search. If not specified, defaults to 10 seconds. Note, there is a separate net-ldap TCP connect_timout (defaulting to 5 seconds) that can be specified via ldap_args, (or globally via ldapquery.yaml).

soft_fail

Data type: Optional[Optional[Boolean]]

When set to true, the function will return undef if it experiences an issue connecting to the LDAP server of performing the query. Defaults to false, which causes the function to fail with an exception if it can't return the requested data.

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v3.1.0 (2023-11-16)

Full Changelog

Version 3.1.0 of the ldapquery module introduces ldapquery::search, a new function for LDAP search queries. This addition is part of our ongoing efforts to enhance and modernise the module. While ldapquery::search is set to become the preferred method for LDAP queries, the existing ldapquery::query function will remain available and unchanged until at least the next major version release.

This approach ensures a smooth transition for users as they adapt to the new functionality. We encourage users to try ldapquery::search and share their feedback.

Implemented enhancements:

• Add Puppet 8 support #48 (bastelfreak)

Merged pull requests:

• Add replacement ldapquery::search function #47 (alexjfisher)

v3.0.0 (2023-05-24)

Full Changelog

Breaking changes:

• Drop Puppet 6 support #41 (bastelfreak)

Implemented enhancements:

• Rename Net::LDAP::LdapError to Net::LDAP::Error #38 (smortex)

Fixed bugs:

• uninitialized constant Net::LDAP::LdapError #43
• Do explicit string conversion on values too #35 (arjenz)

Closed issues:

• Convert to modern function API and namespace #44
• no such file to load -- net/ldap #37

Merged pull requests:

• Convert function to modern API, refactor and namespace #45 (alexjfisher)

v2.1.0 (2021-06-25)

Full Changelog

Implemented enhancements:

• Put options for ldapquery into opts argument #29 (treydock)

v2.0.0 (2021-06-15)

Full Changelog

Breaking changes:

• Drop EoL puppet 5 support; add Puppet 7 #26 (bastelfreak)

Merged pull requests:

• cleanup metadata.json #25 (bastelfreak)
• Declare support for Puppet 5 & 6 #24 (ekohl)
• modulesync 3.0.0 #21 (bastelfreak)
• Ca file optional #20 (Wiston999)
• Update from xaque208 modulesync_config #17 (zachfi)
• Update from xaque208 modulesync_config #16 (zachfi)

1.0.3 (2019-02-27)

Full Changelog

1.0.1 (2019-02-06)

Full Changelog

Merged pull requests:

• Update Readme with some hints on the setup #14 (cbergmann)

1.0.0 (2018-06-03)

Full Changelog

Merged pull requests:

• Update from xaque208 modulesync_config #13 (zachfi)
• Update requirements for net-ldap due to CVE-2017-17718 #12 (zachfi)

0.5.1 (2018-02-10)

Full Changelog

0.5.0 (2018-02-10)

Full Changelog

Closed issues:

• no such file to load -- net/ldap #10

0.4.1 (2017-03-11)

Full Changelog

0.4.0 (2017-02-20)

Full Changelog

Merged pull requests:

• modulesync 2017-02-07 #9 (zachfi)

0.3.1 (2016-05-18)

Full Changelog

0.3.0 (2016-05-16)

Full Changelog

Merged pull requests:

• Add support for scoped queries #8 (zachfi)

0.2.1 (2016-04-04)

Full Changelog

0.2.0 (2016-03-23)

Full Changelog

Merged pull requests:

• Always return an array for the values #7 (zachfi)

0.1.8 (2016-03-13)

Full Changelog

Merged pull requests:

• Update require for puppet_x to use relative path #6 (zachfi)

0.1.7 (2015-11-10)

Full Changelog

0.1.6 (2015-09-17)

Full Changelog

0.1.5 (2015-09-15)

Full Changelog

Merged pull requests:

• Return boolean false if the LDAP query function raises an exception. #5 (Ziaunys)

0.1.4 (2015-08-20)

Full Changelog

Merged pull requests:

• Improve debugging, add timing information #4 (zachfi)

0.1.3 (2015-06-14)

Full Changelog

0.1.2 (2015-05-29)

Full Changelog

0.1.1 (2015-05-29)

Full Changelog

0.1.0 (2015-05-21)

Full Changelog

Merged pull requests:

• Rewrite #3 (zachfi)
• Begin module testing #1 (zachfi)

* This Changelog was automatically generated by github_changelog_generator